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 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 @defvr Hook sml-load-hook
421 Another, maybe better, place for key bindings. This hook is only run when
422 SML mode is loaded into Emacs. @xref{Configuration}.
426 @c ========================================================= INDENTATION
428 @node Indentation, Magic Insertion, Basics, SML Mode
430 @section Automatic indentation
432 @c == Indentation, Magic Insertion, Basics, SML Mode ===================
436 ML is a complicated language to parse, let alone compile. The
437 indentation algorithm is a little wooden (for some tastes), and the best
438 advice is not to fight it! There are several variables that can be
439 adjusted to control the indentation algorithm (@pxref{SML Mode
440 Defaults,,Customising SML Mode}, below).
443 @deffn Command indent-for-tab-command
447 This command indents the current line. If you set the indentation of the
448 previous line by hand, @code{indent-for-tab-command} will indent relative to
453 @deffn Command indent-region
457 Indent the current region. Be patient if the region is large (like the
462 @deffn Command sml-back-to-outer-indent
463 Key: @kbd{M-@key{TAB}}
464 @kindex @kbd{M-@key{TAB}}
466 Unindents the line to the next outer level of indentation.
471 Further indentation commands that Emacs provides (generically, for all
472 modes) that you may like to recall:
476 @kbd{M-x newline-and-indent}
478 On @key{LFD} by default.
480 Insert a newline, then indent according to the major mode. @xref{Program
481 Indent,,Indentation for Programs,emacs,The Emacs Editor Manual}, for
485 @kbd{M-x indent-rigidly}
487 On @kbd{C-x @key{TAB}} by default.
488 @kindex @kbd{C-x @key{TAB}}
489 Moves all lines in the region right by its argument (left, for negative
490 arguments). @xref{Indentation,,,emacs,The Emacs Editor Manual}.
493 @kbd{M-x indent-for-comment}
495 On @kbd{M-;} by default.
497 Indent this line's comment to comment column, or insert an empty
498 comment. @xref{Comment Commands,,,emacs,The Emacs Editor
502 @kbd{M-x indent-new-comment-line}
504 On @kbd{M-@key{LFD}} by default.
505 @kindex @kbd{M-@key{LFD}}
506 Break line at point and indent, continuing comment if within one.
507 @xref{Multi-Line Comments,,,emacs,The Emacs Editor Manual}.
511 As with other language modes, @kbd{M-;} gives you a comment at the end
512 of the current line. The column where the comment starts is determined
513 by the variable @code{comment-column}---default is 40, but it can be
514 changed with @code{set-comment-column} (on @kbd{C-x ;} by default).
517 @c ===================================================== MAGIC INSERTION
519 @node Magic Insertion, SML Mode Defaults, Indentation, SML Mode
521 @section Electric features
523 @c == Magic Insertion, SML Mode Defaults, Indentation, SML Mode ========
527 Electric keys are generally pretty irritating, so those provided by
528 SML mode are fairly muted. The only truly electric key is @kbd{;},
529 and this has to be enabled to take effect.
532 @deffn Command sml-electric-pipe
536 When the point is in a `case' statement this opens a new line, indents
537 and inserts @code{| =>} leaving point just before the double arrow; if
538 the enclosing construct is a `fun' declaration, the newline is indented
539 and the function name copied at the appropriate column. Generally, try
540 it whenever a @code{|} is wanted---you'll like it!
543 @deffn Command sml-electric-space
547 When the point is after a keyword like `let', this inserts the
548 corresponding predefined skeleton if one exists. Else it just inserts a
549 space. Another way to insert those skeletons is to use
550 @code{sml-insert-form}, described below.
553 @deffn Command sml-electric-semi
557 Just inserts a semi-colon, usually. The behaviour of this command is
558 governed by the variable @code{sml-electric-semi-mode}.
562 @defvr Variable sml-electric-semi-mode
565 If this variable is @code{nil}, @code{sml-electric-semi} just inserts a
566 semi-colon, otherwise it inserts a semi-colon and a newline, and indents
571 @deffn Command sml-insert-form
572 Key: @kbd{C-c @key{RET}}
573 @kindex @kbd{C-c @key{RET}}
575 Interactive short-cut to insert common ML forms (a.k.a.@: macros, or
576 templates). Recognised forms are `let', `local', `case', `abstype',
577 `datatype', `signature', `structure', and `functor'. Except for `let'
578 and `local', these will prompt for appropriate parameters like functor
579 name and signature, etc.. This command prompts in the mini-buffer, with
582 By default @kbd{C-c @key{RET}} will insert at point, with the
583 indentation of the current column; if you give a prefix argument (i.e.,
584 @kbd{C-u C-c @key{RET}}) the command will insert a newline first,
585 indent, and then insert the template.
588 @code{sml-insert-form} is also extensible: see @ref{Configuration} for
593 @c ======================================================= MODE DEFAULTS
595 @node SML Mode Defaults, , Magic Insertion, SML Mode
597 @section Indentation defaults
599 @c == SML Mode Defaults, , Magic Insertion, SML Mode ===================
603 Several variables try to control the indentation algorithm and other
604 features of SML mode. Most of them are still in flux so they are not
606 If the default values are not acceptable you can set these variables
607 permanently in your @file{.emacs} file. @xref{Configuration}, for
608 details and examples.
611 @defvr Variable sml-indent-level
612 @findex sml-indent-level
615 This variable controls the block indentation level.
621 @c ========================================================= INTERACTION
623 @node Interaction Mode, Configuration, SML Mode, Top
625 @chapter Running ML under Emacs
627 @c == Interaction Mode, Configuration, SML Mode, Top ===================
631 The most useful feature of SML mode is that it provides a convenient
632 interface to the compiler. How serious users of ML put up with a
633 teletype interface to the compiler is beyond me@.@.@. but perhaps there
634 are other interfaces to compilers that require one to part with serious
635 money. Such remarks can quickly become dated---in this case, let's hope
638 Anyway, SML mode provides an interaction mode,
639 @code{inferior-sml-mode}, where the compiler runs in a separate buffer
640 in a window or frame of its own. You can use this buffer just like a
641 terminal, but it's usually more convenient to mark some text in the
642 SML mode buffer and have Emacs communicate with the sub-process. The
643 features discussed below are syntax-independent, so they should work
644 with a wide range of ML-like tools and compilers. @xref{Process
645 Defaults}, for some hints.
647 @findex inferior-sml-mode
648 @code{inferior-sml-mode} is a specialisation of the @file{comint}
649 package that comes with Emacs and XEmacs.
653 * Running ML:: Commands to run the ML compiler in a buffer
654 * ML Interaction:: Sending program fragments to the compiler
655 * Tracking Errors:: Finding reported syntax errors
656 * Process Defaults:: Setting defaults for process interaction
661 @c ========================================================== RUNNING ML
663 @node Running ML, ML Interaction, Interaction Mode, Interaction Mode
665 @section Starting the compiler
667 @c == Running ML, ML Interaction, Interaction Mode, Interaction Mode ==
670 Start your favourite ML compiler with the command
677 This creates a process interaction buffer that inherits some key
678 bindings from SML mode and from @file{comint} (@pxref{Shell Mode, ,
679 , emacs, The Emacs Editor Manual}). Starting the ML compiler adds some
680 functions to SML mode buffers so that program text can be
681 communicated between editor and compiler (@pxref{ML Interaction}).
683 The name of the ML compiler is the first thing you should know how to
687 @defvar sml-program-name
688 Default: @code{"sml"}
690 The program to run as ML. You might need to specify the full path name
695 @defvar sml-default-arg
698 Useful for Poly/ML users who may supply a database file, or others who
699 have wrappers for setting various options around the command to run the
700 compiler. Moscow ML people might set this to @code{"-P full"}, etc..
703 The variable @code{sml-program-name} is a string holding the name
704 of the program @emph{as you would type it at the shell}. You
705 can always choose a program different to the default by invoking
708 @kbd{C-u M-x run-sml}
712 With the prefix argument Emacs will prompt for the command name and any
713 command line arguments to pass to the compiler. Thereafter Emacs will
714 use this new name as the default, but for a permanent change you should
715 set this in your @file{.emacs} with, e.g.:
718 (setq sml-program-name "nj-sml")
722 @deffn Command run-sml
723 Launches ML as an inferior process in another buffer; if an ML process
724 already exists, just switch to the process buffer. A prefix argument
725 allows you to edit the command line to specify the program, and any
726 command line options.
730 @defvr Hook inferior-sml-mode-hook
733 @kbd{M-x run-sml} runs @code{comint-mode-hook} and
734 @code{inferior-sml-mode-hook} hooks in that order, but @emph{after} the
735 compiler is started. Use @code{inferior-sml-mode-hook} to set any
736 @code{comint} buffer-local configurations for SML mode you like.
740 @defvr Hook inferior-sml-load-hook
743 This hook is analogous to @code{sml-load-hook} and is run just after the
744 code for @code{inferior-sml-mode} is loaded into Emacs. Use this to set
745 process defaults, and preferred key bindings for the interaction buffer.
749 @deffn Command switch-to-sml
751 @kindex @kbd{C-c C-s}
753 Switch from the SML buffer to the interaction buffer. By default point
754 will be placed at the end of the process buffer, but a prefix argument
755 will leave point wherever it was before. If you try @kbd{C-c C-s} before
756 an ML process has been started, you'll just get an error message to the
757 effect that there's no current process buffer.
761 @deffn Command sml-cd
762 When started, the ML compiler's default working directory is the
763 current buffer's default directory. This command allows the working
764 directory to be changed, if the compiler can do this. The variable
765 @code{sml-cd-command} specifies the compiler command to invoke
766 (@pxref{Process Defaults}).
770 @c ======================================================== SENDING TEXT
772 @node ML Interaction, Tracking Errors, Running ML, Interaction Mode
774 @section Speaking to the compiler
776 @c == ML Interaction, Tracking Errors, Running ML, Interaction Mode ====
780 Several commands are defined for sending program fragments to the
781 running compiler. Each of the following commands takes a prefix argument
782 that will switch the input focus to the process buffer afterwards
783 (leaving point at the end of the buffer):
786 @deffn Command sml-load-file
788 @kindex @kbd{C-c C-l}
790 Send a `use file' command to the current ML process. The variable
791 @code{sml-use-command} is used to define the correct template for the
792 command to invoke (@pxref{Process Defaults}). The default file is the
793 file associated with the current buffer, or the last file loaded if you
794 are in the interaction buffer.
799 @deffn Command sml-send-region
800 @findex sml-send-region-and-go
802 @kindex @kbd{C-c C-r}
804 Send the current region of text in the SML buffer.
805 @code{sml-send-region-and-go} is a similar command for you to bind in
806 SML mode if you wish: it'll send the region and then switch-to-sml.
809 @c @deffn Command sml-send-function
810 @c @findex sml-send-function-and-go
812 @c Send the enclosing `function' definition. Contrary to the suggestive
813 @c name, this command @emph{does not} try to determine the extent of the
814 @c function definition because that is too difficult with ML. Instead
815 @c this just sends the enclosing @emph{paragraph} (delimited by blank
816 @c lines or form-feed characters).
819 @deffn Command sml-send-buffer
821 @kindex @kbd{C-c C-b}
823 Send the contents of the current buffer to ML.
826 @c ===================================================== TRACKING ERRORS
828 @node Tracking Errors, Process Defaults, ML Interaction, Interaction Mode
830 @section Finding errors
832 @c == Tracking Errors, Process Defaults, ML Interaction, Interaction Mode
836 SML mode provides one customisable function for locating the source
837 position of errors reported by the compiler. This should work whether
838 you type @code{use "puzzle.sml";} into the interaction buffer, or use
839 one of the mechanisms provided for sending programs directly to the
840 compiler---@pxref{ML Interaction}.
843 @deffn Command next-error
848 Jump to the source location of the next error reported by the compiler.
849 All the usual error-navigation commands are available, see
850 @pxref{Compilation Mode, , , emacs, The Emacs Editor Manual}.
854 @c ==================================================== PROCESS DEFAULTS
856 @node Process Defaults, , Tracking Errors, Interaction Mode
858 @section Process defaults
860 @c == Process Defaults, , Tracking Errors, Interaction Mode ============
863 The process interaction code is independent of the compiler used,
864 deliberately, so SML mode will work with a variety of ML compilers
865 and ML-based tools. There are therefore a number of variables that may
866 need to be set correctly before SML mode can speak to the compiler.
867 Things are by default set up for Standard ML of New Jersey, but
868 switching to a new system is quite easy.
872 @defvar sml-use-command
873 Default: @code{"use \"%s\""}
875 Use file command template. Emacs will replace the @code{%s} with a file
876 name. Note that Emacs requires double quote characters inside strings
877 to be quoted with a backslash.
881 @defvar sml-cd-command
882 Default: @code{"OS.FileSys.chDir \"%s\""}
884 Compiler command to change the working directory. Not all ML systems
885 support this feature (well, Edinburgh (core) ML didn't), but they
890 @defvar sml-prompt-regexp
891 Default: @code{"^[-=>#] *"}
893 Matches the ML compiler's prompt: @file{comint} uses this for various
898 To customise error reportage for different ML compilers you need to set
899 two further variables before @code{next-error} can be useful:
902 @defvar sml-error-regexp-alist
904 Alist that specifies how to match errors in compiler output.
905 Each elt has the form (REGEXP FILE-IDX LINE-IDX [COLUMN-IDX FILE-FORMAT...])
906 If REGEXP matches, the FILE-IDX'th subexpression gives the file name, and
907 the LINE-IDX'th subexpression gives the line number. If COLUMN-IDX is
908 given, the COLUMN-IDX'th subexpression gives the column number on that line.
909 If any FILE-FORMAT is given, each is a format string to produce a file name to
910 try; %s in the string is replaced by the text matching the FILE-IDX'th
915 @c A typical way of (re)setting these variables correctly is to put
916 @c something in your @file{.emacs} file that resembles
919 @c (setq sml-use-command "PolyML.use \"%s\"")
920 @c (setq sml-prompt-regexp "^[>#] *")
923 @c ======================================================= CONFIGURATION
925 @node Configuration, , Interaction Mode, Top
927 @chapter Configuration Summary
929 @c @footnote{@url{http://www.ahl.co.uk/}}
930 @c @footnote{@url{http://www.dina.kvl.dk/~sestoft/mosml.html}}
933 This (sort of pedagogic) section gives more information on how to
934 configure SML mode: menus, key bindings, hooks and highlighting are
935 discussed, along with a few other random topics.
938 * Hooks:: Creating them
939 * Key Bindings:: Binding commands to keys
940 * Highlighting:: Syntax colouring
941 * Advanced Topics:: You may need to speak Emacs Lisp
945 @c =============================================================== HOOKS
947 @node Hooks, Key Bindings, Configuration, Configuration
951 @c == Hooks, Key Bindings, Configuration, Configuration ================
955 One way to set SML mode variables (@pxref{SML Mode
956 Defaults,,Indentation Defaults}), and other defaults, is through the
957 @code{sml-mode-hook} in your @file{.emacs}. A simple example:
960 (defun my-sml-mode-hook () "Local defaults for SML mode"
961 (setq sml-indent-level 2) ; conserve on horizontal space
962 (setq words-include-escape t) ; \ loses word break status
963 (setq indent-tabs-mode nil)) ; never ever indent with tabs
964 (add-hook 'sml-mode-hook 'my-sml-mode-hook)
967 The body of @code{my-sml-mode-hook} is a sequence of assignments. In this
968 case it is not really necessary to set @code{sml-indent-level} in a hook
969 because this variable is global (most SML mode variables are). With
973 (setq sml-indent-level 2)
976 anywhere in your @file{.emacs} file. The variable @code{indent-tabs-mode} is
977 automatically made local to the current buffer whenever it is set
978 explicitly, so it @emph{must} be set in a hook if you always want
979 SML mode to behave like this.
981 Another hook is @code{inferior-sml-mode-hook}. This can be used to
982 control the behaviour of the interaction buffer through various
983 variables meaningful to @file{comint}-based packages:
986 (defun my-inf-sml-mode-hook () "Local defaults for inferior SML mode"
987 (add-hook 'comint-output-filter-functions 'comint-truncate-buffer)
988 (setq comint-scroll-show-maximum-output t)
989 (setq comint-input-autoexpand nil))
990 (add-hook 'inferior-sml-mode-hook 'my-inf-sml-mode-hook)
993 Again, the body is a sequence of assignments. Unless you run several ML
994 compilers simultaneously under one Emacs, this hook will normally only
995 get run once. You might want to look up the documentation (@kbd{C-h v}
996 and @kbd{C-h f}) for these buffer-local @code{comint} things.
999 @c ======================================================== Key Bindings
1001 @node Key Bindings, Highlighting, Hooks, Configuration
1003 @section Key bindings
1006 Customisation (in Emacs) usually entails putting favourite commands on
1007 easily remembered keys. Two `keymaps' are defined in SML mode: one
1008 is effective in program text buffers (@code{sml-mode-map}) and the other
1009 is effective in interaction buffers (@code{inferior-sml-mode-map}).
1010 The initial design ensures that (many of) the default key bindings from
1011 the former keymap will also be available in the latter (e.g.,
1014 Type @kbd{C-h m} in an SML mode buffer to find the default key
1015 bindings (and similarly in an ML interaction buffer), and use the hooks
1016 provided to install your preferred key bindings. Given that the keymaps
1017 are global (variables):
1020 (defun my-sml-load-hook () "Global defaults for SML mode"
1021 (define-key sml-mode-map "\C-cd" 'sml-cd))
1022 (add-hook 'sml-load-hook 'my-sml-load-hook)
1025 This has the effect of binding @code{sml-cd} to the key @kbd{C-c d}.
1026 If you want the same behaviour from @kbd{C-c d} in the ML buffer:
1029 (defun my-inf-sml-load-hook () "Global defaults for inferior SML mode"
1030 (define-key inferior-sml-mode-map "\C-cd" 'sml-cd)
1031 ;; NB. for SML/NJ '96
1032 (setq sml-cd-command "OS.FileSys.chDir \"%s\""))
1033 (add-hook 'inferior-sml-load-hook 'my-inf-sml-load-hook)
1036 There is nothing to stop you rebuilding the entire keymap for
1037 SML mode and the ML interaction buffer in your @file{.emacs} of
1038 course: SML mode won't define @code{sml-mode-map} or
1039 @code{inferior-sml-mode-map} if you have already done so.
1042 @c ======================================================== Highlighting
1044 @node Highlighting, Advanced Topics, Key Bindings, Configuration
1046 @section Syntax colouring
1050 Highlighting is very handy for picking out keywords in the program text,
1051 spotting misspelled kewyords, and, if you have Emacs' @file{ps-print}
1052 package installed (you usually do these days), obtaining pretty, even
1053 colourful code listings---quite properly for your colourful ML programs.
1055 The indentation scheme (strangely enough) also relies on the
1056 highlighting code to properly handle nested comments, which is yet
1057 another reason to turn on highlighting. To turn on highlighting,
1062 (add-hook 'sml-mode-hook 'turn-on-font-lock)
1063 (global-font-lock-mode 1)
1066 The first will turn it on in the current buffer.
1067 The second will turn it on in all sml-mode buffers.
1068 The last will turn it on everywhere.
1069 This is valid for Emacs but maybe not for XEmacs. Check font-lock
1070 documentation if you encounter problems.
1072 @c ===================================================== ADVANCED TOPICS
1074 @node Advanced Topics, , Highlighting, Configuration
1076 @section Advanced Topics
1079 @emph{These forms are bloody useless; can't we have better ones?}
1084 You can indeed. @code{sml-insert-form} is extensible so all you need to
1085 do is create the macros yourself. Define a @emph{keybord macro}
1086 (@kbd{C-x (} <something> @kbd{C-x )}) and give it a suitable name:
1087 @code{sml-addto-forms-alist} prompts for a name, say @code{NAME}, and
1088 binds the macro @code{sml-form-NAME}. Thereafter @kbd{C-c @key{RET}
1089 NAME} will insert the macro at point, and @kbd{C-u C-c @key{RET} NAME}
1090 will insert the macro after a @code{newline-and-indent}. If you want to
1091 keep your macros from one editing session to the next, go to your
1092 @file{.emacs} file and call @code{insert-kbd-macro}; you'll need
1093 to add @code{NAME} to @code{sml-forms-alist} permanently yourself:
1096 (defun my-sml-load-hook () "Global defaults for SML mode"
1097 ;; whatever else you do
1098 (add-to-list 'sml-forms-alist '("NAME" . FUNCTION)))
1101 If you want to create templates like `case' that prompt for parameters
1102 you'll have to do some Lisp programming. The @code{skeleton} package is
1103 a good stating point. Better yet, you can reuse the wrappers used by
1104 sml-mode itself in your sml-load-hook:
1107 (add-hook 'sml-load-hook
1109 (sml-def-skeleton "case" "Case expr: "
1110 str " of" \n _ " => ")))
1113 This will redefine `case' in order to leave the `of' on the first line.
1114 See the documentation of @code{skeleton-insert} to get a better
1115 understanding of how this works.
1119 @emph{I hate that indentation algorithm; can't I tweak it?}
1124 Ah, yes, of course, but this manual will not tell you how.
1129 @emph{Can SML mode handle more than one compiler running at once?}
1132 Sure, just rename the @samp{*sml*} buffer and then use @code{run-sml}
1137 @emph{What needs to be done to support other ML compilers?}
1142 Not much really. Just add the right regular expressions to
1143 @code{sml-error-regexp-alist} and that should be all.
1146 @c ======================================================= COMMAND INDEX
1148 @headings singleafter
1150 @node Command Index, Variable Index, , Top
1152 @unnumbered Command Index
1156 @c ====================================================== VARIABLE INDEX
1158 @c node Variable Index, , Command Index, Top
1159 @node Variable Index, Key Index, Command Index, Top
1161 @unnumbered Variable Index
1163 @c == Variable Index, Key Index, Command Index, Top ====================
1167 @c =========================================================== KEY INDEX
1169 @node Key Index, , Variable Index, Top
1171 @unnumbered Key Index
1173 @c == Key Index, , Variable Index, Top =================================