comparison lispref/modes.texi @ 6451:8240c0b1d695

Initial revision
author Richard M. Stallman <rms@gnu.org>
date Mon, 21 Mar 1994 07:49:21 +0000
parents
children 6ba87aed7836
comparison
equal deleted inserted replaced
6450:1b17fc16d5c5 6451:8240c0b1d695
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/modes
6 @node Modes, Documentation, Keymaps, Top
7 @chapter Major and Minor Modes
8 @cindex mode
9
10 A @dfn{mode} is a set of definitions that customize Emacs and can be
11 turned on and off while you edit. There are two varieties of modes:
12 @dfn{major modes}, which are mutually exclusive and used for editing
13 particular kinds of text, and @dfn{minor modes}, which provide features
14 that users can enable individually.
15
16 This chapter describes how to write both major and minor modes, how to
17 indicate them in the mode line, and how they run hooks supplied by the
18 user. For related topics such as keymaps and syntax tables, see
19 @ref{Keymaps}, and @ref{Syntax Tables}.
20
21 @menu
22 * Major Modes:: Defining major modes.
23 * Minor Modes:: Defining minor modes.
24 * Mode Line Format:: Customizing the text that appears in the mode line.
25 * Hooks:: How to use hooks; how to write code that provides hooks.
26 @end menu
27
28 @node Major Modes
29 @section Major Modes
30 @cindex major mode
31 @cindex Fundamental mode
32
33 Major modes specialize Emacs for editing particular kinds of text.
34 Each buffer has only one major mode at a time.
35
36 The least specialized major mode is called @dfn{Fundamental mode}.
37 This mode has no mode-specific definitions or variable settings, so each
38 Emacs command behaves in its default manner, and each option is in its
39 default state. All other major modes redefine various keys and options.
40 For example, Lisp Interaction mode provides special key bindings for
41 @key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
42 (@code{lisp-indent-line}), and other keys.
43
44 When you need to write several editing commands to help you perform a
45 specialized editing task, creating a new major mode is usually a good
46 idea. In practice, writing a major mode is easy (in contrast to
47 writing a minor mode, which is often difficult).
48
49 If the new mode is similar to an old one, it is often unwise to modify
50 the old one to serve two purposes, since it may become harder to use and
51 maintain. Instead, copy and rename an existing major mode definition
52 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
53 Modes}). For example, Rmail Edit mode, which is in
54 @file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
55 Text mode except that it provides three additional commands. Its
56 definition is distinct from that of Text mode, but was derived from it.
57
58 Rmail Edit mode is an example of a case where one piece of text is put
59 temporarily into a different major mode so it can be edited in a
60 different way (with ordinary Emacs commands rather than Rmail). In such
61 cases, the temporary major mode usually has a command to switch back to
62 the buffer's usual mode (Rmail mode, in this case). You might be
63 tempted to present the temporary redefinitions inside a recursive edit
64 and restore the usual ones when the user exits; but this is a bad idea
65 because it constrains the user's options when it is done in more than
66 one buffer: recursive edits must be exited most-recently-entered first.
67 Using alternative major modes avoids this limitation. @xref{Recursive
68 Editing}.
69
70 The standard GNU Emacs Lisp library directory contains the code for
71 several major modes, in files including @file{text-mode.el},
72 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
73 @file{rmail.el}. You can look at these libraries to see how modes are
74 written. Text mode is perhaps the simplest major mode aside from
75 Fundamental mode. Rmail mode is a complicated and specialized mode.
76
77 @menu
78 * Major Mode Conventions:: Coding conventions for keymaps, etc.
79 * Example Major Modes:: Text mode and Lisp modes.
80 * Auto Major Mode:: How Emacs chooses the major mode automatically.
81 * Mode Help:: Finding out how to use a mode.
82 * Derived Modes:: Defining a new major mode based on another major
83 mode.
84 @end menu
85
86 @node Major Mode Conventions
87 @subsection Major Mode Conventions
88
89 The code for existing major modes follows various coding conventions,
90 including conventions for local keymap and syntax table initialization,
91 global names, and hooks. Please follow these conventions when you
92 define a new major mode:
93
94 @itemize @bullet
95 @item
96 Define a command whose name ends in @samp{-mode}, with no arguments,
97 that switches to the new mode in the current buffer. This command
98 should set up the keymap, syntax table, and local variables in an
99 existing buffer without changing the buffer's text.
100
101 @item
102 Write a documentation string for this command which describes the
103 special commands available in this mode. @kbd{C-h m}
104 (@code{describe-mode}) in your mode will display this string.
105
106 The documentation string may include the special documentation
107 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
108 @samp{\<@var{keymap}>}, that enable the documentation to adapt
109 automatically to the user's own key bindings. @xref{Keys in
110 Documentation}.
111
112 @item
113 The major mode command should start by calling
114 @code{kill-all-local-variables}. This is what gets rid of the local
115 variables of the major mode previously in effect.
116
117 @item
118 The major mode command should set the variable @code{major-mode} to the
119 major mode command symbol. This is how @code{describe-mode} discovers
120 which documentation to print.
121
122 @item
123 The major mode command should set the variable @code{mode-name} to the
124 ``pretty'' name of the mode, as a string. This appears in the mode
125 line.
126
127 @item
128 @cindex functions in modes
129 Since all global names are in the same name space, all the global
130 variables, constants, and functions that are part of the mode should
131 have names that start with the major mode name (or with an abbreviation
132 of it if the name is long). @xref{Style Tips}.
133
134 @item
135 @cindex keymaps in modes
136 The major mode should usually have its own keymap, which is used as the
137 local keymap in all buffers in that mode. The major mode function
138 should call @code{use-local-map} to install this local map.
139 @xref{Active Keymaps}, for more information.
140
141 This keymap should be kept in a global variable named
142 @code{@var{modename}-mode-map}. Normally the library that defines the
143 mode sets this variable. Use @code{defvar} to set the variable, so that
144 it is not reinitialized if it already has a value. (Such
145 reinitialization could discard customizations made by the user.)
146
147 @item
148 @cindex syntax tables in modes
149 The mode may have its own syntax table or may share one with other
150 related modes. If it has its own syntax table, it should store this in
151 a variable named @code{@var{modename}-mode-syntax-table}. The reasons
152 for this are the same as for using a keymap variable. @xref{Syntax
153 Tables}.
154
155 @item
156 @cindex abbrev tables in modes
157 The mode may have its own abbrev table or may share one with other
158 related modes. If it has its own abbrev table, it should store this in
159 a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
160 Tables}.
161
162 @item
163 @cindex buffer-local variables in modes
164 To make a buffer-local binding for an Emacs customization variable, use
165 @code{make-local-variable} in the major mode command, not
166 @code{make-variable-buffer-local}. The latter function would make the
167 variable local to every buffer in which it is subsequently set, which
168 would affect buffers that do not use this mode. It is undesirable for a
169 mode to have such global effects. @xref{Buffer-Local Variables}.
170
171 It's ok to use @code{make-variable-buffer-local}, if you wish, for a
172 variable used only within a single Lisp package.
173
174 @item
175 @cindex mode hook
176 @cindex major mode hook
177 Each major mode should have a @dfn{mode hook} named
178 @code{@var{modename}-mode-hook}. The major mode command should run that
179 hook, with @code{run-hooks}, as the very last thing it
180 does. @xref{Hooks}.
181
182 @item
183 The major mode command may also run the hooks of some more basic modes.
184 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
185 well as @code{indented-text-mode-hook}. It may run these other hooks
186 immediately before the mode's own hook (that is, after everything else),
187 or it may run them earlier.
188
189 @item
190 If something special should be done if the user switches a buffer from
191 this mode to any other major mode, the mode can set a local value for
192 @code{change-major-mode-hook}.
193
194 @item
195 If this mode is appropriate only for specially-prepared text, then the
196 major mode command symbol should have a property named @code{mode-class}
197 with value @code{special}, put on as follows:
198
199 @cindex @code{mode-class} property
200 @cindex @code{special}
201 @example
202 (put 'funny-mode 'mode-class 'special)
203 @end example
204
205 @noindent
206 This tells Emacs that new buffers created while the current buffer has
207 Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
208 and Buffer List use this feature.
209
210 @item
211 If you want to make the new mode the default for files with certain
212 recognizable names, add an element to @code{auto-mode-alist} to select
213 the mode for those file names. If you define the mode command to
214 autoload, you should add this element in the same file that calls
215 @code{autoload}. Otherwise, it is sufficient to add the element in the
216 file that contains the mode definition. @xref{Auto Major Mode}.
217
218 @item
219 @cindex @file{.emacs} customization
220 In the documentation, you should provide a sample @code{autoload} form
221 and an example of how to add to @code{auto-mode-alist}, that users can
222 include in their @file{.emacs} files.
223
224 @item
225 @cindex mode loading
226 The top level forms in the file defining the mode should be written so
227 that they may be evaluated more than once without adverse consequences.
228 Even if you never load the file more than once, someone else will.
229 @end itemize
230
231 @defvar change-major-mode-hook
232 This normal hook is run by @code{kill-all-local-variables} before it
233 does anything else. This gives major modes a way to arrange for
234 something special to be done if the user switches to a different major
235 mode. For best results, make this variable buffer-local, so that it
236 will disappear after doing its job and will not interfere with the
237 subsequent major mode.
238 @end defvar
239
240 @node Example Major Modes
241 @subsection Major Mode Examples
242
243 Text mode is perhaps the simplest mode besides Fundamental mode.
244 Here are excerpts from @file{text-mode.el} that illustrate many of
245 the conventions listed above:
246
247 @smallexample
248 @group
249 ;; @r{Create mode-specific tables.}
250 (defvar text-mode-syntax-table nil
251 "Syntax table used while in text mode.")
252 @end group
253
254 @group
255 (if text-mode-syntax-table
256 () ; @r{Do not change the table if it is already set up.}
257 (setq text-mode-syntax-table (make-syntax-table))
258 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
259 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
260 (modify-syntax-entry ?' "w " text-mode-syntax-table))
261 @end group
262
263 @group
264 (defvar text-mode-abbrev-table nil
265 "Abbrev table used while in text mode.")
266 (define-abbrev-table 'text-mode-abbrev-table ())
267 @end group
268
269 @group
270 (defvar text-mode-map nil) ; @r{Create a mode-specific keymap.}
271
272 (if text-mode-map
273 () ; @r{Do not change the keymap if it is already set up.}
274 (setq text-mode-map (make-sparse-keymap))
275 (define-key text-mode-map "\t" 'tab-to-tab-stop)
276 (define-key text-mode-map "\es" 'center-line)
277 (define-key text-mode-map "\eS" 'center-paragraph))
278 @end group
279 @end smallexample
280
281 Here is the complete major mode function definition for Text mode:
282
283 @smallexample
284 @group
285 (defun text-mode ()
286 "Major mode for editing text intended for humans to read.
287 Special commands: \\@{text-mode-map@}
288 @end group
289 @group
290 Turning on text-mode runs the hook `text-mode-hook'."
291 (interactive)
292 (kill-all-local-variables)
293 @end group
294 @group
295 (use-local-map text-mode-map) ; @r{This provides the local keymap.}
296 (setq mode-name "Text") ; @r{This name goes into the mode line.}
297 (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}}
298 ; @r{finds the doc string to print.}
299 (setq local-abbrev-table text-mode-abbrev-table)
300 (set-syntax-table text-mode-syntax-table)
301 (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
302 ; @r{customize the mode with a hook.}
303 @end group
304 @end smallexample
305
306 @cindex @file{lisp-mode.el}
307 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
308 Interaction mode) have more features than Text mode and the code is
309 correspondingly more complicated. Here are excerpts from
310 @file{lisp-mode.el} that illustrate how these modes are written.
311
312 @cindex syntax table example
313 @smallexample
314 @group
315 ;; @r{Create mode-specific table variables.}
316 (defvar lisp-mode-syntax-table nil "")
317 (defvar emacs-lisp-mode-syntax-table nil "")
318 (defvar lisp-mode-abbrev-table nil "")
319 @end group
320
321 @group
322 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
323 ; @r{if it is already set.}
324 (let ((i 0))
325 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
326 @end group
327
328 @group
329 ;; @r{Set syntax of chars up to 0 to class of chars that are}
330 ;; @r{part of symbol names but not words.}
331 ;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
332 (while (< i ?0)
333 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
334 (setq i (1+ i)))
335 @dots{}
336 @end group
337 @group
338 ;; @r{Set the syntax for other characters.}
339 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
340 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
341 @dots{}
342 @end group
343 @group
344 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
345 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
346 @dots{}))
347 ;; @r{Create an abbrev table for lisp-mode.}
348 (define-abbrev-table 'lisp-mode-abbrev-table ())
349 @end group
350 @end smallexample
351
352 Much code is shared among the three Lisp modes. The following
353 function sets various variables; it is called by each of the major Lisp
354 mode functions:
355
356 @smallexample
357 @group
358 (defun lisp-mode-variables (lisp-syntax)
359 ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
360 ;; @r{and @code{t} in the other two Lisp modes.}
361 (cond (lisp-syntax
362 (if (not lisp-mode-syntax-table)
363 ;; @r{The Emacs Lisp mode syntax table always exists, but}
364 ;; @r{the Lisp Mode syntax table is created the first time a}
365 ;; @r{mode that needs it is called. This is to save space.}
366 @end group
367 @group
368 (progn (setq lisp-mode-syntax-table
369 (copy-syntax-table emacs-lisp-mode-syntax-table))
370 ;; @r{Change some entries for Lisp mode.}
371 (modify-syntax-entry ?\| "\" "
372 lisp-mode-syntax-table)
373 (modify-syntax-entry ?\[ "_ "
374 lisp-mode-syntax-table)
375 (modify-syntax-entry ?\] "_ "
376 lisp-mode-syntax-table)))
377 @end group
378 @group
379 (set-syntax-table lisp-mode-syntax-table)))
380 (setq local-abbrev-table lisp-mode-abbrev-table)
381 @dots{})
382 @end group
383 @end smallexample
384
385 Functions such as @code{forward-paragraph} use the value of the
386 @code{paragraph-start} variable. Since Lisp code is different from
387 ordinary text, the @code{paragraph-start} variable needs to be set
388 specially to handle Lisp. Also, comments are indented in a special
389 fashion in Lisp and the Lisp modes need their own mode-specific
390 @code{comment-indent-function}. The code to set these variables is the
391 rest of @code{lisp-mode-variables}.
392
393 @smallexample
394 @group
395 (make-local-variable 'paragraph-start)
396 (setq paragraph-start (concat "^$\\|" page-delimiter))
397 @dots{}
398 @end group
399 @group
400 (make-local-variable 'comment-indent-function)
401 (setq comment-indent-function 'lisp-comment-indent))
402 @end group
403 @end smallexample
404
405 Each of the different Lisp modes has a slightly different keymap. For
406 example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
407 Lisp modes do not. However, all Lisp modes have some commands in
408 common. The following function adds these common commands to a given
409 keymap.
410
411 @smallexample
412 @group
413 (defun lisp-mode-commands (map)
414 (define-key map "\e\C-q" 'indent-sexp)
415 (define-key map "\177" 'backward-delete-char-untabify)
416 (define-key map "\t" 'lisp-indent-line))
417 @end group
418 @end smallexample
419
420 Here is an example of using @code{lisp-mode-commands} to initialize a
421 keymap, as part of the code for Emacs Lisp mode. First we declare a
422 variable with @code{defvar} to hold the mode-specific keymap. When this
423 @code{defvar} executes, it sets the variable to @code{nil} if it was
424 void. Then we set up the keymap if the variable is @code{nil}.
425
426 This code avoids changing the keymap or the variable if it is already
427 set up. This lets the user customize the keymap if he or she so
428 wishes.
429
430 @smallexample
431 @group
432 (defvar emacs-lisp-mode-map () "")
433 (if emacs-lisp-mode-map
434 ()
435 (setq emacs-lisp-mode-map (make-sparse-keymap))
436 (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
437 (lisp-mode-commands emacs-lisp-mode-map))
438 @end group
439 @end smallexample
440
441 Finally, here is the complete major mode function definition for
442 Emacs Lisp mode.
443
444 @smallexample
445 @group
446 (defun emacs-lisp-mode ()
447 "Major mode for editing Lisp code to run in Emacs.
448 Commands:
449 Delete converts tabs to spaces as it moves back.
450 Blank lines separate paragraphs. Semicolons start comments.
451 \\@{emacs-lisp-mode-map@}
452 @end group
453 @group
454 Entry to this mode runs the hook `emacs-lisp-mode-hook'."
455 (interactive)
456 (kill-all-local-variables)
457 (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.}
458 (set-syntax-table emacs-lisp-mode-syntax-table)
459 @end group
460 @group
461 (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}}
462 ; @r{finds out what to describe.}
463 (setq mode-name "Emacs-Lisp") ; @r{This goes into the mode line.}
464 (lisp-mode-variables nil) ; @r{This define various variables.}
465 (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a}
466 ; @r{hook to customize the mode.}
467 @end group
468 @end smallexample
469
470 @node Auto Major Mode
471 @subsection How Emacs Chooses a Major Mode
472
473 Based on information in the file name or in the file itself, Emacs
474 automatically selects a major mode for the new buffer when a file is
475 visited.
476
477 @deffn Command fundamental-mode
478 Fundamental mode is a major mode that is not specialized for anything
479 in particular. Other major modes are defined in effect by comparison
480 with this one---their definitions say what to change, starting from
481 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
482 run any hooks; you're not supposed to customize it. (If you want Emacs
483 to behave differently in Fundamental mode, change the @emph{global}
484 state of Emacs.)
485 @end deffn
486
487 @deffn Command normal-mode &optional find-file
488 This function establishes the proper major mode and local variable
489 bindings for the current buffer. First it calls @code{set-auto-mode},
490 then it runs @code{hack-local-variables} to parse, and bind or
491 evaluate as appropriate, any local variables.
492
493 If the @var{find-file} argument to @code{normal-mode} is
494 non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
495 function is calling it. In this case, it may process a local variables
496 list at the end of the file. The variable @code{enable-local-variables}
497 controls whether to do so.
498
499 If you run @code{normal-mode} interactively, the argument
500 @var{find-file} is normally @code{nil}. In this case,
501 @code{normal-mode} unconditionally processes any local variables list.
502 @xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
503 Manual}, for the syntax of the local variables section of a file.
504
505 @cindex file mode specification error
506 @code{normal-mode} uses @code{condition-case} around the call to the
507 major mode function, so errors are caught and reported as a @samp{File
508 mode specification error}, followed by the original error message.
509 @end deffn
510
511 @defopt enable-local-variables
512 This variable controls processing of local variables lists in files
513 being visited. A value of @code{t} means process the local variables
514 lists unconditionally; @code{nil} means ignore them; anything else means
515 ask the user what to do for each file. The default value is @code{t}.
516 @end defopt
517
518 @defopt enable-local-eval
519 This variable controls processing of @samp{Eval:} in local variables
520 lists in files being visited. A value of @code{t} means process them
521 unconditionally; @code{nil} means ignore them; anything else means ask
522 the user what to do for each file. The default value is @code{maybe}.
523 @end defopt
524
525 @defun set-auto-mode
526 @cindex visited file mode
527 This function selects the major mode that is appropriate for the
528 current buffer. It may base its decision on the value of the @w{@samp{-*-}}
529 line, on the visited file name (using @code{auto-mode-alist}), or on the
530 value of a local variable). However, this function does not look for
531 the @samp{mode:} local variable near the end of a file; the
532 @code{hack-local-variables} function does that. @xref{Choosing Modes, ,
533 How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
534 @end defun
535
536 @defopt default-major-mode
537 This variable holds the default major mode for new buffers. The
538 standard value is @code{fundamental-mode}.
539
540 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
541 the (previously) current buffer's major mode for the major mode of a new
542 buffer. However, if the major mode symbol has a @code{mode-class}
543 property with value @code{special}, then it is not used for new buffers;
544 Fundamental mode is used instead. The modes that have this property are
545 those such as Dired and Rmail that are useful only with text that has
546 been specially prepared.
547 @end defopt
548
549 @defvar initial-major-mode
550 @cindex @samp{*scratch*}
551 The value of this variable determines the major mode of the initial
552 @samp{*scratch*} buffer. The value should be a symbol that is a major
553 mode command name. The default value is @code{lisp-interaction-mode}.
554 @end defvar
555
556 @defvar auto-mode-alist
557 This variable contains an association list of file name patterns
558 (regular expressions; @pxref{Regular Expressions}) and corresponding
559 major mode functions. Usually, the file name patterns test for
560 suffixes, such as @samp{.el} and @samp{.c}, but this need not be the
561 case. An ordinary element of the alist looks like @code{(@var{regexp} .
562 @var{mode-function})}.
563
564 For example,
565
566 @smallexample
567 @group
568 (("^/tmp/fol/" . text-mode)
569 ("\\.texinfo$" . texinfo-mode)
570 ("\\.texi$" . texinfo-mode)
571 @end group
572 @group
573 ("\\.el$" . emacs-lisp-mode)
574 ("\\.c$" . c-mode)
575 ("\\.h$" . c-mode)
576 @dots{})
577 @end group
578 @end smallexample
579
580 When you visit a file whose expanded file name (@pxref{File Name
581 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
582 corresponding @var{mode-function}. This feature enables Emacs to select
583 the proper major mode for most files.
584
585 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
586 @var{function} t)}, then after calling @var{function}, Emacs searches
587 @code{auto-mode-alist} again for a match against the portion of the file
588 name that did not match before.
589
590 This match-again feature is useful for uncompression packages: an entry
591 of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
592 and then put the uncompressed file in the proper mode according to the
593 name sans @samp{.gz}.
594
595 Here is an example of how to prepend several pattern pairs to
596 @code{auto-mode-alist}. (You might use this sort of expression in your
597 @file{.emacs} file.)
598
599 @smallexample
600 @group
601 (setq auto-mode-alist
602 (append
603 ;; @r{Filename starts with a dot.}
604 '(("/\\.[^/]*$" . fundamental-mode)
605 ;; @r{Filename has no dot.}
606 ("[^\\./]*$" . fundamental-mode)
607 ("\\.C$" . c++-mode))
608 auto-mode-alist))
609 @end group
610 @end smallexample
611 @end defvar
612
613 @defvar interpreter-mode-alist
614 This variable specifes major modes to use for scripts that specify a
615 command interpreter in an @samp{!#} line. Its value is a list of
616 elements of the form @code{(@var{interpreter} . @var{mode})}; for
617 example, @code{("perl" . perl-mode)} is one element present by default.
618 The element says to use mode @var{mode} if the file specifies
619 @var{interpreter}.
620
621 This variable is applicable only when the file name doesn't indicate
622 which major mode to use.
623 @end defvar
624
625 @defun hack-local-variables &optional force
626 This function parses, and binds or evaluates as appropriate, any local
627 variables for the current buffer.
628
629 The handling of @code{enable-local-variables} documented for
630 @code{normal-mode} actually takes place here. The argument @var{force}
631 reflects the argument @var{find-file} given to @code{normal-mode}.
632 @end defun
633
634 @node Mode Help
635 @subsection Getting Help about a Major Mode
636 @cindex mode help
637 @cindex help for major mode
638 @cindex documentation for major mode
639
640 The @code{describe-mode} function is used to provide information
641 about major modes. It is normally called with @kbd{C-h m}. The
642 @code{describe-mode} function uses the value of @code{major-mode},
643 which is why every major mode function needs to set the
644 @code{major-mode} variable.
645
646 @deffn Command describe-mode
647 This function displays the documentation of the current major mode.
648
649 The @code{describe-mode} function calls the @code{documentation}
650 function using the value of @code{major-mode} as an argument. Thus, it
651 displays the documentation string of the major mode function.
652 (@xref{Accessing Documentation}.)
653 @end deffn
654
655 @defvar major-mode
656 This variable holds the symbol for the current buffer's major mode.
657 This symbol should have a function definition which is the command to
658 switch to that major mode. The @code{describe-mode} function uses the
659 documentation string of this symbol as the documentation of the major
660 mode.
661 @end defvar
662
663 @node Derived Modes
664 @subsection Defining Derived Modes
665
666 It's often useful to define a new major mode in terms of an existing
667 one. An easy way to do this is to use @code{define-derived-mode}.
668
669 @defmac define-derived-mode variant parent name doc body@dots{}
670 This construct defines @var{variant} as a major mode command, using
671 @var{name} as the string form of the mode which.
672
673 The definition of the command is to call the function @var{parent}, then
674 override certain aspects of that parent mode:
675
676 @itemize @bullet
677 @item
678 The new mode has its own keymap, named @code{@var{variant}-map}.
679 @code{define-derived-mode} initializes this map to inherit from
680 @code{@var{parent}-map}, if it is not already set.
681
682 @item
683 The new mode has its own syntax table, taken from the variable
684 @code{@var{variant}-syntax-table}.
685 @code{define-derived-mode} initializes this variable by copying
686 @code{@var{parent}-syntax-table}, if it is not already set.
687
688 @item
689 The new mode has its own abbrev table, taken from the variable
690 @code{@var{variant}-abbrev-table}.
691 @code{define-derived-mode} initializes this variable by copying
692 @code{@var{parent}-abbrev-table}, if it is not already set.
693
694 @item
695 The new mode has its own mode hook, @code{@var{variant}-hook},
696 which it runs in standard fashion as the very last thing that it does.
697 (The new mode also runs the mode hook of @var{parent} as part
698 of calling @var{parent}.)
699 @end itemize
700
701 In addition, you can specify how to override other aspects of
702 @var{parent-mode} with @var{body}. The command @var{variant}
703 evaluates the forms in @var{body} after setting up all its usual
704 overrides, just before running @code{@var{variant}-hook}.
705
706 The argument @var{docstring} specifies the documentation string for the
707 new mode. If you omit @var{docstring}, @code{define-derived-mode}
708 generates a documentation string.
709
710 Here is a hypothetical example:
711
712 @example
713 (define-derived-mode hypertext-mode
714 text-mode "Hypertext"
715 "Major mode for hypertext.
716 \\@{hypertext-mode-map@}"
717 (setq case-fold-search nil))
718
719 (define-key hypertext-mode-map
720 [down-mouse-3] 'do-hyper-link)
721 @end example
722 @end defmac
723
724 @node Minor Modes
725 @section Minor Modes
726 @cindex minor mode
727
728 A @dfn{minor mode} provides features that users may enable or disable
729 independently of the choice of major mode. Minor modes can be enabled
730 individually or in combination. Minor modes would be better named
731 ``Generally available, optional feature modes'' except that such a name is
732 unwieldy.
733
734 A minor mode is not usually a modification of single major mode. For
735 example, Auto Fill mode may be used in any major mode that permits text
736 insertion. To be general, a minor mode must be effectively independent
737 of the things major modes do.
738
739 A minor mode is often much more difficult to implement than a major
740 mode. One reason is that you should be able to activate and deactivate
741 minor modes in any order.
742
743 and restore the environment of the major mode to the state it was in
744 before the minor mode was activated.
745
746 Often the biggest problem in implementing a minor mode is finding a
747 way to insert the necessary hook into the rest of Emacs. Minor mode
748 keymaps make this easier in Emacs 19 than it used to be.
749
750 @menu
751 * Minor Mode Conventions:: Tips for writing a minor mode.
752 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
753 @end menu
754
755 @node Minor Mode Conventions
756 @subsection Conventions for Writing Minor Modes
757 @cindex minor mode conventions
758 @cindex conventions for writing minor modes
759
760 There are conventions for writing minor modes just as there are for
761 major modes. Several of the major mode conventions apply to minor
762 modes as well: those regarding the name of the mode initialization
763 function, the names of global symbols, and the use of keymaps and
764 other tables.
765
766 In addition, there are several conventions that are specific to
767 minor modes.
768
769 @itemize @bullet
770 @item
771 @cindex mode variable
772 Make a variable whose name ends in @samp{-mode} to represent the minor
773 mode. Its value should enable or disable the mode (@code{nil} to
774 disable; anything else to enable.) We call this the @dfn{mode
775 variable}.
776
777 This variable is used in conjunction with the @code{minor-mode-alist} to
778 display the minor mode name in the mode line. It can also enable
779 or disable a minor mode keymap. Individual commands or hooks can also
780 check the variable's value.
781
782 If you want the minor mode to be enabled separately in each buffer,
783 make the variable buffer-local.
784
785 @item
786 Define a command whose name is the same as the mode variable.
787 Its job is to enable and disable the mode by setting the variable.
788
789 The command should accept one optional argument. If the argument is
790 @code{nil}, it should toggle the mode (turn it on if it is off, and off
791 if it is on). Otherwise, it should turn the mode on if the argument is
792 a positive integer, a symbol other than @code{nil} or @code{-}, or a
793 list whose @sc{car} is such an integer or symbol; it should turn the
794 mode off otherwise.
795
796 Here is an example taken from the definition of @code{overwrite-mode}.
797 It shows the use of @code{overwrite-mode} as a variable which enables or
798 disables the mode's behavior.
799
800 @smallexample
801 @group
802 (setq overwrite-mode
803 (if (null arg) (not overwrite-mode)
804 (> (prefix-numeric-value arg) 0)))
805 @end group
806 @end smallexample
807
808 @item
809 Add an element to @code{minor-mode-alist} for each minor mode
810 (@pxref{Mode Line Variables}). This element should be a list of the
811 following form:
812
813 @smallexample
814 (@var{mode-variable} @var{string})
815 @end smallexample
816
817 Here @var{mode-variable} is the variable that controls enablement of the
818 minor mode, and @var{string} is a short string, starting with a space,
819 to represent the mode in the mode line. These strings must be short so
820 that there is room for several of them at once.
821
822 When you add an element to @code{minor-mode-alist}, use @code{assq} to
823 check for an existing element, to avoid duplication. For example:
824
825 @smallexample
826 @group
827 (or (assq 'leif-mode minor-mode-alist)
828 (setq minor-mode-alist
829 (cons '(leif-mode " Leif") minor-mode-alist)))
830 @end group
831 @end smallexample
832 @end itemize
833
834 @node Keymaps and Minor Modes
835 @subsection Keymaps and Minor Modes
836
837 As of Emacs version 19, each minor mode can have its own keymap which is
838 active when the mode is enabled. @xref{Active Keymaps}. To set up a
839 keymap for a minor mode, add an element to the alist
840 @code{minor-mode-map-alist}.
841
842 @cindex @code{self-insert-command}, minor modes
843 One use of minor mode keymaps is to modify the behavior of certain
844 self-inserting characters so that they do something else as well as
845 self-insert. In general, this is the only way to do that, since the
846 facilities for customizing @code{self-insert-command} are limited to
847 special cases (designed for abbrevs and Auto Fill mode). (Do not try
848 substituting your own definition of @code{self-insert-command} for the
849 standard one. The editor command loop handles this function specially.)
850
851 @defvar minor-mode-map-alist
852 This variable is an alist of elements that look like this:
853
854 @example
855 (@var{variable} . @var{keymap})
856 @end example
857
858 @noindent
859 where @var{variable} is the variable which indicates whether the minor
860 mode is enabled, and @var{keymap} is the keymap. The keymap
861 @var{keymap} is active whenever @var{variable} has a non-@code{nil}
862 value.
863
864 Note that elements of @code{minor-mode-map-alist} do not have the same
865 structure as elements of @code{minor-mode-alist}. The map must be the
866 @sc{cdr} of the element; a list with the map as the second element will
867 not do.
868
869 What's more, the keymap itself must appear in the @sc{cdr}. It does not
870 work to store a variable in the @sc{cdr} and make the map the value of
871 that variable.
872
873 When more than one minor mode keymap is active, their order of priority
874 is the order of @code{minor-mode-map-alist}. But you should design
875 minor modes so that they don't interfere with each other. If you do
876 this properly, the order will not matter.
877 @end defvar
878
879 @node Mode Line Format
880 @section Mode Line Format
881 @cindex mode line
882
883 Each Emacs window (aside from minibuffer windows) includes a mode line
884 which displays status information about the buffer displayed in the
885 window. The mode line contains information about the buffer such as its
886 name, associated file, depth of recursive editing, and the major and
887 minor modes of the buffer.
888
889 This section describes how the contents of the mode line are
890 controlled. It is in the chapter on modes because much of the
891 information displayed in the mode line relates to the enabled major and
892 minor modes.
893
894 @code{mode-line-format} is a buffer-local variable that holds a
895 template used to display the mode line of the current buffer. All
896 windows for the same buffer use the same @code{mode-line-format} and the
897 mode lines will appear the same (except for scrolling percentages and
898 line numbers).
899
900 The mode line of a window is normally updated whenever a different
901 buffer is shown in the window, or when the buffer's modified-status
902 changes from @code{nil} to @code{t} or vice-versa. If you modify any of
903 the variables referenced by @code{mode-line-format}, you may want to
904 force an update of the mode line so as to display the new information.
905
906 @c Emacs 19 feature
907 @defun force-mode-line-update
908 Force redisplay of the current buffer's mode line.
909 @end defun
910
911 The mode line is usually displayed in inverse video; see
912 @code{mode-line-inverse-video} in @ref{Inverse Video}.
913
914 @menu
915 * Mode Line Data:: The data structure that controls the mode line.
916 * Mode Line Variables:: Variables used in that data structure.
917 * %-Constructs:: Putting information into a mode line.
918 @end menu
919
920 @node Mode Line Data
921 @subsection The Data Structure of the Mode Line
922 @cindex mode line construct
923
924 The mode line contents are controlled by a data structure of lists,
925 strings, symbols and numbers kept in the buffer-local variable
926 @code{mode-line-format}. The data structure is called a @dfn{mode line
927 construct}, and it is built in recursive fashion out of simpler mode line
928 constructs.
929
930 @defvar mode-line-format
931 The value of this variable is a mode line construct with overall
932 responsibility for the mode line format. The value of this variable
933 controls which other variables are used to form the mode line text, and
934 where they appear.
935 @end defvar
936
937 A mode line construct may be as simple as a fixed string of text, but
938 it usually specifies how to use other variables to construct the text.
939 Many of these variables are themselves defined to have mode line
940 constructs as their values.
941
942 The default value of @code{mode-line-format} incorporates the values
943 of variables such as @code{mode-name} and @code{minor-mode-alist}.
944 Because of this, very few modes need to alter @code{mode-line-format}.
945 For most purposes, it is sufficient to alter the variables referenced by
946 @code{mode-line-format}.
947
948 A mode line construct may be a list, cons cell, symbol, or string. If
949 the value is a list, each element may be a list, a cons cell, a symbol,
950 or a string.
951
952 @table @code
953 @cindex percent symbol in mode line
954 @item @var{string}
955 A string as a mode line construct is displayed verbatim in the mode line
956 except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%}
957 specify the field width for space filling on the right (i.e., the data
958 is left justified). @xref{%-Constructs}.
959
960 @item @var{symbol}
961 A symbol as a mode line construct stands for its value. The value of
962 @var{symbol} is used in place of @var{symbol} unless @var{symbol} is
963 @code{t} or @code{nil}, or is void, in which case @var{symbol} is
964 ignored.
965
966 There is one exception: if the value of @var{symbol} is a string, it is
967 processed verbatim in that the @code{%}-constructs are not recognized.
968
969 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
970 A list whose first element is a string or list, means to concatenate all
971 the elements. This is the most common form of mode line construct.
972
973 @item (@var{symbol} @var{then} @var{else})
974 A list whose first element is a symbol is a conditional. Its meaning
975 depends on the value of @var{symbol}. If the value is non-@code{nil},
976 the second element of the list (@var{then}) is processed recursively as
977 a mode line element. But if the value of @var{symbol} is @code{nil},
978 the third element of the list (if there is one) is processed
979 recursively.
980
981 @item (@var{width} @var{rest}@dots{})
982 A list whose first element is an integer specifies truncation or
983 padding of the results of @var{rest}. The remaining elements
984 @var{rest} are processed recursively as mode line constructs and
985 concatenated together. Then the result is space filled (if
986 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
987 if @var{width} is negative) on the right.
988
989 For example, the usual way to show what percentage of a buffer is above
990 the top of the window is to use a list like this: @code{(-3 . "%p")}.
991 @end table
992
993 If you do alter @code{mode-line-format} itself, the new value should
994 use all the same variables that are used by the default value, rather
995 than duplicating their contents or displaying the information in another
996 fashion. This way, customizations made by the user, by libraries (such
997 as @code{display-time}) and by major modes via changes to those
998 variables remain effective.
999
1000 @cindex Shell mode @code{mode-line-format}
1001 Here is an example of a @code{mode-line-format} that might be
1002 useful for @code{shell-mode} since it contains the hostname and default
1003 directory.
1004
1005 @example
1006 @group
1007 (setq mode-line-format
1008 (list ""
1009 'mode-line-modified
1010 "%b--"
1011 @end group
1012 (getenv "HOST") ; @r{One element is not constant.}
1013 ":"
1014 'default-directory
1015 " "
1016 'global-mode-string
1017 " %[(" 'mode-name
1018 'minor-mode-alist
1019 "%n"
1020 'mode-line-process
1021 ")%]----"
1022 @group
1023 (line-number-mode "L%l--")
1024 '(-3 . "%p")
1025 "-%-"))
1026 @end group
1027 @end example
1028
1029 @node Mode Line Variables
1030 @subsection Variables Used in the Mode Line
1031
1032 This section describes variables incorporated by the
1033 standard value of @code{mode-line-format} into the text of the mode
1034 line. There is nothing inherently special about these variables; any
1035 other variables could have the same effects on the mode line if
1036 @code{mode-line-format} were changed to use them.
1037
1038 @defvar mode-line-modified
1039 This variable holds the value of the mode-line construct that displays
1040 whether the current buffer is modified.
1041
1042 The default value of @code{mode-line-modified} is
1043 @code{("--%1*%1*-")}. This means that the mode line displays
1044 @samp{--**-} if the buffer is modified, @samp{-----} if the buffer is
1045 not modified, and @samp{--%%-} if the buffer is read only.
1046
1047 Changing this variable does not force an update of the mode line.
1048 @end defvar
1049
1050 @defvar mode-line-buffer-identification
1051 This variable identifies the buffer being displayed in the window.
1052 Its default value is @samp{Emacs: %17b}, which means that it displays
1053 @samp{Emacs:} followed by the buffer name. You may want to change this
1054 in modes such as Rmail that do not behave like a ``normal'' Emacs.
1055 @end defvar
1056
1057 @defvar global-mode-string
1058 This variable holds a mode line spec that appears in the mode line by
1059 default, just after the buffer name. The command @code{display-time}
1060 sets @code{global-mode-string} to refer to the variable
1061 @code{display-time-string}, which holds a string containing the time and
1062 load information.
1063
1064 The @samp{%M} construct substitutes the value of
1065 @code{global-mode-string}, but this is obsolete, since the variable is
1066 included directly in the mode line.
1067 @end defvar
1068
1069 @defvar mode-name
1070 This buffer-local variable holds the ``pretty'' name of the current
1071 buffer's major mode. Each major mode should set this variable so that the
1072 mode name will appear in the mode line.
1073 @end defvar
1074
1075 @defvar minor-mode-alist
1076 This variable holds an association list whose elements specify how the
1077 mode line should indicate that a minor mode is active. Each element of
1078 the @code{minor-mode-alist} should be a two-element list:
1079
1080 @example
1081 (@var{minor-mode-variable} @var{mode-line-string})
1082 @end example
1083
1084 More generally, @var{mode-line-string} can be any mode line spec. It
1085 appears in the mode line when the value of @var{minor-mode-variable} is
1086 non-@code{nil}, and not otherwise. These strings should begin with
1087 spaces so that they don't run together. Conventionally, the
1088 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
1089 value when that minor mode is activated.
1090
1091 The default value of @code{minor-mode-alist} is:
1092
1093 @example
1094 @group
1095 minor-mode-alist
1096 @result{} ((abbrev-mode " Abbrev")
1097 (overwrite-mode " Ovwrt")
1098 (auto-fill-function " Fill")
1099 (defining-kbd-macro " Def"))
1100 @end group
1101 @end example
1102
1103 @noindent
1104 (In earlier Emacs versions, @code{auto-fill-function} was called
1105 @code{auto-fill-hook}.)
1106
1107 @code{minor-mode-alist} is not buffer-local. The variables mentioned
1108 in the alist should be buffer-local if the minor mode can be enabled
1109 separately in each buffer.
1110 @end defvar
1111
1112 @defvar mode-line-process
1113 This buffer-local variable contains the mode line information on process
1114 status in modes used for communicating with subprocesses. It is
1115 displayed immediately following the major mode name, with no intervening
1116 space. For example, its value in the @samp{*shell*} buffer is
1117 @code{(":@: %s")}, which allows the shell to display its status along
1118 with the major mode as: @samp{(Shell:@: run)}. Normally this variable
1119 is @code{nil}.
1120 @end defvar
1121
1122 @defvar default-mode-line-format
1123 This variable holds the default @code{mode-line-format} for buffers
1124 that do not override it. This is the same as @code{(default-value
1125 'mode-line-format)}.
1126
1127 The default value of @code{default-mode-line-format} is:
1128
1129 @example
1130 @group
1131 (""
1132 mode-line-modified
1133 mode-line-buffer-identification
1134 " "
1135 global-mode-string
1136 " %[("
1137 mode-name
1138 @end group
1139 @group
1140 minor-mode-alist
1141 "%n"
1142 mode-line-process
1143 ")%]----"
1144 (-3 . "%p")
1145 "-%-")
1146 @end group
1147 @end example
1148 @end defvar
1149
1150 @node %-Constructs
1151 @subsection @code{%}-Constructs in the Mode Line
1152
1153 The following table lists the recognized @code{%}-constructs and what
1154 they mean.
1155
1156 @table @code
1157 @item %b
1158 The current buffer name, obtained with the @code{buffer-name} function.
1159 @xref{Buffer Names}.
1160
1161 @item %f
1162 The visited file name, obtained with the @code{buffer-file-name}
1163 function. @xref{Buffer File Name}.
1164
1165 @item %*
1166 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
1167 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
1168 @samp{-} otherwise. @xref{Buffer Modification}.
1169
1170 @item %+
1171 @samp{*} if the buffer is modified, and otherwise @samp{-}.
1172
1173 @item %s
1174 The status of the subprocess belonging to the current buffer, obtained with
1175 @code{process-status}. @xref{Process Information}.
1176
1177 @item %p
1178 The percent of the buffer above the @strong{top} of window, or
1179 @samp{Top}, @samp{Bottom} or @samp{All}.
1180
1181 @item %P
1182 The percentage of the buffer text that is above the @strong{bottom} of
1183 the window (which includes the text visible in the window, as well as
1184 the text above the top), plus @samp{Top} if the top of the buffer is
1185 visible on screen; or @samp{Bottom} or @samp{All}.
1186
1187 @item %n
1188 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
1189 @code{narrow-to-region} in @ref{Narrowing}).
1190
1191 @item %[
1192 An indication of the depth of recursive editing levels (not counting
1193 minibuffer levels): one @samp{[} for each editing level.
1194 @xref{Recursive Editing}.
1195
1196 @item %]
1197 One @samp{]} for each recursive editing level (not counting minibuffer
1198 levels).
1199
1200 @item %%
1201 The character @samp{%}---this is how to include a literal @samp{%} in a
1202 string in which @code{%}-constructs are allowed.
1203
1204 @item %-
1205 Dashes sufficient to fill the remainder of the mode line.
1206 @end table
1207
1208 The following two @code{%}-constructs are still supported, but they are
1209 obsolete, since you can get the same results with the variables
1210 @code{mode-name} and @code{global-mode-string}.
1211
1212 @table @code
1213 @item %m
1214 The value of @code{mode-name}.
1215
1216 @item %M
1217 The value of @code{global-mode-string}. Currently, only
1218 @code{display-time} modifies the value of @code{global-mode-string}.
1219 @end table
1220
1221 @node Hooks
1222 @section Hooks
1223 @cindex hooks
1224
1225 A @dfn{hook} is a variable where you can store a function or functions
1226 to be called on a particular occasion by an existing program. Emacs
1227 provides hooks for the sake of customization. Most often, hooks are set
1228 up in the @file{.emacs} file, but Lisp programs can set them also.
1229 @xref{Standard Hooks}, for a list of standard hook variables.
1230
1231 Most of the hooks in Emacs are @dfn{normal hooks}. These variables
1232 contain lists of functions to be called with no arguments. The reason
1233 most hooks are normal hooks is so that you can use them in a uniform
1234 way. You can always tell when a hook is a normal hook, because its
1235 name ends in @samp{-hook}.
1236
1237 The recommended way to add a hook function to a normal hook is by
1238 calling @code{add-hook} (see below). The hook functions may be any of
1239 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
1240 a Function}). Most normal hook variables are initially void;
1241 @code{add-hook} knows how to deal with this.
1242
1243 As for abnormal hooks, those whose names end in @samp{-function} have
1244 a value which is a single function. Those whose names end in
1245 @samp{-hooks} have a value which is a list of functions. Any hook which
1246 is abnormal is abnormal because a normal hook won't do the job; either
1247 the functions are called with arguments, or their values are meaningful.
1248 The name shows you that the hook is abnormal and that you should look at
1249 its documentation string to see how to use it properly.
1250
1251 Most major modes run hooks as the last step of initialization. This
1252 makes it easy for a user to customize the behavior of the mode, by
1253 overriding the local variable assignments already made by the mode. But
1254 hooks are used in other contexts too. For example, the hook
1255 @code{suspend-hook} runs just before Emacs suspends itself
1256 (@pxref{Suspending Emacs}).
1257
1258 Here's an expression you can put in your @file{.emacs} file to turn on
1259 Auto Fill mode when in Lisp Interaction mode:
1260
1261 @example
1262 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
1263 @end example
1264
1265 The next example shows how to use a hook to customize the way Emacs
1266 formats C code. (People often have strong personal preferences for one
1267 format or another.) Here the hook function is an anonymous lambda
1268 expression.
1269
1270 @cindex lambda expression in hook
1271 @example
1272 @group
1273 (add-hook 'c-mode-hook
1274 (function (lambda ()
1275 (setq c-indent-level 4
1276 c-argdecl-indent 0
1277 c-label-offset -4
1278 @end group
1279 @group
1280 c-continued-statement-indent 0
1281 c-brace-offset 0
1282 comment-column 40))))
1283
1284 (setq c++-mode-hook c-mode-hook)
1285 @end group
1286 @end example
1287
1288 Finally, here is an example of how to use the Text mode hook to
1289 provide a customized mode line for buffers in Text mode, displaying the
1290 default directory in addition to the standard components of the
1291 mode line. (This may cause the mode line to run out of space if you
1292 have very long file names or display the time and load.)
1293
1294 @example
1295 @group
1296 (add-hook 'text-mode-hook
1297 (function (lambda ()
1298 (setq mode-line-format
1299 '(mode-line-modified
1300 "Emacs: %14b"
1301 " "
1302 @end group
1303 default-directory
1304 " "
1305 global-mode-string
1306 "%[("
1307 mode-name
1308 minor-mode-alist
1309 @group
1310 "%n"
1311 mode-line-process
1312 ") %]---"
1313 (-3 . "%p")
1314 "-%-")))))
1315 @end group
1316 @end example
1317
1318 At the appropriate time, Emacs uses the @code{run-hooks} function to
1319 run particular hooks. This function calls the hook functions you have
1320 added with @code{add-hooks}.
1321
1322 @defun run-hooks &rest hookvar
1323 This function takes one or more hook variable names as arguments, and
1324 runs each hook in turn. Each @var{hookvar} argument should be a symbol
1325 that is a hook variable. These arguments are processed in the order
1326 specified.
1327
1328 If a hook variable has a non-@code{nil} value, that value may be a
1329 function or a list of functions. If the value is a function (either a
1330 lambda expression or a symbol with a function definition), it is
1331 called. If it is a list, the elements are called, in order.
1332 The hook functions are called with no arguments.
1333
1334 For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
1335
1336 @example
1337 (run-hooks 'emacs-lisp-mode-hook)
1338 @end example
1339 @end defun
1340
1341 @defun add-hook hook function &optional append
1342 This function is the handy way to add function @var{function} to hook
1343 variable @var{hook}. For example,
1344
1345 @example
1346 (add-hook 'text-mode-hook 'my-text-hook-function)
1347 @end example
1348
1349 @noindent
1350 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
1351
1352 It is best to design your hook functions so that the order in which they
1353 are executed does not matter. Any dependence on the order is ``asking
1354 for trouble.'' However, the order is predictable: normally,
1355 @var{function} goes at the front of the hook list, so it will be
1356 executed first (barring another @code{add-hook} call).
1357
1358 If the optional argument @var{append} is non-@code{nil}, the new hook
1359 function goes at the end of the hook list and will be executed last.
1360 @end defun
1361
1362 @defun remove-hook hook function
1363 This function removes @var{function} from the hook variable @var{hook}.
1364 @end defun