diff options
Diffstat (limited to 'lispref/modes.texi')
| -rw-r--r-- | lispref/modes.texi | 1425 |
1 files changed, 0 insertions, 1425 deletions
diff --git a/lispref/modes.texi b/lispref/modes.texi deleted file mode 100644 index dda63c9c0e5..00000000000 --- a/lispref/modes.texi +++ /dev/null @@ -1,1425 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/modes -@node Modes, Documentation, Keymaps, Top -@chapter Major and Minor Modes -@cindex mode - - A @dfn{mode} is a set of definitions that customize Emacs and can be -turned on and off while you edit. There are two varieties of modes: -@dfn{major modes}, which are mutually exclusive and used for editing -particular kinds of text, and @dfn{minor modes}, which provide features -that users can enable individually. - - This chapter describes how to write both major and minor modes, how to -indicate them in the mode line, and how they run hooks supplied by the -user. For related topics such as keymaps and syntax tables, see -@ref{Keymaps}, and @ref{Syntax Tables}. - -@menu -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Hooks:: How to use hooks; how to write code that provides hooks. -@end menu - -@node Major Modes -@section Major Modes -@cindex major mode -@cindex Fundamental mode - - Major modes specialize Emacs for editing particular kinds of text. -Each buffer has only one major mode at a time. - - The least specialized major mode is called @dfn{Fundamental mode}. -This mode has no mode-specific definitions or variable settings, so each -Emacs command behaves in its default manner, and each option is in its -default state. All other major modes redefine various keys and options. -For example, Lisp Interaction mode provides special key bindings for -@key{LFD} (@code{eval-print-last-sexp}), @key{TAB} -(@code{lisp-indent-line}), and other keys. - - When you need to write several editing commands to help you perform a -specialized editing task, creating a new major mode is usually a good -idea. In practice, writing a major mode is easy (in contrast to -writing a minor mode, which is often difficult). - - If the new mode is similar to an old one, it is often unwise to modify -the old one to serve two purposes, since it may become harder to use and -maintain. Instead, copy and rename an existing major mode definition -and alter the copy---or define a @dfn{derived mode} (@pxref{Derived -Modes}). For example, Rmail Edit mode, which is in -@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to -Text mode except that it provides three additional commands. Its -definition is distinct from that of Text mode, but was derived from it. - - Rmail Edit mode is an example of a case where one piece of text is put -temporarily into a different major mode so it can be edited in a -different way (with ordinary Emacs commands rather than Rmail). In such -cases, the temporary major mode usually has a command to switch back to -the buffer's usual mode (Rmail mode, in this case). You might be -tempted to present the temporary redefinitions inside a recursive edit -and restore the usual ones when the user exits; but this is a bad idea -because it constrains the user's options when it is done in more than -one buffer: recursive edits must be exited most-recently-entered first. -Using alternative major modes avoids this limitation. @xref{Recursive -Editing}. - - The standard GNU Emacs Lisp library directory contains the code for -several major modes, in files including @file{text-mode.el}, -@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and -@file{rmail.el}. You can look at these libraries to see how modes are -written. Text mode is perhaps the simplest major mode aside from -Fundamental mode. Rmail mode is a complicated and specialized mode. - -@menu -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Example Major Modes:: Text mode and Lisp modes. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -@end menu - -@node Major Mode Conventions -@subsection Major Mode Conventions - - The code for existing major modes follows various coding conventions, -including conventions for local keymap and syntax table initialization, -global names, and hooks. Please follow these conventions when you -define a new major mode: - -@itemize @bullet -@item -Define a command whose name ends in @samp{-mode}, with no arguments, -that switches to the new mode in the current buffer. This command -should set up the keymap, syntax table, and local variables in an -existing buffer without changing the buffer's text. - -@item -Write a documentation string for this command that describes the -special commands available in this mode. @kbd{C-h m} -(@code{describe-mode}) in your mode will display this string. - -The documentation string may include the special documentation -substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and -@samp{\<@var{keymap}>}, that enable the documentation to adapt -automatically to the user's own key bindings. @xref{Keys in -Documentation}. - -@item -The major mode command should start by calling -@code{kill-all-local-variables}. This is what gets rid of the local -variables of the major mode previously in effect. - -@item -The major mode command should set the variable @code{major-mode} to the -major mode command symbol. This is how @code{describe-mode} discovers -which documentation to print. - -@item -The major mode command should set the variable @code{mode-name} to the -``pretty'' name of the mode, as a string. This appears in the mode -line. - -@item -@cindex functions in modes -Since all global names are in the same name space, all the global -variables, constants, and functions that are part of the mode should -have names that start with the major mode name (or with an abbreviation -of it if the name is long). @xref{Style Tips}. - -@item -@cindex keymaps in modes -The major mode should usually have its own keymap, which is used as the -local keymap in all buffers in that mode. The major mode function -should call @code{use-local-map} to install this local map. -@xref{Active Keymaps}, for more information. - -This keymap should be kept in a global variable named -@code{@var{modename}-mode-map}. Normally the library that defines the -mode sets this variable. - -@xref{Tips for Defining}, for advice about how to write the code to set -up the mode's keymap variable. - -@item -@cindex syntax tables in modes -The mode may have its own syntax table or may share one with other -related modes. If it has its own syntax table, it should store this in -a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax -Tables}. - -@item -If the mode handles a language that has a syntax for comments, it should -set the variables that define the comment syntax. @xref{Options for -Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. - -@item -@cindex abbrev tables in modes -The mode may have its own abbrev table or may share one with other -related modes. If it has its own abbrev table, it should store this in -a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev -Tables}. - -@item -@vindex font-lock-defaults -The mode should specify how to do highlighting for Font Lock mode, by -setting up a buffer-local value for the variable -@code{font-lock-defaults}. - -@item -@vindex imenu-generic-expression -@vindex imenu-create-index-function -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} or -@code{imenu-create-index-function}. - -@item -Use @code{defvar} to set mode-related variables, so that they are not -reinitialized if they already have a value. (Such reinitialization -could discard customizations made by the user.) - -@item -@cindex buffer-local variables in modes -To make a buffer-local binding for an Emacs customization variable, use -@code{make-local-variable} in the major mode command, not -@code{make-variable-buffer-local}. The latter function would make the -variable local to every buffer in which it is subsequently set, which -would affect buffers that do not use this mode. It is undesirable for a -mode to have such global effects. @xref{Buffer-Local Variables}. - -It's ok to use @code{make-variable-buffer-local}, if you wish, for a -variable used only within a single Lisp package. - -@item -@cindex mode hook -@cindex major mode hook -Each major mode should have a @dfn{mode hook} named -@code{@var{modename}-mode-hook}. The major mode command should run that -hook, with @code{run-hooks}, as the very last thing it -does. @xref{Hooks}. - -@item -The major mode command may also run the hooks of some more basic modes. -For example, @code{indented-text-mode} runs @code{text-mode-hook} as -well as @code{indented-text-mode-hook}. It may run these other hooks -immediately before the mode's own hook (that is, after everything else), -or it may run them earlier. - -@item -If something special should be done if the user switches a buffer from -this mode to any other major mode, the mode can set a local value for -@code{change-major-mode-hook}. - -@item -If this mode is appropriate only for specially-prepared text, then the -major mode command symbol should have a property named @code{mode-class} -with value @code{special}, put on as follows: - -@cindex @code{mode-class} property -@cindex @code{special} -@example -(put 'funny-mode 'mode-class 'special) -@end example - -@noindent -This tells Emacs that new buffers created while the current buffer has -Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, -and Buffer List use this feature. - -@item -If you want to make the new mode the default for files with certain -recognizable names, add an element to @code{auto-mode-alist} to select -the mode for those file names. If you define the mode command to -autoload, you should add this element in the same file that calls -@code{autoload}. Otherwise, it is sufficient to add the element in the -file that contains the mode definition. @xref{Auto Major Mode}. - -@item -@cindex @file{.emacs} customization -In the documentation, you should provide a sample @code{autoload} form -and an example of how to add to @code{auto-mode-alist}, that users can -include in their @file{.emacs} files. - -@item -@cindex mode loading -The top-level forms in the file defining the mode should be written so -that they may be evaluated more than once without adverse consequences. -Even if you never load the file more than once, someone else will. -@end itemize - -@defvar change-major-mode-hook -This normal hook is run by @code{kill-all-local-variables} before it -does anything else. This gives major modes a way to arrange for -something special to be done if the user switches to a different major -mode. For best results, make this variable buffer-local, so that it -will disappear after doing its job and will not interfere with the -subsequent major mode. @xref{Hooks}. -@end defvar - -@node Example Major Modes -@subsection Major Mode Examples - - Text mode is perhaps the simplest mode besides Fundamental mode. -Here are excerpts from @file{text-mode.el} that illustrate many of -the conventions listed above: - -@smallexample -@group -;; @r{Create mode-specific tables.} -(defvar text-mode-syntax-table nil - "Syntax table used while in text mode.") -@end group - -@group -(if text-mode-syntax-table - () ; @r{Do not change the table if it is already set up.} - (setq text-mode-syntax-table (make-syntax-table)) - (modify-syntax-entry ?\" ". " text-mode-syntax-table) - (modify-syntax-entry ?\\ ". " text-mode-syntax-table) - (modify-syntax-entry ?' "w " text-mode-syntax-table)) -@end group - -@group -(defvar text-mode-abbrev-table nil - "Abbrev table used while in text mode.") -(define-abbrev-table 'text-mode-abbrev-table ()) -@end group - -@group -(defvar text-mode-map nil) ; @r{Create a mode-specific keymap.} - -(if text-mode-map - () ; @r{Do not change the keymap if it is already set up.} - (setq text-mode-map (make-sparse-keymap)) - (define-key text-mode-map "\t" 'tab-to-tab-stop) - (define-key text-mode-map "\es" 'center-line) - (define-key text-mode-map "\eS" 'center-paragraph)) -@end group -@end smallexample - - Here is the complete major mode function definition for Text mode: - -@smallexample -@group -(defun text-mode () - "Major mode for editing text intended for humans to read. - Special commands: \\@{text-mode-map@} -@end group -@group -Turning on text-mode runs the hook `text-mode-hook'." - (interactive) - (kill-all-local-variables) -@end group -@group - (use-local-map text-mode-map) ; @r{This provides the local keymap.} - (setq mode-name "Text") ; @r{This name goes into the mode line.} - (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}} - ; @r{finds the doc string to print.} - (setq local-abbrev-table text-mode-abbrev-table) - (set-syntax-table text-mode-syntax-table) - (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} - ; @r{customize the mode with a hook.} -@end group -@end smallexample - -@cindex @file{lisp-mode.el} - The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp -Interaction mode) have more features than Text mode and the code is -correspondingly more complicated. Here are excerpts from -@file{lisp-mode.el} that illustrate how these modes are written. - -@cindex syntax table example -@smallexample -@group -;; @r{Create mode-specific table variables.} -(defvar lisp-mode-syntax-table nil "") -(defvar emacs-lisp-mode-syntax-table nil "") -(defvar lisp-mode-abbrev-table nil "") -@end group - -@group -(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table} - ; @r{if it is already set.} - (let ((i 0)) - (setq emacs-lisp-mode-syntax-table (make-syntax-table)) -@end group - -@group - ;; @r{Set syntax of chars up to 0 to class of chars that are} - ;; @r{part of symbol names but not words.} - ;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)} - (while (< i ?0) - (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table) - (setq i (1+ i))) - @dots{} -@end group -@group - ;; @r{Set the syntax for other characters.} - (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table) - (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table) - @dots{} -@end group -@group - (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table) - (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table) - @dots{})) -;; @r{Create an abbrev table for lisp-mode.} -(define-abbrev-table 'lisp-mode-abbrev-table ()) -@end group -@end smallexample - - Much code is shared among the three Lisp modes. The following -function sets various variables; it is called by each of the major Lisp -mode functions: - -@smallexample -@group -(defun lisp-mode-variables (lisp-syntax) - ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,} - ;; @r{and @code{t} in the other two Lisp modes.} - (cond (lisp-syntax - (if (not lisp-mode-syntax-table) - ;; @r{The Emacs Lisp mode syntax table always exists, but} - ;; @r{the Lisp Mode syntax table is created the first time a} - ;; @r{mode that needs it is called. This is to save space.} -@end group -@group - (progn (setq lisp-mode-syntax-table - (copy-syntax-table emacs-lisp-mode-syntax-table)) - ;; @r{Change some entries for Lisp mode.} - (modify-syntax-entry ?\| "\" " - lisp-mode-syntax-table) - (modify-syntax-entry ?\[ "_ " - lisp-mode-syntax-table) - (modify-syntax-entry ?\] "_ " - lisp-mode-syntax-table))) -@end group -@group - (set-syntax-table lisp-mode-syntax-table))) - (setq local-abbrev-table lisp-mode-abbrev-table) - @dots{}) -@end group -@end smallexample - - Functions such as @code{forward-paragraph} use the value of the -@code{paragraph-start} variable. Since Lisp code is different from -ordinary text, the @code{paragraph-start} variable needs to be set -specially to handle Lisp. Also, comments are indented in a special -fashion in Lisp and the Lisp modes need their own mode-specific -@code{comment-indent-function}. The code to set these variables is the -rest of @code{lisp-mode-variables}. - -@smallexample -@group - (make-local-variable 'paragraph-start) - ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}} - ;; @r{has them too, and removing those is a pain.} - (setq paragraph-start (concat "^$\\|" page-delimiter)) - @dots{} -@end group -@group - (make-local-variable 'comment-indent-function) - (setq comment-indent-function 'lisp-comment-indent)) -@end group -@end smallexample - - Each of the different Lisp modes has a slightly different keymap. For -example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other -Lisp modes do not. However, all Lisp modes have some commands in -common. The following function adds these common commands to a given -keymap. - -@smallexample -@group -(defun lisp-mode-commands (map) - (define-key map "\e\C-q" 'indent-sexp) - (define-key map "\177" 'backward-delete-char-untabify) - (define-key map "\t" 'lisp-indent-line)) -@end group -@end smallexample - - Here is an example of using @code{lisp-mode-commands} to initialize a -keymap, as part of the code for Emacs Lisp mode. First we declare a -variable with @code{defvar} to hold the mode-specific keymap. When this -@code{defvar} executes, it sets the variable to @code{nil} if it was -void. Then we set up the keymap if the variable is @code{nil}. - - This code avoids changing the keymap or the variable if it is already -set up. This lets the user customize the keymap. - -@smallexample -@group -(defvar emacs-lisp-mode-map () "") -(if emacs-lisp-mode-map - () - (setq emacs-lisp-mode-map (make-sparse-keymap)) - (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun) - (lisp-mode-commands emacs-lisp-mode-map)) -@end group -@end smallexample - - Finally, here is the complete major mode function definition for -Emacs Lisp mode. - -@smallexample -@group -(defun emacs-lisp-mode () - "Major mode for editing Lisp code to run in Emacs. -Commands: -Delete converts tabs to spaces as it moves back. -Blank lines separate paragraphs. Semicolons start comments. -\\@{emacs-lisp-mode-map@} -@end group -@group -Entry to this mode runs the hook `emacs-lisp-mode-hook'." - (interactive) - (kill-all-local-variables) - (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.} - (set-syntax-table emacs-lisp-mode-syntax-table) -@end group -@group - (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}} - ; @r{finds out what to describe.} - (setq mode-name "Emacs-Lisp") ; @r{This goes into the mode line.} - (lisp-mode-variables nil) ; @r{This defines various variables.} - (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a} - ; @r{hook to customize the mode.} -@end group -@end smallexample - -@node Auto Major Mode -@subsection How Emacs Chooses a Major Mode - - Based on information in the file name or in the file itself, Emacs -automatically selects a major mode for the new buffer when a file is -visited. - -@deffn Command fundamental-mode - Fundamental mode is a major mode that is not specialized for anything -in particular. Other major modes are defined in effect by comparison -with this one---their definitions say what to change, starting from -Fundamental mode. The @code{fundamental-mode} function does @emph{not} -run any hooks; you're not supposed to customize it. (If you want Emacs -to behave differently in Fundamental mode, change the @emph{global} -state of Emacs.) -@end deffn - -@deffn Command normal-mode &optional find-file -This function establishes the proper major mode and local variable -bindings for the current buffer. First it calls @code{set-auto-mode}, -then it runs @code{hack-local-variables} to parse, and bind or -evaluate as appropriate, any local variables. - -If the @var{find-file} argument to @code{normal-mode} is -non-@code{nil}, @code{normal-mode} assumes that the @code{find-file} -function is calling it. In this case, it may process a local variables -list at the end of the file and in the @samp{-*-} line. The variable -@code{enable-local-variables} controls whether to do so. - -If you run @code{normal-mode} interactively, the argument -@var{find-file} is normally @code{nil}. In this case, -@code{normal-mode} unconditionally processes any local variables list. -@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}, for the syntax of the local variables section of a file. - -@cindex file mode specification error -@code{normal-mode} uses @code{condition-case} around the call to the -major mode function, so errors are caught and reported as a @samp{File -mode specification error}, followed by the original error message. -@end deffn - -@defopt enable-local-variables -This variable controls processing of local variables lists in files -being visited. A value of @code{t} means process the local variables -lists unconditionally; @code{nil} means ignore them; anything else means -ask the user what to do for each file. The default value is @code{t}. -@end defopt - -@defvar ignored-local-variables -This variable holds a list of variables that should not be -set by a local variables list. Any value specified -for one of these variables is ignored. -@end defvar - -In addition to this list, any variable whose name has a non-@code{nil} -@code{risky-local-variable} property is also ignored. - -@defopt enable-local-eval -This variable controls processing of @samp{Eval:} in local variables -lists in files being visited. A value of @code{t} means process them -unconditionally; @code{nil} means ignore them; anything else means ask -the user what to do for each file. The default value is @code{maybe}. -@end defopt - -@defun set-auto-mode -@cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It may base its decision on the value of the @w{@samp{-*-}} -line, on the visited file name (using @code{auto-mode-alist}), on the -@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the -value of a local variable. However, this function does not look for -the @samp{mode:} local variable near the end of a file; the -@code{hack-local-variables} function does that. @xref{Choosing Modes, , -How Major Modes are Chosen, emacs, The GNU Emacs Manual}. -@end defun - -@defopt default-major-mode - This variable holds the default major mode for new buffers. The -standard value is @code{fundamental-mode}. - - If the value of @code{default-major-mode} is @code{nil}, Emacs uses -the (previously) current buffer's major mode for the major mode of a new -buffer. However, if the major mode symbol has a @code{mode-class} -property with value @code{special}, then it is not used for new buffers; -Fundamental mode is used instead. The modes that have this property are -those such as Dired and Rmail that are useful only with text that has -been specially prepared. -@end defopt - -@defun set-buffer-major-mode buffer -This function sets the major mode of @var{buffer} to the value of -@code{default-major-mode}. If that variable is @code{nil}, it uses -the current buffer's major mode (if that is suitable). - -The low-level primitives for creating buffers do not use this function, -but medium-level commands such as @code{switch-to-buffer} and -@code{find-file-noselect} use it whenever they create buffers. -@end defun - -@defvar initial-major-mode -@cindex @samp{*scratch*} -The value of this variable determines the major mode of the initial -@samp{*scratch*} buffer. The value should be a symbol that is a major -mode command name. The default value is @code{lisp-interaction-mode}. -@end defvar - -@defvar auto-mode-alist -This variable contains an association list of file name patterns -(regular expressions; @pxref{Regular Expressions}) and corresponding -major mode functions. Usually, the file name patterns test for -suffixes, such as @samp{.el} and @samp{.c}, but this need not be the -case. An ordinary element of the alist looks like @code{(@var{regexp} . -@var{mode-function})}. - -For example, - -@smallexample -@group -(("^/tmp/fol/" . text-mode) - ("\\.texinfo\\'" . texinfo-mode) - ("\\.texi\\'" . texinfo-mode) -@end group -@group - ("\\.el\\'" . emacs-lisp-mode) - ("\\.c\\'" . c-mode) - ("\\.h\\'" . c-mode) - @dots{}) -@end group -@end smallexample - -When you visit a file whose expanded file name (@pxref{File Name -Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the -corresponding @var{mode-function}. This feature enables Emacs to select -the proper major mode for most files. - -If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} -@var{function} t)}, then after calling @var{function}, Emacs searches -@code{auto-mode-alist} again for a match against the portion of the file -name that did not match before. - -This match-again feature is useful for uncompression packages: an entry -of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file -and then put the uncompressed file in the proper mode according to the -name sans @samp{.gz}. - -Here is an example of how to prepend several pattern pairs to -@code{auto-mode-alist}. (You might use this sort of expression in your -@file{.emacs} file.) - -@smallexample -@group -(setq auto-mode-alist - (append - ;; @r{File name starts with a dot.} - '(("/\\.[^/]*\\'" . fundamental-mode) - ;; @r{File name has no dot.} - ("[^\\./]*\\'" . fundamental-mode) - ;; @r{File name ends in @samp{.C}.} - ("\\.C\\'" . c++-mode)) - auto-mode-alist)) -@end group -@end smallexample -@end defvar - -@defvar interpreter-mode-alist -This variable specifes major modes to use for scripts that specify a -command interpreter in an @samp{#!} line. Its value is a list of -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 -@var{interpreter}. - -This variable is applicable only when the @code{auto-mode-alist} does -not indicate which major mode to use. -@end defvar - -@defun hack-local-variables &optional force - This function parses, and binds or evaluates as appropriate, any local -variables for the current buffer. - - The handling of @code{enable-local-variables} documented for -@code{normal-mode} actually takes place here. The argument @var{force} -usually comes from the argument @var{find-file} given to -@code{normal-mode}. -@end defun - -@node Mode Help -@subsection Getting Help about a Major Mode -@cindex mode help -@cindex help for major mode -@cindex documentation for major mode - - The @code{describe-mode} function is used to provide information -about major modes. It is normally called with @kbd{C-h m}. The -@code{describe-mode} function uses the value of @code{major-mode}, -which is why every major mode function needs to set the -@code{major-mode} variable. - -@deffn Command describe-mode -This function displays the documentation of the current major mode. - -The @code{describe-mode} function calls the @code{documentation} -function using the value of @code{major-mode} as an argument. Thus, it -displays the documentation string of the major mode function. -(@xref{Accessing Documentation}.) -@end deffn - -@defvar major-mode -This variable holds the symbol for the current buffer's major mode. -This symbol should have a function definition that is the command to -switch to that major mode. The @code{describe-mode} function uses the -documentation string of the function as the documentation of the major -mode. -@end defvar - -@node Derived Modes -@subsection Defining Derived Modes - - It's often useful to define a new major mode in terms of an existing -one. An easy way to do this is to use @code{define-derived-mode}. - -@defmac define-derived-mode variant parent name docstring body@dots{} -This construct defines @var{variant} as a major mode command, using -@var{name} as the string form of the mode name. - -The new command @var{variant} is defined to call the function -@var{parent}, then override certain aspects of that parent mode: - -@itemize @bullet -@item -The new mode has its own keymap, named @code{@var{variant}-map}. -@code{define-derived-mode} initializes this map to inherit from -@code{@var{parent}-map}, if it is not already set. - -@item -The new mode has its own syntax table, kept in the variable -@code{@var{variant}-syntax-table}. -@code{define-derived-mode} initializes this variable by copying -@code{@var{parent}-syntax-table}, if it is not already set. - -@item -The new mode has its own abbrev table, kept in the variable -@code{@var{variant}-abbrev-table}. -@code{define-derived-mode} initializes this variable by copying -@code{@var{parent}-abbrev-table}, if it is not already set. - -@item -The new mode has its own mode hook, @code{@var{variant}-hook}, -which it runs in standard fashion as the very last thing that it does. -(The new mode also runs the mode hook of @var{parent} as part -of calling @var{parent}.) -@end itemize - -In addition, you can specify how to override other aspects of -@var{parent} with @var{body}. The command @var{variant} -evaluates the forms in @var{body} after setting up all its usual -overrides, just before running @code{@var{variant}-hook}. - -The argument @var{docstring} specifies the documentation string for the -new mode. If you omit @var{docstring}, @code{define-derived-mode} -generates a documentation string. - -Here is a hypothetical example: - -@example -(define-derived-mode hypertext-mode - text-mode "Hypertext" - "Major mode for hypertext. -\\@{hypertext-mode-map@}" - (setq case-fold-search nil)) - -(define-key hypertext-mode-map - [down-mouse-3] 'do-hyper-link) -@end example -@end defmac - -@node Minor Modes -@section Minor Modes -@cindex minor mode - - A @dfn{minor mode} provides features that users may enable or disable -independently of the choice of major mode. Minor modes can be enabled -individually or in combination. Minor modes would be better named -``Generally available, optional feature modes'' except that such a name is -unwieldy. - - A minor mode is not usually a modification of single major mode. For -example, Auto Fill mode may be used in any major mode that permits text -insertion. To be general, a minor mode must be effectively independent -of the things major modes do. - - A minor mode is often much more difficult to implement than a major -mode. One reason is that you should be able to activate and deactivate -minor modes in any order. A minor mode should be able to have its -desired effect regardless of the major mode and regardless of the other -minor modes in effect. - - Often the biggest problem in implementing a minor mode is finding a -way to insert the necessary hook into the rest of Emacs. Minor mode -keymaps make this easier than it used to be. - -@menu -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -@end menu - -@node Minor Mode Conventions -@subsection Conventions for Writing Minor Modes -@cindex minor mode conventions -@cindex conventions for writing minor modes - - There are conventions for writing minor modes just as there are for -major modes. Several of the major mode conventions apply to minor -modes as well: those regarding the name of the mode initialization -function, the names of global symbols, and the use of keymaps and -other tables. - - In addition, there are several conventions that are specific to -minor modes. - -@itemize @bullet -@item -@cindex mode variable -Make a variable whose name ends in @samp{-mode} to represent the minor -mode. Its value should enable or disable the mode (@code{nil} to -disable; anything else to enable.) We call this the @dfn{mode -variable}. - -This variable is used in conjunction with the @code{minor-mode-alist} to -display the minor mode name in the mode line. It can also enable -or disable a minor mode keymap. Individual commands or hooks can also -check the variable's value. - -If you want the minor mode to be enabled separately in each buffer, -make the variable buffer-local. - -@item -Define a command whose name is the same as the mode variable. -Its job is to enable and disable the mode by setting the variable. - -The command should accept one optional argument. If the argument is -@code{nil}, it should toggle the mode (turn it on if it is off, and off -if it is on). Otherwise, it should turn the mode on if the argument is -a positive integer, a symbol other than @code{nil} or @code{-}, or a -list whose @sc{car} is such an integer or symbol; it should turn the -mode off otherwise. - -Here is an example taken from the definition of @code{transient-mark-mode}. -It shows the use of @code{transient-mark-mode} as a variable that enables or -disables the mode's behavior, and also shows the proper way to toggle, -enable or disable the minor mode based on the raw prefix argument value. - -@smallexample -@group -(setq transient-mark-mode - (if (null arg) (not transient-mark-mode) - (> (prefix-numeric-value arg) 0))) -@end group -@end smallexample - -@item -Add an element to @code{minor-mode-alist} for each minor mode -(@pxref{Mode Line Variables}). This element should be a list of the -following form: - -@smallexample -(@var{mode-variable} @var{string}) -@end smallexample - -Here @var{mode-variable} is the variable that controls enabling of the -minor mode, and @var{string} is a short string, starting with a space, -to represent the mode in the mode line. These strings must be short so -that there is room for several of them at once. - -When you add an element to @code{minor-mode-alist}, use @code{assq} to -check for an existing element, to avoid duplication. For example: - -@smallexample -@group -(or (assq 'leif-mode minor-mode-alist) - (setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist))) -@end group -@end smallexample -@end itemize - -@node Keymaps and Minor Modes -@subsection Keymaps and Minor Modes - - Each minor mode can have its own keymap, which is active when the mode -is enabled. To set up a keymap for a minor mode, add an element to the -alist @code{minor-mode-map-alist}. @xref{Active Keymaps}. - -@cindex @code{self-insert-command}, minor modes -One use of minor mode keymaps is to modify the behavior of certain -self-inserting characters so that they do something else as well as -self-insert. In general, this is the only way to do that, since the -facilities for customizing @code{self-insert-command} are limited to -special cases (designed for abbrevs and Auto Fill mode). (Do not try -substituting your own definition of @code{self-insert-command} for the -standard one. The editor command loop handles this function specially.) - -@node Mode Line Format -@section Mode Line Format -@cindex mode line - - Each Emacs window (aside from minibuffer windows) includes a mode line, -which displays status information about the buffer displayed in the -window. The mode line contains information about the buffer, such as its -name, associated file, depth of recursive editing, and the major and -minor modes. - - This section describes how the contents of the mode line are -controlled. It is in the chapter on modes because much of the -information displayed in the mode line relates to the enabled major and -minor modes. - - @code{mode-line-format} is a buffer-local variable that holds a -template used to display the mode line of the current buffer. All -windows for the same buffer use the same @code{mode-line-format} and -their mode lines appear the same (except for scrolling percentages and -line numbers). - - The mode line of a window is normally updated whenever a different -buffer is shown in the window, or when the buffer's modified-status -changes from @code{nil} to @code{t} or vice-versa. If you modify any of -the variables referenced by @code{mode-line-format} (@pxref{Mode Line -Variables}), you may want to force an update of the mode line so as to -display the new information. - -@c Emacs 19 feature -@defun force-mode-line-update -Force redisplay of the current buffer's mode line. -@end defun - - The mode line is usually displayed in inverse video; see -@code{mode-line-inverse-video} in @ref{Inverse Video}. - -@menu -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -@end menu - -@node Mode Line Data -@subsection The Data Structure of the Mode Line -@cindex mode line construct - - The mode line contents are controlled by a data structure of lists, -strings, symbols, and numbers kept in the buffer-local variable -@code{mode-line-format}. The data structure is called a @dfn{mode line -construct}, and it is built in recursive fashion out of simpler mode line -constructs. The same data structure is used for constructing -frame titles (@pxref{Frame Titles}). - -@defvar mode-line-format -The value of this variable is a mode line construct with overall -responsibility for the mode line format. The value of this variable -controls which other variables are used to form the mode line text, and -where they appear. -@end defvar - - A mode line construct may be as simple as a fixed string of text, but -it usually specifies how to use other variables to construct the text. -Many of these variables are themselves defined to have mode line -constructs as their values. - - The default value of @code{mode-line-format} incorporates the values -of variables such as @code{mode-name} and @code{minor-mode-alist}. -Because of this, very few modes need to alter @code{mode-line-format}. -For most purposes, it is sufficient to alter the variables referenced by -@code{mode-line-format}. - - A mode line construct may be a list, a symbol, or a string. If the -value is a list, each element may be a list, a symbol, or a string. - -@table @code -@cindex percent symbol in mode line -@item @var{string} -A string as a mode line construct is displayed verbatim in the mode line -except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%} -specify the field width for space filling on the right (i.e., the data -is left justified). @xref{%-Constructs}. - -@item @var{symbol} -A symbol as a mode line construct stands for its value. The value of -@var{symbol} is used as a mode line construct, in place of @var{symbol}. -However, the symbols @code{t} and @code{nil} are ignored; so is any -symbol whose value is void. - -There is one exception: if the value of @var{symbol} is a string, it is -displayed verbatim: the @code{%}-constructs are not recognized. - -@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{}) -A list whose first element is a string or list means to process all the -elements recursively and concatenate the results. This is the most -common form of mode line construct. - -@item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol is 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}. - -@item (@var{width} @var{rest}@dots{}) -A list whose first element is an integer specifies truncation or -padding of the results of @var{rest}. The remaining elements -@var{rest} are processed recursively as mode line constructs and -concatenated together. Then the result is space filled (if -@var{width} is positive) or truncated (to @minus{}@var{width} columns, -if @var{width} is negative) on the right. - -For example, the usual way to show what percentage of a buffer is above -the top of the window is to use a list like this: @code{(-3 "%p")}. -@end table - - If you do alter @code{mode-line-format} itself, the new value should -use the same variables that appear in the default value (@pxref{Mode -Line Variables}), rather than duplicating their contents or displaying -the information in another fashion. This way, customizations made by -the user or by Lisp programs (such as @code{display-time} and major -modes) via changes to those variables remain effective. - -@cindex Shell mode @code{mode-line-format} - Here is an example of a @code{mode-line-format} that might be -useful for @code{shell-mode}, since it contains the hostname and default -directory. - -@example -@group -(setq mode-line-format - (list "" - 'mode-line-modified - "%b--" -@end group - (getenv "HOST") ; @r{One element is not constant.} - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - 'mode-name - 'mode-line-process - 'minor-mode-alist - "%n" - ")%]----" -@group - '(line-number-mode "L%l--") - '(-3 . "%p") - "-%-")) -@end group -@end example - -@node Mode Line Variables -@subsection Variables Used in the Mode Line - - This section describes variables incorporated by the -standard value of @code{mode-line-format} into the text of the mode -line. There is nothing inherently special about these variables; any -other variables could have the same effects on the mode line if -@code{mode-line-format} were changed to use them. - -@defvar mode-line-modified -This variable holds the value of the mode-line construct that displays -whether the current buffer is modified. - -The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}. -This means that the mode line displays @samp{--**-} if the buffer is -modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if -the buffer is read only, and @samp{--%*--} if the buffer is read only -and modified. - -Changing this variable does not force an update of the mode line. -@end defvar - -@defvar mode-line-buffer-identification -This variable identifies the buffer being displayed in the window. Its -default value is @code{("%F: %17b")}, which means that it usually -displays @samp{Emacs:} followed by seventeen characters of the buffer -name. (In a terminal frame, it displays the frame name instead of -@samp{Emacs}; this has the effect of showing the frame number.) You may -want to change this in modes such as Rmail that do not behave like a -``normal'' Emacs. -@end defvar - -@defvar global-mode-string -This variable holds a mode line spec that appears in the mode line by -default, just after the buffer name. The command @code{display-time} -sets @code{global-mode-string} to refer to the variable -@code{display-time-string}, which holds a string containing the time and -load information. - -The @samp{%M} construct substitutes the value of -@code{global-mode-string}, but this is obsolete, since the variable is -included directly in the mode line. -@end defvar - -@defvar mode-name -This buffer-local variable holds the ``pretty'' name of the current -buffer's major mode. Each major mode should set this variable so that the -mode name will appear in the mode line. -@end defvar - -@defvar minor-mode-alist -This variable holds an association list whose elements specify how the -mode line should indicate that a minor mode is active. Each element of -the @code{minor-mode-alist} should be a two-element list: - -@example -(@var{minor-mode-variable} @var{mode-line-string}) -@end example - -More generally, @var{mode-line-string} can be any mode line spec. It -appears in the mode line when the value of @var{minor-mode-variable} is -non-@code{nil}, and not otherwise. These strings should begin with -spaces so that they don't run together. Conventionally, the -@var{minor-mode-variable} for a specific mode is set to a non-@code{nil} -value when that minor mode is activated. - -The default value of @code{minor-mode-alist} is: - -@example -@group -minor-mode-alist -@result{} ((vc-mode vc-mode) - (abbrev-mode " Abbrev") - (overwrite-mode overwrite-mode) - (auto-fill-function " Fill") - (defining-kbd-macro " Def") - (isearch-mode isearch-mode)) -@end group -@end example - -@code{minor-mode-alist} is not buffer-local. The variables mentioned -in the alist should be buffer-local if the minor mode can be enabled -separately in each buffer. -@end defvar - -@defvar mode-line-process -This buffer-local variable contains the mode line information on process -status in modes used for communicating with subprocesses. It is -displayed immediately following the major mode name, with no intervening -space. For example, its value in the @samp{*shell*} buffer is -@code{(":@: %s")}, which allows the shell to display its status along -with the major mode as: @samp{(Shell:@: run)}. Normally this variable -is @code{nil}. -@end defvar - -@defvar default-mode-line-format -This variable holds the default @code{mode-line-format} for buffers -that do not override it. This is the same as @code{(default-value -'mode-line-format)}. - -The default value of @code{default-mode-line-format} is: - -@example -@group -("" - mode-line-modified - mode-line-buffer-identification - " " - global-mode-string - " %[(" - mode-name -@end group -@group - mode-line-process - minor-mode-alist - "%n" - ")%]----" - (line-number-mode "L%l--") - (-3 . "%p") - "-%-") -@end group -@end example -@end defvar - -@defvar vc-mode -The variable @code{vc-mode}, local in each buffer, records whether the -buffer's visited file is maintained with version control, and, if so, -which kind. Its value is @code{nil} for no version control, or a string -that appears in the mode line. -@end defvar - -@node %-Constructs -@subsection @code{%}-Constructs in the Mode Line - - The following table lists the recognized @code{%}-constructs and what -they mean. In any construct except @samp{%%}, you can add a decimal -integer after the @samp{%} to specify how many characters to display. - -@table @code -@item %b -The current buffer name, obtained with the @code{buffer-name} function. -@xref{Buffer Names}. - -@item %f -The visited file name, obtained with the @code{buffer-file-name} -function. @xref{Buffer File Name}. - -@item %F -The name of the selected frame. - -@item %c -The current column number of point. - -@item %l -The current line number of point. - -@item %* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{-} otherwise. @xref{Buffer Modification}. - -@item %+ -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{-} otherwise. This differs from @samp{%*} only for a modified -read-only buffer. @xref{Buffer Modification}. - -@item %& -@samp{*} if the buffer is modified, and @samp{-} otherwise. - -@item %s -The status of the subprocess belonging to the current buffer, obtained with -@code{process-status}. @xref{Process Information}. - -@item %t -Whether the visited file is a text file or a binary file. (This is a -meaningful distinction only on certain operating systems.) - -@item %p -The percentage of the buffer text above the @strong{top} of window, or -@samp{Top}, @samp{Bottom} or @samp{All}. - -@item %P -The percentage of the buffer text that is above the @strong{bottom} of -the window (which includes the text visible in the window, as well as -the text above the top), plus @samp{Top} if the top of the buffer is -visible on screen; or @samp{Bottom} or @samp{All}. - -@item %n -@samp{Narrow} when narrowing is in effect; nothing otherwise (see -@code{narrow-to-region} in @ref{Narrowing}). - -@item %[ -An indication of the depth of recursive editing levels (not counting -minibuffer levels): one @samp{[} for each editing level. -@xref{Recursive Editing}. - -@item %] -One @samp{]} for each recursive editing level (not counting minibuffer -levels). - -@item %% -The character @samp{%}---this is how to include a literal @samp{%} in a -string in which @code{%}-constructs are allowed. - -@item %- -Dashes sufficient to fill the remainder of the mode line. -@end table - -The following two @code{%}-constructs are still supported, but they are -obsolete, since you can get the same results with the variables -@code{mode-name} and @code{global-mode-string}. - -@table @code -@item %m -The value of @code{mode-name}. - -@item %M -The value of @code{global-mode-string}. Currently, only -@code{display-time} modifies the value of @code{global-mode-string}. -@end table - -@node Hooks -@section Hooks -@cindex hooks - - A @dfn{hook} is a variable where you can store a function or functions -to be called on a particular occasion by an existing program. Emacs -provides hooks for the sake of customization. Most often, hooks are set -up in the @file{.emacs} file, but Lisp programs can set them also. -@xref{Standard Hooks}, for a list of standard hook variables. - - Most of the hooks in Emacs are @dfn{normal hooks}. These variables -contain lists of functions to be called with no arguments. When the -hook name ends in @samp{-hook}, that tells you it is normal. We try to -make all hooks normal, as much as possible, so that you can use them in -a uniform way. - - Every major mode function is supposed to run a normal hook called the -@dfn{mode hook} as the last step of initialization. This makes it easy -for a user to customize the behavior of the mode, by overriding the -local variable assignments already made by the mode. But hooks are used -in other contexts too. For example, the hook @code{suspend-hook} runs -just before Emacs suspends itself (@pxref{Suspending Emacs}). - - The recommended way to add a hook function to a normal hook is by -calling @code{add-hook} (see below). The hook functions may be any of -the valid kinds of functions that @code{funcall} accepts (@pxref{What Is -a Function}). Most normal hook variables are initially void; -@code{add-hook} knows how to deal with this. - - If the hook variable's name does not end with @samp{-hook}, that -indicates it is probably an abnormal hook; you should look at its -documentation to see how to use the hook properly. - - If the variable's name ends in @samp{-functions} or @samp{-hooks}, -then the value is a list of functions, but it is abnormal in that either -these functions are called with arguments or their values are used in -some way. You can use @code{add-hook} to add a function to the list, -but you must take care in writing the function. (A few of these -variables are actually normal hooks which were named before we -established the convention of using @samp{-hook} for them.) - - If the variable's name ends in @samp{-function}, then its value -is just a single function, not a list of functions. - - Here's an expression that uses a mode hook to turn on Auto Fill mode -when in Lisp Interaction mode: - -@example -(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) -@end example - - The next example shows how to use a hook to customize the way Emacs -formats C code. (People often have strong personal preferences for one -format or another.) Here the hook function is an anonymous lambda -expression. - -@cindex lambda expression in hook -@example -@group -(add-hook 'c-mode-hook - (function (lambda () - (setq c-indent-level 4 - c-argdecl-indent 0 - c-label-offset -4 -@end group -@group - c-continued-statement-indent 0 - c-brace-offset 0 - comment-column 40)))) - -(setq c++-mode-hook c-mode-hook) -@end group -@end example - - At the appropriate time, Emacs uses the @code{run-hooks} function to -run particular hooks. This function calls the hook functions that have -been added with @code{add-hook}. - -@defun run-hooks &rest hookvar -This function takes one or more hook variable names as arguments, and -runs each hook in turn. Each @var{hookvar} argument should be a symbol -that is a hook variable. These arguments are processed in the order -specified. - -If a hook variable has a non-@code{nil} value, that value may be a -function or a list of functions. If the value is a function (either a -lambda expression or a symbol with a function definition), it is -called. If it is a list, the elements are called, in order. -The hook functions are called with no arguments. - -For example, here's how @code{emacs-lisp-mode} runs its mode hook: - -@example -(run-hooks 'emacs-lisp-mode-hook) -@end example -@end defun - -@defun add-hook hook function &optional append local -This function is the handy way to add function @var{function} to hook -variable @var{hook}. The argument @var{function} may be any valid Lisp -function with the proper number of arguments. For example, - -@example -(add-hook 'text-mode-hook 'my-text-hook-function) -@end example - -@noindent -adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. - -You can use @code{add-hook} for abnormal hooks as well as for normal -hooks. - -It is best to design your hook functions so that the order in which they -are executed does not matter. Any dependence on the order is ``asking -for trouble.'' However, the order is predictable: normally, -@var{function} goes at the front of the hook list, so it will be -executed first (barring another @code{add-hook} call). - -If the optional argument @var{append} is non-@code{nil}, the new hook -function goes at the end of the hook list and will be executed last. - -If @var{local} is non-@code{nil}, that says to make the new hook -function local to the current buffer. Before you can do this, you must -make the hook itself buffer-local by calling @code{make-local-hook} -(@strong{not} @code{make-local-variable}). If the hook itself is not -buffer-local, then the value of @var{local} makes no difference---the -hook function is always global. -@end defun - -@defun remove-hook hook function &optional local -This function removes @var{function} from the hook variable @var{hook}. - -If @var{local} is non-@code{nil}, that says to remove @var{function} -from the local hook list instead of from the global hook list. If the -hook itself is not buffer-local, then the value of @var{local} makes no -difference. -@end defun - -@defun make-local-hook hook -This function makes the hook variable @code{hook} local to the current -buffer. When a hook variable is local, it can have local and global -hook functions, and @code{run-hooks} runs all of them. - -This function works by making @code{t} an element of the buffer-local -value. That serves as a flag to use the hook functions in the default -value of the hook variable as well as those in the local value. Since -@code{run-hooks} understands this flag, @code{make-local-hook} works -with all normal hooks. It works for only some non-normal hooks---those -whose callers have been updated to understand this meaning of @code{t}. - -Do not use @code{make-local-variable} directly for hook variables; it is -not sufficient. -@end defun |