6451
|
1 @c -*-texinfo-*-
|
|
2 @c This is part of the GNU Emacs Lisp Reference Manual.
|
27189
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
|
|
4 @c Free Software Foundation, Inc.
|
6451
|
5 @c See the file elisp.texi for copying conditions.
|
|
6 @setfilename ../info/modes
|
|
7 @node Modes, Documentation, Keymaps, Top
|
|
8 @chapter Major and Minor Modes
|
|
9 @cindex mode
|
|
10
|
|
11 A @dfn{mode} is a set of definitions that customize Emacs and can be
|
|
12 turned on and off while you edit. There are two varieties of modes:
|
|
13 @dfn{major modes}, which are mutually exclusive and used for editing
|
|
14 particular kinds of text, and @dfn{minor modes}, which provide features
|
|
15 that users can enable individually.
|
|
16
|
|
17 This chapter describes how to write both major and minor modes, how to
|
|
18 indicate them in the mode line, and how they run hooks supplied by the
|
|
19 user. For related topics such as keymaps and syntax tables, see
|
|
20 @ref{Keymaps}, and @ref{Syntax Tables}.
|
|
21
|
|
22 @menu
|
|
23 * Major Modes:: Defining major modes.
|
|
24 * Minor Modes:: Defining minor modes.
|
|
25 * Mode Line Format:: Customizing the text that appears in the mode line.
|
21007
|
26 * Imenu:: How a mode can provide a menu
|
|
27 of definitions in the buffer.
|
|
28 * Font Lock Mode:: How modes can highlight text according to syntax.
|
6451
|
29 * Hooks:: How to use hooks; how to write code that provides hooks.
|
|
30 @end menu
|
|
31
|
|
32 @node Major Modes
|
|
33 @section Major Modes
|
|
34 @cindex major mode
|
|
35 @cindex Fundamental mode
|
|
36
|
|
37 Major modes specialize Emacs for editing particular kinds of text.
|
|
38 Each buffer has only one major mode at a time.
|
|
39
|
|
40 The least specialized major mode is called @dfn{Fundamental mode}.
|
|
41 This mode has no mode-specific definitions or variable settings, so each
|
|
42 Emacs command behaves in its default manner, and each option is in its
|
|
43 default state. All other major modes redefine various keys and options.
|
|
44 For example, Lisp Interaction mode provides special key bindings for
|
21682
|
45 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
|
6451
|
46 (@code{lisp-indent-line}), and other keys.
|
|
47
|
|
48 When you need to write several editing commands to help you perform a
|
|
49 specialized editing task, creating a new major mode is usually a good
|
|
50 idea. In practice, writing a major mode is easy (in contrast to
|
|
51 writing a minor mode, which is often difficult).
|
|
52
|
|
53 If the new mode is similar to an old one, it is often unwise to modify
|
|
54 the old one to serve two purposes, since it may become harder to use and
|
|
55 maintain. Instead, copy and rename an existing major mode definition
|
|
56 and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
|
|
57 Modes}). For example, Rmail Edit mode, which is in
|
25875
|
58 @file{emacs/lisp/mail/rmailedit.el}, is a major mode that is very similar to
|
|
59 Text mode except that it provides two additional commands. Its
|
|
60 definition is distinct from that of Text mode, but uses that of Text mode.
|
6451
|
61
|
28603
|
62 Even if the new mode is not an obvious derivative of any other mode,
|
39793
1d5b7d31671f
Recommend the use of define-derived-mode (and nil argument).
Stefan Monnier <monnier@iro.umontreal.ca>
diff
changeset
|
63 it is convenient to use @code{define-derived-mode} with a @code{nil}
|
1d5b7d31671f
Recommend the use of define-derived-mode (and nil argument).
Stefan Monnier <monnier@iro.umontreal.ca>
diff
changeset
|
64 parent argument, since it automatically enforces the most important
|
1d5b7d31671f
Recommend the use of define-derived-mode (and nil argument).
Stefan Monnier <monnier@iro.umontreal.ca>
diff
changeset
|
65 coding conventions for you.
|
28603
|
66
|
21682
|
67 Rmail Edit mode offers an example of changing the major mode
|
|
68 temporarily for a buffer, so it can be edited in a different way (with
|
22252
|
69 ordinary Emacs commands rather than Rmail commands). In such cases, the
|
25751
|
70 temporary major mode usually provides a command to switch back to the
|
21682
|
71 buffer's usual mode (Rmail mode, in this case). You might be tempted to
|
|
72 present the temporary redefinitions inside a recursive edit and restore
|
|
73 the usual ones when the user exits; but this is a bad idea because it
|
|
74 constrains the user's options when it is done in more than one buffer:
|
|
75 recursive edits must be exited most-recently-entered first. Using an
|
|
76 alternative major mode avoids this limitation. @xref{Recursive
|
6451
|
77 Editing}.
|
|
78
|
25751
|
79 The standard GNU Emacs Lisp library directory tree contains the code
|
|
80 for several major modes, in files such as @file{text-mode.el},
|
6451
|
81 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
|
25875
|
82 @file{rmail.el}. They are found in various subdirectories of the
|
|
83 @file{lisp} directory. You can study these libraries to see how modes
|
|
84 are written. Text mode is perhaps the simplest major mode aside from
|
6451
|
85 Fundamental mode. Rmail mode is a complicated and specialized mode.
|
|
86
|
|
87 @menu
|
|
88 * Major Mode Conventions:: Coding conventions for keymaps, etc.
|
|
89 * Example Major Modes:: Text mode and Lisp modes.
|
|
90 * Auto Major Mode:: How Emacs chooses the major mode automatically.
|
|
91 * Mode Help:: Finding out how to use a mode.
|
|
92 * Derived Modes:: Defining a new major mode based on another major
|
|
93 mode.
|
|
94 @end menu
|
|
95
|
|
96 @node Major Mode Conventions
|
|
97 @subsection Major Mode Conventions
|
|
98
|
|
99 The code for existing major modes follows various coding conventions,
|
|
100 including conventions for local keymap and syntax table initialization,
|
|
101 global names, and hooks. Please follow these conventions when you
|
38200
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
102 define a new major mode.
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
103
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
104 This list of conventions is only partial, because each major mode
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
105 should aim for consistency in general with other Emacs major modes.
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
106 This makes Emacs as a whole more coherent. It is impossible to list
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
107 here all the possible points where this issue might come up; if the
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
108 Emacs developers point out an area where your major mode deviates from
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
109 the usual conventions, please make it compatible.
|
6451
|
110
|
|
111 @itemize @bullet
|
|
112 @item
|
|
113 Define a command whose name ends in @samp{-mode}, with no arguments,
|
|
114 that switches to the new mode in the current buffer. This command
|
21682
|
115 should set up the keymap, syntax table, and buffer-local variables in an
|
|
116 existing buffer, without changing the buffer's contents.
|
6451
|
117
|
|
118 @item
|
7253
|
119 Write a documentation string for this command that describes the
|
6451
|
120 special commands available in this mode. @kbd{C-h m}
|
|
121 (@code{describe-mode}) in your mode will display this string.
|
|
122
|
|
123 The documentation string may include the special documentation
|
|
124 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
|
24934
|
125 @samp{\<@var{keymap}>}, which enable the documentation to adapt
|
6451
|
126 automatically to the user's own key bindings. @xref{Keys in
|
|
127 Documentation}.
|
|
128
|
|
129 @item
|
|
130 The major mode command should start by calling
|
21682
|
131 @code{kill-all-local-variables}. This is what gets rid of the
|
|
132 buffer-local variables of the major mode previously in effect.
|
6451
|
133
|
|
134 @item
|
|
135 The major mode command should set the variable @code{major-mode} to the
|
|
136 major mode command symbol. This is how @code{describe-mode} discovers
|
|
137 which documentation to print.
|
|
138
|
|
139 @item
|
|
140 The major mode command should set the variable @code{mode-name} to the
|
21682
|
141 ``pretty'' name of the mode, as a string. This string appears in the
|
|
142 mode line.
|
6451
|
143
|
|
144 @item
|
|
145 @cindex functions in modes
|
|
146 Since all global names are in the same name space, all the global
|
|
147 variables, constants, and functions that are part of the mode should
|
|
148 have names that start with the major mode name (or with an abbreviation
|
17278
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
149 of it if the name is long). @xref{Coding Conventions}.
|
6451
|
150
|
|
151 @item
|
38200
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
152 In a major mode for editing some kind of structured text, such as a
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
153 programming language, indentation of text according to structure is
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
154 probably useful. So the mode should set @code{indent-line-function}
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
155 to a suitable function, and probably customize other variables
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
156 for indentation.
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
157
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
158 @item
|
6451
|
159 @cindex keymaps in modes
|
|
160 The major mode should usually have its own keymap, which is used as the
|
21682
|
161 local keymap in all buffers in that mode. The major mode command should
|
|
162 call @code{use-local-map} to install this local map. @xref{Active
|
|
163 Keymaps}, for more information.
|
6451
|
164
|
21682
|
165 This keymap should be stored permanently in a global variable named
|
6451
|
166 @code{@var{modename}-mode-map}. Normally the library that defines the
|
7253
|
167 mode sets this variable.
|
6451
|
168
|
12803
|
169 @xref{Tips for Defining}, for advice about how to write the code to set
|
|
170 up the mode's keymap variable.
|
|
171
|
6451
|
172 @item
|
17278
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
173 The key sequences bound in a major mode keymap should usually start with
|
21682
|
174 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
|
17278
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
175 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
176 characters are reserved for minor modes, and ordinary letters are
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
177 reserved for users.
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
178
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
179 It is reasonable for a major mode to rebind a key sequence with a
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
180 standard meaning, if it implements a command that does ``the same job''
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
181 in a way that fits the major mode better. For example, a major mode for
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
182 editing a programming language might redefine @kbd{C-M-a} to ``move to
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
183 the beginning of a function'' in a way that works better for that
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
184 language.
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
185
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
186 Major modes such as Dired or Rmail that do not allow self-insertion of
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
187 text can reasonably redefine letters and other printing characters as
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
188 editing commands. Dired and Rmail both do this.
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
189
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
190 @item
|
38161
|
191 Major modes must not define @key{RET} to do anything other than insert
|
|
192 a newline. The command to insert a newline and then indent is
|
38200
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
193 @kbd{C-j}. Please keep this distinction uniform for all major modes.
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
194
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
195 @item
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
196 Major modes should not alter options that are primary a matter of user
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
197 preference, such as whether Auto-Fill mode is enabled. Leave this to
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
198 each user to decide. However, a major mode should customize other
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
199 variables so that Auto-Fill mode will work usefully @emph{if} the user
|
6c286c714f74
(Major Mode Conventions): Say not to change meaning of RET, and not to
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
200 decides to use it.
|
38161
|
201
|
|
202 @item
|
6451
|
203 @cindex syntax tables in modes
|
|
204 The mode may have its own syntax table or may share one with other
|
|
205 related modes. If it has its own syntax table, it should store this in
|
7253
|
206 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax
|
6451
|
207 Tables}.
|
|
208
|
|
209 @item
|
16432
|
210 If the mode handles a language that has a syntax for comments, it should
|
|
211 set the variables that define the comment syntax. @xref{Options for
|
|
212 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}.
|
|
213
|
|
214 @item
|
6451
|
215 @cindex abbrev tables in modes
|
|
216 The mode may have its own abbrev table or may share one with other
|
|
217 related modes. If it has its own abbrev table, it should store this in
|
|
218 a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev
|
|
219 Tables}.
|
|
220
|
|
221 @item
|
16432
|
222 The mode should specify how to do highlighting for Font Lock mode, by
|
|
223 setting up a buffer-local value for the variable
|
21682
|
224 @code{font-lock-defaults} (@pxref{Font Lock Mode}).
|
16432
|
225
|
|
226 @item
|
|
227 The mode should specify how Imenu should find the definitions or
|
|
228 sections of a buffer, by setting up a buffer-local value for the
|
|
229 variable @code{imenu-generic-expression} or
|
21682
|
230 @code{imenu-create-index-function} (@pxref{Imenu}).
|
16432
|
231
|
|
232 @item
|
21682
|
233 Use @code{defvar} or @code{defcustom} to set mode-related variables, so
|
|
234 that they are not reinitialized if they already have a value. (Such
|
|
235 reinitialization could discard customizations made by the user.)
|
7253
|
236
|
|
237 @item
|
6451
|
238 @cindex buffer-local variables in modes
|
|
239 To make a buffer-local binding for an Emacs customization variable, use
|
|
240 @code{make-local-variable} in the major mode command, not
|
|
241 @code{make-variable-buffer-local}. The latter function would make the
|
|
242 variable local to every buffer in which it is subsequently set, which
|
|
243 would affect buffers that do not use this mode. It is undesirable for a
|
|
244 mode to have such global effects. @xref{Buffer-Local Variables}.
|
|
245
|
36347
|
246 With rare exceptions, the only reasonable way to use
|
25875
|
247 @code{make-variable-buffer-local} in a Lisp package is for a variable
|
|
248 which is used only within that package. Using it on a variable used by
|
|
249 other packages would interfere with them.
|
6451
|
250
|
|
251 @item
|
|
252 @cindex mode hook
|
|
253 @cindex major mode hook
|
|
254 Each major mode should have a @dfn{mode hook} named
|
|
255 @code{@var{modename}-mode-hook}. The major mode command should run that
|
|
256 hook, with @code{run-hooks}, as the very last thing it
|
17278
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
257 does. @xref{Hooks}.
|
6451
|
258
|
|
259 @item
|
|
260 The major mode command may also run the hooks of some more basic modes.
|
|
261 For example, @code{indented-text-mode} runs @code{text-mode-hook} as
|
|
262 well as @code{indented-text-mode-hook}. It may run these other hooks
|
|
263 immediately before the mode's own hook (that is, after everything else),
|
|
264 or it may run them earlier.
|
|
265
|
|
266 @item
|
|
267 If something special should be done if the user switches a buffer from
|
21007
|
268 this mode to any other major mode, this mode can set up a buffer-local
|
21682
|
269 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
|
6451
|
270
|
|
271 @item
|
|
272 If this mode is appropriate only for specially-prepared text, then the
|
|
273 major mode command symbol should have a property named @code{mode-class}
|
|
274 with value @code{special}, put on as follows:
|
|
275
|
|
276 @cindex @code{mode-class} property
|
|
277 @cindex @code{special}
|
|
278 @example
|
|
279 (put 'funny-mode 'mode-class 'special)
|
|
280 @end example
|
|
281
|
|
282 @noindent
|
25751
|
283 This tells Emacs that new buffers created while the current buffer is in
|
6451
|
284 Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
|
|
285 and Buffer List use this feature.
|
|
286
|
|
287 @item
|
|
288 If you want to make the new mode the default for files with certain
|
|
289 recognizable names, add an element to @code{auto-mode-alist} to select
|
|
290 the mode for those file names. If you define the mode command to
|
|
291 autoload, you should add this element in the same file that calls
|
|
292 @code{autoload}. Otherwise, it is sufficient to add the element in the
|
|
293 file that contains the mode definition. @xref{Auto Major Mode}.
|
|
294
|
|
295 @item
|
|
296 In the documentation, you should provide a sample @code{autoload} form
|
|
297 and an example of how to add to @code{auto-mode-alist}, that users can
|
25875
|
298 include in their init files (@pxref{Init File}).
|
6451
|
299
|
|
300 @item
|
|
301 @cindex mode loading
|
7253
|
302 The top-level forms in the file defining the mode should be written so
|
6451
|
303 that they may be evaluated more than once without adverse consequences.
|
|
304 Even if you never load the file more than once, someone else will.
|
|
305 @end itemize
|
|
306
|
|
307 @node Example Major Modes
|
|
308 @subsection Major Mode Examples
|
|
309
|
|
310 Text mode is perhaps the simplest mode besides Fundamental mode.
|
|
311 Here are excerpts from @file{text-mode.el} that illustrate many of
|
|
312 the conventions listed above:
|
|
313
|
|
314 @smallexample
|
|
315 @group
|
|
316 ;; @r{Create mode-specific tables.}
|
|
317 (defvar text-mode-syntax-table nil
|
|
318 "Syntax table used while in text mode.")
|
|
319 @end group
|
|
320
|
|
321 @group
|
|
322 (if text-mode-syntax-table
|
|
323 () ; @r{Do not change the table if it is already set up.}
|
|
324 (setq text-mode-syntax-table (make-syntax-table))
|
|
325 (modify-syntax-entry ?\" ". " text-mode-syntax-table)
|
|
326 (modify-syntax-entry ?\\ ". " text-mode-syntax-table)
|
|
327 (modify-syntax-entry ?' "w " text-mode-syntax-table))
|
|
328 @end group
|
|
329
|
|
330 @group
|
|
331 (defvar text-mode-abbrev-table nil
|
|
332 "Abbrev table used while in text mode.")
|
|
333 (define-abbrev-table 'text-mode-abbrev-table ())
|
|
334 @end group
|
|
335
|
|
336 @group
|
25875
|
337 (defvar text-mode-map nil ; @r{Create a mode-specific keymap.}
|
|
338 "Keymap for Text mode.
|
|
339 Many other modes, such as Mail mode, Outline mode and Indented Text mode,
|
|
340 inherit all the commands defined in this map.")
|
6451
|
341
|
|
342 (if text-mode-map
|
|
343 () ; @r{Do not change the keymap if it is already set up.}
|
|
344 (setq text-mode-map (make-sparse-keymap))
|
25875
|
345 (define-key text-mode-map "\e\t" 'ispell-complete-word)
|
22138
|
346 (define-key text-mode-map "\t" 'indent-relative)
|
6451
|
347 (define-key text-mode-map "\es" 'center-line)
|
|
348 (define-key text-mode-map "\eS" 'center-paragraph))
|
|
349 @end group
|
|
350 @end smallexample
|
|
351
|
|
352 Here is the complete major mode function definition for Text mode:
|
|
353
|
|
354 @smallexample
|
|
355 @group
|
|
356 (defun text-mode ()
|
25950
|
357 "Major mode for editing text intended for humans to read...
|
6451
|
358 Special commands: \\@{text-mode-map@}
|
|
359 @end group
|
|
360 @group
|
|
361 Turning on text-mode runs the hook `text-mode-hook'."
|
|
362 (interactive)
|
|
363 (kill-all-local-variables)
|
21682
|
364 (use-local-map text-mode-map)
|
|
365 @end group
|
|
366 @group
|
|
367 (setq local-abbrev-table text-mode-abbrev-table)
|
|
368 (set-syntax-table text-mode-syntax-table)
|
6451
|
369 @end group
|
|
370 @group
|
21682
|
371 (make-local-variable 'paragraph-start)
|
|
372 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
|
|
373 (make-local-variable 'paragraph-separate)
|
|
374 (setq paragraph-separate paragraph-start)
|
25875
|
375 (make-local-variable 'indent-line-function)
|
|
376 (setq indent-line-function 'indent-relative-maybe)
|
21682
|
377 @end group
|
|
378 @group
|
|
379 (setq mode-name "Text")
|
|
380 (setq major-mode 'text-mode)
|
6451
|
381 (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
|
|
382 ; @r{customize the mode with a hook.}
|
|
383 @end group
|
|
384 @end smallexample
|
|
385
|
|
386 @cindex @file{lisp-mode.el}
|
|
387 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
|
|
388 Interaction mode) have more features than Text mode and the code is
|
|
389 correspondingly more complicated. Here are excerpts from
|
|
390 @file{lisp-mode.el} that illustrate how these modes are written.
|
|
391
|
|
392 @cindex syntax table example
|
|
393 @smallexample
|
|
394 @group
|
|
395 ;; @r{Create mode-specific table variables.}
|
|
396 (defvar lisp-mode-syntax-table nil "")
|
|
397 (defvar emacs-lisp-mode-syntax-table nil "")
|
|
398 (defvar lisp-mode-abbrev-table nil "")
|
|
399 @end group
|
|
400
|
|
401 @group
|
|
402 (if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table}
|
|
403 ; @r{if it is already set.}
|
|
404 (let ((i 0))
|
|
405 (setq emacs-lisp-mode-syntax-table (make-syntax-table))
|
|
406 @end group
|
|
407
|
|
408 @group
|
|
409 ;; @r{Set syntax of chars up to 0 to class of chars that are}
|
|
410 ;; @r{part of symbol names but not words.}
|
25751
|
411 ;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
|
6451
|
412 (while (< i ?0)
|
|
413 (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
|
|
414 (setq i (1+ i)))
|
|
415 @dots{}
|
|
416 @end group
|
|
417 @group
|
|
418 ;; @r{Set the syntax for other characters.}
|
|
419 (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table)
|
|
420 (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table)
|
|
421 @dots{}
|
|
422 @end group
|
|
423 @group
|
|
424 (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table)
|
|
425 (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table)
|
|
426 @dots{}))
|
|
427 ;; @r{Create an abbrev table for lisp-mode.}
|
|
428 (define-abbrev-table 'lisp-mode-abbrev-table ())
|
|
429 @end group
|
|
430 @end smallexample
|
|
431
|
|
432 Much code is shared among the three Lisp modes. The following
|
|
433 function sets various variables; it is called by each of the major Lisp
|
|
434 mode functions:
|
|
435
|
|
436 @smallexample
|
|
437 @group
|
|
438 (defun lisp-mode-variables (lisp-syntax)
|
|
439 (cond (lisp-syntax
|
21682
|
440 (set-syntax-table lisp-mode-syntax-table)))
|
6451
|
441 (setq local-abbrev-table lisp-mode-abbrev-table)
|
22138
|
442 @dots{}
|
6451
|
443 @end group
|
|
444 @end smallexample
|
|
445
|
|
446 Functions such as @code{forward-paragraph} use the value of the
|
|
447 @code{paragraph-start} variable. Since Lisp code is different from
|
|
448 ordinary text, the @code{paragraph-start} variable needs to be set
|
|
449 specially to handle Lisp. Also, comments are indented in a special
|
|
450 fashion in Lisp and the Lisp modes need their own mode-specific
|
|
451 @code{comment-indent-function}. The code to set these variables is the
|
|
452 rest of @code{lisp-mode-variables}.
|
|
453
|
|
454 @smallexample
|
|
455 @group
|
|
456 (make-local-variable 'paragraph-start)
|
21682
|
457 (setq paragraph-start (concat page-delimiter "\\|$" ))
|
|
458 (make-local-variable 'paragraph-separate)
|
|
459 (setq paragraph-separate paragraph-start)
|
6451
|
460 @dots{}
|
|
461 @end group
|
|
462 @group
|
|
463 (make-local-variable 'comment-indent-function)
|
|
464 (setq comment-indent-function 'lisp-comment-indent))
|
25875
|
465 @dots{}
|
6451
|
466 @end group
|
|
467 @end smallexample
|
|
468
|
|
469 Each of the different Lisp modes has a slightly different keymap. For
|
21007
|
470 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
|
6451
|
471 Lisp modes do not. However, all Lisp modes have some commands in
|
21682
|
472 common. The following code sets up the common commands:
|
6451
|
473
|
|
474 @smallexample
|
|
475 @group
|
21682
|
476 (defvar shared-lisp-mode-map ()
|
|
477 "Keymap for commands shared by all sorts of Lisp modes.")
|
|
478
|
|
479 (if shared-lisp-mode-map
|
|
480 ()
|
|
481 (setq shared-lisp-mode-map (make-sparse-keymap))
|
|
482 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
|
|
483 (define-key shared-lisp-mode-map "\177"
|
|
484 'backward-delete-char-untabify))
|
6451
|
485 @end group
|
|
486 @end smallexample
|
|
487
|
21682
|
488 @noindent
|
|
489 And here is the code to set up the keymap for Lisp mode:
|
6451
|
490
|
|
491 @smallexample
|
|
492 @group
|
21682
|
493 (defvar lisp-mode-map ()
|
25950
|
494 "Keymap for ordinary Lisp mode...")
|
21682
|
495
|
|
496 (if lisp-mode-map
|
6451
|
497 ()
|
21682
|
498 (setq lisp-mode-map (make-sparse-keymap))
|
|
499 (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
|
|
500 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
|
|
501 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
|
6451
|
502 @end group
|
|
503 @end smallexample
|
|
504
|
|
505 Finally, here is the complete major mode function definition for
|
24934
|
506 Lisp mode.
|
6451
|
507
|
|
508 @smallexample
|
|
509 @group
|
21682
|
510 (defun lisp-mode ()
|
|
511 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
|
6451
|
512 Commands:
|
|
513 Delete converts tabs to spaces as it moves back.
|
|
514 Blank lines separate paragraphs. Semicolons start comments.
|
21682
|
515 \\@{lisp-mode-map@}
|
|
516 Note that `run-lisp' may be used either to start an inferior Lisp job
|
|
517 or to switch back to an existing one.
|
6451
|
518 @end group
|
21682
|
519
|
6451
|
520 @group
|
21682
|
521 Entry to this mode calls the value of `lisp-mode-hook'
|
|
522 if that value is non-nil."
|
6451
|
523 (interactive)
|
|
524 (kill-all-local-variables)
|
|
525 @end group
|
|
526 @group
|
21682
|
527 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
|
|
528 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
|
6451
|
529 ; @r{finds out what to describe.}
|
21682
|
530 (setq mode-name "Lisp") ; @r{This goes into the mode line.}
|
|
531 (lisp-mode-variables t) ; @r{This defines various variables.}
|
|
532 @end group
|
|
533 @group
|
|
534 (setq imenu-case-fold-search t)
|
|
535 (set-syntax-table lisp-mode-syntax-table)
|
|
536 (run-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
|
6451
|
537 ; @r{hook to customize the mode.}
|
|
538 @end group
|
|
539 @end smallexample
|
|
540
|
|
541 @node Auto Major Mode
|
|
542 @subsection How Emacs Chooses a Major Mode
|
|
543
|
|
544 Based on information in the file name or in the file itself, Emacs
|
|
545 automatically selects a major mode for the new buffer when a file is
|
21682
|
546 visited. It also processes local variables specified in the file text.
|
6451
|
547
|
|
548 @deffn Command fundamental-mode
|
|
549 Fundamental mode is a major mode that is not specialized for anything
|
|
550 in particular. Other major modes are defined in effect by comparison
|
|
551 with this one---their definitions say what to change, starting from
|
|
552 Fundamental mode. The @code{fundamental-mode} function does @emph{not}
|
|
553 run any hooks; you're not supposed to customize it. (If you want Emacs
|
|
554 to behave differently in Fundamental mode, change the @emph{global}
|
|
555 state of Emacs.)
|
|
556 @end deffn
|
|
557
|
|
558 @deffn Command normal-mode &optional find-file
|
21682
|
559 This function establishes the proper major mode and buffer-local variable
|
6451
|
560 bindings for the current buffer. First it calls @code{set-auto-mode},
|
|
561 then it runs @code{hack-local-variables} to parse, and bind or
|
21682
|
562 evaluate as appropriate, the file's local variables.
|
6451
|
563
|
21682
|
564 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
|
|
565 @code{normal-mode} assumes that the @code{find-file} function is calling
|
|
566 it. In this case, it may process a local variables list at the end of
|
|
567 the file and in the @samp{-*-} line. The variable
|
|
568 @code{enable-local-variables} controls whether to do so. @xref{File
|
|
569 variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
|
|
570 the syntax of the local variables section of a file.
|
6451
|
571
|
12098
|
572 If you run @code{normal-mode} interactively, the argument
|
6451
|
573 @var{find-file} is normally @code{nil}. In this case,
|
|
574 @code{normal-mode} unconditionally processes any local variables list.
|
|
575
|
|
576 @cindex file mode specification error
|
12098
|
577 @code{normal-mode} uses @code{condition-case} around the call to the
|
6451
|
578 major mode function, so errors are caught and reported as a @samp{File
|
|
579 mode specification error}, followed by the original error message.
|
|
580 @end deffn
|
|
581
|
|
582 @defun set-auto-mode
|
|
583 @cindex visited file mode
|
|
584 This function selects the major mode that is appropriate for the
|
|
585 current buffer. It may base its decision on the value of the @w{@samp{-*-}}
|
12888
|
586 line, on the visited file name (using @code{auto-mode-alist}), on the
|
|
587 @w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
|
21682
|
588 file's local variables list. However, this function does not look for
|
6451
|
589 the @samp{mode:} local variable near the end of a file; the
|
|
590 @code{hack-local-variables} function does that. @xref{Choosing Modes, ,
|
|
591 How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
|
|
592 @end defun
|
|
593
|
|
594 @defopt default-major-mode
|
21682
|
595 This variable holds the default major mode for new buffers. The
|
6451
|
596 standard value is @code{fundamental-mode}.
|
|
597
|
21682
|
598 If the value of @code{default-major-mode} is @code{nil}, Emacs uses
|
6451
|
599 the (previously) current buffer's major mode for the major mode of a new
|
21007
|
600 buffer. However, if that major mode symbol has a @code{mode-class}
|
6451
|
601 property with value @code{special}, then it is not used for new buffers;
|
|
602 Fundamental mode is used instead. The modes that have this property are
|
|
603 those such as Dired and Rmail that are useful only with text that has
|
|
604 been specially prepared.
|
|
605 @end defopt
|
|
606
|
12067
|
607 @defun set-buffer-major-mode buffer
|
|
608 This function sets the major mode of @var{buffer} to the value of
|
|
609 @code{default-major-mode}. If that variable is @code{nil}, it uses
|
|
610 the current buffer's major mode (if that is suitable).
|
|
611
|
|
612 The low-level primitives for creating buffers do not use this function,
|
12098
|
613 but medium-level commands such as @code{switch-to-buffer} and
|
|
614 @code{find-file-noselect} use it whenever they create buffers.
|
12067
|
615 @end defun
|
|
616
|
6451
|
617 @defvar initial-major-mode
|
|
618 @cindex @samp{*scratch*}
|
|
619 The value of this variable determines the major mode of the initial
|
|
620 @samp{*scratch*} buffer. The value should be a symbol that is a major
|
21007
|
621 mode command. The default value is @code{lisp-interaction-mode}.
|
6451
|
622 @end defvar
|
|
623
|
|
624 @defvar auto-mode-alist
|
|
625 This variable contains an association list of file name patterns
|
|
626 (regular expressions; @pxref{Regular Expressions}) and corresponding
|
21007
|
627 major mode commands. Usually, the file name patterns test for suffixes,
|
|
628 such as @samp{.el} and @samp{.c}, but this need not be the case. An
|
|
629 ordinary element of the alist looks like @code{(@var{regexp} .
|
6451
|
630 @var{mode-function})}.
|
|
631
|
|
632 For example,
|
|
633
|
|
634 @smallexample
|
|
635 @group
|
21682
|
636 (("\\`/tmp/fol/" . text-mode)
|
8505
|
637 ("\\.texinfo\\'" . texinfo-mode)
|
|
638 ("\\.texi\\'" . texinfo-mode)
|
6451
|
639 @end group
|
|
640 @group
|
8505
|
641 ("\\.el\\'" . emacs-lisp-mode)
|
|
642 ("\\.c\\'" . c-mode)
|
|
643 ("\\.h\\'" . c-mode)
|
6451
|
644 @dots{})
|
|
645 @end group
|
|
646 @end smallexample
|
|
647
|
|
648 When you visit a file whose expanded file name (@pxref{File Name
|
|
649 Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the
|
|
650 corresponding @var{mode-function}. This feature enables Emacs to select
|
|
651 the proper major mode for most files.
|
|
652
|
|
653 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
|
|
654 @var{function} t)}, then after calling @var{function}, Emacs searches
|
|
655 @code{auto-mode-alist} again for a match against the portion of the file
|
21682
|
656 name that did not match before. This feature is useful for
|
|
657 uncompression packages: an entry of the form @code{("\\.gz\\'"
|
|
658 @var{function} t)} can uncompress the file and then put the uncompressed
|
|
659 file in the proper mode according to the name sans @samp{.gz}.
|
6451
|
660
|
|
661 Here is an example of how to prepend several pattern pairs to
|
|
662 @code{auto-mode-alist}. (You might use this sort of expression in your
|
25875
|
663 init file.)
|
6451
|
664
|
|
665 @smallexample
|
|
666 @group
|
|
667 (setq auto-mode-alist
|
|
668 (append
|
21007
|
669 ;; @r{File name (within directory) starts with a dot.}
|
8505
|
670 '(("/\\.[^/]*\\'" . fundamental-mode)
|
7253
|
671 ;; @r{File name has no dot.}
|
8505
|
672 ("[^\\./]*\\'" . fundamental-mode)
|
7253
|
673 ;; @r{File name ends in @samp{.C}.}
|
8505
|
674 ("\\.C\\'" . c++-mode))
|
6451
|
675 auto-mode-alist))
|
|
676 @end group
|
|
677 @end smallexample
|
|
678 @end defvar
|
|
679
|
|
680 @defvar interpreter-mode-alist
|
21007
|
681 This variable specifies major modes to use for scripts that specify a
|
24934
|
682 command interpreter in a @samp{#!} line. Its value is a list of
|
6451
|
683 elements of the form @code{(@var{interpreter} . @var{mode})}; for
|
|
684 example, @code{("perl" . perl-mode)} is one element present by default.
|
|
685 The element says to use mode @var{mode} if the file specifies
|
21007
|
686 an interpreter which matches @var{interpreter}. The value of
|
|
687 @var{interpreter} is actually a regular expression.
|
6451
|
688
|
7253
|
689 This variable is applicable only when the @code{auto-mode-alist} does
|
|
690 not indicate which major mode to use.
|
6451
|
691 @end defvar
|
|
692
|
|
693 @node Mode Help
|
|
694 @subsection Getting Help about a Major Mode
|
|
695 @cindex mode help
|
|
696 @cindex help for major mode
|
|
697 @cindex documentation for major mode
|
|
698
|
|
699 The @code{describe-mode} function is used to provide information
|
|
700 about major modes. It is normally called with @kbd{C-h m}. The
|
|
701 @code{describe-mode} function uses the value of @code{major-mode},
|
|
702 which is why every major mode function needs to set the
|
|
703 @code{major-mode} variable.
|
|
704
|
|
705 @deffn Command describe-mode
|
|
706 This function displays the documentation of the current major mode.
|
|
707
|
|
708 The @code{describe-mode} function calls the @code{documentation}
|
|
709 function using the value of @code{major-mode} as an argument. Thus, it
|
|
710 displays the documentation string of the major mode function.
|
|
711 (@xref{Accessing Documentation}.)
|
|
712 @end deffn
|
|
713
|
|
714 @defvar major-mode
|
|
715 This variable holds the symbol for the current buffer's major mode.
|
7253
|
716 This symbol should have a function definition that is the command to
|
6451
|
717 switch to that major mode. The @code{describe-mode} function uses the
|
7253
|
718 documentation string of the function as the documentation of the major
|
6451
|
719 mode.
|
|
720 @end defvar
|
|
721
|
|
722 @node Derived Modes
|
|
723 @subsection Defining Derived Modes
|
|
724
|
|
725 It's often useful to define a new major mode in terms of an existing
|
|
726 one. An easy way to do this is to use @code{define-derived-mode}.
|
|
727
|
7253
|
728 @defmac define-derived-mode variant parent name docstring body@dots{}
|
6451
|
729 This construct defines @var{variant} as a major mode command, using
|
7253
|
730 @var{name} as the string form of the mode name.
|
6451
|
731
|
7253
|
732 The new command @var{variant} is defined to call the function
|
|
733 @var{parent}, then override certain aspects of that parent mode:
|
6451
|
734
|
|
735 @itemize @bullet
|
|
736 @item
|
|
737 The new mode has its own keymap, named @code{@var{variant}-map}.
|
|
738 @code{define-derived-mode} initializes this map to inherit from
|
|
739 @code{@var{parent}-map}, if it is not already set.
|
|
740
|
|
741 @item
|
7253
|
742 The new mode has its own syntax table, kept in the variable
|
6451
|
743 @code{@var{variant}-syntax-table}.
|
|
744 @code{define-derived-mode} initializes this variable by copying
|
|
745 @code{@var{parent}-syntax-table}, if it is not already set.
|
|
746
|
|
747 @item
|
7253
|
748 The new mode has its own abbrev table, kept in the variable
|
6451
|
749 @code{@var{variant}-abbrev-table}.
|
|
750 @code{define-derived-mode} initializes this variable by copying
|
|
751 @code{@var{parent}-abbrev-table}, if it is not already set.
|
|
752
|
|
753 @item
|
|
754 The new mode has its own mode hook, @code{@var{variant}-hook},
|
|
755 which it runs in standard fashion as the very last thing that it does.
|
|
756 (The new mode also runs the mode hook of @var{parent} as part
|
|
757 of calling @var{parent}.)
|
|
758 @end itemize
|
|
759
|
|
760 In addition, you can specify how to override other aspects of
|
7253
|
761 @var{parent} with @var{body}. The command @var{variant}
|
6451
|
762 evaluates the forms in @var{body} after setting up all its usual
|
|
763 overrides, just before running @code{@var{variant}-hook}.
|
|
764
|
|
765 The argument @var{docstring} specifies the documentation string for the
|
|
766 new mode. If you omit @var{docstring}, @code{define-derived-mode}
|
|
767 generates a documentation string.
|
|
768
|
|
769 Here is a hypothetical example:
|
|
770
|
|
771 @example
|
|
772 (define-derived-mode hypertext-mode
|
|
773 text-mode "Hypertext"
|
|
774 "Major mode for hypertext.
|
|
775 \\@{hypertext-mode-map@}"
|
|
776 (setq case-fold-search nil))
|
|
777
|
|
778 (define-key hypertext-mode-map
|
|
779 [down-mouse-3] 'do-hyper-link)
|
|
780 @end example
|
40928
|
781
|
|
782 Do not write an @code{interactive} spec in the definition;
|
|
783 @code{define-derived-mode} does that automatically.
|
6451
|
784 @end defmac
|
|
785
|
|
786 @node Minor Modes
|
|
787 @section Minor Modes
|
|
788 @cindex minor mode
|
|
789
|
|
790 A @dfn{minor mode} provides features that users may enable or disable
|
|
791 independently of the choice of major mode. Minor modes can be enabled
|
|
792 individually or in combination. Minor modes would be better named
|
21682
|
793 ``generally available, optional feature modes,'' except that such a name
|
|
794 would be unwieldy.
|
6451
|
795
|
25751
|
796 A minor mode is not usually meant as a variation of a single major mode.
|
|
797 Usually they are general and can apply to many major modes. For
|
21682
|
798 example, Auto Fill mode works with any major mode that permits text
|
6451
|
799 insertion. To be general, a minor mode must be effectively independent
|
|
800 of the things major modes do.
|
|
801
|
|
802 A minor mode is often much more difficult to implement than a major
|
|
803 mode. One reason is that you should be able to activate and deactivate
|
7253
|
804 minor modes in any order. A minor mode should be able to have its
|
|
805 desired effect regardless of the major mode and regardless of the other
|
|
806 minor modes in effect.
|
6451
|
807
|
|
808 Often the biggest problem in implementing a minor mode is finding a
|
|
809 way to insert the necessary hook into the rest of Emacs. Minor mode
|
12098
|
810 keymaps make this easier than it used to be.
|
6451
|
811
|
|
812 @menu
|
|
813 * Minor Mode Conventions:: Tips for writing a minor mode.
|
|
814 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
|
26696
|
815 * Defining Minor Modes:: A convenient facility for defining minor modes.
|
6451
|
816 @end menu
|
|
817
|
|
818 @node Minor Mode Conventions
|
|
819 @subsection Conventions for Writing Minor Modes
|
|
820 @cindex minor mode conventions
|
|
821 @cindex conventions for writing minor modes
|
|
822
|
|
823 There are conventions for writing minor modes just as there are for
|
|
824 major modes. Several of the major mode conventions apply to minor
|
|
825 modes as well: those regarding the name of the mode initialization
|
|
826 function, the names of global symbols, and the use of keymaps and
|
|
827 other tables.
|
|
828
|
|
829 In addition, there are several conventions that are specific to
|
|
830 minor modes.
|
|
831
|
|
832 @itemize @bullet
|
|
833 @item
|
|
834 @cindex mode variable
|
21682
|
835 Make a variable whose name ends in @samp{-mode} to control the minor
|
|
836 mode. We call this the @dfn{mode variable}. The minor mode command
|
|
837 should set this variable (@code{nil} to disable; anything else to
|
22252
|
838 enable).
|
21682
|
839
|
25751
|
840 If possible, implement the mode so that setting the variable
|
21682
|
841 automatically enables or disables the mode. Then the minor mode command
|
22252
|
842 does not need to do anything except set the variable.
|
6451
|
843
|
|
844 This variable is used in conjunction with the @code{minor-mode-alist} to
|
|
845 display the minor mode name in the mode line. It can also enable
|
|
846 or disable a minor mode keymap. Individual commands or hooks can also
|
|
847 check the variable's value.
|
|
848
|
|
849 If you want the minor mode to be enabled separately in each buffer,
|
|
850 make the variable buffer-local.
|
|
851
|
|
852 @item
|
|
853 Define a command whose name is the same as the mode variable.
|
|
854 Its job is to enable and disable the mode by setting the variable.
|
|
855
|
|
856 The command should accept one optional argument. If the argument is
|
|
857 @code{nil}, it should toggle the mode (turn it on if it is off, and off
|
|
858 if it is on). Otherwise, it should turn the mode on if the argument is
|
|
859 a positive integer, a symbol other than @code{nil} or @code{-}, or a
|
|
860 list whose @sc{car} is such an integer or symbol; it should turn the
|
|
861 mode off otherwise.
|
|
862
|
12098
|
863 Here is an example taken from the definition of @code{transient-mark-mode}.
|
|
864 It shows the use of @code{transient-mark-mode} as a variable that enables or
|
7253
|
865 disables the mode's behavior, and also shows the proper way to toggle,
|
|
866 enable or disable the minor mode based on the raw prefix argument value.
|
6451
|
867
|
|
868 @smallexample
|
|
869 @group
|
12098
|
870 (setq transient-mark-mode
|
|
871 (if (null arg) (not transient-mark-mode)
|
6451
|
872 (> (prefix-numeric-value arg) 0)))
|
|
873 @end group
|
|
874 @end smallexample
|
|
875
|
|
876 @item
|
|
877 Add an element to @code{minor-mode-alist} for each minor mode
|
21682
|
878 (@pxref{Mode Line Variables}), if you want to indicate the minor mode in
|
|
879 the mode line. This element should be a list of the following form:
|
6451
|
880
|
|
881 @smallexample
|
|
882 (@var{mode-variable} @var{string})
|
|
883 @end smallexample
|
|
884
|
7253
|
885 Here @var{mode-variable} is the variable that controls enabling of the
|
6451
|
886 minor mode, and @var{string} is a short string, starting with a space,
|
|
887 to represent the mode in the mode line. These strings must be short so
|
|
888 that there is room for several of them at once.
|
|
889
|
|
890 When you add an element to @code{minor-mode-alist}, use @code{assq} to
|
|
891 check for an existing element, to avoid duplication. For example:
|
|
892
|
|
893 @smallexample
|
|
894 @group
|
25875
|
895 (unless (assq 'leif-mode minor-mode-alist)
|
|
896 (setq minor-mode-alist
|
|
897 (cons '(leif-mode " Leif") minor-mode-alist)))
|
|
898 @end group
|
|
899 @end smallexample
|
|
900
|
|
901 @noindent
|
|
902 or like this, using @code{add-to-list} (@pxref{Setting Variables}):
|
|
903
|
|
904 @smallexample
|
|
905 @group
|
|
906 (add-to-list 'minor-mode-alist '(leif-mode " Leif"))
|
6451
|
907 @end group
|
|
908 @end smallexample
|
|
909 @end itemize
|
|
910
|
25751
|
911 Global minor modes distributed with Emacs should if possible support
|
|
912 enabling and disabling via Custom (@pxref{Customization}). To do this,
|
|
913 the first step is to define the mode variable with @code{defcustom}, and
|
|
914 specify @code{:type boolean}.
|
|
915
|
|
916 If just setting the variable is not sufficient to enable the mode, you
|
|
917 should also specify a @code{:set} method which enables the mode by
|
|
918 invoke the mode command. Note in the variable's documentation string that
|
|
919 setting the variable other than via Custom may not take effect.
|
|
920
|
|
921 Also mark the definition with an autoload cookie (@pxref{Autoload}),
|
|
922 and specify a @code{:require} so that customizing the variable will load
|
|
923 the library that defines the mode. This will copy suitable definitions
|
|
924 into @file{loaddefs.el} so that users can use @code{customize-option} to
|
|
925 enable the mode. For example:
|
|
926
|
|
927 @smallexample
|
|
928 @group
|
|
929
|
|
930 ;;;###autoload
|
|
931 (defcustom msb-mode nil
|
|
932 "Toggle msb-mode.
|
|
933 Setting this variable directly does not take effect;
|
|
934 use either \\[customize] or the function `msb-mode'."
|
|
935 :set (lambda (symbol value)
|
|
936 (msb-mode (or value 0)))
|
|
937 :initialize 'custom-initialize-default
|
|
938 :version "20.4"
|
|
939 :type 'boolean
|
|
940 :group 'msb
|
|
941 :require 'msb)
|
|
942 @end group
|
|
943 @end smallexample
|
|
944
|
6451
|
945 @node Keymaps and Minor Modes
|
|
946 @subsection Keymaps and Minor Modes
|
|
947
|
12098
|
948 Each minor mode can have its own keymap, which is active when the mode
|
|
949 is enabled. To set up a keymap for a minor mode, add an element to the
|
|
950 alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
|
6451
|
951
|
|
952 @cindex @code{self-insert-command}, minor modes
|
21007
|
953 One use of minor mode keymaps is to modify the behavior of certain
|
6451
|
954 self-inserting characters so that they do something else as well as
|
|
955 self-insert. In general, this is the only way to do that, since the
|
|
956 facilities for customizing @code{self-insert-command} are limited to
|
|
957 special cases (designed for abbrevs and Auto Fill mode). (Do not try
|
|
958 substituting your own definition of @code{self-insert-command} for the
|
|
959 standard one. The editor command loop handles this function specially.)
|
|
960
|
17278
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
961 The key sequences bound in a minor mode should consist of @kbd{C-c}
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
962 followed by a punctuation character @emph{other than} @kbd{@{},
|
25751
|
963 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
|
17278
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
964 characters are reserved for major modes.)
|
8ed8412c1ce7
Document key binding conventions for major modes and minor modes.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
965
|
26696
|
966 @node Defining Minor Modes
|
|
967 @subsection Defining Minor Modes
|
21007
|
968
|
26696
|
969 The macro @code{define-minor-mode} offers a convenient way of
|
|
970 implementing a mode in one self-contained definition. It supports only
|
25751
|
971 buffer-local minor modes, not global ones.
|
21007
|
972
|
26696
|
973 @defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...
|
|
974 @tindex define-minor-mode
|
21007
|
975 This macro defines a new minor mode whose name is @var{mode} (a symbol).
|
26696
|
976 It defines a command named @var{mode} to toggle the minor
|
|
977 mode, with @var{doc} as its documentation string. It also defines a
|
|
978 variable named @var{mode}, which is set to @code{t} or @code{nil} by
|
|
979 enabling or disabling the mode. The variable is initialized to
|
|
980 @var{init-value}.
|
21007
|
981
|
26696
|
982 The command named @var{mode} finishes by executing the @var{body} forms,
|
|
983 if any, after it has performed the standard actions such as setting
|
|
984 the variable named @var{mode}.
|
21007
|
985
|
|
986 The string @var{mode-indicator} says what to display in the mode line
|
|
987 when the mode is enabled; if it is @code{nil}, the mode is not displayed
|
|
988 in the mode line.
|
|
989
|
|
990 The optional argument @var{keymap} specifies the keymap for the minor mode.
|
|
991 It can be a variable name, whose value is the keymap, or it can be an alist
|
|
992 specifying bindings in this form:
|
|
993
|
|
994 @example
|
|
995 (@var{key-sequence} . @var{definition})
|
|
996 @end example
|
|
997 @end defmac
|
|
998
|
26696
|
999 Here is an example of using @code{define-minor-mode}:
|
21007
|
1000
|
|
1001 @smallexample
|
26696
|
1002 (define-minor-mode hungry-mode
|
21682
|
1003 "Toggle Hungry mode.
|
21007
|
1004 With no argument, this command toggles the mode.
|
|
1005 Non-null prefix argument turns on the mode.
|
|
1006 Null prefix argument turns off the mode.
|
|
1007
|
|
1008 When Hungry mode is enabled, the control delete key
|
|
1009 gobbles all preceding whitespace except the last.
|
|
1010 See the command \\[hungry-electric-delete]."
|
|
1011 ;; The initial value.
|
|
1012 nil
|
|
1013 ;; The indicator for the mode line.
|
|
1014 " Hungry"
|
|
1015 ;; The minor mode bindings.
|
|
1016 '(("\C-\^?" . hungry-electric-delete)
|
|
1017 ("\C-\M-\^?"
|
|
1018 . (lambda ()
|
|
1019 (interactive)
|
|
1020 (hungry-electric-delete t)))))
|
|
1021 @end smallexample
|
|
1022
|
|
1023 @noindent
|
|
1024 This defines a minor mode named ``Hungry mode'', a command named
|
|
1025 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
|
|
1026 which indicates whether the mode is enabled, and a variable named
|
|
1027 @code{hungry-mode-map} which holds the keymap that is active when the
|
|
1028 mode is enabled. It initializes the keymap with key bindings for
|
|
1029 @kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
|
|
1030
|
26696
|
1031
|
|
1032 @findex easy-mmode-define-minor-mode
|
|
1033 The name @code{easy-mmode-define-minor-mode} is an alias
|
|
1034 for this macro.
|
|
1035
|
6451
|
1036 @node Mode Line Format
|
|
1037 @section Mode Line Format
|
|
1038 @cindex mode line
|
|
1039
|
25751
|
1040 Each Emacs window (aside from minibuffer windows) typically has a mode
|
|
1041 line at the bottom, which displays status information about the buffer
|
|
1042 displayed in the window. The mode line contains information about the
|
|
1043 buffer, such as its name, associated file, depth of recursive editing,
|
|
1044 and major and minor modes. A window can also have a @dfn{header
|
|
1045 line}, which is much like the mode line but appears at the top of the
|
|
1046 window (starting in Emacs 21).
|
6451
|
1047
|
25751
|
1048 This section describes how to control the contents of the mode line
|
|
1049 and header line. We include it in this chapter because much of the
|
6451
|
1050 information displayed in the mode line relates to the enabled major and
|
|
1051 minor modes.
|
|
1052
|
|
1053 @code{mode-line-format} is a buffer-local variable that holds a
|
|
1054 template used to display the mode line of the current buffer. All
|
25751
|
1055 windows for the same buffer use the same @code{mode-line-format}, so
|
|
1056 their mode lines appear the same---except for scrolling percentages, and
|
|
1057 line and column numbers, since those depend on point and on how the
|
|
1058 window is scrolled. @code{header-line-format} is used likewise for
|
|
1059 header lines.
|
6451
|
1060
|
42296
|
1061 For efficiency, Emacs does not recompute the mode line and header
|
|
1062 line of a window in every redisplay. It does so when circumstances
|
|
1063 appear to call for it---for instance, if you change the window
|
|
1064 configuration, switch buffers, narrow or widen the buffer, scroll, or
|
|
1065 change the buffer's modification status. If you modify any of the
|
|
1066 variables referenced by @code{mode-line-format} (@pxref{Mode Line
|
|
1067 Variables}), or any other variables and data structures that affect
|
|
1068 how text is displayed (@pxref{Display}), you may want to force an
|
|
1069 update of the mode line so as to display the new information or
|
|
1070 display it in the new way.
|
6451
|
1071
|
|
1072 @c Emacs 19 feature
|
|
1073 @defun force-mode-line-update
|
25751
|
1074 Force redisplay of the current buffer's mode line and header line.
|
42296
|
1075 The next redisplay will update the mode line and header line based on
|
|
1076 the latest values of all relevant variables.
|
|
1077
|
|
1078 This function also forces recomputation of the menu bar menus
|
|
1079 and the frame title.
|
6451
|
1080 @end defun
|
|
1081
|
|
1082 The mode line is usually displayed in inverse video; see
|
|
1083 @code{mode-line-inverse-video} in @ref{Inverse Video}.
|
|
1084
|
42866
03dd2df2b595
(Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
1085 A window that is just one line tall does not display either a mode
|
03dd2df2b595
(Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
1086 line or a header line, even if the variables call for one. A window
|
03dd2df2b595
(Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
1087 that is two lines tall cannot display both a mode line and a header
|
03dd2df2b595
(Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
1088 line at once; if the variables call for both, only the mode line
|
03dd2df2b595
(Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
1089 actually appears.
|
03dd2df2b595
(Mode Line Format): Short windows can suppress the mode line and header line.
Richard M. Stallman <rms@gnu.org>
diff
changeset
|
1090
|
6451
|
1091 @menu
|
|
1092 * Mode Line Data:: The data structure that controls the mode line.
|
|
1093 * Mode Line Variables:: Variables used in that data structure.
|
|
1094 * %-Constructs:: Putting information into a mode line.
|
25751
|
1095 * Properties in Mode:: Using text properties in the mode line.
|
|
1096 * Header Lines:: Like a mode line, but at the top.
|
6451
|
1097 @end menu
|
|
1098
|
|
1099 @node Mode Line Data
|
|
1100 @subsection The Data Structure of the Mode Line
|
|
1101 @cindex mode line construct
|
|
1102
|
|
1103 The mode line contents are controlled by a data structure of lists,
|
25875
|
1104 strings, symbols, and numbers kept in buffer-local variables. The data
|
|
1105 structure is called a @dfn{mode line construct}, and it is built in
|
|
1106 recursive fashion out of simpler mode line constructs. The same data
|
|
1107 structure is used for constructing frame titles (@pxref{Frame Titles})
|
|
1108 and header lines (@pxref{Header Lines}).
|
6451
|
1109
|
|
1110 @defvar mode-line-format
|
|
1111 The value of this variable is a mode line construct with overall
|
|
1112 responsibility for the mode line format. The value of this variable
|
|
1113 controls which other variables are used to form the mode line text, and
|
|
1114 where they appear.
|
25751
|
1115
|
|
1116 If you set this variable to @code{nil} in a buffer, that buffer does not
|
|
1117 have a mode line. (This feature was added in Emacs 21.)
|
6451
|
1118 @end defvar
|
|
1119
|
|
1120 A mode line construct may be as simple as a fixed string of text, but
|
|
1121 it usually specifies how to use other variables to construct the text.
|
|
1122 Many of these variables are themselves defined to have mode line
|
|
1123 constructs as their values.
|
|
1124
|
|
1125 The default value of @code{mode-line-format} incorporates the values
|
|
1126 of variables such as @code{mode-name} and @code{minor-mode-alist}.
|
21007
|
1127 Because of this, very few modes need to alter @code{mode-line-format}
|
|
1128 itself. For most purposes, it is sufficient to alter some of the
|
|
1129 variables that @code{mode-line-format} refers to.
|
6451
|
1130
|
7253
|
1131 A mode line construct may be a list, a symbol, or a string. If the
|
|
1132 value is a list, each element may be a list, a symbol, or a string.
|
6451
|
1133
|
25751
|
1134 The mode line can display various faces, if the strings that control
|
|
1135 it have the @code{face} property. @xref{Properties in Mode}. In
|
|
1136 addition, the face @code{mode-line} is used as a default for the whole
|
|
1137 mode line (@pxref{Standard Faces}).
|
|
1138
|
6451
|
1139 @table @code
|
|
1140 @cindex percent symbol in mode line
|
|
1141 @item @var{string}
|
|
1142 A string as a mode line construct is displayed verbatim in the mode line
|
12098
|
1143 except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
|
6451
|
1144 specify the field width for space filling on the right (i.e., the data
|
|
1145 is left justified). @xref{%-Constructs}.
|
|
1146
|
|
1147 @item @var{symbol}
|
|
1148 A symbol as a mode line construct stands for its value. The value of
|
7253
|
1149 @var{symbol} is used as a mode line construct, in place of @var{symbol}.
|
25751
|
1150 However, the symbols @code{t} and @code{nil} are ignored, as is any
|
7253
|
1151 symbol whose value is void.
|
6451
|
1152
|
|
1153 There is one exception: if the value of @var{symbol} is a string, it is
|
7253
|
1154 displayed verbatim: the @code{%}-constructs are not recognized.
|
6451
|
1155
|
|
1156 @item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
|
7253
|
1157 A list whose first element is a string or list means to process all the
|
|
1158 elements recursively and concatenate the results. This is the most
|
|
1159 common form of mode line construct.
|
6451
|
1160
|
25751
|
1161 @item (:eval @var{form})
|
|
1162 A list whose first element is the symbol @code{:eval} says to evaluate
|
|
1163 @var{form}, and use the result as a string to display.
|
|
1164 (This feature is new as of Emacs 21.)
|
|
1165
|
6451
|
1166 @item (@var{symbol} @var{then} @var{else})
|
25751
|
1167 A list whose first element is a symbol that is not a keyword specifies a
|
|
1168 conditional. Its meaning depends on the value of @var{symbol}. If the
|
|
1169 value is non-@code{nil}, the second element, @var{then}, is processed
|
|
1170 recursively as a mode line element. But if the value of @var{symbol} is
|
|
1171 @code{nil}, the third element, @var{else}, is processed recursively.
|
|
1172 You may omit @var{else}; then the mode line element displays nothing if
|
|
1173 the value of @var{symbol} is @code{nil}.
|
6451
|
1174
|
|
1175 @item (@var{width} @var{rest}@dots{})
|
|
1176 A list whose first element is an integer specifies truncation or
|
|
1177 padding of the results of @var{rest}. The remaining elements
|
|
1178 @var{rest} are processed recursively as mode line constructs and
|
|
1179 concatenated together. Then the result is space filled (if
|
|
1180 @var{width} is positive) or truncated (to @minus{}@var{width} columns,
|
|
1181 if @var{width} is negative) on the right.
|
|
1182
|
|
1183 For example, the usual way to show what percentage of a buffer is above
|
7253
|
1184 the top of the window is to use a list like this: @code{(-3 "%p")}.
|
6451
|
1185 @end table
|
|
1186
|
|
1187 If you do alter @code{mode-line-format} itself, the new value should
|
7253
|
1188 use the same variables that appear in the default value (@pxref{Mode
|
|
1189 Line Variables}), rather than duplicating their contents or displaying
|
|
1190 the information in another fashion. This way, customizations made by
|
12098
|
1191 the user or by Lisp programs (such as @code{display-time} and major
|
|
1192 modes) via changes to those variables remain effective.
|
6451
|
1193
|
|
1194 @cindex Shell mode @code{mode-line-format}
|
|
1195 Here is an example of a @code{mode-line-format} that might be
|
21682
|
1196 useful for @code{shell-mode}, since it contains the host name and default
|
6451
|
1197 directory.
|
|
1198
|
|
1199 @example
|
|
1200 @group
|
|
1201 (setq mode-line-format
|
21682
|
1202 (list "-"
|
|
1203 'mode-line-mule-info
|
6451
|
1204 'mode-line-modified
|
21682
|
1205 'mode-line-frame-identification
|
6451
|
1206 "%b--"
|
|
1207 @end group
|
21007
|
1208 @group
|
|
1209 ;; @r{Note that this is evaluated while making the list.}
|
|
1210 ;; @r{It makes a mode line construct which is just a string.}
|
|
1211 (getenv "HOST")
|
|
1212 @end group
|
6451
|
1213 ":"
|
|
1214 'default-directory
|
|
1215 " "
|
|
1216 'global-mode-string
|
7253
|
1217 " %[("
|
25751
|
1218 '(:eval (mode-line-mode-name))
|
7253
|
1219 'mode-line-process
|
6451
|
1220 'minor-mode-alist
|
|
1221 "%n"
|
21682
|
1222 ")%]--"
|
6451
|
1223 @group
|
21682
|
1224 '(which-func-mode ("" which-func-format "--"))
|
12098
|
1225 '(line-number-mode "L%l--")
|
21682
|
1226 '(column-number-mode "C%c--")
|
6451
|
1227 '(-3 . "%p")
|
|
1228 "-%-"))
|
|
1229 @end group
|
|
1230 @end example
|
|
1231
|
22252
|
1232 @noindent
|
|
1233 (The variables @code{line-number-mode}, @code{column-number-mode}
|
|
1234 and @code{which-func-mode} enable particular minor modes; as usual,
|
|
1235 these variable names are also the minor mode command names.)
|
|
1236
|
6451
|
1237 @node Mode Line Variables
|
|
1238 @subsection Variables Used in the Mode Line
|
|
1239
|
|
1240 This section describes variables incorporated by the
|
|
1241 standard value of @code{mode-line-format} into the text of the mode
|
|
1242 line. There is nothing inherently special about these variables; any
|
|
1243 other variables could have the same effects on the mode line if
|
|
1244 @code{mode-line-format} were changed to use them.
|
|
1245
|
22138
|
1246 @defvar mode-line-mule-info
|
21682
|
1247 This variable holds the value of the mode-line construct that displays
|
|
1248 information about the language environment, buffer coding system, and
|
22138
|
1249 current input method. @xref{Non-ASCII Characters}.
|
21682
|
1250 @end defvar
|
|
1251
|
6451
|
1252 @defvar mode-line-modified
|
7253
|
1253 This variable holds the value of the mode-line construct that displays
|
6451
|
1254 whether the current buffer is modified.
|
|
1255
|
21682
|
1256 The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
|
|
1257 This means that the mode line displays @samp{**} if the buffer is
|
|
1258 modified, @samp{--} if the buffer is not modified, @samp{%%} if the
|
|
1259 buffer is read only, and @samp{%*} if the buffer is read only and
|
|
1260 modified.
|
6451
|
1261
|
|
1262 Changing this variable does not force an update of the mode line.
|
|
1263 @end defvar
|
|
1264
|
22138
|
1265 @defvar mode-line-frame-identification
|
21682
|
1266 This variable identifies the current frame. The default value is
|
|
1267 @code{" "} if you are using a window system which can show multiple
|
|
1268 frames, or @code{"-%F "} on an ordinary terminal which shows only one
|
|
1269 frame at a time.
|
|
1270 @end defvar
|
|
1271
|
6451
|
1272 @defvar mode-line-buffer-identification
|
7253
|
1273 This variable identifies the buffer being displayed in the window. Its
|
22267
|
1274 default value is @code{("%12b")}, which displays the buffer name, padded
|
|
1275 with spaces to at least 12 columns.
|
6451
|
1276 @end defvar
|
|
1277
|
|
1278 @defvar global-mode-string
|
|
1279 This variable holds a mode line spec that appears in the mode line by
|
|
1280 default, just after the buffer name. The command @code{display-time}
|
|
1281 sets @code{global-mode-string} to refer to the variable
|
|
1282 @code{display-time-string}, which holds a string containing the time and
|
|
1283 load information.
|
|
1284
|
|
1285 The @samp{%M} construct substitutes the value of
|
21007
|
1286 @code{global-mode-string}, but that is obsolete, since the variable is
|
|
1287 included in the mode line from @code{mode-line-format}.
|
6451
|
1288 @end defvar
|
|
1289
|
|
1290 @defvar mode-name
|
7253
|
1291 This buffer-local variable holds the ``pretty'' name of the current
|
6451
|
1292 buffer's major mode. Each major mode should set this variable so that the
|
|
1293 mode name will appear in the mode line.
|
|
1294 @end defvar
|
|
1295
|
|
1296 @defvar minor-mode-alist
|
7253
|
1297 This variable holds an association list whose elements specify how the
|
6451
|
1298 mode line should indicate that a minor mode is active. Each element of
|
|
1299 the @code{minor-mode-alist} should be a two-element list:
|
|
1300
|
|
1301 @example
|
|
1302 (@var{minor-mode-variable} @var{mode-line-string})
|
|
1303 @end example
|
|
1304
|
|
1305 More generally, @var{mode-line-string} can be any mode line spec. It
|
|
1306 appears in the mode line when the value of @var{minor-mode-variable} is
|
|
1307 non-@code{nil}, and not otherwise. These strings should begin with
|
|
1308 spaces so that they don't run together. Conventionally, the
|
|
1309 @var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
|
|
1310 value when that minor mode is activated.
|
|
1311
|
|
1312 The default value of @code{minor-mode-alist} is:
|
|
1313
|
|
1314 @example
|
|
1315 @group
|
|
1316 minor-mode-alist
|
12098
|
1317 @result{} ((vc-mode vc-mode)
|
|
1318 (abbrev-mode " Abbrev")
|
|
1319 (overwrite-mode overwrite-mode)
|
6451
|
1320 (auto-fill-function " Fill")
|
12098
|
1321 (defining-kbd-macro " Def")
|
|
1322 (isearch-mode isearch-mode))
|
6451
|
1323 @end group
|
|
1324 @end example
|
|
1325
|
21007
|
1326 @code{minor-mode-alist} itself is not buffer-local. Each variable
|
|
1327 mentioned in the alist should be buffer-local if its minor mode can be
|
|
1328 enabled separately in each buffer.
|
6451
|
1329 @end defvar
|
|
1330
|
|
1331 @defvar mode-line-process
|
|
1332 This buffer-local variable contains the mode line information on process
|
|
1333 status in modes used for communicating with subprocesses. It is
|
|
1334 displayed immediately following the major mode name, with no intervening
|
|
1335 space. For example, its value in the @samp{*shell*} buffer is
|
22252
|
1336 @code{(":%s")}, which allows the shell to display its status along
|
25875
|
1337 with the major mode as: @samp{(Shell:run)}. Normally this variable
|
6451
|
1338 is @code{nil}.
|
|
1339 @end defvar
|
|
1340
|
25875
|
1341 Some variables are used by @code{minor-mode-alist} to display
|
|
1342 a string for various minor modes when enabled. This is a typical
|
|
1343 example:
|
|
1344
|
|
1345 @defvar vc-mode
|
|
1346 The variable @code{vc-mode}, buffer-local in each buffer, records
|
|
1347 whether the buffer's visited file is maintained with version control,
|
|
1348 and, if so, which kind. Its value is a string that appears in the mode
|
|
1349 line, or @code{nil} for no version control.
|
|
1350 @end defvar
|
|
1351
|
|
1352 The variable @code{default-mode-line-format} is where
|
|
1353 @code{mode-line-format} usually gets its value:
|
|
1354
|
6451
|
1355 @defvar default-mode-line-format
|
7253
|
1356 This variable holds the default @code{mode-line-format} for buffers
|
6451
|
1357 that do not override it. This is the same as @code{(default-value
|
|
1358 'mode-line-format)}.
|
|
1359
|
21007
|
1360 The default value of @code{default-mode-line-format} is this list:
|
6451
|
1361
|
|
1362 @example
|
|
1363 @group
|
21007
|
1364 ("-"
|
|
1365 mode-line-mule-info
|
6451
|
1366 mode-line-modified
|
21007
|
1367 mode-line-frame-identification
|
6451
|
1368 mode-line-buffer-identification
|
21007
|
1369 @end group
|
6451
|
1370 " "
|
|
1371 global-mode-string
|
21007
|
1372 @group
|
6451
|
1373 " %[("
|
25875
|
1374 ;; @r{@code{mode-line-mode-name} is a function}
|
26211
|
1375 ;; @r{that copies the mode name and adds text}
|
25875
|
1376 ;; @r{properties to make it mouse-sensitive.}
|
25751
|
1377 (:eval (mode-line-mode-name))
|
12098
|
1378 mode-line-process
|
6451
|
1379 minor-mode-alist
|
|
1380 "%n"
|
21007
|
1381 ")%]--"
|
|
1382 @end group
|
|
1383 @group
|
|
1384 (which-func-mode ("" which-func-format "--"))
|
12098
|
1385 (line-number-mode "L%l--")
|
21007
|
1386 (column-number-mode "C%c--")
|
6451
|
1387 (-3 . "%p")
|
|
1388 "-%-")
|
|
1389 @end group
|
|
1390 @end example
|
|
1391 @end defvar
|
|
1392
|
|
1393 @node %-Constructs
|
|
1394 @subsection @code{%}-Constructs in the Mode Line
|
|
1395
|
|
1396 The following table lists the recognized @code{%}-constructs and what
|
7253
|
1397 they mean. In any construct except @samp{%%}, you can add a decimal
|
|
1398 integer after the @samp{%} to specify how many characters to display.
|
6451
|
1399
|
|
1400 @table @code
|
|
1401 @item %b
|
|
1402 The current buffer name, obtained with the @code{buffer-name} function.
|
|
1403 @xref{Buffer Names}.
|
|
1404
|
25875
|
1405 @item %c
|
|
1406 The current column number of point.
|
|
1407
|
6451
|
1408 @item %f
|
|
1409 The visited file name, obtained with the @code{buffer-file-name}
|
|
1410 function. @xref{Buffer File Name}.
|
|
1411
|
12067
|
1412 @item %F
|
21682
|
1413 The title (only on a window system) or the name of the selected frame.
|
|
1414 @xref{Window Frame Parameters}.
|
12067
|
1415
|
|
1416 @item %l
|
25751
|
1417 The current line number of point, counting within the accessible portion
|
|
1418 of the buffer.
|
12067
|
1419
|
25875
|
1420 @item %n
|
|
1421 @samp{Narrow} when narrowing is in effect; nothing otherwise (see
|
|
1422 @code{narrow-to-region} in @ref{Narrowing}).
|
|
1423
|
|
1424 @item %p
|
|
1425 The percentage of the buffer text above the @strong{top} of window, or
|
|
1426 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
|
|
1427 mode-line specification truncates this to three characters.
|
|
1428
|
|
1429 @item %P
|
|
1430 The percentage of the buffer text that is above the @strong{bottom} of
|
|
1431 the window (which includes the text visible in the window, as well as
|
|
1432 the text above the top), plus @samp{Top} if the top of the buffer is
|
|
1433 visible on screen; or @samp{Bottom} or @samp{All}.
|
|
1434
|
|
1435 @item %s
|
|
1436 The status of the subprocess belonging to the current buffer, obtained with
|
|
1437 @code{process-status}. @xref{Process Information}.
|
|
1438
|
|
1439 @item %t
|
|
1440 Whether the visited file is a text file or a binary file. This is a
|
|
1441 meaningful distinction only on certain operating systems (@pxref{MS-DOS
|
|
1442 File Types}).
|
|
1443
|
6451
|
1444 @item %*
|
|
1445 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
|
|
1446 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
|
|
1447 @samp{-} otherwise. @xref{Buffer Modification}.
|
|
1448
|
|
1449 @item %+
|
12067
|
1450 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
|
|
1451 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
|
|
1452 @samp{-} otherwise. This differs from @samp{%*} only for a modified
|
|
1453 read-only buffer. @xref{Buffer Modification}.
|
|
1454
|
|
1455 @item %&
|
7253
|
1456 @samp{*} if the buffer is modified, and @samp{-} otherwise.
|
6451
|
1457
|
|
1458 @item %[
|
|
1459 An indication of the depth of recursive editing levels (not counting
|
|
1460 minibuffer levels): one @samp{[} for each editing level.
|
|
1461 @xref{Recursive Editing}.
|
|
1462
|
|
1463 @item %]
|
|
1464 One @samp{]} for each recursive editing level (not counting minibuffer
|
|
1465 levels).
|
|
1466
|
25875
|
1467 @item %-
|
|
1468 Dashes sufficient to fill the remainder of the mode line.
|
|
1469
|
6451
|
1470 @item %%
|
|
1471 The character @samp{%}---this is how to include a literal @samp{%} in a
|
|
1472 string in which @code{%}-constructs are allowed.
|
|
1473 @end table
|
|
1474
|
|
1475 The following two @code{%}-constructs are still supported, but they are
|
|
1476 obsolete, since you can get the same results with the variables
|
|
1477 @code{mode-name} and @code{global-mode-string}.
|
|
1478
|
|
1479 @table @code
|
|
1480 @item %m
|
|
1481 The value of @code{mode-name}.
|
|
1482
|
|
1483 @item %M
|
|
1484 The value of @code{global-mode-string}. Currently, only
|
|
1485 @code{display-time} modifies the value of @code{global-mode-string}.
|
|
1486 @end table
|
|
1487
|
25751
|
1488 @node Properties in Mode
|
|
1489 @subsection Properties in the Mode Line
|
|
1490
|
|
1491 Starting in Emacs 21, certain text properties are meaningful in the
|
|
1492 mode line. The @code{face} property affects the appearance of text; the
|
|
1493 @code{help-echo} property associate help strings with the text, and
|
29102
|
1494 @code{local-map} can make the text mouse-sensitive.
|
25751
|
1495
|
|
1496 There are three ways to specify text properties for text in the mode
|
|
1497 line:
|
|
1498
|
|
1499 @enumerate
|
|
1500 @item
|
29102
|
1501 Put a string with the @code{local-map} property directly into the
|
|
1502 mode-line data structure.
|
25751
|
1503
|
|
1504 @item
|
29102
|
1505 Put a @code{local-map} property on a mode-line %-construct
|
|
1506 such as @samp{%12b}; then the expansion of the %-construct
|
|
1507 will have that same text property.
|
25751
|
1508
|
|
1509 @item
|
|
1510 Use a list containing @code{:eval @var{form}} in the mode-line data
|
|
1511 structure, and make @var{form} evaluate to a string that has a
|
29102
|
1512 @code{local-map} property.
|
25751
|
1513 @end enumerate
|
|
1514
|
29102
|
1515 You use the @code{local-map} property to specify a keymap. Like any
|
25751
|
1516 keymap, it can bind character keys and function keys; but that has no
|
25875
|
1517 effect, since it is impossible to move point into the mode line. This
|
25751
|
1518 keymap can only take real effect for mouse clicks.
|
|
1519
|
|
1520 @node Header Lines
|
|
1521 @subsection Window Header Lines
|
|
1522 @cindex header line (of a window)
|
|
1523 @cindex window header line
|
|
1524
|
|
1525 Starting in Emacs 21, a window can have a @dfn{header line} at the
|
|
1526 top, just as it can have a mode line at the bottom. The header line
|
|
1527 feature works just like the mode line feature, except that it's
|
|
1528 controlled by different variables.
|
|
1529
|
|
1530 @tindex header-line-format
|
|
1531 @defvar header-line-format
|
|
1532 This variable, local in every buffer, specifies how to display the
|
|
1533 header line, for windows displaying the buffer. The format of the value
|
26783
|
1534 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}).
|
25751
|
1535 @end defvar
|
|
1536
|
|
1537 @tindex default-header-line-format
|
|
1538 @defvar default-header-line-format
|
|
1539 This variable holds the default @code{header-line-format} for buffers
|
|
1540 that do not override it. This is the same as @code{(default-value
|
|
1541 'header-line-format)}.
|
|
1542
|
|
1543 It is normally @code{nil}, so that ordinary buffers have no header line.
|
|
1544 @end defvar
|
|
1545
|
21007
|
1546 @node Imenu
|
|
1547 @section Imenu
|
|
1548
|
|
1549 @cindex Imenu
|
21682
|
1550 @dfn{Imenu} is a feature that lets users select a definition or
|
|
1551 section in the buffer, from a menu which lists all of them, to go
|
|
1552 directly to that location in the buffer. Imenu works by constructing a
|
25751
|
1553 buffer index which lists the names and buffer positions of the
|
25875
|
1554 definitions, or other named portions of the buffer; then the user can
|
|
1555 choose one of them and move point to it. This section explains how to
|
|
1556 customize how Imenu finds the definitions or buffer portions for a
|
|
1557 particular major mode.
|
21682
|
1558
|
|
1559 The usual and simplest way is to set the variable
|
|
1560 @code{imenu-generic-expression}:
|
21007
|
1561
|
|
1562 @defvar imenu-generic-expression
|
|
1563 This variable, if non-@code{nil}, specifies regular expressions for
|
|
1564 finding definitions for Imenu. In the simplest case, elements should
|
|
1565 look like this:
|
|
1566
|
|
1567 @example
|
|
1568 (@var{menu-title} @var{regexp} @var{subexp})
|
|
1569 @end example
|
|
1570
|
|
1571 Here, if @var{menu-title} is non-@code{nil}, it says that the matches
|
|
1572 for this element should go in a submenu of the buffer index;
|
|
1573 @var{menu-title} itself specifies the name for the submenu. If
|
|
1574 @var{menu-title} is @code{nil}, the matches for this element go directly
|
|
1575 in the top level of the buffer index.
|
|
1576
|
|
1577 The second item in the list, @var{regexp}, is a regular expression
|
25751
|
1578 (@pxref{Regular Expressions}); anything in the buffer that it matches is
|
25875
|
1579 considered a definition, something to mention in the buffer index. The
|
|
1580 third item, @var{subexp}, indicates which subexpression in @var{regexp}
|
25751
|
1581 matches the definition's name.
|
21007
|
1582
|
|
1583 An element can also look like this:
|
|
1584
|
|
1585 @example
|
|
1586 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
|
|
1587 @end example
|
|
1588
|
|
1589 Each match for this element creates a special index item which, if
|
25875
|
1590 selected by the user, calls @var{function} with arguments consisting of
|
|
1591 the item name, the buffer position, and @var{arguments}.
|
21007
|
1592
|
|
1593 For Emacs Lisp mode, @var{pattern} could look like this:
|
|
1594
|
22138
|
1595 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
|
21007
|
1596 @example
|
|
1597 @group
|
|
1598 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
|
|
1599 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
|
|
1600 @end group
|
|
1601 @group
|
|
1602 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
|
|
1603 \\s-+\\([-A-Za-z0-9+]+\\)" 2)
|
|
1604 @end group
|
|
1605 @group
|
|
1606 ("*Types*"
|
22138
|
1607 "^\\s-*\
|
|
1608 (def\\(type\\|struct\\|class\\|ine-condition\\)\
|
21007
|
1609 \\s-+\\([-A-Za-z0-9+]+\\)" 2))
|
|
1610 @end group
|
|
1611 @end example
|
|
1612
|
21682
|
1613 Setting this variable makes it buffer-local in the current buffer.
|
21007
|
1614 @end defvar
|
|
1615
|
|
1616 @defvar imenu-case-fold-search
|
22138
|
1617 This variable controls whether matching against
|
|
1618 @var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
|
|
1619 means matching should ignore case.
|
|
1620
|
|
1621 Setting this variable makes it buffer-local in the current buffer.
|
|
1622 @end defvar
|
|
1623
|
|
1624 @defvar imenu-syntax-alist
|
|
1625 This variable is an alist of syntax table modifiers to use while
|
22252
|
1626 processing @code{imenu-generic-expression}, to override the syntax table
|
|
1627 of the current buffer. Each element should have this form:
|
22138
|
1628
|
|
1629 @example
|
|
1630 (@var{characters} . @var{syntax-description})
|
|
1631 @end example
|
|
1632
|
|
1633 The @sc{car}, @var{characters}, can be either a character or a string.
|
|
1634 The element says to give that character or characters the syntax
|
|
1635 specified by @var{syntax-description}, which is passed to
|
|
1636 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
|
|
1637
|
|
1638 This feature is typically used to give word syntax to characters which
|
|
1639 normally have symbol syntax, and thus to simplify
|
|
1640 @code{imenu-generic-expression} and speed up matching.
|
|
1641 For example, Fortran mode uses it this way:
|
|
1642
|
|
1643 @example
|
|
1644 (setq imenu-syntax-alist '(("_$" . "w")))
|
|
1645 @end example
|
|
1646
|
|
1647 The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
|
22252
|
1648 instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be
|
25751
|
1649 inconvenient when the mode needs to limit the initial character
|
22267
|
1650 of a name to a smaller set of characters than are allowed in the rest
|
|
1651 of a name.
|
21007
|
1652
|
21682
|
1653 Setting this variable makes it buffer-local in the current buffer.
|
21007
|
1654 @end defvar
|
|
1655
|
|
1656 Another way to customize Imenu for a major mode is to set the
|
|
1657 variables @code{imenu-prev-index-position-function} and
|
21682
|
1658 @code{imenu-extract-index-name-function}:
|
21007
|
1659
|
|
1660 @defvar imenu-prev-index-position-function
|
27332
|
1661 If this variable is non-@code{nil}, its value should be a function that
|
25875
|
1662 finds the next ``definition'' to put in the buffer index, scanning
|
|
1663 backward in the buffer from point. It should return @code{nil} if it
|
|
1664 doesn't find another ``definition'' before point. Otherwise it shuould
|
|
1665 leave point at the place it finds a ``definition,'' and return any
|
|
1666 non-@code{nil} value.
|
21007
|
1667
|
21682
|
1668 Setting this variable makes it buffer-local in the current buffer.
|
21007
|
1669 @end defvar
|
|
1670
|
|
1671 @defvar imenu-extract-index-name-function
|
|
1672 If this variable is non-@code{nil}, its value should be a function to
|
21682
|
1673 return the name for a definition, assuming point is in that definition
|
|
1674 as the @code{imenu-prev-index-position-function} function would leave
|
|
1675 it.
|
21007
|
1676
|
21682
|
1677 Setting this variable makes it buffer-local in the current buffer.
|
21007
|
1678 @end defvar
|
|
1679
|
21682
|
1680 The last way to customize Imenu for a major mode is to set the
|
25875
|
1681 variable @code{imenu-create-index-function}:
|
21682
|
1682
|
21007
|
1683 @defvar imenu-create-index-function
|
|
1684 This variable specifies the function to use for creating a buffer index.
|
|
1685 The function should take no arguments, and return an index for the
|
|
1686 current buffer. It is called within @code{save-excursion}, so where it
|
|
1687 leaves point makes no difference.
|
|
1688
|
|
1689 The default value is a function that uses
|
|
1690 @code{imenu-generic-expression} to produce the index alist. If you
|
|
1691 specify a different function, then @code{imenu-generic-expression} is
|
|
1692 not used.
|
|
1693
|
21682
|
1694 Setting this variable makes it buffer-local in the current buffer.
|
21007
|
1695 @end defvar
|
|
1696
|
|
1697 @defvar imenu-index-alist
|
|
1698 This variable holds the index alist for the current buffer.
|
21682
|
1699 Setting it makes it buffer-local in the current buffer.
|
21007
|
1700
|
|
1701 Simple elements in the alist look like @code{(@var{index-name}
|
|
1702 . @var{index-position})}. Selecting a simple element has the effect of
|
|
1703 moving to position @var{index-position} in the buffer.
|
|
1704
|
|
1705 Special elements look like @code{(@var{index-name} @var{position}
|
|
1706 @var{function} @var{arguments}@dots{})}. Selecting a special element
|
|
1707 performs
|
|
1708
|
|
1709 @example
|
|
1710 (funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
|
|
1711 @end example
|
|
1712
|
|
1713 A nested sub-alist element looks like @code{(@var{index-name}
|
|
1714 @var{sub-alist})}.
|
|
1715 @end defvar
|
|
1716
|
|
1717 @node Font Lock Mode
|
|
1718 @section Font Lock Mode
|
|
1719 @cindex Font Lock Mode
|
|
1720
|
|
1721 @dfn{Font Lock mode} is a feature that automatically attaches
|
|
1722 @code{face} properties to certain parts of the buffer based on their
|
|
1723 syntactic role. How it parses the buffer depends on the major mode;
|
25875
|
1724 most major modes define syntactic criteria for which faces to use in
|
21682
|
1725 which contexts. This section explains how to customize Font Lock for a
|
25875
|
1726 particular major mode.
|
21007
|
1727
|
|
1728 Font Lock mode finds text to highlight in two ways: through syntactic
|
|
1729 parsing based on the syntax table, and through searching (usually for
|
|
1730 regular expressions). Syntactic fontification happens first; it finds
|
|
1731 comments and string constants, and highlights them using
|
|
1732 @code{font-lock-comment-face} and @code{font-lock-string-face}
|
25875
|
1733 (@pxref{Faces for Font Lock}). Search-based fontification follows.
|
21007
|
1734
|
|
1735 @menu
|
|
1736 * Font Lock Basics::
|
|
1737 * Search-based Fontification::
|
|
1738 * Other Font Lock Variables::
|
|
1739 * Levels of Font Lock::
|
|
1740 * Faces for Font Lock::
|
21682
|
1741 * Syntactic Font Lock::
|
21007
|
1742 @end menu
|
|
1743
|
|
1744 @node Font Lock Basics
|
|
1745 @subsection Font Lock Basics
|
|
1746
|
|
1747 There are several variables that control how Font Lock mode highlights
|
|
1748 text. But major modes should not set any of these variables directly.
|
24934
|
1749 Instead, they should set @code{font-lock-defaults} as a buffer-local
|
21682
|
1750 variable. The value assigned to this variable is used, if and when Font
|
|
1751 Lock mode is enabled, to set all the other variables.
|
21007
|
1752
|
|
1753 @defvar font-lock-defaults
|
|
1754 This variable is set by major modes, as a buffer-local variable, to
|
|
1755 specify how to fontify text in that mode. The value should look like
|
|
1756 this:
|
|
1757
|
|
1758 @example
|
|
1759 (@var{keywords} @var{keywords-only} @var{case-fold}
|
|
1760 @var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
|
|
1761 @end example
|
|
1762
|
|
1763 The first element, @var{keywords}, indirectly specifies the value of
|
|
1764 @code{font-lock-keywords}. It can be a symbol, a variable whose value
|
25875
|
1765 is the list to use for @code{font-lock-keywords}. It can also be a list of
|
21007
|
1766 several such symbols, one for each possible level of fontification. The
|
|
1767 first symbol specifies how to do level 1 fontification, the second
|
|
1768 symbol how to do level 2, and so on.
|
|
1769
|
|
1770 The second element, @var{keywords-only}, specifies the value of the
|
22138
|
1771 variable @code{font-lock-keywords-only}. If this is non-@code{nil},
|
21682
|
1772 syntactic fontification (of strings and comments) is not performed.
|
21007
|
1773
|
|
1774 The third element, @var{case-fold}, specifies the value of
|
|
1775 @code{font-lock-case-fold-search}. If it is non-@code{nil}, Font Lock
|
21682
|
1776 mode ignores case when searching as directed by
|
|
1777 @code{font-lock-keywords}.
|
21007
|
1778
|
|
1779 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
|
|
1780 a list of cons cells of the form @code{(@var{char-or-string}
|
|
1781 . @var{string})}. These are used to set up a syntax table for
|
|
1782 fontification (@pxref{Syntax Table Functions}). The resulting syntax
|
|
1783 table is stored in @code{font-lock-syntax-table}.
|
|
1784
|
|
1785 The fifth element, @var{syntax-begin}, specifies the value of
|
21682
|
1786 @code{font-lock-beginning-of-syntax-function} (see below).
|
21007
|
1787
|
25875
|
1788 All the remaining elements (if any) are collectively called
|
|
1789 @var{other-vars}. Each of these elements should have the form
|
|
1790 @code{(@var{variable} . @var{value})}---which means, make @var{variable}
|
|
1791 buffer-local and then set it to @var{value}. You can use these
|
|
1792 @var{other-vars} to set other variables that affect fontification,
|
|
1793 aside from those you can control with the first five elements.
|
21007
|
1794 @end defvar
|
|
1795
|
|
1796 @node Search-based Fontification
|
|
1797 @subsection Search-based Fontification
|
|
1798
|
|
1799 The most important variable for customizing Font Lock mode is
|
|
1800 @code{font-lock-keywords}. It specifies the search criteria for
|
|
1801 search-based fontification.
|
|
1802
|
|
1803 @defvar font-lock-keywords
|
|
1804 This variable's value is a list of the keywords to highlight. Be
|
21682
|
1805 careful when composing regular expressions for this list; a poorly
|
|
1806 written pattern can dramatically slow things down!
|
21007
|
1807 @end defvar
|
|
1808
|
|
1809 Each element of @code{font-lock-keywords} specifies how to find
|
21682
|
1810 certain cases of text, and how to highlight those cases. Font Lock mode
|
|
1811 processes the elements of @code{font-lock-keywords} one by one, and for
|
|
1812 each element, it finds and handles all matches. Ordinarily, once
|
|
1813 part of the text has been fontified already, this cannot be overridden
|
|
1814 by a subsequent match in the same text; but you can specify different
|
|
1815 behavior using the @var{override} element of a @var{highlighter}.
|
|
1816
|
|
1817 Each element of @code{font-lock-keywords} should have one of these
|
|
1818 forms:
|
21007
|
1819
|
|
1820 @table @code
|
|
1821 @item @var{regexp}
|
|
1822 Highlight all matches for @var{regexp} using
|
|
1823 @code{font-lock-keyword-face}. For example,
|
|
1824
|
|
1825 @example
|
|
1826 ;; @r{Highlight discrete occurrences of @samp{foo}}
|
|
1827 ;; @r{using @code{font-lock-keyword-face}.}
|
|
1828 "\\<foo\\>"
|
|
1829 @end example
|
|
1830
|
21682
|
1831 The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for
|
|
1832 calculating optimal regular expressions to match a number of different
|
|
1833 keywords.
|
21007
|
1834
|
|
1835 @item @var{function}
|
|
1836 Find text by calling @var{function}, and highlight the matches
|
|
1837 it finds using @code{font-lock-keyword-face}.
|
|
1838
|
|
1839 When @var{function} is called, it receives one argument, the limit of
|
41938
|
1840 the search; it should searching at point, and not search beyond the
|
|
1841 limit. It should return non-@code{nil} if it succeeds, and set the
|
|
1842 match data to describe the match that was found. Returning @code{nil}
|
|
1843 indicates failure of the search.
|
|
1844
|
|
1845 Fontification will call @var{function} repeatedly with the same limit,
|
|
1846 and with point where the previous invocation left it, until
|
|
1847 @var{function} fails. On failure, @var{function} need not reset point
|
|
1848 in any particular way.
|
21007
|
1849
|
|
1850 @item (@var{matcher} . @var{match})
|
24934
|
1851 In this kind of element, @var{matcher} is either a regular
|
21007
|
1852 expression or a function, as described above. The @sc{cdr},
|
|
1853 @var{match}, specifies which subexpression of @var{matcher} should be
|
21682
|
1854 highlighted (instead of the entire text that @var{matcher} matched).
|
21007
|
1855
|
|
1856 @example
|
25751
|
1857 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
|
21007
|
1858 ;; @r{using @code{font-lock-keyword-face}.}
|
|
1859 ("fu\\(bar\\)" . 1)
|
|
1860 @end example
|
|
1861
|
21682
|
1862 If you use @code{regexp-opt} to produce the regular expression
|
21007
|
1863 @var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
|
|
1864 of Regexps}) to calculate the value for @var{match}.
|
|
1865
|
|
1866 @item (@var{matcher} . @var{facename})
|
|
1867 In this kind of element, @var{facename} is an expression whose value
|
|
1868 specifies the face name to use for highlighting.
|
|
1869
|
|
1870 @example
|
|
1871 ;; @r{Highlight occurrences of @samp{fubar},}
|
|
1872 ;; @r{using the face which is the value of @code{fubar-face}.}
|
|
1873 ("fubar" . fubar-face)
|
|
1874 @end example
|
|
1875
|
|
1876 @item (@var{matcher} . @var{highlighter})
|
|
1877 In this kind of element, @var{highlighter} is a list
|
|
1878 which specifies how to highlight matches found by @var{matcher}.
|
|
1879 It has the form
|
|
1880
|
|
1881 @example
|
|
1882 (@var{subexp} @var{facename} @var{override} @var{laxmatch})
|
|
1883 @end example
|
|
1884
|
|
1885 The @sc{car}, @var{subexp}, is an integer specifying which subexpression
|
21682
|
1886 of the match to fontify (0 means the entire matching text). The second
|
|
1887 subelement, @var{facename}, specifies the face, as described above.
|
21007
|
1888
|
|
1889 The last two values in @var{highlighter}, @var{override} and
|
|
1890 @var{laxmatch}, are flags. If @var{override} is @code{t}, this element
|
|
1891 can override existing fontification made by previous elements of
|
|
1892 @code{font-lock-keywords}. If it is @code{keep}, then each character is
|
|
1893 fontified if it has not been fontified already by some other element.
|
|
1894 If it is @code{prepend}, the face @var{facename} is added to the
|
|
1895 beginning of the @code{face} property. If it is @code{append}, the face
|
|
1896 @var{facename} is added to the end of the @code{face} property.
|
|
1897
|
|
1898 If @var{laxmatch} is non-@code{nil}, it means there should be no error
|
|
1899 if there is no subexpression numbered @var{subexp} in @var{matcher}.
|
25975
|
1900 Obviously, fontification of the subexpression numbered @var{subexp} will
|
|
1901 not occur. However, fontification of other subexpressions (and other
|
|
1902 regexps) will continue. If @var{laxmatch} is @code{nil}, and the
|
|
1903 specified subexpression is missing, then an error is signalled which
|
|
1904 terminates search-based fontification.
|
21007
|
1905
|
|
1906 Here are some examples of elements of this kind, and what they do:
|
|
1907
|
|
1908 @smallexample
|
|
1909 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar},}
|
|
1910 ;; @r{using @code{foo-bar-face}, even if they have already been highlighted.}
|
|
1911 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
|
|
1912 ("foo\\|bar" 0 foo-bar-face t)
|
|
1913
|
25751
|
1914 ;; @r{Highlight the first subexpression within each occurrence}
|
21007
|
1915 ;; @r{that the function @code{fubar-match} finds,}
|
|
1916 ;; @r{using the face which is the value of @code{fubar-face}.}
|
|
1917 (fubar-match 1 fubar-face)
|
|
1918 @end smallexample
|
|
1919
|
|
1920 @item (@var{matcher} @var{highlighters}@dots{})
|
|
1921 This sort of element specifies several @var{highlighter} lists for a
|
|
1922 single @var{matcher}. In order for this to be useful, each
|
|
1923 @var{highlighter} should have a different value of @var{subexp}; that is,
|
|
1924 each one should apply to a different subexpression of @var{matcher}.
|
|
1925
|
|
1926 @ignore
|
|
1927 @item (@var{matcher} . @var{anchored})
|
|
1928 In this kind of element, @var{anchored} acts much like a
|
|
1929 @var{highlighter}, but it is more complex and can specify multiple
|
|
1930 successive searches.
|
|
1931
|
|
1932 For highlighting single items, typically only @var{highlighter} is
|
|
1933 required. However, if an item or (typically) items are to be
|
|
1934 highlighted following the instance of another item (the anchor) then
|
|
1935 @var{anchored} may be required.
|
|
1936
|
|
1937 It has this format:
|
|
1938
|
|
1939 @example
|
|
1940 (@var{submatcher} @var{pre-match-form} @var{post-match-form} @var{highlighters}@dots{})
|
|
1941 @end example
|
|
1942
|
|
1943 @c I can't parse this text -- rms
|
|
1944 where @var{submatcher} is much like @var{matcher}, with one
|
|
1945 exception---see below. @var{pre-match-form} and @var{post-match-form}
|
|
1946 are evaluated before the first, and after the last, instance
|
|
1947 @var{anchored}'s @var{submatcher} is used. Therefore they can be used
|
22138
|
1948 to initialize before, and cleanup after, @var{submatcher} is used.
|
21007
|
1949 Typically, @var{pre-match-form} is used to move to some position
|
|
1950 relative to the original @var{submatcher}, before starting with
|
|
1951 @var{anchored}'s @var{submatcher}. @var{post-match-form} might be used
|
|
1952 to move, before resuming with @var{anchored}'s parent's @var{matcher}.
|
|
1953
|
|
1954 For example, an element of the form highlights (if not already highlighted):
|
|
1955
|
|
1956 @example
|
|
1957 ("\\<anchor\\>" (0 anchor-face) ("\\<item\\>" nil nil (0 item-face)))
|
|
1958 @end example
|
|
1959
|
|
1960 Discrete occurrences of @samp{anchor} in the value of
|
|
1961 @code{anchor-face}, and subsequent discrete occurrences of @samp{item}
|
|
1962 (on the same line) in the value of @code{item-face}. (Here
|
|
1963 @var{pre-match-form} and @var{post-match-form} are @code{nil}.
|
|
1964 Therefore @samp{item} is initially searched for starting from the end of
|
|
1965 the match of @samp{anchor}, and searching for subsequent instance of
|
|
1966 @samp{anchor} resumes from where searching for @samp{item} concluded.)
|
|
1967
|
|
1968 The above-mentioned exception is as follows. The limit of the
|
|
1969 @var{submatcher} search defaults to the end of the line after
|
|
1970 @var{pre-match-form} is evaluated. However, if @var{pre-match-form}
|
|
1971 returns a position greater than the position after @var{pre-match-form}
|
|
1972 is evaluated, that position is used as the limit of the search. It is
|
|
1973 generally a bad idea to return a position greater than the end of the
|
|
1974 line; in other words, the @var{submatcher} search should not span lines.
|
|
1975
|
|
1976 @item (@var{matcher} @var{highlighters-or-anchoreds} ...)
|
|
1977 @end ignore
|
|
1978
|
|
1979 @item (eval . @var{form})
|
21682
|
1980 Here @var{form} is an expression to be evaluated the first time
|
21007
|
1981 this value of @code{font-lock-keywords} is used in a buffer.
|
21682
|
1982 Its value should have one of the forms described in this table.
|
21007
|
1983 @end table
|
|
1984
|
|
1985 @strong{Warning:} Do not design an element of @code{font-lock-keywords}
|
|
1986 to match text which spans lines; this does not work reliably. While
|
|
1987 @code{font-lock-fontify-buffer} handles multi-line patterns correctly,
|
|
1988 updating when you edit the buffer does not, since it considers text one
|
|
1989 line at a time.
|
|
1990
|
|
1991 @node Other Font Lock Variables
|
|
1992 @subsection Other Font Lock Variables
|
|
1993
|
|
1994 This section describes additional variables that a major mode
|
|
1995 can set by means of @code{font-lock-defaults}.
|
|
1996
|
|
1997 @defvar font-lock-keywords-only
|
|
1998 Non-@code{nil} means Font Lock should not fontify comments or strings
|
21682
|
1999 syntactically; it should only fontify based on
|
|
2000 @code{font-lock-keywords}.
|
21007
|
2001 @end defvar
|
|
2002
|
|
2003 @ignore
|
22138
|
2004 Other variables include those for buffer-specialized fontification functions,
|
21007
|
2005 `font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
|
|
2006 `font-lock-fontify-region-function', `font-lock-unfontify-region-function',
|
|
2007 `font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
|
|
2008 @end ignore
|
|
2009
|
|
2010 @defvar font-lock-keywords-case-fold-search
|
21682
|
2011 Non-@code{nil} means that regular expression matching for the sake of
|
|
2012 @code{font-lock-keywords} should be case-insensitive.
|
|
2013 @end defvar
|
|
2014
|
|
2015 @defvar font-lock-syntax-table
|
|
2016 This variable specifies the syntax table to use for fontification of
|
|
2017 comments and strings.
|
21007
|
2018 @end defvar
|
|
2019
|
|
2020 @defvar font-lock-beginning-of-syntax-function
|
21682
|
2021 If this variable is non-@code{nil}, it should be a function to move
|
|
2022 point back to a position that is syntactically at ``top level'' and
|
|
2023 outside of strings or comments. Font Lock uses this when necessary
|
|
2024 to get the right results for syntactic fontification.
|
21007
|
2025
|
|
2026 This function is called with no arguments. It should leave point at the
|
|
2027 beginning of any enclosing syntactic block. Typical values are
|
|
2028 @code{beginning-of-line} (i.e., the start of the line is known to be
|
|
2029 outside a syntactic block), or @code{beginning-of-defun} for programming
|
|
2030 modes or @code{backward-paragraph} for textual modes (i.e., the
|
|
2031 mode-dependent function is known to move outside a syntactic block).
|
|
2032
|
|
2033 If the value is @code{nil}, the beginning of the buffer is used as a
|
21682
|
2034 position outside of a syntactic block. This cannot be wrong, but it can
|
|
2035 be slow.
|
21007
|
2036 @end defvar
|
|
2037
|
|
2038 @defvar font-lock-mark-block-function
|
21682
|
2039 If this variable is non-@code{nil}, it should be a function that is
|
|
2040 called with no arguments, to choose an enclosing range of text for
|
|
2041 refontification for the command @kbd{M-g M-g}
|
|
2042 (@code{font-lock-fontify-block}).
|
21007
|
2043
|
21682
|
2044 The function should report its choice by placing the region around it.
|
|
2045 A good choice is a range of text large enough to give proper results,
|
|
2046 but not too large so that refontification becomes slow. Typical values
|
|
2047 are @code{mark-defun} for programming modes or @code{mark-paragraph} for
|
|
2048 textual modes.
|
21007
|
2049 @end defvar
|
|
2050
|
|
2051 @node Levels of Font Lock
|
|
2052 @subsection Levels of Font Lock
|
|
2053
|
|
2054 Many major modes offer three different levels of fontification. You
|
|
2055 can define multiple levels by using a list of symbols for @var{keywords}
|
|
2056 in @code{font-lock-defaults}. Each symbol specifies one level of
|
|
2057 fontification; it is up to the user to choose one of these levels. The
|
|
2058 chosen level's symbol value is used to initialize
|
|
2059 @code{font-lock-keywords}.
|
|
2060
|
21682
|
2061 Here are the conventions for how to define the levels of
|
|
2062 fontification:
|
|
2063
|
21007
|
2064 @itemize @bullet
|
|
2065 @item
|
|
2066 Level 1: highlight function declarations, file directives (such as include or
|
|
2067 import directives), strings and comments. The idea is speed, so only
|
|
2068 the most important and top-level components are fontified.
|
|
2069
|
|
2070 @item
|
21682
|
2071 Level 2: in addition to level 1, highlight all language keywords,
|
|
2072 including type names that act like keywords, as well as named constant
|
|
2073 values. The idea is that all keywords (either syntactic or semantic)
|
|
2074 should be fontified appropriately.
|
21007
|
2075
|
|
2076 @item
|
21682
|
2077 Level 3: in addition to level 2, highlight the symbols being defined in
|
|
2078 function and variable declarations, and all builtin function names,
|
|
2079 wherever they appear.
|
21007
|
2080 @end itemize
|
|
2081
|
|
2082 @node Faces for Font Lock
|
|
2083 @subsection Faces for Font Lock
|
|
2084
|
|
2085 You can make Font Lock mode use any face, but several faces are
|
|
2086 defined specifically for Font Lock mode. Each of these symbols is both
|
|
2087 a face name, and a variable whose default value is the symbol itself.
|
|
2088 Thus, the default value of @code{font-lock-comment-face} is
|
|
2089 @code{font-lock-comment-face}. This means you can write
|
|
2090 @code{font-lock-comment-face} in a context such as
|
|
2091 @code{font-lock-keywords} where a face-name-valued expression is used.
|
|
2092
|
|
2093 @table @code
|
|
2094 @item font-lock-comment-face
|
|
2095 @vindex font-lock-comment-face
|
|
2096 Used (typically) for comments.
|
|
2097
|
|
2098 @item font-lock-string-face
|
|
2099 @vindex font-lock-string-face
|
|
2100 Used (typically) for string constants.
|
|
2101
|
|
2102 @item font-lock-keyword-face
|
|
2103 @vindex font-lock-keyword-face
|
|
2104 Used (typically) for keywords---names that have special syntactic
|
|
2105 significance, like @code{for} and @code{if} in C.
|
|
2106
|
|
2107 @item font-lock-builtin-face
|
|
2108 @vindex font-lock-builtin-face
|
|
2109 Used (typically) for built-in function names.
|
|
2110
|
|
2111 @item font-lock-function-name-face
|
|
2112 @vindex font-lock-function-name-face
|
|
2113 Used (typically) for the name of a function being defined or declared,
|
|
2114 in a function definition or declaration.
|
|
2115
|
|
2116 @item font-lock-variable-name-face
|
|
2117 @vindex font-lock-variable-name-face
|
|
2118 Used (typically) for the name of a variable being defined or declared,
|
|
2119 in a variable definition or declaration.
|
|
2120
|
|
2121 @item font-lock-type-face
|
|
2122 @vindex font-lock-type-face
|
|
2123 Used (typically) for names of user-defined data types,
|
|
2124 where they are defined and where they are used.
|
|
2125
|
|
2126 @item font-lock-constant-face
|
|
2127 @vindex font-lock-constant-face
|
|
2128 Used (typically) for constant names.
|
|
2129
|
|
2130 @item font-lock-warning-face
|
|
2131 @vindex font-lock-warning-face
|
|
2132 Used (typically) for constructs that are peculiar, or that greatly
|
|
2133 change the meaning of other text. For example, this is used for
|
|
2134 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
|
|
2135 directives in C.
|
|
2136 @end table
|
|
2137
|
21682
|
2138 @node Syntactic Font Lock
|
|
2139 @subsection Syntactic Font Lock
|
|
2140
|
|
2141 Font Lock mode can be used to update @code{syntax-table} properties
|
|
2142 automatically. This is useful in languages for which a single syntax
|
|
2143 table by itself is not sufficient.
|
|
2144
|
|
2145 @defvar font-lock-syntactic-keywords
|
|
2146 This variable enables and controls syntactic Font Lock. Its value
|
|
2147 should be a list of elements of this form:
|
|
2148
|
|
2149 @example
|
|
2150 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
|
|
2151 @end example
|
|
2152
|
|
2153 The parts of this element have the same meanings as in the corresponding
|
|
2154 sort of element of @code{font-lock-keywords},
|
|
2155
|
|
2156 @example
|
|
2157 (@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
|
|
2158 @end example
|
|
2159
|
|
2160 However, instead of specifying the value @var{facename} to use for the
|
|
2161 @code{face} property, it specifies the value @var{syntax} to use for the
|
|
2162 @code{syntax-table} property. Here, @var{syntax} can be a variable
|
|
2163 whose value is a syntax table, a syntax entry of the form
|
|
2164 @code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
|
|
2165 value is one of those two types.
|
|
2166 @end defvar
|
|
2167
|
6451
|
2168 @node Hooks
|
|
2169 @section Hooks
|
|
2170 @cindex hooks
|
|
2171
|
|
2172 A @dfn{hook} is a variable where you can store a function or functions
|
|
2173 to be called on a particular occasion by an existing program. Emacs
|
|
2174 provides hooks for the sake of customization. Most often, hooks are set
|
25875
|
2175 up in the init file (@pxref{Init File}), but Lisp programs can set them also.
|
6451
|
2176 @xref{Standard Hooks}, for a list of standard hook variables.
|
|
2177
|
21007
|
2178 @cindex normal hook
|
6451
|
2179 Most of the hooks in Emacs are @dfn{normal hooks}. These variables
|
16056
|
2180 contain lists of functions to be called with no arguments. When the
|
|
2181 hook name ends in @samp{-hook}, that tells you it is normal. We try to
|
|
2182 make all hooks normal, as much as possible, so that you can use them in
|
|
2183 a uniform way.
|
|
2184
|
|
2185 Every major mode function is supposed to run a normal hook called the
|
|
2186 @dfn{mode hook} as the last step of initialization. This makes it easy
|
|
2187 for a user to customize the behavior of the mode, by overriding the
|
21682
|
2188 buffer-local variable assignments already made by the mode. But hooks
|
|
2189 are used in other contexts too. For example, the hook
|
|
2190 @code{suspend-hook} runs just before Emacs suspends itself
|
|
2191 (@pxref{Suspending Emacs}).
|
6451
|
2192
|
|
2193 The recommended way to add a hook function to a normal hook is by
|
|
2194 calling @code{add-hook} (see below). The hook functions may be any of
|
|
2195 the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
|
|
2196 a Function}). Most normal hook variables are initially void;
|
|
2197 @code{add-hook} knows how to deal with this.
|
|
2198
|
21007
|
2199 @cindex abnormal hook
|
16056
|
2200 If the hook variable's name does not end with @samp{-hook}, that
|
25875
|
2201 indicates it is probably an @dfn{abnormal hook}. Then you should look at its
|
16056
|
2202 documentation to see how to use the hook properly.
|
6451
|
2203
|
16056
|
2204 If the variable's name ends in @samp{-functions} or @samp{-hooks},
|
|
2205 then the value is a list of functions, but it is abnormal in that either
|
|
2206 these functions are called with arguments or their values are used in
|
|
2207 some way. You can use @code{add-hook} to add a function to the list,
|
|
2208 but you must take care in writing the function. (A few of these
|
|
2209 variables are actually normal hooks which were named before we
|
|
2210 established the convention of using @samp{-hook} for them.)
|
|
2211
|
|
2212 If the variable's name ends in @samp{-function}, then its value
|
|
2213 is just a single function, not a list of functions.
|
6451
|
2214
|
21682
|
2215 Here's an example that uses a mode hook to turn on Auto Fill mode when
|
|
2216 in Lisp Interaction mode:
|
6451
|
2217
|
|
2218 @example
|
|
2219 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
|
|
2220 @end example
|
|
2221
|
|
2222 At the appropriate time, Emacs uses the @code{run-hooks} function to
|
12098
|
2223 run particular hooks. This function calls the hook functions that have
|
|
2224 been added with @code{add-hook}.
|
6451
|
2225
|
25875
|
2226 @defun run-hooks &rest hookvars
|
6451
|
2227 This function takes one or more hook variable names as arguments, and
|
25875
|
2228 runs each hook in turn. Each argument should be a symbol that is a hook
|
|
2229 variable. These arguments are processed in the order specified.
|
6451
|
2230
|
|
2231 If a hook variable has a non-@code{nil} value, that value may be a
|
|
2232 function or a list of functions. If the value is a function (either a
|
21007
|
2233 lambda expression or a symbol with a function definition), it is called.
|
|
2234 If it is a list, the elements are called, in order. The hook functions
|
|
2235 are called with no arguments. Nowadays, storing a single function in
|
|
2236 the hook variable is semi-obsolete; you should always use a list of
|
|
2237 functions.
|
6451
|
2238
|
12098
|
2239 For example, here's how @code{emacs-lisp-mode} runs its mode hook:
|
6451
|
2240
|
|
2241 @example
|
|
2242 (run-hooks 'emacs-lisp-mode-hook)
|
|
2243 @end example
|
|
2244 @end defun
|
|
2245
|
22138
|
2246 @defun run-hook-with-args hook &rest args
|
|
2247 This function is the way to run an abnormal hook which passes arguments
|
|
2248 to the hook functions. It calls each of the hook functions, passing
|
|
2249 each of them the arguments @var{args}.
|
|
2250 @end defun
|
|
2251
|
|
2252 @defun run-hook-with-args-until-failure hook &rest args
|
|
2253 This function is the way to run an abnormal hook which passes arguments
|
|
2254 to the hook functions, and stops as soon as any hook function fails. It
|
|
2255 calls each of the hook functions, passing each of them the arguments
|
22252
|
2256 @var{args}, until some hook function returns @code{nil}. Then it stops,
|
25875
|
2257 and returns @code{nil} if some hook function returned @code{nil}.
|
|
2258 Otherwise it returns a non-@code{nil} value.
|
22138
|
2259 @end defun
|
|
2260
|
|
2261 @defun run-hook-with-args-until-success hook &rest args
|
|
2262 This function is the way to run an abnormal hook which passes arguments
|
|
2263 to the hook functions, and stops as soon as any hook function succeeds.
|
|
2264 It calls each of the hook functions, passing each of them the arguments
|
|
2265 @var{args}, until some hook function returns non-@code{nil}. Then it
|
22252
|
2266 stops, and returns whatever was returned by the last hook function
|
|
2267 that was called.
|
22138
|
2268 @end defun
|
|
2269
|
12067
|
2270 @defun add-hook hook function &optional append local
|
6451
|
2271 This function is the handy way to add function @var{function} to hook
|
7253
|
2272 variable @var{hook}. The argument @var{function} may be any valid Lisp
|
|
2273 function with the proper number of arguments. For example,
|
6451
|
2274
|
|
2275 @example
|
|
2276 (add-hook 'text-mode-hook 'my-text-hook-function)
|
|
2277 @end example
|
|
2278
|
|
2279 @noindent
|
|
2280 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}.
|
|
2281
|
7253
|
2282 You can use @code{add-hook} for abnormal hooks as well as for normal
|
|
2283 hooks.
|
|
2284
|
6451
|
2285 It is best to design your hook functions so that the order in which they
|
|
2286 are executed does not matter. Any dependence on the order is ``asking
|
|
2287 for trouble.'' However, the order is predictable: normally,
|
|
2288 @var{function} goes at the front of the hook list, so it will be
|
21682
|
2289 executed first (barring another @code{add-hook} call). If the optional
|
|
2290 argument @var{append} is non-@code{nil}, the new hook function goes at
|
|
2291 the end of the hook list and will be executed last.
|
6451
|
2292
|
12067
|
2293 If @var{local} is non-@code{nil}, that says to make the new hook
|
34016
|
2294 function buffer-local in the current buffer and automatically calls
|
|
2295 @code{make-local-hook} to make the hook itself buffer-local.
|
6451
|
2296 @end defun
|
8929
|
2297
|
12067
|
2298 @defun remove-hook hook function &optional local
|
|
2299 This function removes @var{function} from the hook variable @var{hook}.
|
|
2300
|
|
2301 If @var{local} is non-@code{nil}, that says to remove @var{function}
|
21682
|
2302 from the buffer-local hook list instead of from the global hook list.
|
|
2303 If the hook variable itself is not buffer-local, then the value of
|
|
2304 @var{local} makes no difference.
|
12067
|
2305 @end defun
|
8929
|
2306
|
12067
|
2307 @defun make-local-hook hook
|
21682
|
2308 This function makes the hook variable @code{hook} buffer-local in the
|
|
2309 current buffer. When a hook variable is buffer-local, it can have
|
|
2310 buffer-local and global hook functions, and @code{run-hooks} runs all of
|
|
2311 them.
|
8929
|
2312
|
25875
|
2313 This function works by adding @code{t} as an element of the buffer-local
|
|
2314 value. That serves as a flag to use the hook functions listed in the default
|
|
2315 value of the hook variable, as well as those listed in the buffer-local value.
|
21682
|
2316 Since @code{run-hooks} understands this flag, @code{make-local-hook}
|
|
2317 works with all normal hooks. It works for only some non-normal
|
|
2318 hooks---those whose callers have been updated to understand this meaning
|
|
2319 of @code{t}.
|
12234
|
2320
|
12067
|
2321 Do not use @code{make-local-variable} directly for hook variables; it is
|
|
2322 not sufficient.
|
|
2323 @end defun
|