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

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

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