1 \input texinfo @c -*-texinfo-*-
3 @comment "@(#)$Name$:$Id$"
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 3 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 3, 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 3, 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@@iro.umontreal.ca}) 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-insert-form
546 Key: @kbd{C-c @key{RET}}
547 @kindex @kbd{C-c @key{RET}}
549 Interactive short-cut to insert common ML forms (a.k.a.@: macros, or
550 templates). Recognised forms are `let', `local', `case', `abstype',
551 `datatype', `signature', `structure', and `functor'. Except for `let'
552 and `local', these will prompt for appropriate parameters like functor
553 name and signature, etc.. This command prompts in the mini-buffer, with
556 By default @kbd{C-c @key{RET}} will insert at point, with the
557 indentation of the current column; if you give a prefix argument (i.e.,
558 @kbd{C-u C-c @key{RET}}) the command will insert a newline first,
559 indent, and then insert the template.
562 @code{sml-insert-form} is also extensible: see @ref{Configuration} for
567 @c ======================================================= MODE DEFAULTS
569 @node SML Mode Defaults, , Magic Insertion, SML Mode
571 @section Indentation defaults
573 @c == SML Mode Defaults, , Magic Insertion, SML Mode ===================
577 Several variables try to control the indentation algorithm and other
578 features of SML mode. Most of them are still in flux so they are not
580 If the default values are not acceptable you can set these variables
581 permanently in your @file{.emacs} file. @xref{Configuration}, for
582 details and examples.
585 @defvr Variable sml-indent-level
586 @findex sml-indent-level
589 This variable controls the block indentation level.
595 @c ========================================================= INTERACTION
597 @node Interaction Mode, Configuration, SML Mode, Top
599 @chapter Running ML under Emacs
601 @c == Interaction Mode, Configuration, SML Mode, Top ===================
605 The most useful feature of SML mode is that it provides a convenient
606 interface to the compiler. How serious users of ML put up with a
607 teletype interface to the compiler is beyond me@.@.@. but perhaps there
608 are other interfaces to compilers that require one to part with serious
609 money. Such remarks can quickly become dated---in this case, let's hope
612 Anyway, SML mode provides an interaction mode,
613 @code{inferior-sml-mode}, where the compiler runs in a separate buffer
614 in a window or frame of its own. You can use this buffer just like a
615 terminal, but it's usually more convenient to mark some text in the
616 SML mode buffer and have Emacs communicate with the sub-process. The
617 features discussed below are syntax-independent, so they should work
618 with a wide range of ML-like tools and compilers. @xref{Process
619 Defaults}, for some hints.
621 @findex inferior-sml-mode
622 @code{inferior-sml-mode} is a specialisation of the @file{comint}
623 package that comes with Emacs and XEmacs.
627 * Running ML:: Commands to run the ML compiler in a buffer
628 * ML Interaction:: Sending program fragments to the compiler
629 * Tracking Errors:: Finding reported syntax errors
630 * Process Defaults:: Setting defaults for process interaction
635 @c ========================================================== RUNNING ML
637 @node Running ML, ML Interaction, Interaction Mode, Interaction Mode
639 @section Starting the compiler
641 @c == Running ML, ML Interaction, Interaction Mode, Interaction Mode ==
644 Start your favourite ML compiler with the command
651 This creates a process interaction buffer that inherits some key
652 bindings from SML mode and from @file{comint} (@pxref{Shell Mode, ,
653 , emacs, The Emacs Editor Manual}). Starting the ML compiler adds some
654 functions to SML mode buffers so that program text can be
655 communicated between editor and compiler (@pxref{ML Interaction}).
657 The name of the ML compiler is the first thing you should know how to
661 @defvar sml-program-name
662 Default: @code{"sml"}
664 The program to run as ML. You might need to specify the full path name
669 @defvar sml-default-arg
672 Useful for Poly/ML users who may supply a database file, or others who
673 have wrappers for setting various options around the command to run the
674 compiler. Moscow ML people might set this to @code{"-P full"}, etc..
677 The variable @code{sml-program-name} is a string holding the name
678 of the program @emph{as you would type it at the shell}. You
679 can always choose a program different to the default by invoking
682 @kbd{C-u M-x run-sml}
686 With the prefix argument Emacs will prompt for the command name and any
687 command line arguments to pass to the compiler. Thereafter Emacs will
688 use this new name as the default, but for a permanent change you should
689 set this in your @file{.emacs} with, e.g.:
692 (setq sml-program-name "nj-sml")
696 @deffn Command run-sml
697 Launches ML as an inferior process in another buffer; if an ML process
698 already exists, just switch to the process buffer. A prefix argument
699 allows you to edit the command line to specify the program, and any
700 command line options.
704 @defvr Hook inferior-sml-mode-hook
707 @kbd{M-x run-sml} runs @code{comint-mode-hook} and
708 @code{inferior-sml-mode-hook} hooks in that order, but @emph{after} the
709 compiler is started. Use @code{inferior-sml-mode-hook} to set any
710 @code{comint} buffer-local configurations for SML mode you like.
714 @deffn Command switch-to-sml
716 @kindex @kbd{C-c C-s}
718 Switch from the SML buffer to the interaction buffer. By default point
719 will be placed at the end of the process buffer, but a prefix argument
720 will leave point wherever it was before. If you try @kbd{C-c C-s} before
721 an ML process has been started, you'll just get an error message to the
722 effect that there's no current process buffer.
726 @deffn Command sml-cd
727 When started, the ML compiler's default working directory is the
728 current buffer's default directory. This command allows the working
729 directory to be changed, if the compiler can do this. The variable
730 @code{sml-cd-command} specifies the compiler command to invoke
731 (@pxref{Process Defaults}).
735 @c ======================================================== SENDING TEXT
737 @node ML Interaction, Tracking Errors, Running ML, Interaction Mode
739 @section Speaking to the compiler
741 @c == ML Interaction, Tracking Errors, Running ML, Interaction Mode ====
745 Several commands are defined for sending program fragments to the
746 running compiler. Each of the following commands takes a prefix argument
747 that will switch the input focus to the process buffer afterwards
748 (leaving point at the end of the buffer):
751 @deffn Command sml-load-file
753 @kindex @kbd{C-c C-l}
755 Send a `use file' command to the current ML process. The variable
756 @code{sml-use-command} is used to define the correct template for the
757 command to invoke (@pxref{Process Defaults}). The default file is the
758 file associated with the current buffer, or the last file loaded if you
759 are in the interaction buffer.
764 @deffn Command sml-send-region
765 @findex sml-send-region-and-go
767 @kindex @kbd{C-c C-r}
769 Send the current region of text in the SML buffer.
770 @code{sml-send-region-and-go} is a similar command for you to bind in
771 SML mode if you wish: it'll send the region and then switch-to-sml.
774 @c @deffn Command sml-send-function
775 @c @findex sml-send-function-and-go
777 @c Send the enclosing `function' definition. Contrary to the suggestive
778 @c name, this command @emph{does not} try to determine the extent of the
779 @c function definition because that is too difficult with ML. Instead
780 @c this just sends the enclosing @emph{paragraph} (delimited by blank
781 @c lines or form-feed characters).
784 @deffn Command sml-send-buffer
786 @kindex @kbd{C-c C-b}
788 Send the contents of the current buffer to ML.
791 @c ===================================================== TRACKING ERRORS
793 @node Tracking Errors, Process Defaults, ML Interaction, Interaction Mode
795 @section Finding errors
797 @c == Tracking Errors, Process Defaults, ML Interaction, Interaction Mode
801 SML mode provides one customisable function for locating the source
802 position of errors reported by the compiler. This should work whether
803 you type @code{use "puzzle.sml";} into the interaction buffer, or use
804 one of the mechanisms provided for sending programs directly to the
805 compiler---@pxref{ML Interaction}.
808 @deffn Command next-error
813 Jump to the source location of the next error reported by the compiler.
814 All the usual error-navigation commands are available, see
815 @pxref{Compilation Mode, , , emacs, The Emacs Editor Manual}.
819 @c ==================================================== PROCESS DEFAULTS
821 @node Process Defaults, , Tracking Errors, Interaction Mode
823 @section Process defaults
825 @c == Process Defaults, , Tracking Errors, Interaction Mode ============
828 The process interaction code is independent of the compiler used,
829 deliberately, so SML mode will work with a variety of ML compilers
830 and ML-based tools. There are therefore a number of variables that may
831 need to be set correctly before SML mode can speak to the compiler.
832 Things are by default set up for Standard ML of New Jersey, but
833 switching to a new system is quite easy.
837 @defvar sml-use-command
838 Default: @code{"use \"%s\""}
840 Use file command template. Emacs will replace the @code{%s} with a file
841 name. Note that Emacs requires double quote characters inside strings
842 to be quoted with a backslash.
846 @defvar sml-cd-command
847 Default: @code{"OS.FileSys.chDir \"%s\""}
849 Compiler command to change the working directory. Not all ML systems
850 support this feature (well, Edinburgh (core) ML didn't), but they
855 @defvar sml-prompt-regexp
856 Default: @code{"^[-=>#] *"}
858 Matches the ML compiler's prompt: @file{comint} uses this for various
863 To customise error reportage for different ML compilers you need to set
864 two further variables before @code{next-error} can be useful:
867 @defvar sml-error-regexp-alist
869 Alist that specifies how to match errors in compiler output.
870 Each elt has the form (REGEXP FILE-IDX LINE-IDX [COLUMN-IDX FILE-FORMAT...])
871 If REGEXP matches, the FILE-IDX'th subexpression gives the file name, and
872 the LINE-IDX'th subexpression gives the line number. If COLUMN-IDX is
873 given, the COLUMN-IDX'th subexpression gives the column number on that line.
874 If any FILE-FORMAT is given, each is a format string to produce a file name to
875 try; %s in the string is replaced by the text matching the FILE-IDX'th
880 @c A typical way of (re)setting these variables correctly is to put
881 @c something in your @file{.emacs} file that resembles
884 @c (setq sml-use-command "PolyML.use \"%s\"")
885 @c (setq sml-prompt-regexp "^[>#] *")
888 @c ======================================================= CONFIGURATION
890 @node Configuration, , Interaction Mode, Top
892 @chapter Configuration Summary
894 @c @footnote{@url{http://www.ahl.co.uk/}}
895 @c @footnote{@url{http://www.dina.kvl.dk/~sestoft/mosml.html}}
898 This (sort of pedagogic) section gives more information on how to
899 configure SML mode: menus, key bindings, hooks and highlighting are
900 discussed, along with a few other random topics.
903 * Hooks:: Creating them
904 * Key Bindings:: Binding commands to keys
905 * Highlighting:: Syntax colouring
906 * Advanced Topics:: You may need to speak Emacs Lisp
910 @c =============================================================== HOOKS
912 @node Hooks, Key Bindings, Configuration, Configuration
916 @c == Hooks, Key Bindings, Configuration, Configuration ================
920 One way to set SML mode variables (@pxref{SML Mode
921 Defaults,,Indentation Defaults}), and other defaults, is through the
922 @code{sml-mode-hook} in your @file{.emacs}. A simple example:
925 (defun my-sml-mode-hook () "Local defaults for SML mode"
926 (setq sml-indent-level 2) ; conserve on horizontal space
927 (setq words-include-escape t) ; \ loses word break status
928 (setq indent-tabs-mode nil)) ; never ever indent with tabs
929 (add-hook 'sml-mode-hook #'my-sml-mode-hook)
932 The body of @code{my-sml-mode-hook} is a sequence of assignments. In this
933 case it is not really necessary to set @code{sml-indent-level} in a hook
934 because this variable is global (most SML mode variables are). With
938 (setq sml-indent-level 2)
941 anywhere in your @file{.emacs} file. The variable @code{indent-tabs-mode} is
942 automatically made local to the current buffer whenever it is set
943 explicitly, so it @emph{must} be set in a hook if you always want
944 SML mode to behave like this.
946 Another hook is @code{inferior-sml-mode-hook}. This can be used to
947 control the behaviour of the interaction buffer through various
948 variables meaningful to @file{comint}-based packages:
951 (defun my-inf-sml-mode-hook () "Local defaults for inferior SML mode"
952 (add-hook 'comint-output-filter-functions 'comint-truncate-buffer)
953 (setq comint-scroll-show-maximum-output t)
954 (setq comint-input-autoexpand nil))
955 (add-hook 'inferior-sml-mode-hook 'my-inf-sml-mode-hook)
958 Again, the body is a sequence of assignments. Unless you run several ML
959 compilers simultaneously under one Emacs, this hook will normally only
960 get run once. You might want to look up the documentation (@kbd{C-h v}
961 and @kbd{C-h f}) for these buffer-local @code{comint} things.
964 @c ======================================================== Key Bindings
966 @node Key Bindings, Highlighting, Hooks, Configuration
968 @section Key bindings
971 Customisation (in Emacs) usually entails putting favourite commands on
972 easily remembered keys. Two `keymaps' are defined in SML mode: one
973 is effective in program text buffers (@code{sml-mode-map}) and the other
974 is effective in interaction buffers (@code{inferior-sml-mode-map}).
975 The initial design ensures that (many of) the default key bindings from
976 the former keymap will also be available in the latter (e.g.,
979 Type @kbd{C-h m} in an SML mode buffer to find the default key
980 bindings (and similarly in an ML interaction buffer), and use the hooks
981 provided to install your preferred key bindings. Given that the keymaps
982 are global (variables):
985 (defun my-sml-mode-hook () "Global defaults for SML mode"
986 (define-key sml-mode-map "\C-cd" 'sml-cd))
987 (add-hook 'sml-mode-hook 'my-sml-mode-hook)
990 This has the effect of binding @code{sml-cd} to the key @kbd{C-c d}.
991 If you want the same behaviour from @kbd{C-c d} in the ML buffer:
994 (defun my-inf-sml-mode-hook () "Global defaults for inferior SML mode"
995 (define-key inferior-sml-mode-map "\C-cd" 'sml-cd)
996 ;; NB. for SML/NJ '96
997 (setq sml-cd-command "OS.FileSys.chDir \"%s\""))
998 (add-hook 'inferior-sml-mode-hook 'my-inf-sml-mode-hook)
1001 There is nothing to stop you rebuilding the entire keymap for
1002 SML mode and the ML interaction buffer in your @file{.emacs} of
1003 course: SML mode won't define @code{sml-mode-map} or
1004 @code{inferior-sml-mode-map} if you have already done so.
1007 @c ======================================================== Highlighting
1009 @node Highlighting, Advanced Topics, Key Bindings, Configuration
1011 @section Syntax colouring
1015 Highlighting is very handy for picking out keywords in the program text,
1016 spotting misspelled kewyords, and, if you have Emacs' @file{ps-print}
1017 package installed (you usually do these days), obtaining pretty, even
1018 colourful code listings---quite properly for your colourful ML programs.
1020 The indentation scheme (strangely enough) also relies on the
1021 highlighting code to properly handle nested comments, which is yet
1022 another reason to turn on highlighting. To turn on highlighting,
1027 (add-hook 'sml-mode-hook 'turn-on-font-lock)
1028 (global-font-lock-mode 1)
1031 The first will turn it on in the current buffer.
1032 The second will turn it on in all sml-mode buffers.
1033 The last will turn it on everywhere.
1034 This is valid for Emacs but maybe not for XEmacs. Check font-lock
1035 documentation if you encounter problems.
1037 @c ===================================================== ADVANCED TOPICS
1039 @node Advanced Topics, , Highlighting, Configuration
1041 @section Advanced Topics
1044 @emph{These forms are bloody useless; can't we have better ones?}
1049 You can indeed. @code{sml-insert-form} is extensible so all you need to
1050 do is create the macros yourself. Define a @emph{keybord macro}
1051 (@kbd{C-x (} <something> @kbd{C-x )}) and give it a suitable name:
1052 @code{sml-addto-forms-alist} prompts for a name, say @code{NAME}, and
1053 binds the macro @code{sml-form-NAME}. Thereafter @kbd{C-c @key{RET}
1054 NAME} will insert the macro at point, and @kbd{C-u C-c @key{RET} NAME}
1055 will insert the macro after a @code{newline-and-indent}. If you want to
1056 keep your macros from one editing session to the next, go to your
1057 @file{.emacs} file and call @code{insert-kbd-macro}; you'll need
1058 to add @code{NAME} to @code{sml-forms-alist} permanently yourself:
1061 (defun my-sml-mode-hook () "Global defaults for SML mode"
1062 ;; whatever else you do
1063 (add-to-list 'sml-forms-alist '("NAME" . FUNCTION)))
1066 If you want to create templates like `case' that prompt for parameters
1067 you'll have to do some Lisp programming. The @code{skeleton} package is
1068 a good stating point. Better yet, you can reuse the wrappers used by
1069 sml-mode itself in your sml-mode-hook:
1072 (add-hook 'sml-mode-hook
1074 (sml-def-skeleton "case" "Case expr: "
1075 str " of" \n _ " => ")))
1078 This will redefine `case' in order to leave the `of' on the first line.
1079 See the documentation of @code{skeleton-insert} to get a better
1080 understanding of how this works.
1084 @emph{I hate that indentation algorithm; can't I tweak it?}
1089 Ah, yes, of course, but this manual will not tell you how.
1094 @emph{Can SML mode handle more than one compiler running at once?}
1097 Sure, just rename the @samp{*sml*} buffer and then use @code{run-sml}
1102 @emph{What needs to be done to support other ML compilers?}
1107 Not much really. Just add the right regular expressions to
1108 @code{sml-error-regexp-alist} and that should be all.
1111 @c ======================================================= COMMAND INDEX
1113 @headings singleafter
1115 @node Command Index, Variable Index, , Top
1117 @unnumbered Command Index
1121 @c ====================================================== VARIABLE INDEX
1123 @c node Variable Index, , Command Index, Top
1124 @node Variable Index, Key Index, Command Index, Top
1126 @unnumbered Variable Index
1128 @c == Variable Index, Key Index, Command Index, Top ====================
1132 @c =========================================================== KEY INDEX
1134 @node Key Index, , Variable Index, Top
1136 @unnumbered Key Index
1138 @c == Key Index, , Variable Index, Top =================================