@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Modes
in some way. The hook's documentation says how the functions are
called. You can use @code{add-hook} to add a function to an abnormal
hook, but you must write the function to follow the hook's calling
-convention.
+convention. By convention, abnormal hook names end in @samp{-functions}.
- By convention, abnormal hook names end in @samp{-functions}. If the
-variable's name ends in @samp{-function}, then its value is just a single
-function, not a list of functions.
+@cindex single-function hook
+If the variable's name ends in @samp{-function}, then its value is
+just a single function, not a list of functions. @code{add-hook} cannot be
+used to modify such a @emph{single function hook}, and you have to use
+@code{add-function} instead (@pxref{Advising Functions}).
@menu
* Running Hooks:: How to run a hook.
@code{nil}.
@end defun
-@defmac with-wrapper-hook hook args &rest body
-This macro runs the abnormal hook @code{hook} as a series of nested
-``wrapper functions'' around the @var{body} forms. The effect is
-similar to nested @code{around} advices (@pxref{Around-Advice}).
-
-Each hook function should accept an argument list consisting of a function
-@var{fun}, followed by the additional arguments listed in @var{args}.
-The first hook function is passed a function @var{fun} that, if it is
-called with arguments @var{args}, performs @var{body} (i.e., the default
-operation). The @var{fun} passed to each successive hook function is
-constructed from all the preceding hook functions (and @var{body}); if
-this @var{fun} is called with arguments @var{args}, it does what the
-@code{with-wrapper-hook} call would if the preceding hook functions were
-the only ones in @var{hook}.
-
-Each hook function may call its @var{fun} argument as many times as it
-wishes, including never. In that case, such a hook function acts to
-replace the default definition altogether, and any preceding hook
-functions. Of course, a subsequent hook function may do the same thing.
-
-Each hook function definition is used to construct the @var{fun} passed
-to the next hook function in @var{hook}, if any. The last or
-``outermost'' @var{fun} is called once to produce the overall effect.
-
-When might you want to use a wrapper hook? The function
-@code{filter-buffer-substring} illustrates a common case. There is a
-basic functionality, performed by @var{body}---in this case, to extract
-a buffer-substring. Then any number of hook functions can act in
-sequence to modify that string, before returning the final result.
-A wrapper-hook also allows for a hook function to completely replace the
-default definition (by not calling @var{fun}).
-@end defmac
-
-@defun run-hook-wrapped hook wrap-function &rest args
-This function is similar to @code{run-hook-with-args-until-success}.
-Like that function, it runs the functions on the abnormal hook
-@code{hook}, stopping at the first one that returns non-@code{nil}.
-Instead of calling the hook functions directly, though, it actually
-calls @code{wrap-function} with arguments @code{fun} and @code{args}.
-@end defun
-
@node Setting Hooks
@subsection Setting Hooks
retrieve the documentation strings of the major and minor mode
commands (@pxref{Accessing Documentation}).
-If called from Lisp with a non-nil @var{buffer} argument, this
+If called from Lisp with a non-@code{nil} @var{buffer} argument, this
function displays the documentation for that buffer's major and minor
modes, rather than those of the current buffer.
@end deffn
@item
The new mode has its own mode hook, @code{@var{variant}-hook}. It
runs this hook, after running the hooks of its ancestor modes, with
-@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
+@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}.
@end itemize
In addition, you can specify how to override other aspects of
way, specifying @code{tabulated-list-mode} as the second argument
(@pxref{Derived Modes}). The body of the @code{define-derived-mode}
form should specify the format of the tabulated data, by assigning
-values to the variables documented below; then, it should call the
-function @code{tabulated-list-init-header} to initialize the header
-line.
+values to the variables documented below; optionally, it can then call
+the function @code{tabulated-list-init-header}, which will populate a
+header with the names of the columns.
The derived mode should also define a @dfn{listing command}. This,
not the mode command, is what the user calls (e.g., @kbd{M-x
@code{tabulated-list-format}).
@end defun
-@defun tabulated-list-print &optional remember-pos
+@defun tabulated-list-print &optional remember-pos update
This function populates the current buffer with entries. It should be
called by the listing command. It erases the buffer, sorts the entries
specified by @code{tabulated-list-entries} according to
If the optional argument @var{remember-pos} is non-@code{nil}, this
function looks for the @var{id} element on the current line, if any, and
tries to move to that entry after all the entries are (re)inserted.
+
+If the optional argument @var{update} is non-@code{nil}, this function
+will only erase or add entries that have changed since the last print.
+This is several times faster if most entries haven't changed since the
+last time this function was called. The only difference in outcome is
+that tags placed via @code{tabulated-list-put-tag} will not be removed
+from entries that haven't changed (normally all tags are removed).
@end defun
@node Generic Modes
(let ((st (make-syntax-table)))
(modify-syntax-entry ?\" ". " st)
(modify-syntax-entry ?\\ ". " st)
- ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'.
+ ;; Add 'p' so M-c on 'hello' leads to 'Hello', not 'hello'.
(modify-syntax-entry ?' "w p" st)
st)
"Syntax table used while in `text-mode'.")
disables it. From Lisp, an argument of @code{toggle} toggles the mode,
whereas an omitted or @code{nil} argument enables the mode.
This makes it easy to enable the minor mode in a major mode hook, for example.
-If @var{doc} is nil, the macro supplies a default documentation string
+If @var{doc} is @code{nil}, the macro supplies a default documentation string
explaining the above.
By default, it also defines a variable named @var{mode}, which is set to
It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar
+@defun window-header-line-height &optional window
+This function returns the height in pixels of @var{window}'s header
+line. @var{window} must be a live window, and defaults to the
+selected window.
+@end defun
+
A window that is just one line tall never displays a header line. A
window that is two lines tall cannot display both a mode line and a
header line at once; if it has a mode line, then it does not display a
@section Automatic Indentation of code
For programming languages, an important feature of a major mode is to
-provide automatic indentation. This is controlled in Emacs by
-@code{indent-line-function} (@pxref{Mode-Specific Indent}).
-Writing a good indentation function can be difficult and to a large
-extent it is still a black art.
-
-Many major mode authors will start by writing a simple indentation
-function that works for simple cases, for example by comparing with the
-indentation of the previous text line. For most programming languages
-that are not really line-based, this tends to scale very poorly:
-improving such a function to let it handle more diverse situations tends
-to become more and more difficult, resulting in the end with a large,
-complex, unmaintainable indentation function which nobody dares to touch.
+provide automatic indentation. There are two parts: one is to decide what
+is the right indentation of a line, and the other is to decide when to
+reindent a line. By default, Emacs reindents a line whenever you
+type a character in @code{electric-indent-chars}, which by default only
+includes Newline. Major modes can add chars to @code{electric-indent-chars}
+according to the syntax of the language.
+
+Deciding what is the right indentation is controlled in Emacs by
+@code{indent-line-function} (@pxref{Mode-Specific Indent}). For some modes,
+the @emph{right} indentation cannot be known reliably, typically because
+indentation is significant so several indentations are valid but with different
+meanings. In that case, the mode should set @code{electric-indent-inhibit} to
+make sure the line is not constantly re-indented against the user's wishes.
+
+Writing a good indentation function can be difficult and to a large extent it
+is still a black art. Many major mode authors will start by writing a simple
+indentation function that works for simple cases, for example by comparing with
+the indentation of the previous text line. For most programming languages that
+are not really line-based, this tends to scale very poorly: improving
+such a function to let it handle more diverse situations tends to become more
+and more difficult, resulting in the end with a large, complex, unmaintainable
+indentation function which nobody dares to touch.
A good indentation function will usually need to actually parse the
text, according to the syntax of the language. Luckily, it is not
purpose of indentation it has the advantage of not needing to
guess a ``safe'' starting point, and it generally enjoys the property
that only a minimum of text will be analyzed to decide the indentation
-of a line, so indentation will tend to be unaffected by syntax errors in
+of a line, so indentation will tend to be less affected by syntax errors in
some earlier unrelated piece of code. Parsing forward on the other hand
is usually easier and has the advantage of making it possible to
reindent efficiently a whole region at a time, with a single parse.
* SMIE Indentation:: Specifying indentation rules.
* SMIE Indentation Helpers:: Helper functions for indentation rules.
* SMIE Indentation Example:: Sample indentation rules.
+* SMIE Customization:: Customizing indentation.
@end menu
@node SMIE setup
transpose the two arguments of a @code{+} operator, taking into account
the precedence rules of the language.
-Calling `smie-setup' is also sufficient to make TAB indentation work in
+Calling @code{smie-setup} is also sufficient to make TAB indentation work in
the expected way, extends @code{blink-matching-paren} to apply to
elements like @code{begin...end}, and provides some commands that you
can bind in the major mode keymap.
Notice how those lexers return the empty string when in front of
parentheses. This is because SMIE automatically takes care of the
parentheses defined in the syntax table. More specifically if the lexer
-returns nil or an empty string, SMIE tries to handle the corresponding
+returns @code{nil} or an empty string, SMIE tries to handle the corresponding
text as a sexp according to syntax tables.
@node SMIE Tricks
@end itemize
When @var{arg} is a token, the function is called with point just before
-that token. A return value of nil always means to fallback on the
-default behavior, so the function should return nil for arguments it
+that token. A return value of @code{nil} always means to fallback on the
+default behavior, so the function should return @code{nil} for arguments it
does not expect.
@var{offset} can be:
block).
@var{method} should be the method name that was passed to
-`smie-rules-function'.
+@code{smie-rules-function}.
@end defun
@node SMIE Indentation Example
@itemize
@item
The first case indicates the basic indentation increment to use.
-If @code{sample-indent-basic} is nil, then SMIE uses the global
+If @code{sample-indent-basic} is @code{nil}, then SMIE uses the global
setting @code{smie-indent-basic}. The major mode could have set
@code{smie-indent-basic} buffer-locally instead, but that
is discouraged.
first @code{"if"} of the sequence.
@end itemize
+@c In some sense this belongs more in the Emacs manual.
+@node SMIE Customization
+@subsubsection Customizing Indentation
+
+If you are using a mode whose indentation is provided by SMIE, you can
+customize the indentation to suit your preferences. You can do this
+on a per-mode basis (using the option @code{smie-config}), or a
+per-file basis (using the function @code{smie-config-local} in a
+file-local variable specification).
+
+@defopt smie-config
+This option lets you customize indentation on a per-mode basis.
+It is an alist with elements of the form @code{(@var{mode} . @var{rules})}.
+For the precise form of rules, see the variable's documentation; but
+you may find it easier to use the command @code{smie-config-guess}.
+@end defopt
+
+@deffn Command smie-config-guess
+This command tries to work out appropriate settings to produce
+your preferred style of indentation. Simply call the command while
+visiting a file that is indented with your style.
+@end deffn
+
+@deffn Command smie-config-save
+Call this command after using @code{smie-config-guess}, to save your
+settings for future sessions.
+@end deffn
+
+@deffn Command smie-config-show-indent &optional move
+This command displays the rules that are used to indent the current
+line.
+@end deffn
+
+@deffn Command smie-config-set-indent
+This command adds a local rule to adjust the indentation of the current line.
+@end deffn
+
+@defun smie-config-local rules
+This function adds @var{rules} as indentation rules for the current buffer.
+These add to any mode-specific rules defined by the @code{smie-config} option.
+To specify custom indentation rules for a specific file, add an entry
+to the file's local variables of the form:
+@code{eval: (smie-config-local '(@var{rules}))}.
+@end defun
+
+
@node Desktop Save Mode
@section Desktop Save Mode
@cindex desktop save mode