Home My Page Projects Code Snippets Project Openings SML/NJ
Summary Activity Forums Tracker Lists Tasks Docs Surveys News SCM Files

SCM Repository

[smlnj] Diff of /sml/trunk/sml-mode/sml-mode.texi
ViewVC logotype

Diff of /sml/trunk/sml-mode/sml-mode.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 35, Fri Mar 13 15:54:50 1998 UTC revision 36, Fri Mar 13 17:58:26 1998 UTC
# Line 788  Line 788 
788  Start your favourite ML compiler with the command  Start your favourite ML compiler with the command
789    
790  @example  @example
791  @kbd{M-x sml}  @kbd{M-x run-sml}
792  @end example  @end example
793    
794  @noindent  @noindent
# Line 823  Line 823 
823  can always choose a program different to the default by invoking  can always choose a program different to the default by invoking
824    
825  @example  @example
826  @kbd{C-u M-x sml}  @kbd{C-u M-x run-sml}
827  @end example  @end example
828    
829  @noindent  @noindent
# Line 843  Line 843 
843    
844    
845    
846  @deffn Command sml  @deffn Command run-sml
847  Launches ML as an inferior process in another buffer; if an ML process  Launches ML as an inferior process in another buffer; if an ML process
848  already exists, just switch to the process buffer. A prefix argument  already exists, just switch to the process buffer. A prefix argument
849  allows you to edit the command line to specify the program, and any  allows you to edit the command line to specify the program, and any
# Line 854  Line 854 
854  @defvr Hook inferior-sml-mode-hook  @defvr Hook inferior-sml-mode-hook
855  Default: @code{nil}  Default: @code{nil}
856    
857  @kbd{M-x sml} runs @code{comint-mode-hook} and  @kbd{M-x run-sml} runs @code{comint-mode-hook} and
858  @code{inferior-sml-mode-hook} hooks in that order, but @emph{after} the  @code{inferior-sml-mode-hook} hooks in that order, but @emph{after} the
859  compiler is started. Use @code{inferior-sml-mode-hook} to set any  compiler is started. Use @code{inferior-sml-mode-hook} to set any
860  @code{comint} buffer-local configurations for SML mode you like.  @code{comint} buffer-local configurations for SML mode you like.
# Line 882  Line 882 
882  @end deffn  @end deffn
883    
884    
 @defvar sml-dedicated-frame  
 @vindex sml-display-frame-alist  
 Default: @code{(if window-system t nil)}  
   
 If @code{t} this indicates to @code{switch-to-sml} and other functions  
 that the interaction buffer where ML is running will be displayed on its  
 own, dedicated frame; otherwise the interaction buffer will appear on  
 the current frame, splitting the window if necessary. The default means  
 SML mode will try and use a dedicated frame if you are running Emacs  
 under X Windows (say), but not otherwise. The variable  
 @code{sml-display-frame-alist} configures the dedicated frame's  
 appearance (@kbd{C-h v sml-display-frame-alist} for details).  
 @end defvar  
   
   
   
