1 \input texinfo @c -*-texinfo-*-
3 @comment "@(#)$Name: $:$Id: sml-mode.texi,v 1.8 2003/01/12 19:19:24 monnier Exp $"
5 @comment Documentation for the GNU Emacs SML mode.
6 @comment Copyright (C) 1997-1999 Matthew J.@: Morley
8 @comment This file is part of the sml-mode distribution.
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.
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.
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.
24 @setfilename sml-mode.info
25 @settitle SML mode - The Emacs SML editing mode
28 * sml: (sml-mode). Emacs mode for editing SML
34 @center @titlefont{Editing and Running Standard ML}
35 @center @titlefont{under GNU Emacs}
37 @center SML mode, Version $Name: $
40 @author Authors: Matthew J.@: Morley and Stefan Monnier
43 @vskip 0pt plus 1filll
44 Copyright @copyright{} (Anon)
48 GNU General Public License as published by the Free Software Foundation;
49 either version 2, or (at your option) any later version.
53 SML mode is distributed in the hope that it will be useful, but
54 WITHOUT ANY WARRANTY; without even the implied warranty of
55 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
56 Public License for more details.
60 You should have received a copy of the GNU General Public License along
61 with GNU Emacs; see the file COPYING. If not, write to the Free Software
62 Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
66 @setchapternewpage off
69 @c ============================================================ TOP NODE
71 @node Top, Copying, (dir), (dir)
74 @chapter SML Mode Info
76 @c == Top, Copying, (dir), (dir) =======================================
79 You are looking at the top node of the Info tree documenting
80 @sc{sml-mode} (Version $Name: $). Not all functions are documented here, but
81 those that aren't you probably won't miss. All commands and settable
82 variables have built-in documentation, as per usual Emacs conventions.
86 * Copying:: You can copy SML mode
87 * Introduction:: Setting things up
88 * SML Mode:: Editing SML source
89 * Interaction Mode:: Running ML processes
90 * Configuration:: Menus, highlighting, setting defaults
93 * Command Index:: Commands you can invoke
94 * Variable Index:: Variables you can set
95 * Key Index:: Default keybindings
98 * Contributors:: Who did what
99 * Getting Started:: What to tell Emacs
100 * Getting Help:: How Emacs can help
103 * Basics:: On entering SML mode
104 * Indentation:: Prettying SML text
105 * Magic Insertion:: Templates and electric keys
106 * SML Mode Defaults:: Variables controlling indentation
109 * Running ML:: Commands to run the ML compiler in a buffer
110 * ML Interaction:: Sending program fragments to the compiler
111 * Tracking Errors:: Finding reported syntax errors
112 * Process Defaults:: Setting defaults for process interaction
115 * Hooks:: Creating hooks
116 * Key Bindings:: Binding commands to keys
117 * Highlighting:: Syntax colouring
118 * Advanced Topics:: You may need to speak Emacs Lisp
122 @c ============================================================= COPYING
124 @node Copying, Introduction, Top, Top
129 @c == Copying, Introduction, Top, Top ==================================
132 You can freely copy, modify and redistribute SML mode because it's
133 made available under the liberal terms of the GNU General Public
136 GNU General Public License as published by the Free Software Foundation;
137 either version 2, or (at your option) any later version.
139 SML mode is distributed in the hope that it will be useful, but
140 WITHOUT ANY WARRANTY; without even the implied warranty of
141 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
142 Public License for more details.
144 You should have received a copy of the GNU General Public License along
145 with GNU Emacs; see the file COPYING. If not, write to the Free Software
146 Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
153 @c ======================================================== INTRODUCTION
155 @node Introduction, SML Mode, Copying, Top
157 @chapter Introduction
159 @c == Introduction, SML Mode, Copying, Top =============================
163 SML mode is a major mode for Emacs for editing Standard ML. It has
164 some novel bugs, and some nice features:
168 Automatic indentation of sml code---a number of variables to customise
171 Easy insertion for commonly used templates like let, local, signature,
172 and structure declarations, with minibuffer prompting for types and
175 Magic pipe insertion: @code{|} automatically determines if it is used
176 in a case or fun construct, and indents the next line as appropriate,
177 inserting @code{=>} or the name of the function.
179 Inferior shell for running ML. There's no need to leave Emacs, just keep
180 on editing while the compiler runs in another window.
182 Automatic ``use file'' in the inferior shell---you can send files,
183 buffers, or regions of code to the ML subprocess.
185 Menus, and syntax and keyword highlighting supported for Emacs 19 and
188 Parsing errors from the inferior shell, and repositioning the
189 source with next-error---just like in c-mode.
191 SML mode can be easily configured to work with a number of Standard
192 ML compilers, and other SML based tools.
196 * Contributors:: Who did what
197 * Getting Started:: What to tell Emacs
198 * Getting Help:: How Emacs can help
203 @c ======================================================== CONTRIBUTORS
205 @node Contributors, Getting Started, Introduction, Introduction
207 @section Contributors to the SML mode
211 Contributions to the package are welcome. I have limited time to work
212 on this project, but I will gladly add any code that you contribute to
215 Although the history of sml-mode is obscure, it seems that
216 the following persons have made contributions to sml-mode:
220 Lars Bo Nielsen wrote the original version of the code, providing the
221 sml editing mode and the inferior-sml support.
224 Olin Shivers (@samp{shivers@@ai.mit.edu}) hacked the inferior-sml support
225 to use comint and call the whole thing ml-mode.
228 Steven Gilmore supposedly provided some early attempt at menubar support.
231 Matthew J. Morley (@samp{matthew@@verisity.com}) was maintainer for
232 a long time (until version 3.4) and provided many additions and fixes in
236 Frederick Knabe (@samp{knabe@@ecrc.de}) provided the original code for
237 font-lock and hilite support as well as for proper handling of nested
238 comments and of all the string escape sequences.
241 Matthias Blume (@samp{blume@@kurims.kyoto-u.ac.jp}) provided a sml-make
242 which was replaced by sml-compile.
245 Monnier Stefan (@samp{monnier@@cs.yale.edu}) completely reworked the
246 indentation engine as well as most of the rest of the code and is
247 the current maintainer since after version 3.4.
252 @c ===================================================== GETTING STARTED
254 @node Getting Started, Getting Help, Contributors, Introduction
256 @section Getting started
258 @c == Getting Started, Getting Help, Contributors, Introduction ========
262 With luck your system administrator will have installed SML mode
263 somewhere convenient, so it will just magically all work---you can
264 skip the rest of this getting started section. Otherwise you will need
265 to tell Emacs where to find all the SML mode @file{.el} files, and
266 when to use them. The where is addressed by locating the Lisp code on
267 your Emacs Lisp load path---you may have to create a directory for this,
268 say @file{/home/mjm/elisp}, and then insert the following lines in your
269 @file{/home/mjm/.emacs} file:
272 (add-to-list 'load-path "/home/mjm/elisp")
273 (autoload 'sml-mode "sml-mode" "Major mode for editing SML." t)
274 (autoload 'run-sml "sml-proc" "Run an inferior SML process." t)
278 The first line adjusts Emacs' internal search path so it can locate the
279 Lisp source you have copied to that directory; the second and third
280 lines tell Emacs to load the code automatically when it is needed. You
281 can then switch any Emacs buffer into SML mode by entering the command
288 It is usually more convenient to have Emacs automatically place the
289 buffer in SML mode whenever you visit a file containing ML
290 programs. The simplest way of achieving this is to put something like
293 (add-to-list 'auto-mode-alist '("\\.\\(sml\\|sig\\)\\'" . sml-mode))
297 also in your @file{.emacs} file. Subsequently (after a restart), any
298 files with these extensions will be placed in SML mode buffers when
302 You may want to pre-compile the @file{sml-*.el} files (@kbd{M-x
303 byte-compile-file}) for greater speed---byte compiled code loads and
304 runs somewhat faster.
307 @c ======================================================== GETTING HELP
309 @node Getting Help, , Getting Started, Introduction
313 @c == Getting Help, , Getting Started, Introduction ====================
317 You're reading it. Apart from the on-line info tree (@kbd{C-h i} is the
318 Emacs key to enter the @code{info} system---you should follow the brief
319 tutorial if this is unfamiliar), there are further details on specific
320 commands in their documentation strings. Only the most useful
321 SML mode commands are documented in the info tree: to find out more
322 use Emacs' help facilities.
324 Briefly, to get help on a specific function use @kbd{C-h f} and enter
325 the command name. All (almost all, then) SML mode commands begin
326 with @code{sml-}, so if you type this and press @key{TAB} (for
327 completion) you will get a list of all commands. Another way is to use
328 @kbd{C-h a} and enter the string @code{sml}. This is command apropos; it
329 will list all commands with that sub-string in their names, and any key
330 binding they may have in the current buffer. Command apropos gives a
331 one-line synopsis of what each command does.
333 Some commands are also variables---such things are allowed in Lisp, if
334 not in ML! @xref{Command Index}, for a list of (info) documented
335 functions. @xref{Variable Index}, for a list of user settable variables
336 to control the behaviour of SML mode.
338 Before accessing this information on-line from within Emacs you may have
339 to set the variable @code{sml-mode-info}. Put in your @file{.emacs} file
342 @vindex sml-mode-info
343 @findex sml-mode-info
344 @kindex @kbd{C-c C-i}
346 (setq sml-mode-info "/home/mjm/info/sml-mode.info")
350 When different from the default this variable should be a string giving
351 the absolute name of the @file{.info} file. Then @kbd{C-c C-i} in
352 SML mode (i.e., the command @kbd{M-x sml-mode-info}) will bring up
353 the manual. This help is also accessible from the menu. (Resetting this
354 variable will not be necessary if your site administrator has been kind
355 enough to install SML mode and its attendant documentation in the
359 @c ============================================================ SML MODE
361 @node SML Mode, Interaction Mode, Introduction, Top
363 @chapter Editing with SML Mode
365 @c == SML Mode, Interaction Mode, Introduction, Top ====================
369 Now SML mode provides just a few additional editing commands. Most of
370 the work has gone into implementing the indentation algorithm which, if
371 you think about it, has to be complicated for a language like
372 ML. @xref{SML Mode Defaults,,Indentation Defaults}, for details on how
373 to control some of the behaviour of the indentation algorithm. Principal
374 goodies are the `electric pipe' feature, and the ability to insert
375 common SML forms (macros or templates).
378 * Basics:: On entering SML mode
379 * Indentation:: Prettying SML text
380 * Magic Insertion:: Templates and electric keys
381 * SML Mode Defaults:: Variables controlling indentation
385 @c ============================================================== BASICS
387 @node Basics, Indentation, SML Mode, SML Mode
389 @section On entering SML mode
391 @c == Basics, Indentation, SML Mode, SML Mode ==========================
396 @deffn Command sml-mode
397 This switches a buffer into SML mode. This is a @emph{major mode} in
398 Emacs. To get out of SML mode the buffer's major mode must be set to
399 something else, like @t{text-mode}. @xref{Getting Started}, for details
400 on how to set this up automatically when visiting an SML file.
403 Emacs is all hooks of course. A hook is a variable: if the variable is
404 non-nil it binds a list of Emacs Lisp functions to be run in some order
405 (usually left to right). You can customise SML mode with these
409 @defvr Hook sml-mode-hook
412 This is run every time a new SML mode buffer is created (or if you
413 type @kbd{M-x sml-mode}). This is one place to put your preferred key
414 bindings. @xref{Configuration}, for some examples.
418 @c ========================================================= INDENTATION
420 @node Indentation, Magic Insertion, Basics, SML Mode
422 @section Automatic indentation
424 @c == Indentation, Magic Insertion, Basics, SML Mode ===================
428 ML is a complicated language to parse, let alone compile. The
429 indentation algorithm is a little wooden (for some tastes), and the best
430 advice is not to fight it! There are several variables that can be
431 adjusted to control the indentation algorithm (@pxref{SML Mode
432 Defaults,,Customising SML Mode}, below).
435 @deffn Command indent-for-tab-command
439 This command indents the current line. If you set the indentation of the
440 previous line by hand, @code{indent-for-tab-command} will indent relative to
445 @deffn Command indent-region
449 Indent the current region. Be patient if the region is large (like the
454 @deffn Command sml-back-to-outer-indent
455 Key: @kbd{M-@key{TAB}}
456 @kindex @kbd{M-@key{TAB}}
458 Unindents the line to the next outer level of indentation.
463 Further indentation commands that Emacs provides (generically, for all
464 modes) that you may like to recall:
468 @kbd{M-x newline-and-indent}
470 On @key{LFD} by default.
472 Insert a newline, then indent according to the major mode. @xref{Program
473 Indent,,Indentation for Programs,emacs,The Emacs Editor Manual}, for
477 @kbd{M-x indent-rigidly}
479 On @kbd{C-x @key{TAB}} by default.
480 @kindex @kbd{C-x @key{TAB}}
481 Moves all lines in the region right by its argument (left, for negative
482 arguments). @xref{Indentation,,,emacs,The Emacs Editor Manual}.
485 @kbd{M-x indent-for-comment}
487 On @kbd{M-;} by default.
489 Indent this line's comment to comment column, or insert an empty
490 comment. @xref{Comment Commands,,,emacs,The Emacs Editor
494 @kbd{M-x indent-new-comment-line}
496 On @kbd{M-@key{LFD}} by default.
497 @kindex @kbd{M-@key{LFD}}
498 Break line at point and indent, continuing comment if within one.
499 @xref{Multi-Line Comments,,,emacs,The Emacs Editor Manual}.
503 As with other language modes, @kbd{M-;} gives you a comment at the end
504 of the current line. The column where the comment starts is determined
505 by the variable @code{comment-column}---default is 40, but it can be
506 changed with @code{set-comment-column} (on @kbd{C-x ;} by default).
509 @c ===================================================== MAGIC INSERTION
511 @node Magic Insertion, SML Mode Defaults, Indentation, SML Mode
513 @section Electric features
515 @c == Magic Insertion, SML Mode Defaults, Indentation, SML Mode ========
519 Electric keys are generally pretty irritating, so those provided by
520 SML mode are fairly muted. The only truly electric key is @kbd{;},
521 and this has to be enabled to take effect.
524 @deffn Command sml-electric-pipe
528 When the point is in a `case' statement this opens a new line, indents
529 and inserts @code{| =>} leaving point just before the double arrow; if
530 the enclosing construct is a `fun' declaration, the newline is indented
531 and the function name copied at the appropriate column. Generally, try
532 it whenever a @code{|} is wanted---you'll like it!
535 @deffn Command sml-electric-space
539 When the point is after a keyword like `let', this inserts the
540 corresponding predefined skeleton if one exists. Else it just inserts a
541 space. Another way to insert those skeletons is to use
542 @code{sml-insert-form}, described below.
545 @deffn Command sml-electric-semi
549 Just inserts a semi-colon, usually. The behaviour of this command is
550 governed by the variable @code{sml-electric-semi-mode}.
554 @defvr Variable sml-electric-semi-mode
557 If this variable is @code{nil}, @code{sml-electric-semi} just inserts a
558 semi-colon, otherwise it inserts a semi-colon and a newline, and indents
563 @deffn Command sml-insert-form
564 Key: @kbd{C-c @key{RET}}
565 @kindex @kbd{C-c @key{RET}}
567 Interactive short-cut to insert common ML forms (a.k.a.@: macros, or
568 templates). Recognised forms are `let', `local', `case', `abstype',
569 `datatype', `signature', `structure', and `functor'. Except for `let'
570 and `local', these will prompt for appropriate parameters like functor
571 name and signature, etc.. This command prompts in the mini-buffer, with
574 By default @kbd{C-c @key{RET}} will insert at point, with the
575 indentation of the current column; if you give a prefix argument (i.e.,
576 @kbd{C-u C-c @key{RET}}) the command will insert a newline first,
577 indent, and then insert the template.
580 @code{sml-insert-form} is also extensible: see @ref{Configuration} for
585 @c ======================================================= MODE DEFAULTS
587 @node SML Mode Defaults, , Magic Insertion, SML Mode
589 @section Indentation defaults
591 @c == SML Mode Defaults, , Magic Insertion, SML Mode ===================
595 Several variables try to control the indentation algorithm and other
596 features of SML mode. Most of them are still in flux so they are not
598 If the default values are not acceptable you can set these variables
599 permanently in your @file{.emacs} file. @xref{Configuration}, for
600 details and examples.
603 @defvr Variable sml-indent-level
604 @findex sml-indent-level
607 This variable controls the block indentation level.
613 @c ========================================================= INTERACTION
615 @node Interaction Mode, Configuration, SML Mode, Top
617 @chapter Running ML under Emacs
619 @c == Interaction Mode, Configuration, SML Mode, Top ===================
623 The most useful feature of SML mode is that it provides a convenient
624 interface to the compiler. How serious users of ML put up with a
625 teletype interface to the compiler is beyond me@.@.@. but perhaps there
626 are other interfaces to compilers that require one to part with serious
627 money. Such remarks can quickly become dated---in this case, let's hope
630 Anyway, SML mode provides an interaction mode,
631 @code{inferior-sml-mode}, where the compiler runs in a separate buffer
632 in a window or frame of its own. You can use this buffer just like a
633 terminal, but it's usually more convenient to mark some text in the
634 SML mode buffer and have Emacs communicate with the sub-process. The
635 features discussed below are syntax-independent, so they should work
636 with a wide range of ML-like tools and compilers. @xref{Process
637 Defaults}, for some hints.
639 @findex inferior-sml-mode
640 @code{inferior-sml-mode} is a specialisation of the @file{comint}
641 package that comes with Emacs and XEmacs.
645 * Running ML:: Commands to run the ML compiler in a buffer
646 * ML Interaction:: Sending program fragments to the compiler
647 * Tracking Errors:: Finding reported syntax errors
648 * Process Defaults:: Setting defaults for process interaction
653 @c ========================================================== RUNNING ML
655 @node Running ML, ML Interaction, Interaction Mode, Interaction Mode
657 @section Starting the compiler
659 @c == Running ML, ML Interaction, Interaction Mode, Interaction Mode ==
662 Start your favourite ML compiler with the command
669 This creates a process interaction buffer that inherits some key
670 bindings from SML mode and from @file{comint} (@pxref{Shell Mode, ,
671 , emacs, The Emacs Editor Manual}). Starting the ML compiler adds some
672 functions to SML mode buffers so that program text can be
673 communicated between editor and compiler (@pxref{ML Interaction}).
675 The name of the ML compiler is the first thing you should know how to
679 @defvar sml-program-name
680 Default: @code{"sml"}
682 The program to run as ML. You might need to specify the full path name
687 @defvar sml-default-arg
690 Useful for Poly/ML users who may supply a database file, or others who
691 have wrappers for setting various options around the command to run the
692 compiler. Moscow ML people might set this to @code{"-P full"}, etc..
695 The variable @code{sml-program-name} is a string holding the name
696 of the program @emph{as you would type it at the shell}. You
697 can always choose a program different to the default by invoking
700 @kbd{C-u M-x run-sml}
704 With the prefix argument Emacs will prompt for the command name and any
705 command line arguments to pass to the compiler. Thereafter Emacs will
706 use this new name as the default, but for a permanent change you should
707 set this in your @file{.emacs} with, e.g.:
710 (setq sml-program-name "nj-sml")
714 @deffn Command run-sml
715 Launches ML as an inferior process in another buffer; if an ML process
716 already exists, just switch to the process buffer. A prefix argument
717 allows you to edit the command line to specify the program, and any
718 command line options.
722 @defvr Hook inferior-sml-mode-hook
725 @kbd{M-x run-sml} runs @code{comint-mode-hook} and
726 @code{inferior-sml-mode-hook} hooks in that order, but @emph{after} the
727 compiler is started. Use @code{inferior-sml-mode-hook} to set any
728 @code{comint} buffer-local configurations for SML mode you like.
732 @deffn Command switch-to-sml
734 @kindex @kbd{C-c C-s}
736 Switch from the SML buffer to the interaction buffer. By default point
737 will be placed at the end of the process buffer, but a prefix argument
738 will leave point wherever it was before. If you try @kbd{C-c C-s} before
739 an ML process has been started, you'll just get an error message to the
740 effect that there's no current process buffer.
744 @deffn Command sml-cd
745 When started, the ML compiler's default working directory is the
746 current buffer's default directory. This command allows the working
747 directory to be changed, if the compiler can do this. The variable
748 @code{sml-cd-command} specifies the compiler command to invoke
749 (@pxref{Process Defaults}).
753 @c ======================================================== SENDING TEXT
755 @node ML Interaction, Tracking Errors, Running ML, Interaction Mode
757 @section Speaking to the compiler
759 @c == ML Interaction, Tracking Errors, Running ML, Interaction Mode ====
763 Several commands are defined for sending program fragments to the
764 running compiler. Each of the following commands takes a prefix argument
765 that will switch the input focus to the process buffer afterwards
766 (leaving point at the end of the buffer):
769 @deffn Command sml-load-file
771 @kindex @kbd{C-c C-l}
773 Send a `use file' command to the current ML process. The variable
774 @code{sml-use-command} is used to define the correct template for the
775 command to invoke (@pxref{Process Defaults}). The default file is the
776 file associated with the current buffer, or the last file loaded if you
777 are in the interaction buffer.
782 @deffn Command sml-send-region
783 @findex sml-send-region-and-go
785 @kindex @kbd{C-c C-r}
787 Send the current region of text in the SML buffer.
788 @code{sml-send-region-and-go} is a similar command for you to bind in
789 SML mode if you wish: it'll send the region and then switch-to-sml.
792 @c @deffn Command sml-send-function
793 @c @findex sml-send-function-and-go
795 @c Send the enclosing `function' definition. Contrary to the suggestive
796 @c name, this command @emph{does not} try to determine the extent of the
797 @c function definition because that is too difficult with ML. Instead
798 @c this just sends the enclosing @emph{paragraph} (delimited by blank
799 @c lines or form-feed characters).
802 @deffn Command sml-send-buffer
804 @kindex @kbd{C-c C-b}
806 Send the contents of the current buffer to ML.
809 @c ===================================================== TRACKING ERRORS
811 @node Tracking Errors, Process Defaults, ML Interaction, Interaction Mode
813 @section Finding errors
815 @c == Tracking Errors, Process Defaults, ML Interaction, Interaction Mode
819 SML mode provides one customisable function for locating the source
820 position of errors reported by the compiler. This should work whether
821 you type @code{use "puzzle.sml";} into the interaction buffer, or use
822 one of the mechanisms provided for sending programs directly to the
823 compiler---@pxref{ML Interaction}.
826 @deffn Command next-error
831 Jump to the source location of the next error reported by the compiler.
832 All the usual error-navigation commands are available, see
833 @pxref{Compilation Mode, , , emacs, The Emacs Editor Manual}.
837 @c ==================================================== PROCESS DEFAULTS
839 @node Process Defaults, , Tracking Errors, Interaction Mode
841 @section Process defaults
843 @c == Process Defaults, , Tracking Errors, Interaction Mode ============
846 The process interaction code is independent of the compiler used,
847 deliberately, so SML mode will work with a variety of ML compilers
848 and ML-based tools. There are therefore a number of variables that may
849 need to be set correctly before SML mode can speak to the compiler.
850 Things are by default set up for Standard ML of New Jersey, but
851 switching to a new system is quite easy.
855 @defvar sml-use-command
856 Default: @code{"use \"%s\""}
858 Use file command template. Emacs will replace the @code{%s} with a file
859 name. Note that Emacs requires double quote characters inside strings
860 to be quoted with a backslash.
864 @defvar sml-cd-command
865 Default: @code{"OS.FileSys.chDir \"%s\""}
867 Compiler command to change the working directory. Not all ML systems
868 support this feature (well, Edinburgh (core) ML didn't), but they
873 @defvar sml-prompt-regexp
874 Default: @code{"^[-=>#] *"}
876 Matches the ML compiler's prompt: @file{comint} uses this for various
881 To customise error reportage for different ML compilers you need to set
882 two further variables before @code{next-error} can be useful:
885 @defvar sml-error-regexp-alist
887 Alist that specifies how to match errors in compiler output.
888 Each elt has the form (REGEXP FILE-IDX LINE-IDX [COLUMN-IDX FILE-FORMAT...])
889 If REGEXP matches, the FILE-IDX'th subexpression gives the file name, and
890 the LINE-IDX'th subexpression gives the line number. If COLUMN-IDX is
891 given, the COLUMN-IDX'th subexpression gives the column number on that line.
892 If any FILE-FORMAT is given, each is a format string to produce a file name to
893 try; %s in the string is replaced by the text matching the FILE-IDX'th
898 @c A typical way of (re)setting these variables correctly is to put
899 @c something in your @file{.emacs} file that resembles
902 @c (setq sml-use-command "PolyML.use \"%s\"")
903 @c (setq sml-prompt-regexp "^[>#] *")
906 @c ======================================================= CONFIGURATION
908 @node Configuration, , Interaction Mode, Top
910 @chapter Configuration Summary
912 @c @footnote{@url{http://www.ahl.co.uk/}}
913 @c @footnote{@url{http://www.dina.kvl.dk/~sestoft/mosml.html}}
916 This (sort of pedagogic) section gives more information on how to
917 configure SML mode: menus, key bindings, hooks and highlighting are
918 discussed, along with a few other random topics.
921 * Hooks:: Creating them
922 * Key Bindings:: Binding commands to keys
923 * Highlighting:: Syntax colouring
924 * Advanced Topics:: You may need to speak Emacs Lisp
928 @c =============================================================== HOOKS
930 @node Hooks, Key Bindings, Configuration, Configuration
934 @c == Hooks, Key Bindings, Configuration, Configuration ================
938 One way to set SML mode variables (@pxref{SML Mode
939 Defaults,,Indentation Defaults}), and other defaults, is through the
940 @code{sml-mode-hook} in your @file{.emacs}. A simple example:
943 (defun my-sml-mode-hook () "Local defaults for SML mode"
944 (setq sml-indent-level 2) ; conserve on horizontal space
945 (setq words-include-escape t) ; \ loses word break status
946 (setq indent-tabs-mode nil)) ; never ever indent with tabs
947 (add-hook 'sml-mode-hook 'my-sml-mode-hook)
950 The body of @code{my-sml-mode-hook} is a sequence of assignments. In this
951 case it is not really necessary to set @code{sml-indent-level} in a hook
952 because this variable is global (most SML mode variables are). With
956 (setq sml-indent-level 2)
959 anywhere in your @file{.emacs} file. The variable @code{indent-tabs-mode} is
960 automatically made local to the current buffer whenever it is set
961 explicitly, so it @emph{must} be set in a hook if you always want
962 SML mode to behave like this.
964 Another hook is @code{inferior-sml-mode-hook}. This can be used to
965 control the behaviour of the interaction buffer through various
966 variables meaningful to @file{comint}-based packages:
969 (defun my-inf-sml-mode-hook () "Local defaults for inferior SML mode"
970 (add-hook 'comint-output-filter-functions 'comint-truncate-buffer)
971 (setq comint-scroll-show-maximum-output t)
972 (setq comint-input-autoexpand nil))
973 (add-hook 'inferior-sml-mode-hook 'my-inf-sml-mode-hook)
976 Again, the body is a sequence of assignments. Unless you run several ML
977 compilers simultaneously under one Emacs, this hook will normally only
978 get run once. You might want to look up the documentation (@kbd{C-h v}
979 and @kbd{C-h f}) for these buffer-local @code{comint} things.
982 @c ======================================================== Key Bindings
984 @node Key Bindings, Highlighting, Hooks, Configuration
986 @section Key bindings
989 Customisation (in Emacs) usually entails putting favourite commands on
990 easily remembered keys. Two `keymaps' are defined in SML mode: one
991 is effective in program text buffers (@code{sml-mode-map}) and the other
992 is effective in interaction buffers (@code{inferior-sml-mode-map}).
993 The initial design ensures that (many of) the default key bindings from
994 the former keymap will also be available in the latter (e.g.,
997 Type @kbd{C-h m} in an SML mode buffer to find the default key
998 bindings (and similarly in an ML interaction buffer), and use the hooks
999 provided to install your preferred key bindings. Given that the keymaps
1000 are global (variables):
1003 (defun my-sml-mode-hook () "Global defaults for SML mode"
1004 (define-key sml-mode-map "\C-cd" 'sml-cd))
1005 (add-hook 'sml-mode-hook 'my-sml-mode-hook)
1008 This has the effect of binding @code{sml-cd} to the key @kbd{C-c d}.
1009 If you want the same behaviour from @kbd{C-c d} in the ML buffer:
1012 (defun my-inf-sml-mode-hook () "Global defaults for inferior SML mode"
1013 (define-key inferior-sml-mode-map "\C-cd" 'sml-cd)
1014 ;; NB. for SML/NJ '96
1015 (setq sml-cd-command "OS.FileSys.chDir \"%s\""))
1016 (add-hook 'inferior-sml-mode-hook 'my-inf-sml-mode-hook)
1019 There is nothing to stop you rebuilding the entire keymap for
1020 SML mode and the ML interaction buffer in your @file{.emacs} of
1021 course: SML mode won't define @code{sml-mode-map} or
1022 @code{inferior-sml-mode-map} if you have already done so.
1025 @c ======================================================== Highlighting
1027 @node Highlighting, Advanced Topics, Key Bindings, Configuration
1029 @section Syntax colouring
1033 Highlighting is very handy for picking out keywords in the program text,
1034 spotting misspelled kewyords, and, if you have Emacs' @file{ps-print}
1035 package installed (you usually do these days), obtaining pretty, even
1036 colourful code listings---quite properly for your colourful ML programs.
1038 The indentation scheme (strangely enough) also relies on the
1039 highlighting code to properly handle nested comments, which is yet
1040 another reason to turn on highlighting. To turn on highlighting,
1045 (add-hook 'sml-mode-hook 'turn-on-font-lock)
1046 (global-font-lock-mode 1)
1049 The first will turn it on in the current buffer.
1050 The second will turn it on in all sml-mode buffers.
1051 The last will turn it on everywhere.
1052 This is valid for Emacs but maybe not for XEmacs. Check font-lock
1053 documentation if you encounter problems.
1055 @c ===================================================== ADVANCED TOPICS
1057 @node Advanced Topics, , Highlighting, Configuration
1059 @section Advanced Topics
1062 @emph{These forms are bloody useless; can't we have better ones?}
1067 You can indeed. @code{sml-insert-form} is extensible so all you need to
1068 do is create the macros yourself. Define a @emph{keybord macro}
1069 (@kbd{C-x (} <something> @kbd{C-x )}) and give it a suitable name:
1070 @code{sml-addto-forms-alist} prompts for a name, say @code{NAME}, and
1071 binds the macro @code{sml-form-NAME}. Thereafter @kbd{C-c @key{RET}
1072 NAME} will insert the macro at point, and @kbd{C-u C-c @key{RET} NAME}
1073 will insert the macro after a @code{newline-and-indent}. If you want to
1074 keep your macros from one editing session to the next, go to your
1075 @file{.emacs} file and call @code{insert-kbd-macro}; you'll need
1076 to add @code{NAME} to @code{sml-forms-alist} permanently yourself:
1079 (defun my-sml-mode-hook () "Global defaults for SML mode"
1080 ;; whatever else you do
1081 (add-to-list 'sml-forms-alist '("NAME" . FUNCTION)))
1084 If you want to create templates like `case' that prompt for parameters
1085 you'll have to do some Lisp programming. The @code{skeleton} package is
1086 a good stating point. Better yet, you can reuse the wrappers used by
1087 sml-mode itself in your sml-mode-hook:
1090 (add-hook 'sml-mode-hook
1092 (sml-def-skeleton "case" "Case expr: "
1093 str " of" \n _ " => ")))
1096 This will redefine `case' in order to leave the `of' on the first line.
1097 See the documentation of @code{skeleton-insert} to get a better
1098 understanding of how this works.
1102 @emph{I hate that indentation algorithm; can't I tweak it?}
1107 Ah, yes, of course, but this manual will not tell you how.
1112 @emph{Can SML mode handle more than one compiler running at once?}
1115 Sure, just rename the @samp{*sml*} buffer and then use @code{run-sml}
1120 @emph{What needs to be done to support other ML compilers?}
1125 Not much really. Just add the right regular expressions to
1126 @code{sml-error-regexp-alist} and that should be all.
1129 @c ======================================================= COMMAND INDEX
1131 @headings singleafter
1133 @node Command Index, Variable Index, , Top
1135 @unnumbered Command Index
1139 @c ====================================================== VARIABLE INDEX
1141 @c node Variable Index, , Command Index, Top
1142 @node Variable Index, Key Index, Command Index, Top
1144 @unnumbered Variable Index
1146 @c == Variable Index, Key Index, Command Index, Top ====================
1150 @c =========================================================== KEY INDEX
1152 @node Key Index, , Variable Index, Top
1154 @unnumbered Key Index
1156 @c == Key Index, , Variable Index, Top =================================