X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/b4a83bb86f7b6aae03f9db2da139ce0317fed844..a69add875cbb2d7e1a95e8ee02e33a07ed8d676d:/lispref/modes.texi diff --git a/lispref/modes.texi b/lispref/modes.texi index 1b30a23e12..49b05021d9 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, @c 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/modes @@ -395,7 +395,7 @@ setting up a buffer-local value for the variable @item The mode should specify how Imenu should find the definitions or sections of a buffer, by setting up a buffer-local value for the -variable @code{imenu-generic-expression}, for the pair of variables +variable @code{imenu-generic-expression}, for the two variables @code{imenu-prev-index-position-function} and @code{imenu-extract-index-name-function}, or for the variable @code{imenu-create-index-function} (@pxref{Imenu}). @@ -437,10 +437,8 @@ The major mode command may start by calling some other major mode command (called the @dfn{parent mode}) and then alter some of its settings. A mode that does this is called a @dfn{derived mode}. The recommended way to define one is to use @code{define-derived-mode}, -but this is not required. Such a mode should use -@code{delay-mode-hooks} around its entire body (including the call to -the parent mode command) @emph{except} for the final call to -@code{run-mode-hooks}, which runs the derived mode's hook. (Using +but this is not required. Such a mode should call the parent mode +command inside a @code{delay-mode-hooks} form. (Using @code{define-derived-mode} does this automatically.) @xref{Derived Modes}, and @ref{Mode Hooks}. @@ -871,9 +869,7 @@ command interpreter in a @samp{#!} line. Its value is an alist with elements of the form @code{(@var{interpreter} . @var{mode})}; for example, @code{("perl" . perl-mode)} is one element present by default. The element says to use mode @var{mode} if the file -specifies an interpreter which matches @var{interpreter}. The value -of @var{interpreter} is actually a regular expression. @xref{Regular -Expressions}. +specifies an interpreter which matches @var{interpreter}. @end defvar @defvar magic-mode-alist @@ -1032,9 +1028,6 @@ The @var{keyword-args} are pairs of keywords and values. The values are evaluated. The following keywords are currently supported: @table @code -@item :group -If this is specified, it is the customization group for this mode. - @item :syntax-table You can use this to explicitly specify a syntax table for the new mode. If you specify a @code{nil} value, the new mode uses the same @@ -1049,6 +1042,13 @@ mode. If you specify a @code{nil} value, the new mode uses the same abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} if @var{parent} is @code{nil}. (Again, a @code{nil} value is @emph{not} equivalent to not specifying this keyword.) + +@item :group +If this is specified, the value should be the customization group for +this mode. (Not all major modes have one.) Only the (still +experimental and unadvertised) command @code{customize-mode} currently +uses this. @code{define-derived-mode} does @emph{not} automatically +define the specified customization group. @end table Here is a hypothetical example: @@ -1113,7 +1113,7 @@ it runs the mode hook variable @code{@var{mode}-hook}. @node Mode Hooks @subsection Mode Hooks -The two last things a major mode function does is to run its mode + The two last things a major mode function should do is run its mode hook and finally the mode independent normal hook @code{after-change-major-mode-hook}. If the major mode is a derived mode, that is if it calls another major mode (the parent mode) in its @@ -1121,45 +1121,53 @@ body, then the parent's mode hook is run just before the derived mode's hook. Neither the parent's mode hook nor @code{after-change-major-mode-hook} are run at the end of the actual call to the parent mode. This applies recursively if the parent mode -has itself a parent. That is, the mode hooks of all major modes called -directly or indirectly by the major mode function are all run in -sequence at the end, just before @code{after-change-major-mode-hook}. - -If you are customizing a major mode, rather than defining one, the -above is all you need to know about the hooks run at the end of a -major mode. This also applies if you use @code{define-derived-mode} -to define a major mode, because that macro will automatically -implement the above for you. - -Programmers wishing to define a major mode without using -@code{define-derived-mode}, should make sure that their major mode -follows the above conventions. @xref{Major Mode Conventions}, for how -this should be accomplished. Below, we give some implementation -details. +has itself a parent. That is, the mode hooks of all major modes +called directly or indirectly by the major mode function are all run +in sequence at the end, just before +@code{after-change-major-mode-hook}. + + These conventions are new in Emacs 22, and some major modes +implemented by users do not follow them yet. So if you put a function +onto @code{after-change-major-mode-hook}, keep in mind that some modes +will fail to run it. If a user complains about that, you can respond, +``That major mode fails to follow Emacs conventions, and that's why it +fails to work. Please fix the major mode.'' In most cases, that is +good enough, so go ahead and use @code{after-change-major-mode-hook}. +However, if a certain feature needs to be completely reliable, +it should not use @code{after-change-major-mode-hook} as of yet. + + When you defined a major mode using @code{define-derived-mode}, it +automatically makes sure these conventions are followed. If you +define a major mode ``from scratch'', not using +@code{define-derived-mode}, make sure the major mode command follows +these and other conventions. @xref{Major Mode Conventions}. You use +these functions to do it properly. @defun run-mode-hooks &rest hookvars Major modes should run their mode hook using this function. It is -similar to @code{run-hooks} (@pxref{Hooks}), but if run inside a -@code{delay-mode-hooks} form, this function does not run any hooks. -Instead, it arranges for @var{hookvars} to be run at a later call to -the function. Otherwise, @code{run-mode-hooks} runs any delayed hooks -in order, then @var{hookvars} and finally +similar to @code{run-hooks} (@pxref{Hooks}), but it also runs @code{after-change-major-mode-hook}. + +When the call to this function is dynamically inside a +@code{delay-mode-hooks} form, this function does not run any hooks. +Instead, it arranges for the next call to @code{run-mode-hooks} to run +@var{hookvars}. @end defun @defmac delay-mode-hooks body... This macro executes @var{body} like @code{progn}, but all calls to @code{run-mode-hooks} inside @var{body} delay running their hooks. They will be run by the first call to @code{run-mode-hooks} after exit -from @code{delay-mode-hooks}. +from @code{delay-mode-hooks}. This is the proper way for a major mode +command to invoke its parent mode. @end defmac @defvar after-change-major-mode-hook Every major mode function should run this normal hook at its very end. It normally does not need to do so explicitly. Indeed, a major mode function should normally run its mode hook with @code{run-mode-hooks} -as the very last thing it does and @code{run-mode-hooks} runs -@code{after-change-major-mode-hook} at its very end. +as the very last thing it does, and the last thing +@code{run-mode-hooks} does is run @code{after-change-major-mode-hook}. @end defvar @node Minor Modes @@ -1363,7 +1371,8 @@ symbol). It defines a command named @var{mode} to toggle the minor mode, with @var{doc} as its documentation string. It also defines a variable named @var{mode}, which is set to @code{t} or @code{nil} by enabling or disabling the mode. The variable is initialized to -@var{init-value}. +@var{init-value}. Except in unusual circumstances (see below), this +value must be @code{nil}. The string @var{lighter} says what to display in the mode line when the mode is enabled; if it is @code{nil}, the mode is not displayed @@ -1405,7 +1414,7 @@ This is equivalent to specifying @var{lighter} positionally. This is equivalent to specifying @var{keymap} positionally. @end table -Any other keyword arguments are passed passed directly to the +Any other keyword arguments are passed directly to the @code{defcustom} generated for the variable @var{mode}. The command named @var{mode} first performs the standard actions such @@ -1414,6 +1423,14 @@ as setting the variable named @var{mode} and then executes the variable @code{@var{mode}-hook}. @end defmac + The initial value must be @code{nil} except in cases where (1) the +mode is preloaded in Emacs, or (2) it is painless to for loading to +enable the mode even though the user did not request it. For +instance, if the mode has no effect unless something else is enabled, +and will always be loaded by that time, enabling it by default is +harmless. But these are unusual circumstances. Normally, the +initial value must be @code{nil}. + @findex easy-mmode-define-minor-mode The name @code{easy-mmode-define-minor-mode} is an alias for this macro. @@ -1462,7 +1479,7 @@ When Hungry mode is enabled, the control delete key gobbles all preceding whitespace except the last. See the command \\[hungry-electric-delete]." ;; The initial value. - :initial-value nil + :init-value nil ;; The indicator for the mode line. :lighter " Hungry" ;; The minor mode bindings. @@ -1597,7 +1614,7 @@ value is a list, each element may be a list, a symbol, or a string. The mode line can display various faces, if the strings that control it have the @code{face} property. @xref{Properties in Mode}. In addition, the face @code{mode-line} is used as a default for the whole -mode line (@pxref{Standard Faces}). +mode line (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). @table @code @cindex percent symbol in mode line @@ -1640,13 +1657,13 @@ properties specified by @var{props} to the result. The argument @var{value}. (This feature is new as of Emacs 22.1.) @item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol that is not a keyword specifies a -conditional. Its meaning depends on the value of @var{symbol}. If the -value is non-@code{nil}, the second element, @var{then}, is processed -recursively as a mode-line element. But if the value of @var{symbol} is -@code{nil}, the third element, @var{else}, is processed recursively. -You may omit @var{else}; then the mode-line element displays nothing if -the value of @var{symbol} is @code{nil}. +A list whose first element is a symbol that is not a keyword specifies +a conditional. Its meaning depends on the value of @var{symbol}. If +@var{symbol} has a non-@code{nil} value, the second element, +@var{then}, is processed recursively as a mode-line element. +Otherwise, the third element, @var{else}, is processed recursively. +You may omit @var{else}; then the mode-line element displays nothing +if the value of @var{symbol} is @code{nil} or void. @item (@var{width} @var{rest}@dots{}) A list whose first element is an integer specifies truncation or @@ -1910,7 +1927,7 @@ function. @xref{Buffer File Name}. @item %F The title (only on a window system) or the name of the selected frame. -@xref{Window Frame Parameters}. +@xref{Basic Parameters}. @item %i The size of the accessible part of the current buffer; basically @@ -2280,8 +2297,8 @@ A nested sub-alist element looks like this: It creates the submenu @var{menu-title} specified by @var{sub-alist}. The default value of @code{imenu-create-index-function} is -@code{imenu-default-create-index-function}. This function uses -@code{imenu-prev-index-position-function} and +@code{imenu-default-create-index-function}. This function calls the +value of @code{imenu-prev-index-position-function} and the value of @code{imenu-extract-index-name-function} to produce the index alist. However, if either of these two variables is @code{nil}, the default function uses @code{imenu-generic-expression} instead. @@ -2309,6 +2326,7 @@ Search-based fontification happens second. @menu * Font Lock Basics:: Overview of customizing Font Lock. * Search-based Fontification:: Fontification based on regexps. +* Customizing Keywords:: Customizing search-based fontification. * Other Font Lock Variables:: Additional customization facilities. * Levels of Font Lock:: Each mode can define alternative levels so that the user can select more or less. @@ -2364,7 +2382,9 @@ syntactic fontification (@pxref{Syntax Table Functions}). The resulting syntax table is stored in @code{font-lock-syntax-table}. The fifth element, @var{syntax-begin}, specifies the value of -@code{font-lock-beginning-of-syntax-function}. +@code{font-lock-beginning-of-syntax-function}. We recommend setting +this variable to @code{nil} and using @code{syntax-begin-function} +instead. All the remaining elements (if any) are collectively called @var{other-vars}. Each of these elements should have the form @@ -2443,7 +2463,7 @@ highlighted (instead of the entire text that @var{matcher} matched). @end example If you use @code{regexp-opt} to produce the regular expression -@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Regexp +@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp Functions}) to calculate the value for @var{subexp}. @item (@var{matcher} . @var{facespec}) @@ -2612,19 +2632,27 @@ Non-@code{nil} means that regular expression matching for the sake of @code{font-lock-keywords} should be case-insensitive. @end defvar -You can use @code{font-lock-add-keywords} to add additional +@node Customizing Keywords +@subsection Customizing Search-Based Fontification + + You can use @code{font-lock-add-keywords} to add additional search-based fontification rules to a major mode, and @code{font-lock-remove-keywords} to removes rules. @defun font-lock-add-keywords mode keywords &optional append -This function adds highlighting @var{keywords} for @var{mode}. The -argument @var{keywords} should be a list with the same format as the -variable @code{font-lock-keywords}. @var{mode} should be a symbol, -the major mode command name, such as @code{c-mode}. When Font Lock -mode is turned on in @var{mode}, it adds @var{keywords} to -@code{font-lock-keywords}. @var{mode} can also be @code{nil}; the -highlighting @var{keywords} are immediately added to -@code{font-lock-keywords} in the current buffer in that case. +This function adds highlighting @var{keywords}, for the current buffer +or for major mode @var{mode}. The argument @var{keywords} should be a +list with the same format as the variable @code{font-lock-keywords}. + +If @var{mode} is a symbol which is a major mode command name, such as +@code{c-mode}, the effect is that enabling Font Lock mode in +@var{mode} will add @var{keywords} to @code{font-lock-keywords}. +Calling with a non-@code{nil} value of @var{mode} is correct only in +your @file{~/.emacs} file. + +If @var{mode} is @code{nil}, this function adds @var{keywords} to +@code{font-lock-keywords} in the current buffer. This way of calling +@code{font-lock-add-keywords} is usually used in mode hook functions. By default, @var{keywords} are added at the beginning of @code{font-lock-keywords}. If the optional argument @var{append} is @@ -2633,7 +2661,28 @@ By default, @var{keywords} are added at the beginning of non-@code{nil} value, they are added at the end of @code{font-lock-keywords}. -For example: +Some modes provide specialized support you can use in additional +highlighting patterns. See the variables +@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, +and @code{java-font-lock-extra-types}, for example. + +@strong{Warning:} major mode functions must not call +@code{font-lock-add-keywords} under any circumstances, either directly +or indirectly, except through their mode hooks. (Doing so would lead +to incorrect behavior for some minor modes.) They should set up their +rules for search-based fontification by setting +@code{font-lock-keywords}. +@end defun + +@defun font-lock-remove-keywords mode keywords +This function removes @var{keywords} from @code{font-lock-keywords} +for the current buffer or for major mode @var{mode}. As in +@code{font-lock-add-keywords}, @var{mode} should be a major mode +command name or @code{nil}. All the caveats and requirments for +@code{font-lock-add-keywords} apply here too. +@end defun + + For example, this code @smallexample (font-lock-add-keywords 'c-mode @@ -2641,30 +2690,23 @@ For example: ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) @end smallexample +@noindent adds two fontification patterns for C mode: one to fontify the word @samp{FIXME}, even in comments, and another to fontify the words @samp{and}, @samp{or} and @samp{not} as keywords. -Some modes have specialized support for additional patterns. See the -variables @code{c-font-lock-extra-types}, -@code{c++-font-lock-extra-types}, @code{objc-font-lock-extra-types} -and @code{java-font-lock-extra-types}, for example. -@end defun - -@defun font-lock-remove-keywords mode keywords -This function removes highlighting @var{keywords} for @var{mode}. As -in @code{font-lock-add-keywords}, @var{mode} should be a major mode -command name or @code{nil}. If @code{nil}, the highlighting -@var{keywords} are immediately removed in the current buffer. -@end defun +@noindent +That example affects only C mode proper. To add the same patterns to +C mode @emph{and} all modes derived from it, do this instead: -@strong{Warning:} Only use a non-@code{nil} @var{mode} argument when -you use @code{font-lock-add-keywords} or -@code{font-lock-remove-keywords} in your @file{.emacs} file. When you -use these functions from a Lisp program (such as a minor mode), we -recommend that you use @code{nil} for @var{mode} (and place the call -on a hook) to avoid subtle problems due to the details of the -implementation. +@smallexample +(add-hook 'c-mode-hook + (lambda () + (font-lock-add-keywords nil + '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) + ("\\<\\(and\\|or\\|not\\)\\>" . + font-lock-keyword-face))))) +@end smallexample @node Other Font Lock Variables @subsection Other Font Lock Variables @@ -2876,10 +2918,6 @@ comments and strings. Specify it using @var{syntax-alist} in @code{font-lock-defaults}. @end defvar -@c ??? -@c The docstring says that font-lock-syntax-table is semi-obsolete. -@c How the alternative should be used is not clear. --lute - @defvar font-lock-beginning-of-syntax-function If this variable is non-@code{nil}, it should be a function to move point back to a position that is syntactically at ``top level'' and @@ -2892,9 +2930,10 @@ the beginning of any enclosing syntactic block. Typical values are be outside a syntactic block), or @code{beginning-of-defun} for programming modes, or @code{backward-paragraph} for textual modes. -If the value is @code{nil}, the beginning of the buffer is used as a -position outside of a syntactic block. This cannot be wrong, but it -can be slow. +If the value is @code{nil}, Font Lock uses +@code{syntax-begin-function} to move back outside of any comment, +string, or sexp. This variable is semi-obsolete; we recommend setting +@code{syntax-begin-function} instead. Specify this variable using @var{syntax-begin} in @code{font-lock-defaults}.