885  @deffn Command sml-cd  @deffn Command sml-cd
886  When started, the ML compiler's default working directory is the  When started, the ML compiler's default working directory is the
887  current buffer's default directory. This command allows the working  current buffer's default directory. This command allows the working
# Line 1228  Line 1212 
1212  @code{sml-error-regexp} and its ilk (@pxref{Process Defaults}) are  @code{sml-error-regexp} and its ilk (@pxref{Process Defaults}) are
1213  correctly initialised; I have to set @code{sml-program-name} explicitly  correctly initialised; I have to set @code{sml-program-name} explicitly
1214  here because that directory isn't on my (Unix) PATH. The story is  here because that directory isn't on my (Unix) PATH. The story is
1215  simila  similar if you use Poly/ML.
1216    Note, by the way, that order matters here: the @code{load-library} call
1217    comes first because the default for @code{sml-program-name} in
1218    @file{sml-mosml.el} is just @code{"mosml"}.
1219    
1220    @c @example
1221    @c (eval-after-load "sml-proc" '(my-mosml-setup))
1222    @c @end example
1223    @c @noindent
1224    @c is perhaps a better way to achieve the same effect, but last time I
1225    @c looked this wouldn't work in XEmacs.
1226    
1227    The auxiliary libraries bundled with SML mode define commands
1228    @code{sml-mosml} and @code{sml-poly-ml} (there's also an
1229    @code{sml-smlnj} for uniformity); these commands prompt for suitable
1230    values for @code{sml-program-name} and @code{sml-default-arg} before
1231    starting the compiler and setting the other process defaults. A prefix
1232    argument will give you the builtin defaults with no questions asked.
1233    
1234    @menu
1235    * Hooks::               Creating them
1236    * Key Bindings::        Binding commands to keys
1237    * Menus::               Taking advantage of bitmapped screens
1238    * Highlighting::        Syntax colouring
1239    * Advanced Topics::     You may need to speak Emacs Lisp
1240    @end menu
1241    
1242    
1243    @c =============================================================== HOOKS
1244    
1245    @node Hooks, Key Bindings, Configuration, Configuration
1246    
1247    @section Hooks
1248    
1249    @c == Hooks, Key Bindings, Configuration, Configuration ================
1250    
1251    
1252    @noindent
1253    One way to set SML mode variables (@pxref{SML Mode
1254    Defaults,,Indentation Defaults}), and other defaults, is through the
1255    @code{sml-mode-hook} in your @file{.emacs}. A simple example:
1256    
1257    @lisp
1258    (defun my-sml-mode-hook () "Local defaults for SML mode"
1259      (setq sml-indent-level 2)        ; conserve on horizontal space
1260      (setq words-include-escape t)    ; \ loses word break status
1261      (setq indent-tabs-mode nil))     ; never ever indent with tabs
1262    (add-hook 'sml-mode-hook 'my-sml-mode-hook)
1263    @end lisp
1264    @noindent
1265    The body of @code{my-sml-mode-hook} is a sequence of bindings. In this
1266    case it is not really necessary to set @code{sml-indent-level} in a hook
1267    because this variable is global (most SML mode variables are). With
1268    similar effect:
1269    
1270    @lisp
1271    (setq sml-indent-level 2)
1272    @end lisp
1273    @noindent
1274    anywhere in your @file{.emacs} file (but probably on
1275    @code{sml-load-hook}). The variable @code{indent-tabs-mode} is
1276    automatically made local to the current buffer whenever it is set
1277    explicitly, so it @emph{must} be set in a hook if you always want
1278    SML mode to behave like this. The same goes for the buffer-local
1279    @code{sml-error-overlay}; since this is globally @code{t} by default,
1280    set it globally @code{nil} if you never want errors highlighted:
1281    
1282    @lisp
1283    (setq-default sml-error-overlay nil)
1284    @end lisp
1285    @noindent
1286    Again, on @code{sml-load-hook} would probably be the best place.
1287    
1288    
1289    Another hook is @code{inferior-sml-mode-hook}. This can be used to
1290    control the behaviour of the interaction buffer through various
1291    variables meaningful to @file{comint}-based packages:
1292    
1293    @lisp
1294    (defun my-inf-sml-mode-hook () "Local defaults for inferior SML mode"
1295      (add-hook 'comint-output-filter-functions 'comint-truncate-buffer)
1296      (setq      comint-scroll-show-maximum-output t)
1297      (setq      comint-input-autoexpand nil))
1298    (add-hook 'inferior-sml-mode-hook 'my-inf-sml-mode-hook)
1299    @end lisp
1300    @noindent
1301    Again, the body is a sequence of bindings. Unless you run several ML
1302    compilers simultaneously under one Emacs, this hook will normally only
1303    get run once. You might want to look up the documentation (@kbd{C-h v}
1304    and @kbd{C-h f}) for these buffer-local @code{comint} things.
1305    
1306    
1307    @c ======================================================== Key Bindings
1308    
1309    @node Key Bindings, Menus, Hooks, Configuration
1310    
1311    @section Key bindings
1312    
1313    @c == Key Bindings, Menus, Hooks, Configuration ========================
1314    
1315    
1316    @noindent
1317    Customisation (in Emacs) usually entails putting favourite commands on
1318    easily remembered keys. Two `keymaps' are defined in SML mode: one
1319    is effective in program text buffers (@code{sml-mode-map}) and the other
1320    is effective in interaction buffers (@code{inferior-sml-mode-map}).
1321    The initial design ensures that (many of) the default key bindings from
1322    the former keymap will also be available in the latter (e.g.,
1323    @kbd{C-c`}).
1324    
1325    Type @kbd{C-h m} in an SML mode buffer to find the default key
1326    bindings (and similarly in an ML interaction buffer), and use the hooks
1327    provided to install your preferred key bindings. Given that the keymaps
1328    are global (variables):
1329    
1330    @lisp
1331    (defun my-sml-load-hook () "Global defaults for SML mode"
1332      (define-key   sml-mode-map "\C-cd" 'sml-cd)
1333      (define-key   sml-mode-map "\C-co" 'sml-error-overlay))
1334    (add-hook 'sml-load-hook 'my-sml-load-hook)
1335    @end lisp
1336    @noindent
1337    This has the effect of binding @code{sml-cd} to the key @kbd{C-c d}, and
1338    the command @code{sml-error-overlay} to the key @kbd{C-c o}. If you want
1339    the same behaviour from @kbd{C-c d} in the ML buffer:
1340    
1341    @lisp
1342    (defun my-inf-sml-load-hook () "Global defaults for inferior SML mode"
1343      (define-key inferior-sml-mode-map "\C-cd" 'sml-cd)
1344      ;; NB. for SML/NJ '96
1345      (setq sml-cd-command "OS.FileSys.chDir \"%s\""))
1346    (add-hook 'inferior-sml-load-hook 'my-inf-sml-load-hook)
1347    @end lisp
1348    
1349    There is nothing to stop you rebuilding the entire keymap for
1350    SML mode and the ML interaction buffer in your @file{.emacs} of
1351    course: SML mode won't define @code{sml-mode-map} or
1352    @code{inferior-sml-mode-map} if you have already done so.
1353    
1354    
1355    @c =============================================================== Menus
1356    
1357    @node Menus, Highlighting, Key Bindings, Configuration
1358    
1359    @section Menus
1360    
1361    @c == Menus, Highlighting, Key Bindings, Configuration =================
1362    
1363    
1364    @noindent
1365    Menus are useful for fiddling with mode defaults and finding out what
1366    keys commands are on if you are forgetful (not all commands are listed
1367    in the menu). For menus to appear in the menu bar under GNU Emacs or GNU
1368    XEmacs, the editor must be able to find one of two packages---i.e., one
1369    or both must be on your @code{load-path}. The first option is
1370    @file{easymenu} which is distributed with GNU Emacs. Easy!
1371    
1372    The second option is @file{auc-menu} which was written by Per Abrahamsen
1373    and distributed with AUCTeX, but it is independently available from the
1374    IESD lisp archive@footnote{@url{ftp://sunsite.auc.dk/packages/auctex/}}
1375    at Aalborg. You'll also find @file{auc-menu} is available from the LCD
1376    archive@footnote{@url{ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/misc/}},
1377    the main repository for all Emacs Lisp. The advantage of @file{auc-menu}
1378    is that it works with XEmacs too.
1379    
1380    Notice that certain menu entries are not illuminated at first---these
1381    are generally functions that depend on there being an ML process running
1382    with which to communicate.
1383    
1384    
1385    @c ======================================================== Highlighting
1386    
1387    @node Highlighting, Advanced Topics, Menus, Configuration
1388    
1389    @section Syntax colouring
1390    
1391    @c == Highlighting, Advanced Topics, Menus, Configuration ==============
1392    
1393    
1394    @noindent
1395    Highlighting is very handy for picking out keywords in the program text,
1396    spotting misspelled kewyords, and, if you have Emacs' @file{ps-print}
1397    package installed (you usually do these days), obtaining pretty, even
1398    colourful code listings---quite properly for your colourful ML programs.
1399    
1400    @vindex sml-font-lock-extra-keywords
1401    @vindex sml-font-lock-auto-on
1402    
1403    Various highlight (hilite, if you spell real bad!) packages are
1404    available for GNU Emacs 19, and GNU XEmacs. SML mode can use either
1405    @file{hilit19} which only comes with Emacs, or @file{font-lock} which is
1406    the package of choice with XEmacs. If you are not familiar with these
1407    highlight packages you'll have to check their sources for installation
1408    guidelines, etc..
1409    
1410    Use @code{sml-load-hook} to tell Emacs which scheme you prefer for
1411    SML mode. For example:
1412    
1413    @lisp
1414    (add-hook 'sml-load-hook '(lambda () (require 'sml-font)))
1415    @end lisp
1416    
1417    @noindent
1418    This ensures the SML extensions to @file{font-lock} will be available
1419    once SML mode loads (from @file{sml-font.el}---if you prefer
1420    @file{hilit19} you should @code{(require 'sml-hilite)} instead.
1421    
1422    The variable @code{sml-font-lock-extra-keywords} is for further
1423    customising @file{font-lock} for SML mode. The value of the variable
1424    should be a list of strings, each of which is a regular expression that
1425    should match the desired keyword exactly. Here's an example:
1426    
1427    @lisp
1428    (setq sml-font-lock-extra-keywords
1429          '("\\babstraction\\b" "\\bfunsig\\b" "=>" "::"))))
1430    @end lisp
1431    
1432    @noindent
1433    The @code{\b} marks a word boundary, according to the syntax table
1434    defined for SML mode. Backslash must be quoted inside a string.
1435    @xref{Regexps,,,emacs,The Emacs Editor Manual}, for a summary of Emacs'
1436    regular expression syntax.
1437    
1438    
1439    Finally, the variable @code{sml-font-lock-auto-on} can be used to
1440    control whether or not @file{font-lock} should be enabled by default in
1441    SML mode buffers; it is enabled by default. The @code{sml-hilite}
1442    package is customisable, but only with regard to colour changes.
1443    
1444    
1445    @c ===================================================== ADVANCED TOPICS
1446    
1447    @node Advanced Topics, , Highlighting, Configuration
1448    
1449    @section Advanced Topics
1450    
1451    @c == Advanced Topics, , Highlighting, Configuration ===================
1452    
1453    @menu
1454    * Forms::    These forms are bloody useless; can't we have better ones?
1455    * Indents::  I hate that indentation algorithm; can't I suppress it?
1456    * Multi ML:: Can SML mode handle more than one compiler running at once?
1457    * Other ML:: What needs to be done to support other ML compilers?
1458    @end menu
1459    
1460    
1461    @node Forms, Indents, Advanced Topics, Advanced Topics
1462    
1463    @flushright
1464    @emph{These forms are bloody useless; can't we have better ones?}
1465    @end flushright
1466    
1467    @sp 1
1468    @noindent
1469    You can indeed. @code{sml-insert-form} is extensible so all you need to
1470    do is create the macros yourself. Define a @emph{keybord macro}
1471    (@kbd{C-x (} <something> @kbd{C-x )}) and give it a suitable name:
1472    @code{sml-addto-forms-alist} prompts for a name, say @code{NAME}, and
1473    binds the macro @code{sml-form-NAME}. Thereafter @kbd{C-c @key{RET}
1474    NAME} will insert the macro at point, and @kbd{C-u C-c @key{RET} NAME}
1475    will insert the macro after a @code{newline-and-indent}. If you want to
1476    keep your macros from one editing session to the next, go to your
1477    @file{.emacs} file and call @code{insert-kbd-macro}; you'll need
1478    to add @code{NAME} to @code{sml-forms-alist} permanently yourself:
1479    
1480    @lisp
1481    (defun my-sml-load-hook () "Global defaults for SML mode"
1482      ;; whatever else you do
1483      (setq sml-forms-alist (cons '("NAME") sml-forms-alist)))
1484    @end lisp
1485    
1486    If you want to create templates like `case' that prompt for parameters
1487    you'll have to do some Lisp programming. The @code{tempo} package looks
1488    like a good stating point. You can always overwrite your own macros, but
1489    the builtin forms for `let', etc., can't be overwritten.
1490    
1491    
1492    @node Indents, Multi ML, Forms, Advanced Topics
1493    
1494    @sp 1
1495    @flushright
1496    @emph{I hate that indentation algorithm; can't I suppress it?}
1497    @end flushright
1498    
1499    @sp 1
1500    @noindent
1501    Ah, yes, a common complaint. It's actually very easy to use SML mode
1502    without the troublesome @code{sml-indent-line}:
1503    
1504    @lisp
1505    (defun my-sml-load-hook () "Global defaults for SML mode"
1506      ;; whatever else you do
1507      (fset 'sml-indent-line 'ignore))
1508    @end lisp
1509    @noindent
1510    though @code{indent-relative-maybe} may conceivable be more useful than
1511    @code{ignore}.
1512    
1513    
1514    @node Multi ML, Other ML, Indents, Advanced Topics
1515    
1516    @sp 1
1517    @flushright
1518    @emph{Can SML mode handle more than one compiler running at once?}
1519    @end flushright
1520    
1521    @findex sml-buffer
1522    @vindex sml-buffer
1523    @sp 1
1524    @noindent
1525    The question is whether you can! See the @code{sml-buffer} variable's
1526    on-line help (@kbd{C-h v sml-buffer}). Note that the SML mode
1527    compiler variables (@pxref{Process Defaults}) are all buffer-local, so
1528    you can even switch between different ML compilers, not just different
1529    invocations of the same one. Well, you @emph{can}.
1530    
1531    
1532    
1533    @node Other ML, , Multi ML, Advanced Topics
1534    
1535    @sp 1
1536    @flushright
1537    @emph{What needs to be done to support other ML compilers?}
1538    @end flushright
1539    
1540    @sp 1
1541    @noindent
1542    Not that much really, at least not to create minimal support. The
1543    interface between SML mode and the compiler is determined by the
1544    variables
1545    @code{sml-use-command},
1546    @code{sml-cd-command},
1547    @code{sml-prompt-regexp}
1548    (which are easy to get right), and
1549    @code{sml-error-regexp}, and
1550    @code{sml-error-parser} (which are more tricky).
1551    The general template to follow in setting this up
1552    is in the files @file{sml-@{poly-ml,mosml@}.el}.
1553    These rules will not change, I hope:
1554    
1555    @itemize @bullet
1556    @item
1557    @code{sml-next-error} uses @code{sml-error-regexp} to locate the start
1558    of the next error report in the ML interaction buffer (@var{P})
1559    
1560    @item
1561    @code{sml-next-error} calls @code{sml-error-parser}, passing @var{P}, and
1562    expects up to five return values in this order:
1563    
1564    @enumerate
1565    @item file name in which the error occurs (@var{F})
1566    @item start line of the error (@var{L} > 0)
1567    @item start column of the error (@var{C})
1568    @item an Emacs Lisp expression to be @code{eval}'d
1569    at (@var{L},@var{C}) in @var{F} (@var{EOE})
1570    @item the actual text of the one-line error report (@var{MSG})
1571    @end enumerate
1572    
1573    
1574    @item
1575    @code{sml-error-parser} can assume that @var{P} is the start of the next
1576    error message that the user is interested in---since she defines this
1577    point by defining @code{sml-error-regexp}.
1578    
1579    @item
1580    What @code{sml-error-parser} returns is a list. In the event of problems,
1581    I foresee the following needs:
1582    
1583    @itemize -
1584    @item if the file is the standard input,
1585    return @code{("std_in" @var{L} @var{C})}
1586    @item if the file cannot be inferred,
1587    return @code{(nil @var{L} @var{C})}
1588    @item if @var{L}=0, or the start cannot be inferred,
1589    return @code{(@var{F} nil @var{C})}
1590    @item if the start column cannot be inferred,
1591    return @code{(@var{F} @var{L} 1)}
1592    @end itemize
1593    @end itemize
1594    
1595    There's no need to return anything else. However, if you do want the
1596    errorful text in @var{F} highlighted you should return a simple Lisp
1597    expression in the fourth argument that'll compute the region. @var{EOE}
1598    will be called with point at character (@var{L},@var{C}) in @var{F}, and
1599    should move point to the end of the errorful text. In fact, @var{EOE}
1600    can actually do anything you wish, but in the simplest cases it'll just
1601    @code{(forward-char 45)}, or
1602    
1603    @lisp
1604    (progn (forward-line 4) (forward-char 37))
1605    @end lisp
1606    @noindent
1607    etc.. If it does more, make sure it leaves point at the end of the
1608    region in @var{F}---use @code{save-excursion} if switching buffers.
1609    @var{MSG}, if returned, will be echoed in the minibuffer.
1610    
1611    @c ============================================================== CREDIT
1612    
1613    @c H A C K   A T T A C K   O N
1614    @c page
1615    @c H A C K   A T T A C K   O F F
1616    
1617    @node Credits, Command Index, Configuration, Top
1618    
1619    @unnumbered Credit & Blame
1620    
1621    @c == Credits, Command Index, Configuration, Top =======================
1622    
1623    @noindent
1624    SML Mode was written originally by Lars Bo Nielsen for Emacs 18.5n;
1625    later hacked for comint by Olin Shivers (who called it @t{ml-mode});
1626    much later hacked by myself because it didn't seem to work@dots{} Fritz
1627    Knabe brilliantly posted the @code{hilit19} and @code{font-lock}
1628    functions on the net. Lars probably would recognise much of what
1629    remains, yet now there're menus, syntax highlighting, support for
1630    various ML compilers, Texinfo (hey!), and more than a little hope it'll
1631    work with a variety of Emacs 19s. But there are still things to do. Lars
1632    wrote:
1633    @quotation
1634    @emph{The indentation algorithm still can be fooled. I don't know if it will
1635    ever be 100% right, as this means it will have to actually parse all of
1636    the buffer up to the actual line [@dots{}].}
1637    @end quotation
1638    @noindent
1639    This is still the main cause of grief; SML's syntax is a nightmare for
1640    Emacs modes, and of course opinions vary about proper indentation. But
1641    there may be something we can do@dots{}
1642    
1643    @c ======================================================= COMMAND INDEX
1644    
1645    @headings singleafter
1646    
1647    @node Command Index, Variable Index, Credits, Top
1648    
1649    @unnumbered Command Index
1650    
1651    @c == Command Index, Variable Index, Credits, Top ======================
1652    
1653    @printindex fn
1654    
1655    @c ====================================================== VARIABLE INDEX
1656    
1657    @c node Variable Index, , Command Index, Top
1658    @node Variable Index, Key Index, Command Index, Top
1659    
1660    @unnumbered Variable Index
1661    
1662    @c == Variable Index, Key Index, Command Index, Top ====================
1663    
1664    @printindex vr
1665    
1666    @c =========================================================== KEY INDEX
1667    
1668    @node Key Index, , Variable Index, Top
1669    
1670    @unnumbered Key Index
1671    
1672    @c == Key Index, , Variable Index, Top =================================
1673    
1674    @printindex ky
1675    
1676    @contents
1677    @bye

Legend:
Removed from v.35  
changed lines
  Added in v.36

root@smlnj-gforge.cs.uchicago.edu
ViewVC Help
Powered by ViewVC 1.0.0