Mercurial > emacs
annotate doc/lispref/modes.texi @ 97366:d2c211c8ceda
(w32_list_system_processes, w32_system_process_attributes): Add prototypes.
(Qeuid, Qegid, Qcomm, Qstate, Qppid, Qpgrp, Qsess, Qttname)
(Qminflt, Qmajflt, Qcminflt, Qcmajflt, Qutime, Qstime, Qcutime)
(Qpri, Qnice, Qthcount, Qstart, Qvsize, Qrss, Qargs, Quser, Qgroup)
(Qetime, Qpcpu, Qpmem, Qtpgid, Qcstime): Add extern declarations.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 09 Aug 2008 17:53:30 +0000 |
parents | 8eba27dae69a |
children | a0397c75f952 |
rev | line source |
---|---|
84089 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, | |
87649 | 4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
84089 | 5 @c See the file elisp.texi for copying conditions. |
84116
0ba80d073e27
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84089
diff
changeset
|
6 @setfilename ../../info/modes |
84089 | 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 * Hooks:: How to use hooks; how to write code that provides hooks. | |
24 * Major Modes:: Defining major modes. | |
25 * Minor Modes:: Defining minor modes. | |
26 * Mode Line Format:: Customizing the text that appears in the mode line. | |
27 * Imenu:: How a mode can provide a menu | |
28 of definitions in the buffer. | |
29 * Font Lock Mode:: How modes can highlight text according to syntax. | |
30 * Desktop Save Mode:: How modes can have buffer state saved between | |
31 Emacs sessions. | |
32 @end menu | |
33 | |
34 @node Hooks | |
35 @section Hooks | |
36 @cindex hooks | |
37 | |
38 A @dfn{hook} is a variable where you can store a function or functions | |
39 to be called on a particular occasion by an existing program. Emacs | |
40 provides hooks for the sake of customization. Most often, hooks are set | |
41 up in the init file (@pxref{Init File}), but Lisp programs can set them also. | |
42 @xref{Standard Hooks}, for a list of standard hook variables. | |
43 | |
44 @cindex normal hook | |
45 Most of the hooks in Emacs are @dfn{normal hooks}. These variables | |
46 contain lists of functions to be called with no arguments. By | |
47 convention, whenever the hook name ends in @samp{-hook}, that tells | |
48 you it is normal. We try to make all hooks normal, as much as | |
49 possible, so that you can use them in a uniform way. | |
50 | |
51 Every major mode function is supposed to run a normal hook called | |
52 the @dfn{mode hook} as the one of the last steps of initialization. | |
53 This makes it easy for a user to customize the behavior of the mode, | |
54 by overriding the buffer-local variable assignments already made by | |
55 the mode. Most minor mode functions also run a mode hook at the end. | |
56 But hooks are used in other contexts too. For example, the hook | |
57 @code{suspend-hook} runs just before Emacs suspends itself | |
58 (@pxref{Suspending Emacs}). | |
59 | |
60 The recommended way to add a hook function to a normal hook is by | |
61 calling @code{add-hook} (see below). The hook functions may be any of | |
62 the valid kinds of functions that @code{funcall} accepts (@pxref{What | |
63 Is a Function}). Most normal hook variables are initially void; | |
64 @code{add-hook} knows how to deal with this. You can add hooks either | |
65 globally or buffer-locally with @code{add-hook}. | |
66 | |
67 @cindex abnormal hook | |
68 If the hook variable's name does not end with @samp{-hook}, that | |
69 indicates it is probably an @dfn{abnormal hook}. That means the hook | |
70 functions are called with arguments, or their return values are used | |
71 in some way. The hook's documentation says how the functions are | |
72 called. You can use @code{add-hook} to add a function to an abnormal | |
73 hook, but you must write the function to follow the hook's calling | |
74 convention. | |
75 | |
76 By convention, abnormal hook names end in @samp{-functions} or | |
77 @samp{-hooks}. If the variable's name ends in @samp{-function}, then | |
78 its value is just a single function, not a list of functions. | |
79 | |
87981
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
80 @menu |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
81 * Running Hooks:: How to run a hook. |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
82 * Setting Hooks:: How to put functions on a hook, or remove them. |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
83 @end menu |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
84 |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
85 @node Running Hooks |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
86 @subsection Running Hooks |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
87 |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
88 At the appropriate times, Emacs uses the @code{run-hooks} function |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
89 and the other functions below to run particular hooks. |
84089 | 90 |
91 @defun run-hooks &rest hookvars | |
92 This function takes one or more normal hook variable names as | |
93 arguments, and runs each hook in turn. Each argument should be a | |
94 symbol that is a normal hook variable. These arguments are processed | |
95 in the order specified. | |
96 | |
97 If a hook variable has a non-@code{nil} value, that value should be a | |
98 list of functions. @code{run-hooks} calls all the functions, one by | |
99 one, with no arguments. | |
100 | |
101 The hook variable's value can also be a single function---either a | |
102 lambda expression or a symbol with a function definition---which | |
103 @code{run-hooks} calls. But this usage is obsolete. | |
104 @end defun | |
105 | |
106 @defun run-hook-with-args hook &rest args | |
107 This function is the way to run an abnormal hook and always call all | |
108 of the hook functions. It calls each of the hook functions one by | |
109 one, passing each of them the arguments @var{args}. | |
110 @end defun | |
111 | |
112 @defun run-hook-with-args-until-failure hook &rest args | |
113 This function is the way to run an abnormal hook until one of the hook | |
114 functions fails. It calls each of the hook functions, passing each of | |
115 them the arguments @var{args}, until some hook function returns | |
116 @code{nil}. It then stops and returns @code{nil}. If none of the | |
117 hook functions return @code{nil}, it returns a non-@code{nil} value. | |
118 @end defun | |
119 | |
120 @defun run-hook-with-args-until-success hook &rest args | |
121 This function is the way to run an abnormal hook until a hook function | |
122 succeeds. It calls each of the hook functions, passing each of them | |
123 the arguments @var{args}, until some hook function returns | |
124 non-@code{nil}. Then it stops, and returns whatever was returned by | |
125 the last hook function that was called. If all hook functions return | |
126 @code{nil}, it returns @code{nil} as well. | |
127 @end defun | |
128 | |
87981
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
129 @node Setting Hooks |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
130 @subsection Setting Hooks |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
131 |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
132 Here's an example that uses a mode hook to turn on Auto Fill mode when |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
133 in Lisp Interaction mode: |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
134 |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
135 @example |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
136 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
137 @end example |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
138 |
84089 | 139 @defun add-hook hook function &optional append local |
140 This function is the handy way to add function @var{function} to hook | |
141 variable @var{hook}. You can use it for abnormal hooks as well as for | |
142 normal hooks. @var{function} can be any Lisp function that can accept | |
143 the proper number of arguments for @var{hook}. For example, | |
144 | |
145 @example | |
146 (add-hook 'text-mode-hook 'my-text-hook-function) | |
147 @end example | |
148 | |
149 @noindent | |
150 adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. | |
151 | |
152 If @var{function} is already present in @var{hook} (comparing using | |
153 @code{equal}), then @code{add-hook} does not add it a second time. | |
154 | |
87981
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
155 If @var{function} has a non-@code{nil} property |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
156 @code{permanent-local-hook}, then @code{kill-all-local-variables} (or |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
157 changing major modes) won't delete it from the hook variable's local |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
158 value. |
8eba27dae69a
(Running Hooks, Setting Hooks): New nodes.
Richard M. Stallman <rms@gnu.org>
parents:
87649
diff
changeset
|
159 |
84089 | 160 It is best to design your hook functions so that the order in which they |
161 are executed does not matter. Any dependence on the order is ``asking | |
162 for trouble.'' However, the order is predictable: normally, | |
163 @var{function} goes at the front of the hook list, so it will be | |
164 executed first (barring another @code{add-hook} call). If the optional | |
165 argument @var{append} is non-@code{nil}, the new hook function goes at | |
166 the end of the hook list and will be executed last. | |
167 | |
168 @code{add-hook} can handle the cases where @var{hook} is void or its | |
169 value is a single function; it sets or changes the value to a list of | |
170 functions. | |
171 | |
172 If @var{local} is non-@code{nil}, that says to add @var{function} to | |
173 the buffer-local hook list instead of to the global hook list. If | |
174 needed, this makes the hook buffer-local and adds @code{t} to the | |
175 buffer-local value. The latter acts as a flag to run the hook | |
176 functions in the default value as well as in the local value. | |
177 @end defun | |
178 | |
179 @defun remove-hook hook function &optional local | |
180 This function removes @var{function} from the hook variable | |
181 @var{hook}. It compares @var{function} with elements of @var{hook} | |
182 using @code{equal}, so it works for both symbols and lambda | |
183 expressions. | |
184 | |
185 If @var{local} is non-@code{nil}, that says to remove @var{function} | |
186 from the buffer-local hook list instead of from the global hook list. | |
187 @end defun | |
188 | |
189 @node Major Modes | |
190 @section Major Modes | |
191 @cindex major mode | |
192 | |
193 Major modes specialize Emacs for editing particular kinds of text. | |
194 Each buffer has only one major mode at a time. For each major mode | |
195 there is a function to switch to that mode in the current buffer; its | |
196 name should end in @samp{-mode}. These functions work by setting | |
197 buffer-local variable bindings and other data associated with the | |
198 buffer, such as a local keymap. The effect lasts until you switch | |
199 to another major mode in the same buffer. | |
200 | |
201 @menu | |
202 * Major Mode Basics:: | |
203 * Major Mode Conventions:: Coding conventions for keymaps, etc. | |
204 * Auto Major Mode:: How Emacs chooses the major mode automatically. | |
205 * Mode Help:: Finding out how to use a mode. | |
206 * Derived Modes:: Defining a new major mode based on another major | |
207 mode. | |
208 * Generic Modes:: Defining a simple major mode that supports | |
209 comment syntax and Font Lock mode. | |
210 * Mode Hooks:: Hooks run at the end of major mode functions. | |
211 * Example Major Modes:: Text mode and Lisp modes. | |
212 @end menu | |
213 | |
214 @node Major Mode Basics | |
215 @subsection Major Mode Basics | |
216 @cindex Fundamental mode | |
217 | |
218 The least specialized major mode is called @dfn{Fundamental mode}. | |
219 This mode has no mode-specific definitions or variable settings, so each | |
220 Emacs command behaves in its default manner, and each option is in its | |
221 default state. All other major modes redefine various keys and options. | |
222 For example, Lisp Interaction mode provides special key bindings for | |
223 @kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB} | |
224 (@code{lisp-indent-line}), and other keys. | |
225 | |
226 When you need to write several editing commands to help you perform a | |
227 specialized editing task, creating a new major mode is usually a good | |
228 idea. In practice, writing a major mode is easy (in contrast to | |
229 writing a minor mode, which is often difficult). | |
230 | |
231 If the new mode is similar to an old one, it is often unwise to | |
232 modify the old one to serve two purposes, since it may become harder | |
233 to use and maintain. Instead, copy and rename an existing major mode | |
234 definition and alter the copy---or use @code{define-derived-mode} to | |
235 define a @dfn{derived mode} (@pxref{Derived Modes}). For example, | |
236 Rmail Edit mode is a major mode that is very similar to Text mode | |
237 except that it provides two additional commands. Its definition is | |
238 distinct from that of Text mode, but uses that of Text mode. | |
239 | |
240 Even if the new mode is not an obvious derivative of any other mode, | |
241 it is convenient to use @code{define-derived-mode} with a @code{nil} | |
242 parent argument, since it automatically enforces the most important | |
243 coding conventions for you. | |
244 | |
245 For a very simple programming language major mode that handles | |
246 comments and fontification, you can use @code{define-generic-mode}. | |
247 @xref{Generic Modes}. | |
248 | |
249 Rmail Edit mode offers an example of changing the major mode | |
250 temporarily for a buffer, so it can be edited in a different way (with | |
251 ordinary Emacs commands rather than Rmail commands). In such cases, the | |
252 temporary major mode usually provides a command to switch back to the | |
253 buffer's usual mode (Rmail mode, in this case). You might be tempted to | |
254 present the temporary redefinitions inside a recursive edit and restore | |
255 the usual ones when the user exits; but this is a bad idea because it | |
256 constrains the user's options when it is done in more than one buffer: | |
257 recursive edits must be exited most-recently-entered first. Using an | |
258 alternative major mode avoids this limitation. @xref{Recursive | |
259 Editing}. | |
260 | |
261 The standard GNU Emacs Lisp library directory tree contains the code | |
262 for several major modes, in files such as @file{text-mode.el}, | |
263 @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and | |
264 @file{rmail.el}. They are found in various subdirectories of the | |
265 @file{lisp} directory. You can study these libraries to see how modes | |
266 are written. Text mode is perhaps the simplest major mode aside from | |
267 Fundamental mode. Rmail mode is a complicated and specialized mode. | |
268 | |
269 @node Major Mode Conventions | |
270 @subsection Major Mode Conventions | |
271 @cindex major mode conventions | |
272 @cindex conventions for writing major modes | |
273 | |
274 The code for existing major modes follows various coding conventions, | |
275 including conventions for local keymap and syntax table initialization, | |
276 global names, and hooks. Please follow these conventions when you | |
277 define a new major mode. (Fundamental mode is an exception to many | |
278 of these conventions, because its definition is to present the global | |
279 state of Emacs.) | |
280 | |
281 This list of conventions is only partial, because each major mode | |
282 should aim for consistency in general with other Emacs major modes. | |
283 This makes Emacs as a whole more coherent. It is impossible to list | |
284 here all the possible points where this issue might come up; if the | |
285 Emacs developers point out an area where your major mode deviates from | |
286 the usual conventions, please make it compatible. | |
287 | |
288 @itemize @bullet | |
289 @item | |
290 Define a command whose name ends in @samp{-mode}, with no arguments, | |
291 that switches to the new mode in the current buffer. This command | |
292 should set up the keymap, syntax table, and buffer-local variables in an | |
293 existing buffer, without changing the buffer's contents. | |
294 | |
295 @item | |
296 Write a documentation string for this command that describes the | |
297 special commands available in this mode. @kbd{C-h m} | |
298 (@code{describe-mode}) in your mode will display this string. | |
299 | |
300 The documentation string may include the special documentation | |
301 substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and | |
302 @samp{\<@var{keymap}>}, which enable the documentation to adapt | |
303 automatically to the user's own key bindings. @xref{Keys in | |
304 Documentation}. | |
305 | |
306 @item | |
307 The major mode command should start by calling | |
308 @code{kill-all-local-variables}. This runs the normal hook | |
309 @code{change-major-mode-hook}, then gets rid of the buffer-local | |
310 variables of the major mode previously in effect. @xref{Creating | |
311 Buffer-Local}. | |
312 | |
313 @item | |
314 The major mode command should set the variable @code{major-mode} to the | |
315 major mode command symbol. This is how @code{describe-mode} discovers | |
316 which documentation to print. | |
317 | |
318 @item | |
319 The major mode command should set the variable @code{mode-name} to the | |
320 ``pretty'' name of the mode, as a string. This string appears in the | |
321 mode line. | |
322 | |
323 @item | |
324 @cindex functions in modes | |
325 Since all global names are in the same name space, all the global | |
326 variables, constants, and functions that are part of the mode should | |
327 have names that start with the major mode name (or with an abbreviation | |
328 of it if the name is long). @xref{Coding Conventions}. | |
329 | |
330 @item | |
331 In a major mode for editing some kind of structured text, such as a | |
332 programming language, indentation of text according to structure is | |
333 probably useful. So the mode should set @code{indent-line-function} | |
334 to a suitable function, and probably customize other variables | |
335 for indentation. | |
336 | |
337 @item | |
338 @cindex keymaps in modes | |
339 The major mode should usually have its own keymap, which is used as the | |
340 local keymap in all buffers in that mode. The major mode command should | |
341 call @code{use-local-map} to install this local map. @xref{Active | |
342 Keymaps}, for more information. | |
343 | |
344 This keymap should be stored permanently in a global variable named | |
345 @code{@var{modename}-mode-map}. Normally the library that defines the | |
346 mode sets this variable. | |
347 | |
348 @xref{Tips for Defining}, for advice about how to write the code to set | |
349 up the mode's keymap variable. | |
350 | |
351 @item | |
352 The key sequences bound in a major mode keymap should usually start with | |
353 @kbd{C-c}, followed by a control character, a digit, or @kbd{@{}, | |
354 @kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation | |
355 characters are reserved for minor modes, and ordinary letters are | |
356 reserved for users. | |
357 | |
358 A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and | |
359 @kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally | |
360 be some kind of ``moving forward and backward,'' but this does not | |
361 necessarily mean cursor motion. | |
362 | |
363 It is legitimate for a major mode to rebind a standard key sequence if | |
364 it provides a command that does ``the same job'' in a way better | |
365 suited to the text this mode is used for. For example, a major mode | |
366 for editing a programming language might redefine @kbd{C-M-a} to | |
367 ``move to the beginning of a function'' in a way that works better for | |
368 that language. | |
369 | |
370 It is also legitimate for a major mode to rebind a standard key | |
371 sequence whose standard meaning is rarely useful in that mode. For | |
372 instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is | |
373 rarely of any use in the minibuffer. Major modes such as Dired or | |
374 Rmail that do not allow self-insertion of text can reasonably redefine | |
375 letters and other printing characters as special commands. | |
376 | |
377 @item | |
378 Major modes modes for editing text should not define @key{RET} to do | |
379 anything other than insert a newline. However, it is ok for | |
380 specialized modes for text that users don't directly edit, such as | |
381 Dired and Info modes, to redefine @key{RET} to do something entirely | |
382 different. | |
383 | |
384 @item | |
385 Major modes should not alter options that are primarily a matter of user | |
386 preference, such as whether Auto-Fill mode is enabled. Leave this to | |
387 each user to decide. However, a major mode should customize other | |
388 variables so that Auto-Fill mode will work usefully @emph{if} the user | |
389 decides to use it. | |
390 | |
391 @item | |
392 @cindex syntax tables in modes | |
393 The mode may have its own syntax table or may share one with other | |
394 related modes. If it has its own syntax table, it should store this in | |
395 a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax | |
396 Tables}. | |
397 | |
398 @item | |
399 If the mode handles a language that has a syntax for comments, it should | |
400 set the variables that define the comment syntax. @xref{Options for | |
401 Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. | |
402 | |
403 @item | |
404 @cindex abbrev tables in modes | |
405 The mode may have its own abbrev table or may share one with other | |
406 related modes. If it has its own abbrev table, it should store this | |
407 in a variable named @code{@var{modename}-mode-abbrev-table}. If the | |
408 major mode command defines any abbrevs itself, it should pass @code{t} | |
409 for the @var{system-flag} argument to @code{define-abbrev}. | |
410 @xref{Defining Abbrevs}. | |
411 | |
412 @item | |
413 The mode should specify how to do highlighting for Font Lock mode, by | |
414 setting up a buffer-local value for the variable | |
415 @code{font-lock-defaults} (@pxref{Font Lock Mode}). | |
416 | |
417 @item | |
418 The mode should specify how Imenu should find the definitions or | |
419 sections of a buffer, by setting up a buffer-local value for the | |
420 variable @code{imenu-generic-expression}, for the two variables | |
421 @code{imenu-prev-index-position-function} and | |
422 @code{imenu-extract-index-name-function}, or for the variable | |
423 @code{imenu-create-index-function} (@pxref{Imenu}). | |
424 | |
425 @item | |
426 The mode can specify a local value for | |
427 @code{eldoc-documentation-function} to tell ElDoc mode how to handle | |
428 this mode. | |
429 | |
430 @item | |
431 Use @code{defvar} or @code{defcustom} to set mode-related variables, so | |
432 that they are not reinitialized if they already have a value. (Such | |
433 reinitialization could discard customizations made by the user.) | |
434 | |
435 @item | |
436 @cindex buffer-local variables in modes | |
437 To make a buffer-local binding for an Emacs customization variable, use | |
438 @code{make-local-variable} in the major mode command, not | |
439 @code{make-variable-buffer-local}. The latter function would make the | |
440 variable local to every buffer in which it is subsequently set, which | |
441 would affect buffers that do not use this mode. It is undesirable for a | |
442 mode to have such global effects. @xref{Buffer-Local Variables}. | |
443 | |
444 With rare exceptions, the only reasonable way to use | |
445 @code{make-variable-buffer-local} in a Lisp package is for a variable | |
446 which is used only within that package. Using it on a variable used by | |
447 other packages would interfere with them. | |
448 | |
449 @item | |
450 @cindex mode hook | |
451 @cindex major mode hook | |
452 Each major mode should have a normal @dfn{mode hook} named | |
453 @code{@var{modename}-mode-hook}. The very last thing the major mode command | |
454 should do is to call @code{run-mode-hooks}. This runs the mode hook, | |
455 and then runs the normal hook @code{after-change-major-mode-hook}. | |
456 @xref{Mode Hooks}. | |
457 | |
458 @item | |
459 The major mode command may start by calling some other major mode | |
460 command (called the @dfn{parent mode}) and then alter some of its | |
461 settings. A mode that does this is called a @dfn{derived mode}. The | |
462 recommended way to define one is to use @code{define-derived-mode}, | |
463 but this is not required. Such a mode should call the parent mode | |
464 command inside a @code{delay-mode-hooks} form. (Using | |
465 @code{define-derived-mode} does this automatically.) @xref{Derived | |
466 Modes}, and @ref{Mode Hooks}. | |
467 | |
468 @item | |
469 If something special should be done if the user switches a buffer from | |
470 this mode to any other major mode, this mode can set up a buffer-local | |
471 value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}). | |
472 | |
473 @item | |
474 If this mode is appropriate only for specially-prepared text, then the | |
475 major mode command symbol should have a property named @code{mode-class} | |
476 with value @code{special}, put on as follows: | |
477 | |
478 @kindex mode-class @r{(property)} | |
479 @cindex @code{special} | |
480 @example | |
481 (put 'funny-mode 'mode-class 'special) | |
482 @end example | |
483 | |
484 @noindent | |
485 This tells Emacs that new buffers created while the current buffer is | |
486 in Funny mode should not inherit Funny mode, in case | |
487 @code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail, | |
488 and Buffer List use this feature. | |
489 | |
490 @item | |
491 If you want to make the new mode the default for files with certain | |
492 recognizable names, add an element to @code{auto-mode-alist} to select | |
493 the mode for those file names (@pxref{Auto Major Mode}). If you | |
494 define the mode command to autoload, you should add this element in | |
495 the same file that calls @code{autoload}. If you use an autoload | |
496 cookie for the mode command, you can also use an autoload cookie for | |
497 the form that adds the element (@pxref{autoload cookie}). If you do | |
498 not autoload the mode command, it is sufficient to add the element in | |
499 the file that contains the mode definition. | |
500 | |
501 @item | |
502 In the comments that document the file, you should provide a sample | |
503 @code{autoload} form and an example of how to add to | |
504 @code{auto-mode-alist}, that users can include in their init files | |
505 (@pxref{Init File}). | |
506 | |
507 @item | |
508 @cindex mode loading | |
509 The top-level forms in the file defining the mode should be written so | |
510 that they may be evaluated more than once without adverse consequences. | |
511 Even if you never load the file more than once, someone else will. | |
512 @end itemize | |
513 | |
514 @node Auto Major Mode | |
515 @subsection How Emacs Chooses a Major Mode | |
516 @cindex major mode, automatic selection | |
517 | |
518 Based on information in the file name or in the file itself, Emacs | |
519 automatically selects a major mode for the new buffer when a file is | |
520 visited. It also processes local variables specified in the file text. | |
521 | |
522 @deffn Command fundamental-mode | |
523 Fundamental mode is a major mode that is not specialized for anything | |
524 in particular. Other major modes are defined in effect by comparison | |
525 with this one---their definitions say what to change, starting from | |
526 Fundamental mode. The @code{fundamental-mode} function does @emph{not} | |
527 run any mode hooks; you're not supposed to customize it. (If you want Emacs | |
528 to behave differently in Fundamental mode, change the @emph{global} | |
529 state of Emacs.) | |
530 @end deffn | |
531 | |
532 @deffn Command normal-mode &optional find-file | |
533 This function establishes the proper major mode and buffer-local variable | |
534 bindings for the current buffer. First it calls @code{set-auto-mode} | |
535 (see below), then it runs @code{hack-local-variables} to parse, and | |
536 bind or evaluate as appropriate, the file's local variables | |
537 (@pxref{File Local Variables}). | |
538 | |
539 If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, | |
540 @code{normal-mode} assumes that the @code{find-file} function is calling | |
541 it. In this case, it may process local variables in the @samp{-*-} | |
542 line or at the end of the file. The variable | |
543 @code{enable-local-variables} controls whether to do so. @xref{File | |
544 Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, | |
545 for the syntax of the local variables section of a file. | |
546 | |
547 If you run @code{normal-mode} interactively, the argument | |
548 @var{find-file} is normally @code{nil}. In this case, | |
549 @code{normal-mode} unconditionally processes any file local variables. | |
550 | |
551 If @code{normal-mode} processes the local variables list and this list | |
552 specifies a major mode, that mode overrides any mode chosen by | |
553 @code{set-auto-mode}. If neither @code{set-auto-mode} nor | |
554 @code{hack-local-variables} specify a major mode, the buffer stays in | |
555 the major mode determined by @code{default-major-mode} (see below). | |
556 | |
557 @cindex file mode specification error | |
558 @code{normal-mode} uses @code{condition-case} around the call to the | |
559 major mode function, so errors are caught and reported as a @samp{File | |
560 mode specification error}, followed by the original error message. | |
561 @end deffn | |
562 | |
563 @defun set-auto-mode &optional keep-mode-if-same | |
564 @cindex visited file mode | |
565 This function selects the major mode that is appropriate for the | |
566 current buffer. It bases its decision (in order of precedence) on | |
567 the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using | |
568 @code{interpreter-mode-alist}), on the text at the beginning of the | |
569 buffer (using @code{magic-mode-alist}), and finally on the visited | |
570 file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How | |
571 Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this | |
572 function does not look for the @samp{mode:} local variable near the | |
573 end of a file; the @code{hack-local-variables} function does that. | |
574 If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode} | |
575 does not check the @w{@samp{-*-}} line for a mode tag either. | |
576 | |
577 If @var{keep-mode-if-same} is non-@code{nil}, this function does not | |
578 call the mode command if the buffer is already in the proper major | |
579 mode. For instance, @code{set-visited-file-name} sets this to | |
580 @code{t} to avoid killing buffer local variables that the user may | |
581 have set. | |
582 @end defun | |
583 | |
584 @defopt default-major-mode | |
585 This variable holds the default major mode for new buffers. The | |
586 standard value is @code{fundamental-mode}. | |
587 | |
588 If the value of @code{default-major-mode} is @code{nil}, Emacs uses | |
589 the (previously) current buffer's major mode as the default major mode | |
590 of a new buffer. However, if that major mode symbol has a @code{mode-class} | |
591 property with value @code{special}, then it is not used for new buffers; | |
592 Fundamental mode is used instead. The modes that have this property are | |
593 those such as Dired and Rmail that are useful only with text that has | |
594 been specially prepared. | |
595 @end defopt | |
596 | |
597 @defun set-buffer-major-mode buffer | |
598 This function sets the major mode of @var{buffer} to the value of | |
599 @code{default-major-mode}; if that variable is @code{nil}, it uses the | |
600 current buffer's major mode (if that is suitable). As an exception, | |
601 if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to | |
602 @code{initial-major-mode}. | |
603 | |
604 The low-level primitives for creating buffers do not use this function, | |
605 but medium-level commands such as @code{switch-to-buffer} and | |
606 @code{find-file-noselect} use it whenever they create buffers. | |
607 @end defun | |
608 | |
609 @defopt initial-major-mode | |
610 @cindex @samp{*scratch*} | |
611 The value of this variable determines the major mode of the initial | |
612 @samp{*scratch*} buffer. The value should be a symbol that is a major | |
613 mode command. The default value is @code{lisp-interaction-mode}. | |
614 @end defopt | |
615 | |
616 @defvar interpreter-mode-alist | |
617 This variable specifies major modes to use for scripts that specify a | |
618 command interpreter in a @samp{#!} line. Its value is an alist with | |
619 elements of the form @code{(@var{interpreter} . @var{mode})}; for | |
620 example, @code{("perl" . perl-mode)} is one element present by | |
621 default. The element says to use mode @var{mode} if the file | |
622 specifies an interpreter which matches @var{interpreter}. | |
623 @end defvar | |
624 | |
625 @defvar magic-mode-alist | |
626 This variable's value is an alist with elements of the form | |
627 @code{(@var{regexp} . @var{function})}, where @var{regexp} is a | |
628 regular expression and @var{function} is a function or @code{nil}. | |
629 After visiting a file, @code{set-auto-mode} calls @var{function} if | |
630 the text at the beginning of the buffer matches @var{regexp} and | |
631 @var{function} is non-@code{nil}; if @var{function} is @code{nil}, | |
632 @code{auto-mode-alist} gets to decide the mode. | |
633 @end defvar | |
634 | |
635 @defvar magic-fallback-mode-alist | |
636 This works like @code{magic-mode-alist}, except that it is handled | |
637 only if @code{auto-mode-alist} does not specify a mode for this file. | |
638 @end defvar | |
639 | |
640 @defvar auto-mode-alist | |
641 This variable contains an association list of file name patterns | |
642 (regular expressions) and corresponding major mode commands. Usually, | |
643 the file name patterns test for suffixes, such as @samp{.el} and | |
644 @samp{.c}, but this need not be the case. An ordinary element of the | |
645 alist looks like @code{(@var{regexp} . @var{mode-function})}. | |
646 | |
647 For example, | |
648 | |
649 @smallexample | |
650 @group | |
651 (("\\`/tmp/fol/" . text-mode) | |
652 ("\\.texinfo\\'" . texinfo-mode) | |
653 ("\\.texi\\'" . texinfo-mode) | |
654 @end group | |
655 @group | |
656 ("\\.el\\'" . emacs-lisp-mode) | |
657 ("\\.c\\'" . c-mode) | |
658 ("\\.h\\'" . c-mode) | |
659 @dots{}) | |
660 @end group | |
661 @end smallexample | |
662 | |
663 When you visit a file whose expanded file name (@pxref{File Name | |
664 Expansion}), with version numbers and backup suffixes removed using | |
665 @code{file-name-sans-versions} (@pxref{File Name Components}), matches | |
666 a @var{regexp}, @code{set-auto-mode} calls the corresponding | |
667 @var{mode-function}. This feature enables Emacs to select the proper | |
668 major mode for most files. | |
669 | |
670 If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} | |
671 @var{function} t)}, then after calling @var{function}, Emacs searches | |
672 @code{auto-mode-alist} again for a match against the portion of the file | |
673 name that did not match before. This feature is useful for | |
674 uncompression packages: an entry of the form @code{("\\.gz\\'" | |
675 @var{function} t)} can uncompress the file and then put the uncompressed | |
676 file in the proper mode according to the name sans @samp{.gz}. | |
677 | |
678 Here is an example of how to prepend several pattern pairs to | |
679 @code{auto-mode-alist}. (You might use this sort of expression in your | |
680 init file.) | |
681 | |
682 @smallexample | |
683 @group | |
684 (setq auto-mode-alist | |
685 (append | |
686 ;; @r{File name (within directory) starts with a dot.} | |
687 '(("/\\.[^/]*\\'" . fundamental-mode) | |
688 ;; @r{File name has no dot.} | |
689 ("[^\\./]*\\'" . fundamental-mode) | |
690 ;; @r{File name ends in @samp{.C}.} | |
691 ("\\.C\\'" . c++-mode)) | |
692 auto-mode-alist)) | |
693 @end group | |
694 @end smallexample | |
695 @end defvar | |
696 | |
697 @node Mode Help | |
698 @subsection Getting Help about a Major Mode | |
699 @cindex mode help | |
700 @cindex help for major mode | |
701 @cindex documentation for major mode | |
702 | |
703 The @code{describe-mode} function is used to provide information | |
704 about major modes. It is normally called with @kbd{C-h m}. The | |
705 @code{describe-mode} function uses the value of @code{major-mode}, | |
706 which is why every major mode function needs to set the | |
707 @code{major-mode} variable. | |
708 | |
709 @deffn Command describe-mode | |
710 This function displays the documentation of the current major mode. | |
711 | |
712 The @code{describe-mode} function calls the @code{documentation} | |
713 function using the value of @code{major-mode} as an argument. Thus, it | |
714 displays the documentation string of the major mode function. | |
715 (@xref{Accessing Documentation}.) | |
716 @end deffn | |
717 | |
718 @defvar major-mode | |
719 This buffer-local variable holds the symbol for the current buffer's | |
720 major mode. This symbol should have a function definition that is the | |
721 command to switch to that major mode. The @code{describe-mode} | |
722 function uses the documentation string of the function as the | |
723 documentation of the major mode. | |
724 @end defvar | |
725 | |
726 @node Derived Modes | |
727 @subsection Defining Derived Modes | |
728 @cindex derived mode | |
729 | |
730 It's often useful to define a new major mode in terms of an existing | |
731 one. An easy way to do this is to use @code{define-derived-mode}. | |
732 | |
733 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} | |
734 This construct defines @var{variant} as a major mode command, using | |
735 @var{name} as the string form of the mode name. @var{variant} and | |
736 @var{parent} should be unquoted symbols. | |
737 | |
738 The new command @var{variant} is defined to call the function | |
739 @var{parent}, then override certain aspects of that parent mode: | |
740 | |
741 @itemize @bullet | |
742 @item | |
743 The new mode has its own sparse keymap, named | |
744 @code{@var{variant}-map}. @code{define-derived-mode} | |
745 makes the parent mode's keymap the parent of the new map, unless | |
746 @code{@var{variant}-map} is already set and already has a parent. | |
747 | |
748 @item | |
749 The new mode has its own syntax table, kept in the variable | |
750 @code{@var{variant}-syntax-table}, unless you override this using the | |
751 @code{:syntax-table} keyword (see below). @code{define-derived-mode} | |
752 makes the parent mode's syntax-table the parent of | |
753 @code{@var{variant}-syntax-table}, unless the latter is already set | |
754 and already has a parent different from the standard syntax table. | |
755 | |
756 @item | |
757 The new mode has its own abbrev table, kept in the variable | |
758 @code{@var{variant}-abbrev-table}, unless you override this using the | |
759 @code{:abbrev-table} keyword (see below). | |
760 | |
761 @item | |
762 The new mode has its own mode hook, @code{@var{variant}-hook}. It | |
763 runs this hook, after running the hooks of its ancestor modes, with | |
764 @code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. | |
765 @end itemize | |
766 | |
767 In addition, you can specify how to override other aspects of | |
768 @var{parent} with @var{body}. The command @var{variant} | |
769 evaluates the forms in @var{body} after setting up all its usual | |
770 overrides, just before running the mode hooks. | |
771 | |
772 You can also specify @code{nil} for @var{parent}. This gives the new | |
773 mode no parent. Then @code{define-derived-mode} behaves as described | |
774 above, but, of course, omits all actions connected with @var{parent}. | |
775 | |
776 The argument @var{docstring} specifies the documentation string for | |
777 the new mode. @code{define-derived-mode} adds some general | |
778 information about the mode's hook, followed by the mode's keymap, at | |
779 the end of this docstring. If you omit @var{docstring}, | |
780 @code{define-derived-mode} generates a documentation string. | |
781 | |
782 The @var{keyword-args} are pairs of keywords and values. The values | |
783 are evaluated. The following keywords are currently supported: | |
784 | |
785 @table @code | |
786 @item :syntax-table | |
787 You can use this to explicitly specify a syntax table for the new | |
788 mode. If you specify a @code{nil} value, the new mode uses the same | |
789 syntax table as @var{parent}, or the standard syntax table if | |
790 @var{parent} is @code{nil}. (Note that this does @emph{not} follow | |
791 the convention used for non-keyword arguments that a @code{nil} value | |
792 is equivalent with not specifying the argument.) | |
793 | |
794 @item :abbrev-table | |
795 You can use this to explicitly specify an abbrev table for the new | |
796 mode. If you specify a @code{nil} value, the new mode uses the same | |
797 abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} | |
798 if @var{parent} is @code{nil}. (Again, a @code{nil} value is | |
799 @emph{not} equivalent to not specifying this keyword.) | |
800 | |
801 @item :group | |
802 If this is specified, the value should be the customization group for | |
803 this mode. (Not all major modes have one.) Only the (still | |
804 experimental and unadvertised) command @code{customize-mode} currently | |
805 uses this. @code{define-derived-mode} does @emph{not} automatically | |
806 define the specified customization group. | |
807 @end table | |
808 | |
809 Here is a hypothetical example: | |
810 | |
811 @example | |
812 (define-derived-mode hypertext-mode | |
813 text-mode "Hypertext" | |
814 "Major mode for hypertext. | |
815 \\@{hypertext-mode-map@}" | |
816 (setq case-fold-search nil)) | |
817 | |
818 (define-key hypertext-mode-map | |
819 [down-mouse-3] 'do-hyper-link) | |
820 @end example | |
821 | |
822 Do not write an @code{interactive} spec in the definition; | |
823 @code{define-derived-mode} does that automatically. | |
824 @end defmac | |
825 | |
826 @node Generic Modes | |
827 @subsection Generic Modes | |
828 @cindex generic mode | |
829 | |
830 @dfn{Generic modes} are simple major modes with basic support for | |
831 comment syntax and Font Lock mode. To define a generic mode, use the | |
832 macro @code{define-generic-mode}. See the file @file{generic-x.el} | |
833 for some examples of the use of @code{define-generic-mode}. | |
834 | |
835 @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring | |
836 This macro defines a generic mode command named @var{mode} (a symbol, | |
837 not quoted). The optional argument @var{docstring} is the | |
838 documentation for the mode command. If you do not supply it, | |
839 @code{define-generic-mode} generates one by default. | |
840 | |
841 The argument @var{comment-list} is a list in which each element is | |
842 either a character, a string of one or two characters, or a cons cell. | |
843 A character or a string is set up in the mode's syntax table as a | |
844 ``comment starter.'' If the entry is a cons cell, the @sc{car} is set | |
845 up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' | |
846 (Use @code{nil} for the latter if you want comments to end at the end | |
847 of the line.) Note that the syntax table mechanism has limitations | |
848 about what comment starters and enders are actually possible. | |
849 @xref{Syntax Tables}. | |
850 | |
851 The argument @var{keyword-list} is a list of keywords to highlight | |
852 with @code{font-lock-keyword-face}. Each keyword should be a string. | |
853 Meanwhile, @var{font-lock-list} is a list of additional expressions to | |
854 highlight. Each element of this list should have the same form as an | |
855 element of @code{font-lock-keywords}. @xref{Search-based | |
856 Fontification}. | |
857 | |
858 The argument @var{auto-mode-list} is a list of regular expressions to | |
859 add to the variable @code{auto-mode-alist}. They are added by the execution | |
860 of the @code{define-generic-mode} form, not by expanding the macro call. | |
861 | |
862 Finally, @var{function-list} is a list of functions for the mode | |
863 command to call for additional setup. It calls these functions just | |
864 before it runs the mode hook variable @code{@var{mode}-hook}. | |
865 @end defmac | |
866 | |
867 @node Mode Hooks | |
868 @subsection Mode Hooks | |
869 | |
870 Every major mode function should finish by running its mode hook and | |
871 the mode-independent normal hook @code{after-change-major-mode-hook}. | |
872 It does this by calling @code{run-mode-hooks}. If the major mode is a | |
873 derived mode, that is if it calls another major mode (the parent mode) | |
874 in its body, it should do this inside @code{delay-mode-hooks} so that | |
875 the parent won't run these hooks itself. Instead, the derived mode's | |
876 call to @code{run-mode-hooks} runs the parent's mode hook too. | |
877 @xref{Major Mode Conventions}. | |
878 | |
879 Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. | |
880 When user-implemented major modes have not been updated to use it, | |
881 they won't entirely follow these conventions: they may run the | |
882 parent's mode hook too early, or fail to run | |
883 @code{after-change-major-mode-hook}. If you encounter such a major | |
884 mode, please correct it to follow these conventions. | |
885 | |
886 When you defined a major mode using @code{define-derived-mode}, it | |
887 automatically makes sure these conventions are followed. If you | |
888 define a major mode ``by hand,'' not using @code{define-derived-mode}, | |
889 use the following functions to handle these conventions automatically. | |
890 | |
891 @defun run-mode-hooks &rest hookvars | |
892 Major modes should run their mode hook using this function. It is | |
893 similar to @code{run-hooks} (@pxref{Hooks}), but it also runs | |
894 @code{after-change-major-mode-hook}. | |
895 | |
896 When this function is called during the execution of a | |
897 @code{delay-mode-hooks} form, it does not run the hooks immediately. | |
898 Instead, it arranges for the next call to @code{run-mode-hooks} to run | |
899 them. | |
900 @end defun | |
901 | |
902 @defmac delay-mode-hooks body@dots{} | |
903 When one major mode command calls another, it should do so inside of | |
904 @code{delay-mode-hooks}. | |
905 | |
906 This macro executes @var{body}, but tells all @code{run-mode-hooks} | |
907 calls during the execution of @var{body} to delay running their hooks. | |
908 The hooks will actually run during the next call to | |
909 @code{run-mode-hooks} after the end of the @code{delay-mode-hooks} | |
910 construct. | |
911 @end defmac | |
912 | |
913 @defvar after-change-major-mode-hook | |
914 This is a normal hook run by @code{run-mode-hooks}. It is run at the | |
915 very end of every properly-written major mode function. | |
916 @end defvar | |
917 | |
918 @node Example Major Modes | |
919 @subsection Major Mode Examples | |
920 | |
921 Text mode is perhaps the simplest mode besides Fundamental mode. | |
922 Here are excerpts from @file{text-mode.el} that illustrate many of | |
923 the conventions listed above: | |
924 | |
925 @smallexample | |
926 @group | |
927 ;; @r{Create the syntax table for this mode.} | |
928 (defvar text-mode-syntax-table | |
929 (let ((st (make-syntax-table))) | |
930 (modify-syntax-entry ?\" ". " st) | |
931 (modify-syntax-entry ?\\ ". " st) | |
932 ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. | |
933 (modify-syntax-entry ?' "w p" st) | |
934 st) | |
935 "Syntax table used while in `text-mode'.") | |
936 @end group | |
937 | |
938 ;; @r{Create the keymap for this mode.} | |
939 @group | |
940 (defvar text-mode-map | |
941 (let ((map (make-sparse-keymap))) | |
942 (define-key map "\e\t" 'ispell-complete-word) | |
943 (define-key map "\es" 'center-line) | |
944 (define-key map "\eS" 'center-paragraph) | |
945 map) | |
946 "Keymap for `text-mode'. | |
947 Many other modes, such as Mail mode, Outline mode | |
948 and Indented Text mode, inherit all the commands | |
949 defined in this map.") | |
950 @end group | |
951 @end smallexample | |
952 | |
953 Here is how the actual mode command is defined now: | |
954 | |
955 @smallexample | |
956 @group | |
957 (define-derived-mode text-mode nil "Text" | |
958 "Major mode for editing text written for humans to read. | |
959 In this mode, paragraphs are delimited only by blank or white lines. | |
960 You can thus get the full benefit of adaptive filling | |
961 (see the variable `adaptive-fill-mode'). | |
962 \\@{text-mode-map@} | |
963 Turning on Text mode runs the normal hook `text-mode-hook'." | |
964 @end group | |
965 @group | |
966 (make-local-variable 'text-mode-variant) | |
967 (setq text-mode-variant t) | |
968 ;; @r{These two lines are a feature added recently.} | |
969 (set (make-local-variable 'require-final-newline) | |
970 mode-require-final-newline) | |
971 (set (make-local-variable 'indent-line-function) 'indent-relative)) | |
972 @end group | |
973 @end smallexample | |
974 | |
975 @noindent | |
976 (The last line is redundant nowadays, since @code{indent-relative} is | |
977 the default value, and we'll delete it in a future version.) | |
978 | |
979 Here is how it was defined formerly, before | |
980 @code{define-derived-mode} existed: | |
981 | |
982 @smallexample | |
983 @group | |
984 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} | |
985 (defvar text-mode-abbrev-table nil | |
986 "Abbrev table used while in text mode.") | |
987 (define-abbrev-table 'text-mode-abbrev-table ()) | |
988 @end group | |
989 | |
990 @group | |
991 (defun text-mode () | |
992 "Major mode for editing text intended for humans to read... | |
993 Special commands: \\@{text-mode-map@} | |
994 @end group | |
995 @group | |
996 Turning on text-mode runs the hook `text-mode-hook'." | |
997 (interactive) | |
998 (kill-all-local-variables) | |
999 (use-local-map text-mode-map) | |
1000 @end group | |
1001 @group | |
1002 (setq local-abbrev-table text-mode-abbrev-table) | |
1003 (set-syntax-table text-mode-syntax-table) | |
1004 @end group | |
1005 @group | |
1006 ;; @r{These four lines are absent from the current version} | |
1007 ;; @r{not because this is done some other way, but rather} | |
1008 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} | |
1009 (make-local-variable 'paragraph-start) | |
1010 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) | |
1011 (make-local-variable 'paragraph-separate) | |
1012 (setq paragraph-separate paragraph-start) | |
1013 (make-local-variable 'indent-line-function) | |
1014 (setq indent-line-function 'indent-relative-maybe) | |
1015 @end group | |
1016 @group | |
1017 (setq mode-name "Text") | |
1018 (setq major-mode 'text-mode) | |
1019 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} | |
1020 ; @r{customize the mode with a hook.} | |
1021 @end group | |
1022 @end smallexample | |
1023 | |
1024 @cindex @file{lisp-mode.el} | |
1025 The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp | |
1026 Interaction mode) have more features than Text mode and the code is | |
1027 correspondingly more complicated. Here are excerpts from | |
1028 @file{lisp-mode.el} that illustrate how these modes are written. | |
1029 | |
1030 @cindex syntax table example | |
1031 @smallexample | |
1032 @group | |
1033 ;; @r{Create mode-specific table variables.} | |
1034 (defvar lisp-mode-syntax-table nil "") | |
1035 (defvar lisp-mode-abbrev-table nil "") | |
1036 @end group | |
1037 | |
1038 @group | |
1039 (defvar emacs-lisp-mode-syntax-table | |
1040 (let ((table (make-syntax-table))) | |
1041 (let ((i 0)) | |
1042 @end group | |
1043 | |
1044 @group | |
1045 ;; @r{Set syntax of chars up to @samp{0} to say they are} | |
1046 ;; @r{part of symbol names but not words.} | |
1047 ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} | |
1048 (while (< i ?0) | |
1049 (modify-syntax-entry i "_ " table) | |
1050 (setq i (1+ i))) | |
1051 ;; @r{@dots{} similar code follows for other character ranges.} | |
1052 @end group | |
1053 @group | |
1054 ;; @r{Then set the syntax codes for characters that are special in Lisp.} | |
1055 (modify-syntax-entry ? " " table) | |
1056 (modify-syntax-entry ?\t " " table) | |
1057 (modify-syntax-entry ?\f " " table) | |
1058 (modify-syntax-entry ?\n "> " table) | |
1059 @end group | |
1060 @group | |
1061 ;; @r{Give CR the same syntax as newline, for selective-display.} | |
1062 (modify-syntax-entry ?\^m "> " table) | |
1063 (modify-syntax-entry ?\; "< " table) | |
1064 (modify-syntax-entry ?` "' " table) | |
1065 (modify-syntax-entry ?' "' " table) | |
1066 (modify-syntax-entry ?, "' " table) | |
1067 @end group | |
1068 @group | |
1069 ;; @r{@dots{}likewise for many other characters@dots{}} | |
1070 (modify-syntax-entry ?\( "() " table) | |
1071 (modify-syntax-entry ?\) ")( " table) | |
1072 (modify-syntax-entry ?\[ "(] " table) | |
1073 (modify-syntax-entry ?\] ")[ " table)) | |
1074 table)) | |
1075 @end group | |
1076 @group | |
1077 ;; @r{Create an abbrev table for lisp-mode.} | |
1078 (define-abbrev-table 'lisp-mode-abbrev-table ()) | |
1079 @end group | |
1080 @end smallexample | |
1081 | |
1082 The three modes for Lisp share much of their code. For instance, | |
1083 each calls the following function to set various variables: | |
1084 | |
1085 @smallexample | |
1086 @group | |
1087 (defun lisp-mode-variables (lisp-syntax) | |
1088 (when lisp-syntax | |
1089 (set-syntax-table lisp-mode-syntax-table)) | |
1090 (setq local-abbrev-table lisp-mode-abbrev-table) | |
1091 @dots{} | |
1092 @end group | |
1093 @end smallexample | |
1094 | |
1095 In Lisp and most programming languages, we want the paragraph | |
1096 commands to treat only blank lines as paragraph separators. And the | |
1097 modes should understand the Lisp conventions for comments. The rest of | |
1098 @code{lisp-mode-variables} sets this up: | |
1099 | |
1100 @smallexample | |
1101 @group | |
1102 (make-local-variable 'paragraph-start) | |
1103 (setq paragraph-start (concat page-delimiter "\\|$" )) | |
1104 (make-local-variable 'paragraph-separate) | |
1105 (setq paragraph-separate paragraph-start) | |
1106 @dots{} | |
1107 @end group | |
1108 @group | |
1109 (make-local-variable 'comment-indent-function) | |
1110 (setq comment-indent-function 'lisp-comment-indent)) | |
1111 @dots{} | |
1112 @end group | |
1113 @end smallexample | |
1114 | |
1115 Each of the different Lisp modes has a slightly different keymap. For | |
1116 example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other | |
1117 Lisp modes do not. However, all Lisp modes have some commands in | |
1118 common. The following code sets up the common commands: | |
1119 | |
1120 @smallexample | |
1121 @group | |
1122 (defvar shared-lisp-mode-map () | |
1123 "Keymap for commands shared by all sorts of Lisp modes.") | |
1124 | |
1125 ;; @r{Putting this @code{if} after the @code{defvar} is an older style.} | |
1126 (if shared-lisp-mode-map | |
1127 () | |
1128 (setq shared-lisp-mode-map (make-sparse-keymap)) | |
1129 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) | |
1130 (define-key shared-lisp-mode-map "\177" | |
1131 'backward-delete-char-untabify)) | |
1132 @end group | |
1133 @end smallexample | |
1134 | |
1135 @noindent | |
1136 And here is the code to set up the keymap for Lisp mode: | |
1137 | |
1138 @smallexample | |
1139 @group | |
1140 (defvar lisp-mode-map () | |
1141 "Keymap for ordinary Lisp mode...") | |
1142 | |
1143 (if lisp-mode-map | |
1144 () | |
1145 (setq lisp-mode-map (make-sparse-keymap)) | |
1146 (set-keymap-parent lisp-mode-map shared-lisp-mode-map) | |
1147 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun) | |
1148 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp)) | |
1149 @end group | |
1150 @end smallexample | |
1151 | |
1152 Finally, here is the complete major mode function definition for | |
1153 Lisp mode. | |
1154 | |
1155 @smallexample | |
1156 @group | |
1157 (defun lisp-mode () | |
1158 "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. | |
1159 Commands: | |
1160 Delete converts tabs to spaces as it moves back. | |
1161 Blank lines separate paragraphs. Semicolons start comments. | |
1162 \\@{lisp-mode-map@} | |
1163 Note that `run-lisp' may be used either to start an inferior Lisp job | |
1164 or to switch back to an existing one. | |
1165 @end group | |
1166 | |
1167 @group | |
1168 Entry to this mode calls the value of `lisp-mode-hook' | |
1169 if that value is non-nil." | |
1170 (interactive) | |
1171 (kill-all-local-variables) | |
1172 @end group | |
1173 @group | |
1174 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} | |
1175 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} | |
1176 ; @r{finds out what to describe.} | |
1177 (setq mode-name "Lisp") ; @r{This goes into the mode line.} | |
1178 (lisp-mode-variables t) ; @r{This defines various variables.} | |
1179 (make-local-variable 'comment-start-skip) | |
1180 (setq comment-start-skip | |
1181 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") | |
1182 (make-local-variable 'font-lock-keywords-case-fold-search) | |
1183 (setq font-lock-keywords-case-fold-search t) | |
1184 @end group | |
1185 @group | |
1186 (setq imenu-case-fold-search t) | |
1187 (set-syntax-table lisp-mode-syntax-table) | |
1188 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} | |
1189 ; @r{hook to customize the mode.} | |
1190 @end group | |
1191 @end smallexample | |
1192 | |
1193 @node Minor Modes | |
1194 @section Minor Modes | |
1195 @cindex minor mode | |
1196 | |
1197 A @dfn{minor mode} provides features that users may enable or disable | |
1198 independently of the choice of major mode. Minor modes can be enabled | |
1199 individually or in combination. Minor modes would be better named | |
1200 ``generally available, optional feature modes,'' except that such a name | |
1201 would be unwieldy. | |
1202 | |
1203 A minor mode is not usually meant as a variation of a single major mode. | |
1204 Usually they are general and can apply to many major modes. For | |
1205 example, Auto Fill mode works with any major mode that permits text | |
1206 insertion. To be general, a minor mode must be effectively independent | |
1207 of the things major modes do. | |
1208 | |
1209 A minor mode is often much more difficult to implement than a major | |
1210 mode. One reason is that you should be able to activate and deactivate | |
1211 minor modes in any order. A minor mode should be able to have its | |
1212 desired effect regardless of the major mode and regardless of the other | |
1213 minor modes in effect. | |
1214 | |
1215 Often the biggest problem in implementing a minor mode is finding a | |
1216 way to insert the necessary hook into the rest of Emacs. Minor mode | |
1217 keymaps make this easier than it used to be. | |
1218 | |
1219 @defvar minor-mode-list | |
1220 The value of this variable is a list of all minor mode commands. | |
1221 @end defvar | |
1222 | |
1223 @menu | |
1224 * Minor Mode Conventions:: Tips for writing a minor mode. | |
1225 * Keymaps and Minor Modes:: How a minor mode can have its own keymap. | |
1226 * Defining Minor Modes:: A convenient facility for defining minor modes. | |
1227 @end menu | |
1228 | |
1229 @node Minor Mode Conventions | |
1230 @subsection Conventions for Writing Minor Modes | |
1231 @cindex minor mode conventions | |
1232 @cindex conventions for writing minor modes | |
1233 | |
1234 There are conventions for writing minor modes just as there are for | |
1235 major modes. Several of the major mode conventions apply to minor | |
1236 modes as well: those regarding the name of the mode initialization | |
1237 function, the names of global symbols, the use of a hook at the end of | |
1238 the initialization function, and the use of keymaps and other tables. | |
1239 | |
1240 In addition, there are several conventions that are specific to | |
1241 minor modes. (The easiest way to follow all the conventions is to use | |
1242 the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.) | |
1243 | |
1244 @itemize @bullet | |
1245 @item | |
1246 @cindex mode variable | |
1247 Make a variable whose name ends in @samp{-mode} to control the minor | |
1248 mode. We call this the @dfn{mode variable}. The minor mode command | |
1249 should set this variable (@code{nil} to disable; anything else to | |
1250 enable). | |
1251 | |
1252 If possible, implement the mode so that setting the variable | |
1253 automatically enables or disables the mode. Then the minor mode command | |
1254 does not need to do anything except set the variable. | |
1255 | |
1256 This variable is used in conjunction with the @code{minor-mode-alist} to | |
1257 display the minor mode name in the mode line. It can also enable | |
1258 or disable a minor mode keymap. Individual commands or hooks can also | |
1259 check the variable's value. | |
1260 | |
1261 If you want the minor mode to be enabled separately in each buffer, | |
1262 make the variable buffer-local. | |
1263 | |
1264 @item | |
1265 Define a command whose name is the same as the mode variable. | |
1266 Its job is to enable and disable the mode by setting the variable. | |
1267 | |
1268 The command should accept one optional argument. If the argument is | |
1269 @code{nil}, it should toggle the mode (turn it on if it is off, and | |
1270 off if it is on). It should turn the mode on if the argument is a | |
1271 positive integer, the symbol @code{t}, or a list whose @sc{car} is one | |
1272 of those. It should turn the mode off if the argument is a negative | |
1273 integer or zero, the symbol @code{-}, or a list whose @sc{car} is a | |
1274 negative integer or zero. The meaning of other arguments is not | |
1275 specified. | |
1276 | |
1277 Here is an example taken from the definition of @code{transient-mark-mode}. | |
1278 It shows the use of @code{transient-mark-mode} as a variable that enables or | |
1279 disables the mode's behavior, and also shows the proper way to toggle, | |
1280 enable or disable the minor mode based on the raw prefix argument value. | |
1281 | |
1282 @smallexample | |
1283 @group | |
1284 (setq transient-mark-mode | |
1285 (if (null arg) (not transient-mark-mode) | |
1286 (> (prefix-numeric-value arg) 0))) | |
1287 @end group | |
1288 @end smallexample | |
1289 | |
1290 @item | |
1291 Add an element to @code{minor-mode-alist} for each minor mode | |
1292 (@pxref{Definition of minor-mode-alist}), if you want to indicate the | |
1293 minor mode in the mode line. This element should be a list of the | |
1294 following form: | |
1295 | |
1296 @smallexample | |
1297 (@var{mode-variable} @var{string}) | |
1298 @end smallexample | |
1299 | |
1300 Here @var{mode-variable} is the variable that controls enabling of the | |
1301 minor mode, and @var{string} is a short string, starting with a space, | |
1302 to represent the mode in the mode line. These strings must be short so | |
1303 that there is room for several of them at once. | |
1304 | |
1305 When you add an element to @code{minor-mode-alist}, use @code{assq} to | |
1306 check for an existing element, to avoid duplication. For example: | |
1307 | |
1308 @smallexample | |
1309 @group | |
1310 (unless (assq 'leif-mode minor-mode-alist) | |
1311 (setq minor-mode-alist | |
1312 (cons '(leif-mode " Leif") minor-mode-alist))) | |
1313 @end group | |
1314 @end smallexample | |
1315 | |
1316 @noindent | |
1317 or like this, using @code{add-to-list} (@pxref{List Variables}): | |
1318 | |
1319 @smallexample | |
1320 @group | |
1321 (add-to-list 'minor-mode-alist '(leif-mode " Leif")) | |
1322 @end group | |
1323 @end smallexample | |
1324 @end itemize | |
1325 | |
1326 Global minor modes distributed with Emacs should if possible support | |
1327 enabling and disabling via Custom (@pxref{Customization}). To do this, | |
1328 the first step is to define the mode variable with @code{defcustom}, and | |
1329 specify @code{:type boolean}. | |
1330 | |
1331 If just setting the variable is not sufficient to enable the mode, you | |
1332 should also specify a @code{:set} method which enables the mode by | |
1333 invoking the mode command. Note in the variable's documentation string that | |
1334 setting the variable other than via Custom may not take effect. | |
1335 | |
1336 Also mark the definition with an autoload cookie (@pxref{autoload cookie}), | |
1337 and specify a @code{:require} so that customizing the variable will load | |
1338 the library that defines the mode. This will copy suitable definitions | |
1339 into @file{loaddefs.el} so that users can use @code{customize-option} to | |
1340 enable the mode. For example: | |
1341 | |
1342 @smallexample | |
1343 @group | |
1344 | |
1345 ;;;###autoload | |
1346 (defcustom msb-mode nil | |
1347 "Toggle msb-mode. | |
1348 Setting this variable directly does not take effect; | |
1349 use either \\[customize] or the function `msb-mode'." | |
1350 :set 'custom-set-minor-mode | |
1351 :initialize 'custom-initialize-default | |
1352 :version "20.4" | |
1353 :type 'boolean | |
1354 :group 'msb | |
1355 :require 'msb) | |
1356 @end group | |
1357 @end smallexample | |
1358 | |
1359 @node Keymaps and Minor Modes | |
1360 @subsection Keymaps and Minor Modes | |
1361 | |
1362 Each minor mode can have its own keymap, which is active when the mode | |
1363 is enabled. To set up a keymap for a minor mode, add an element to the | |
1364 alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. | |
1365 | |
1366 @cindex @code{self-insert-command}, minor modes | |
1367 One use of minor mode keymaps is to modify the behavior of certain | |
1368 self-inserting characters so that they do something else as well as | |
1369 self-insert. In general, this is the only way to do that, since the | |
1370 facilities for customizing @code{self-insert-command} are limited to | |
1371 special cases (designed for abbrevs and Auto Fill mode). (Do not try | |
1372 substituting your own definition of @code{self-insert-command} for the | |
1373 standard one. The editor command loop handles this function specially.) | |
1374 | |
1375 The key sequences bound in a minor mode should consist of @kbd{C-c} | |
1376 followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other | |
1377 punctuation characters are reserved for major modes.) | |
1378 | |
1379 @node Defining Minor Modes | |
1380 @subsection Defining Minor Modes | |
1381 | |
1382 The macro @code{define-minor-mode} offers a convenient way of | |
1383 implementing a mode in one self-contained definition. | |
1384 | |
1385 @defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} | |
1386 This macro defines a new minor mode whose name is @var{mode} (a | |
1387 symbol). It defines a command named @var{mode} to toggle the minor | |
1388 mode, with @var{doc} as its documentation string. It also defines a | |
1389 variable named @var{mode}, which is set to @code{t} or @code{nil} by | |
1390 enabling or disabling the mode. The variable is initialized to | |
1391 @var{init-value}. Except in unusual circumstances (see below), this | |
1392 value must be @code{nil}. | |
1393 | |
1394 The string @var{lighter} says what to display in the mode line | |
1395 when the mode is enabled; if it is @code{nil}, the mode is not displayed | |
1396 in the mode line. | |
1397 | |
1398 The optional argument @var{keymap} specifies the keymap for the minor mode. | |
1399 It can be a variable name, whose value is the keymap, or it can be an alist | |
1400 specifying bindings in this form: | |
1401 | |
1402 @example | |
1403 (@var{key-sequence} . @var{definition}) | |
1404 @end example | |
1405 | |
1406 The above three arguments @var{init-value}, @var{lighter}, and | |
1407 @var{keymap} can be (partially) omitted when @var{keyword-args} are | |
1408 used. The @var{keyword-args} consist of keywords followed by | |
1409 corresponding values. A few keywords have special meanings: | |
1410 | |
1411 @table @code | |
1412 @item :group @var{group} | |
1413 Custom group name to use in all generated @code{defcustom} forms. | |
1414 Defaults to @var{mode} without the possible trailing @samp{-mode}. | |
1415 @strong{Warning:} don't use this default group name unless you have | |
1416 written a @code{defgroup} to define that group properly. @xref{Group | |
1417 Definitions}. | |
1418 | |
1419 @item :global @var{global} | |
1420 If non-@code{nil}, this specifies that the minor mode should be global | |
1421 rather than buffer-local. It defaults to @code{nil}. | |
1422 | |
1423 One of the effects of making a minor mode global is that the | |
1424 @var{mode} variable becomes a customization variable. Toggling it | |
1425 through the Custom interface turns the mode on and off, and its value | |
1426 can be saved for future Emacs sessions (@pxref{Saving | |
1427 Customizations,,, emacs, The GNU Emacs Manual}. For the saved | |
1428 variable to work, you should ensure that the @code{define-minor-mode} | |
1429 form is evaluated each time Emacs starts; for packages that are not | |
1430 part of Emacs, the easiest way to do this is to specify a | |
1431 @code{:require} keyword. | |
1432 | |
1433 @item :init-value @var{init-value} | |
1434 This is equivalent to specifying @var{init-value} positionally. | |
1435 | |
1436 @item :lighter @var{lighter} | |
1437 This is equivalent to specifying @var{lighter} positionally. | |
1438 | |
1439 @item :keymap @var{keymap} | |
1440 This is equivalent to specifying @var{keymap} positionally. | |
1441 @end table | |
1442 | |
1443 Any other keyword arguments are passed directly to the | |
1444 @code{defcustom} generated for the variable @var{mode}. | |
1445 | |
1446 The command named @var{mode} first performs the standard actions such | |
1447 as setting the variable named @var{mode} and then executes the | |
1448 @var{body} forms, if any. It finishes by running the mode hook | |
1449 variable @code{@var{mode}-hook}. | |
1450 @end defmac | |
1451 | |
1452 The initial value must be @code{nil} except in cases where (1) the | |
1453 mode is preloaded in Emacs, or (2) it is painless for loading to | |
1454 enable the mode even though the user did not request it. For | |
1455 instance, if the mode has no effect unless something else is enabled, | |
1456 and will always be loaded by that time, enabling it by default is | |
1457 harmless. But these are unusual circumstances. Normally, the | |
1458 initial value must be @code{nil}. | |
1459 | |
1460 @findex easy-mmode-define-minor-mode | |
1461 The name @code{easy-mmode-define-minor-mode} is an alias | |
1462 for this macro. | |
1463 | |
1464 Here is an example of using @code{define-minor-mode}: | |
1465 | |
1466 @smallexample | |
1467 (define-minor-mode hungry-mode | |
1468 "Toggle Hungry mode. | |
1469 With no argument, this command toggles the mode. | |
1470 Non-null prefix argument turns on the mode. | |
1471 Null prefix argument turns off the mode. | |
1472 | |
1473 When Hungry mode is enabled, the control delete key | |
1474 gobbles all preceding whitespace except the last. | |
1475 See the command \\[hungry-electric-delete]." | |
1476 ;; The initial value. | |
1477 nil | |
1478 ;; The indicator for the mode line. | |
1479 " Hungry" | |
1480 ;; The minor mode bindings. | |
1481 '(("\C-\^?" . hungry-electric-delete)) | |
1482 :group 'hunger) | |
1483 @end smallexample | |
1484 | |
1485 @noindent | |
1486 This defines a minor mode named ``Hungry mode,'' a command named | |
1487 @code{hungry-mode} to toggle it, a variable named @code{hungry-mode} | |
1488 which indicates whether the mode is enabled, and a variable named | |
1489 @code{hungry-mode-map} which holds the keymap that is active when the | |
1490 mode is enabled. It initializes the keymap with a key binding for | |
1491 @kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into | |
1492 custom group @code{hunger}. There are no @var{body} forms---many | |
1493 minor modes don't need any. | |
1494 | |
1495 Here's an equivalent way to write it: | |
1496 | |
1497 @smallexample | |
1498 (define-minor-mode hungry-mode | |
1499 "Toggle Hungry mode. | |
1500 With no argument, this command toggles the mode. | |
1501 Non-null prefix argument turns on the mode. | |
1502 Null prefix argument turns off the mode. | |
1503 | |
1504 When Hungry mode is enabled, the control delete key | |
1505 gobbles all preceding whitespace except the last. | |
1506 See the command \\[hungry-electric-delete]." | |
1507 ;; The initial value. | |
1508 :init-value nil | |
1509 ;; The indicator for the mode line. | |
1510 :lighter " Hungry" | |
1511 ;; The minor mode bindings. | |
1512 :keymap | |
1513 '(("\C-\^?" . hungry-electric-delete) | |
1514 ("\C-\M-\^?" | |
1515 . (lambda () | |
1516 (interactive) | |
1517 (hungry-electric-delete t)))) | |
1518 :group 'hunger) | |
1519 @end smallexample | |
1520 | |
1521 @defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{} | |
1522 This defines a global toggle named @var{global-mode} whose meaning is | |
1523 to enable or disable the buffer-local minor mode @var{mode} in all | |
1524 buffers. To turn on the minor mode in a buffer, it uses the function | |
1525 @var{turn-on}; to turn off the minor mode, it calls @code{mode} with | |
1526 @minus{}1 as argument. | |
1527 | |
1528 Globally enabling the mode also affects buffers subsequently created | |
1529 by visiting files, and buffers that use a major mode other than | |
1530 Fundamental mode; but it does not detect the creation of a new buffer | |
1531 in Fundamental mode. | |
1532 | |
1533 This defines the customization option @var{global-mode} (@pxref{Customization}), | |
1534 which can be toggled in the Custom interface to turn the minor mode on | |
1535 and off. As with @code{define-minor-mode}, you should ensure that the | |
1536 @code{define-globalized-minor-mode} form is evaluated each time Emacs | |
1537 starts, for example by providing a @code{:require} keyword. | |
1538 | |
1539 Use @code{:group @var{group}} in @var{keyword-args} to specify the | |
1540 custom group for the mode variable of the global minor mode. | |
1541 @end defmac | |
1542 | |
1543 @node Mode Line Format | |
1544 @section Mode-Line Format | |
1545 @cindex mode line | |
1546 | |
1547 Each Emacs window (aside from minibuffer windows) typically has a mode | |
1548 line at the bottom, which displays status information about the buffer | |
1549 displayed in the window. The mode line contains information about the | |
1550 buffer, such as its name, associated file, depth of recursive editing, | |
1551 and major and minor modes. A window can also have a @dfn{header | |
1552 line}, which is much like the mode line but appears at the top of the | |
1553 window. | |
1554 | |
1555 This section describes how to control the contents of the mode line | |
1556 and header line. We include it in this chapter because much of the | |
1557 information displayed in the mode line relates to the enabled major and | |
1558 minor modes. | |
1559 | |
1560 @menu | |
1561 * Base: Mode Line Basics. Basic ideas of mode line control. | |
1562 * Data: Mode Line Data. The data structure that controls the mode line. | |
1563 * Top: Mode Line Top. The top level variable, mode-line-format. | |
1564 * Mode Line Variables:: Variables used in that data structure. | |
1565 * %-Constructs:: Putting information into a mode line. | |
1566 * Properties in Mode:: Using text properties in the mode line. | |
1567 * Header Lines:: Like a mode line, but at the top. | |
1568 * Emulating Mode Line:: Formatting text as the mode line would. | |
1569 @end menu | |
1570 | |
1571 @node Mode Line Basics | |
1572 @subsection Mode Line Basics | |
1573 | |
1574 @code{mode-line-format} is a buffer-local variable that holds a | |
1575 @dfn{mode line construct}, a kind of template, which controls what is | |
1576 displayed on the mode line of the current buffer. The value of | |
1577 @code{header-line-format} specifies the buffer's header line in the | |
1578 same way. All windows for the same buffer use the same | |
1579 @code{mode-line-format} and @code{header-line-format}. | |
1580 | |
1581 For efficiency, Emacs does not continuously recompute the mode | |
1582 line and header line of a window. It does so when circumstances | |
1583 appear to call for it---for instance, if you change the window | |
1584 configuration, switch buffers, narrow or widen the buffer, scroll, or | |
1585 change the buffer's modification status. If you modify any of the | |
1586 variables referenced by @code{mode-line-format} (@pxref{Mode Line | |
1587 Variables}), or any other variables and data structures that affect | |
1588 how text is displayed (@pxref{Display}), you may want to force an | |
1589 update of the mode line so as to display the new information or | |
1590 display it in the new way. | |
1591 | |
1592 @defun force-mode-line-update &optional all | |
1593 Force redisplay of the current buffer's mode line and header line. | |
1594 The next redisplay will update the mode line and header line based on | |
1595 the latest values of all relevant variables. With optional | |
1596 non-@code{nil} @var{all}, force redisplay of all mode lines and header | |
1597 lines. | |
1598 | |
1599 This function also forces recomputation of the menu bar menus | |
1600 and the frame title. | |
1601 @end defun | |
1602 | |
1603 The selected window's mode line is usually displayed in a different | |
1604 color using the face @code{mode-line}. Other windows' mode lines | |
1605 appear in the face @code{mode-line-inactive} instead. @xref{Faces}. | |
1606 | |
1607 @node Mode Line Data | |
1608 @subsection The Data Structure of the Mode Line | |
1609 @cindex mode-line construct | |
1610 | |
1611 The mode-line contents are controlled by a data structure called a | |
1612 @dfn{mode-line construct}, made up of lists, strings, symbols, and | |
1613 numbers kept in buffer-local variables. Each data type has a specific | |
1614 meaning for the mode-line appearance, as described below. The same | |
1615 data structure is used for constructing frame titles (@pxref{Frame | |
1616 Titles}) and header lines (@pxref{Header Lines}). | |
1617 | |
1618 A mode-line construct may be as simple as a fixed string of text, | |
1619 but it usually specifies how to combine fixed strings with variables' | |
1620 values to construct the text. Many of these variables are themselves | |
1621 defined to have mode-line constructs as their values. | |
1622 | |
1623 Here are the meanings of various data types as mode-line constructs: | |
1624 | |
1625 @table @code | |
1626 @cindex percent symbol in mode line | |
1627 @item @var{string} | |
1628 A string as a mode-line construct appears verbatim except for | |
1629 @dfn{@code{%}-constructs} in it. These stand for substitution of | |
1630 other data; see @ref{%-Constructs}. | |
1631 | |
1632 If parts of the string have @code{face} properties, they control | |
1633 display of the text just as they would text in the buffer. Any | |
1634 characters which have no @code{face} properties are displayed, by | |
1635 default, in the face @code{mode-line} or @code{mode-line-inactive} | |
1636 (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The | |
1637 @code{help-echo} and @code{local-map} properties in @var{string} have | |
1638 special meanings. @xref{Properties in Mode}. | |
1639 | |
1640 @item @var{symbol} | |
1641 A symbol as a mode-line construct stands for its value. The value of | |
1642 @var{symbol} is used as a mode-line construct, in place of @var{symbol}. | |
1643 However, the symbols @code{t} and @code{nil} are ignored, as is any | |
1644 symbol whose value is void. | |
1645 | |
1646 There is one exception: if the value of @var{symbol} is a string, it is | |
1647 displayed verbatim: the @code{%}-constructs are not recognized. | |
1648 | |
1649 Unless @var{symbol} is marked as ``risky'' (i.e., it has a | |
1650 non-@code{nil} @code{risky-local-variable} property), all text | |
1651 properties specified in @var{symbol}'s value are ignored. This | |
1652 includes the text properties of strings in @var{symbol}'s value, as | |
1653 well as all @code{:eval} and @code{:propertize} forms in it. (The | |
1654 reason for this is security: non-risky variables could be set | |
1655 automatically from file variables without prompting the user.) | |
1656 | |
1657 @item (@var{string} @var{rest}@dots{}) | |
1658 @itemx (@var{list} @var{rest}@dots{}) | |
1659 A list whose first element is a string or list means to process all the | |
1660 elements recursively and concatenate the results. This is the most | |
1661 common form of mode-line construct. | |
1662 | |
1663 @item (:eval @var{form}) | |
1664 A list whose first element is the symbol @code{:eval} says to evaluate | |
1665 @var{form}, and use the result as a string to display. Make sure this | |
1666 evaluation cannot load any files, as doing so could cause infinite | |
1667 recursion. | |
1668 | |
1669 @item (:propertize @var{elt} @var{props}@dots{}) | |
1670 A list whose first element is the symbol @code{:propertize} says to | |
1671 process the mode-line construct @var{elt} recursively, then add the text | |
1672 properties specified by @var{props} to the result. The argument | |
1673 @var{props} should consist of zero or more pairs @var{text-property} | |
1674 @var{value}. (This feature is new as of Emacs 22.1.) | |
1675 | |
1676 @item (@var{symbol} @var{then} @var{else}) | |
1677 A list whose first element is a symbol that is not a keyword specifies | |
1678 a conditional. Its meaning depends on the value of @var{symbol}. If | |
1679 @var{symbol} has a non-@code{nil} value, the second element, | |
1680 @var{then}, is processed recursively as a mode-line element. | |
1681 Otherwise, the third element, @var{else}, is processed recursively. | |
1682 You may omit @var{else}; then the mode-line element displays nothing | |
1683 if the value of @var{symbol} is @code{nil} or void. | |
1684 | |
1685 @item (@var{width} @var{rest}@dots{}) | |
1686 A list whose first element is an integer specifies truncation or | |
1687 padding of the results of @var{rest}. The remaining elements | |
1688 @var{rest} are processed recursively as mode-line constructs and | |
1689 concatenated together. When @var{width} is positive, the result is | |
1690 space filled on the right if its width is less than @var{width}. When | |
1691 @var{width} is negative, the result is truncated on the right to | |
1692 @minus{}@var{width} columns if its width exceeds @minus{}@var{width}. | |
1693 | |
1694 For example, the usual way to show what percentage of a buffer is above | |
1695 the top of the window is to use a list like this: @code{(-3 "%p")}. | |
1696 @end table | |
1697 | |
1698 @node Mode Line Top | |
1699 @subsection The Top Level of Mode Line Control | |
1700 | |
1701 The variable in overall control of the mode line is | |
1702 @code{mode-line-format}. | |
1703 | |
1704 @defvar mode-line-format | |
1705 The value of this variable is a mode-line construct that controls the | |
1706 contents of the mode-line. It is always buffer-local in all buffers. | |
1707 | |
1708 If you set this variable to @code{nil} in a buffer, that buffer does | |
1709 not have a mode line. (A window that is just one line tall never | |
1710 displays a mode line.) | |
1711 @end defvar | |
1712 | |
1713 The default value of @code{mode-line-format} is designed to use the | |
1714 values of other variables such as @code{mode-line-position} and | |
1715 @code{mode-line-modes} (which in turn incorporates the values of the | |
1716 variables @code{mode-name} and @code{minor-mode-alist}). Very few | |
1717 modes need to alter @code{mode-line-format} itself. For most | |
1718 purposes, it is sufficient to alter some of the variables that | |
1719 @code{mode-line-format} either directly or indirectly refers to. | |
1720 | |
1721 If you do alter @code{mode-line-format} itself, the new value should | |
1722 use the same variables that appear in the default value (@pxref{Mode | |
1723 Line Variables}), rather than duplicating their contents or displaying | |
1724 the information in another fashion. This way, customizations made by | |
1725 the user or by Lisp programs (such as @code{display-time} and major | |
1726 modes) via changes to those variables remain effective. | |
1727 | |
1728 Here is an example of a @code{mode-line-format} that might be | |
1729 useful for @code{shell-mode}, since it contains the host name and default | |
1730 directory. | |
1731 | |
1732 @example | |
1733 @group | |
1734 (setq mode-line-format | |
1735 (list "-" | |
1736 'mode-line-mule-info | |
1737 'mode-line-modified | |
1738 'mode-line-frame-identification | |
1739 "%b--" | |
1740 @end group | |
1741 @group | |
1742 ;; @r{Note that this is evaluated while making the list.} | |
1743 ;; @r{It makes a mode-line construct which is just a string.} | |
1744 (getenv "HOST") | |
1745 @end group | |
1746 ":" | |
1747 'default-directory | |
1748 " " | |
1749 'global-mode-string | |
1750 " %[(" | |
1751 '(:eval (mode-line-mode-name)) | |
1752 'mode-line-process | |
1753 'minor-mode-alist | |
1754 "%n" | |
1755 ")%]--" | |
1756 @group | |
1757 '(which-func-mode ("" which-func-format "--")) | |
1758 '(line-number-mode "L%l--") | |
1759 '(column-number-mode "C%c--") | |
1760 '(-3 "%p") | |
1761 "-%-")) | |
1762 @end group | |
1763 @end example | |
1764 | |
1765 @noindent | |
1766 (The variables @code{line-number-mode}, @code{column-number-mode} | |
1767 and @code{which-func-mode} enable particular minor modes; as usual, | |
1768 these variable names are also the minor mode command names.) | |
1769 | |
1770 @node Mode Line Variables | |
1771 @subsection Variables Used in the Mode Line | |
1772 | |
1773 This section describes variables incorporated by the standard value | |
1774 of @code{mode-line-format} into the text of the mode line. There is | |
1775 nothing inherently special about these variables; any other variables | |
1776 could have the same effects on the mode line if | |
1777 @code{mode-line-format}'s value were changed to use them. However, | |
1778 various parts of Emacs set these variables on the understanding that | |
1779 they will control parts of the mode line; therefore, practically | |
1780 speaking, it is essential for the mode line to use them. | |
1781 | |
1782 @defvar mode-line-mule-info | |
1783 This variable holds the value of the mode-line construct that displays | |
1784 information about the language environment, buffer coding system, and | |
1785 current input method. @xref{Non-ASCII Characters}. | |
1786 @end defvar | |
1787 | |
1788 @defvar mode-line-modified | |
1789 This variable holds the value of the mode-line construct that displays | |
1790 whether the current buffer is modified. | |
1791 | |
1792 The default value of @code{mode-line-modified} is @code{("%1*%1+")}. | |
1793 This means that the mode line displays @samp{**} if the buffer is | |
1794 modified, @samp{--} if the buffer is not modified, @samp{%%} if the | |
1795 buffer is read only, and @samp{%*} if the buffer is read only and | |
1796 modified. | |
1797 | |
1798 Changing this variable does not force an update of the mode line. | |
1799 @end defvar | |
1800 | |
1801 @defvar mode-line-frame-identification | |
1802 This variable identifies the current frame. The default value is | |
1803 @code{" "} if you are using a window system which can show multiple | |
1804 frames, or @code{"-%F "} on an ordinary terminal which shows only one | |
1805 frame at a time. | |
1806 @end defvar | |
1807 | |
1808 @defvar mode-line-buffer-identification | |
1809 This variable identifies the buffer being displayed in the window. Its | |
1810 default value is @code{("%12b")}, which displays the buffer name, padded | |
1811 with spaces to at least 12 columns. | |
1812 @end defvar | |
1813 | |
1814 @defvar mode-line-position | |
1815 This variable indicates the position in the buffer. Here is a | |
1816 simplified version of its default value. The actual default value | |
1817 also specifies addition of the @code{help-echo} text property. | |
1818 | |
1819 @example | |
1820 @group | |
1821 ((-3 "%p") | |
1822 (size-indication-mode (8 " of %I")) | |
1823 @end group | |
1824 @group | |
1825 (line-number-mode | |
1826 ((column-number-mode | |
1827 (10 " (%l,%c)") | |
1828 (6 " L%l"))) | |
1829 ((column-number-mode | |
1830 (5 " C%c"))))) | |
1831 @end group | |
1832 @end example | |
1833 | |
1834 This means that @code{mode-line-position} displays at least the buffer | |
1835 percentage and possibly the buffer size, the line number and the column | |
1836 number. | |
1837 @end defvar | |
1838 | |
1839 @defvar vc-mode | |
1840 The variable @code{vc-mode}, buffer-local in each buffer, records | |
1841 whether the buffer's visited file is maintained with version control, | |
1842 and, if so, which kind. Its value is a string that appears in the mode | |
1843 line, or @code{nil} for no version control. | |
1844 @end defvar | |
1845 | |
1846 @defvar mode-line-modes | |
1847 This variable displays the buffer's major and minor modes. Here is a | |
1848 simplified version of its default value. The real default value also | |
1849 specifies addition of text properties. | |
1850 | |
1851 @example | |
1852 @group | |
1853 ("%[(" mode-name | |
1854 mode-line-process minor-mode-alist | |
1855 "%n" ")%]--") | |
1856 @end group | |
1857 @end example | |
1858 | |
1859 So @code{mode-line-modes} normally also displays the recursive editing | |
1860 level, information on the process status and whether narrowing is in | |
1861 effect. | |
1862 @end defvar | |
1863 | |
1864 The following three variables are used in @code{mode-line-modes}: | |
1865 | |
1866 @defvar mode-name | |
1867 This buffer-local variable holds the ``pretty'' name of the current | |
1868 buffer's major mode. Each major mode should set this variable so that the | |
1869 mode name will appear in the mode line. | |
1870 @end defvar | |
1871 | |
1872 @defvar mode-line-process | |
1873 This buffer-local variable contains the mode-line information on process | |
1874 status in modes used for communicating with subprocesses. It is | |
1875 displayed immediately following the major mode name, with no intervening | |
1876 space. For example, its value in the @samp{*shell*} buffer is | |
1877 @code{(":%s")}, which allows the shell to display its status along | |
1878 with the major mode as: @samp{(Shell:run)}. Normally this variable | |
1879 is @code{nil}. | |
1880 @end defvar | |
1881 | |
1882 @defvar minor-mode-alist | |
1883 @anchor{Definition of minor-mode-alist} | |
1884 This variable holds an association list whose elements specify how the | |
1885 mode line should indicate that a minor mode is active. Each element of | |
1886 the @code{minor-mode-alist} should be a two-element list: | |
1887 | |
1888 @example | |
1889 (@var{minor-mode-variable} @var{mode-line-string}) | |
1890 @end example | |
1891 | |
1892 More generally, @var{mode-line-string} can be any mode-line spec. It | |
1893 appears in the mode line when the value of @var{minor-mode-variable} | |
1894 is non-@code{nil}, and not otherwise. These strings should begin with | |
1895 spaces so that they don't run together. Conventionally, the | |
1896 @var{minor-mode-variable} for a specific mode is set to a | |
1897 non-@code{nil} value when that minor mode is activated. | |
1898 | |
1899 @code{minor-mode-alist} itself is not buffer-local. Each variable | |
1900 mentioned in the alist should be buffer-local if its minor mode can be | |
1901 enabled separately in each buffer. | |
1902 @end defvar | |
1903 | |
1904 @defvar global-mode-string | |
1905 This variable holds a mode-line spec that, by default, appears in the | |
1906 mode line just after the @code{which-func-mode} minor mode if set, | |
1907 else after @code{mode-line-modes}. The command @code{display-time} | |
1908 sets @code{global-mode-string} to refer to the variable | |
1909 @code{display-time-string}, which holds a string containing the time | |
1910 and load information. | |
1911 | |
1912 The @samp{%M} construct substitutes the value of | |
1913 @code{global-mode-string}, but that is obsolete, since the variable is | |
1914 included in the mode line from @code{mode-line-format}. | |
1915 @end defvar | |
1916 | |
1917 The variable @code{default-mode-line-format} is where | |
1918 @code{mode-line-format} usually gets its value: | |
1919 | |
1920 @defvar default-mode-line-format | |
1921 This variable holds the default @code{mode-line-format} for buffers | |
1922 that do not override it. This is the same as @code{(default-value | |
1923 'mode-line-format)}. | |
1924 | |
1925 Here is a simplified version of the default value of | |
1926 @code{default-mode-line-format}. The real default value also | |
1927 specifies addition of text properties. | |
1928 | |
1929 @example | |
1930 @group | |
1931 ("-" | |
1932 mode-line-mule-info | |
1933 mode-line-modified | |
1934 mode-line-frame-identification | |
1935 mode-line-buffer-identification | |
1936 @end group | |
1937 " " | |
1938 mode-line-position | |
1939 (vc-mode vc-mode) | |
1940 " " | |
1941 @group | |
1942 mode-line-modes | |
1943 (which-func-mode ("" which-func-format "--")) | |
1944 (global-mode-string ("--" global-mode-string)) | |
1945 "-%-") | |
1946 @end group | |
1947 @end example | |
1948 @end defvar | |
1949 | |
1950 @node %-Constructs | |
1951 @subsection @code{%}-Constructs in the Mode Line | |
1952 | |
1953 Strings used as mode-line constructs can use certain | |
1954 @code{%}-constructs to substitute various kinds of data. Here is a | |
1955 list of the defined @code{%}-constructs, and what they mean. In any | |
1956 construct except @samp{%%}, you can add a decimal integer after the | |
1957 @samp{%} to specify a minimum field width. If the width is less, the | |
1958 field is padded with spaces to the right. | |
1959 | |
1960 @table @code | |
1961 @item %b | |
1962 The current buffer name, obtained with the @code{buffer-name} function. | |
1963 @xref{Buffer Names}. | |
1964 | |
1965 @item %c | |
1966 The current column number of point. | |
1967 | |
1968 @item %e | |
1969 When Emacs is nearly out of memory for Lisp objects, a brief message | |
1970 saying so. Otherwise, this is empty. | |
1971 | |
1972 @item %f | |
1973 The visited file name, obtained with the @code{buffer-file-name} | |
1974 function. @xref{Buffer File Name}. | |
1975 | |
1976 @item %F | |
1977 The title (only on a window system) or the name of the selected frame. | |
1978 @xref{Basic Parameters}. | |
1979 | |
1980 @item %i | |
1981 The size of the accessible part of the current buffer; basically | |
1982 @code{(- (point-max) (point-min))}. | |
1983 | |
1984 @item %I | |
1985 Like @samp{%i}, but the size is printed in a more readable way by using | |
1986 @samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to | |
1987 abbreviate. | |
1988 | |
1989 @item %l | |
1990 The current line number of point, counting within the accessible portion | |
1991 of the buffer. | |
1992 | |
1993 @item %n | |
1994 @samp{Narrow} when narrowing is in effect; nothing otherwise (see | |
1995 @code{narrow-to-region} in @ref{Narrowing}). | |
1996 | |
1997 @item %p | |
1998 The percentage of the buffer text above the @strong{top} of window, or | |
1999 @samp{Top}, @samp{Bottom} or @samp{All}. Note that the default | |
2000 mode-line specification truncates this to three characters. | |
2001 | |
2002 @item %P | |
2003 The percentage of the buffer text that is above the @strong{bottom} of | |
2004 the window (which includes the text visible in the window, as well as | |
2005 the text above the top), plus @samp{Top} if the top of the buffer is | |
2006 visible on screen; or @samp{Bottom} or @samp{All}. | |
2007 | |
2008 @item %s | |
2009 The status of the subprocess belonging to the current buffer, obtained with | |
2010 @code{process-status}. @xref{Process Information}. | |
2011 | |
2012 @item %t | |
2013 Whether the visited file is a text file or a binary file. This is a | |
2014 meaningful distinction only on certain operating systems (@pxref{MS-DOS | |
2015 File Types}). | |
2016 | |
2017 @item %z | |
2018 The mnemonics of keyboard, terminal, and buffer coding systems. | |
2019 | |
2020 @item %Z | |
2021 Like @samp{%z}, but including the end-of-line format. | |
2022 | |
2023 @item %* | |
2024 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @* | |
2025 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* | |
2026 @samp{-} otherwise. @xref{Buffer Modification}. | |
2027 | |
2028 @item %+ | |
2029 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* | |
2030 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @* | |
2031 @samp{-} otherwise. This differs from @samp{%*} only for a modified | |
2032 read-only buffer. @xref{Buffer Modification}. | |
2033 | |
2034 @item %& | |
2035 @samp{*} if the buffer is modified, and @samp{-} otherwise. | |
2036 | |
2037 @item %[ | |
2038 An indication of the depth of recursive editing levels (not counting | |
2039 minibuffer levels): one @samp{[} for each editing level. | |
2040 @xref{Recursive Editing}. | |
2041 | |
2042 @item %] | |
2043 One @samp{]} for each recursive editing level (not counting minibuffer | |
2044 levels). | |
2045 | |
2046 @item %- | |
2047 Dashes sufficient to fill the remainder of the mode line. | |
2048 | |
2049 @item %% | |
2050 The character @samp{%}---this is how to include a literal @samp{%} in a | |
2051 string in which @code{%}-constructs are allowed. | |
2052 @end table | |
2053 | |
2054 The following two @code{%}-constructs are still supported, but they are | |
2055 obsolete, since you can get the same results with the variables | |
2056 @code{mode-name} and @code{global-mode-string}. | |
2057 | |
2058 @table @code | |
2059 @item %m | |
2060 The value of @code{mode-name}. | |
2061 | |
2062 @item %M | |
2063 The value of @code{global-mode-string}. | |
2064 @end table | |
2065 | |
2066 @node Properties in Mode | |
2067 @subsection Properties in the Mode Line | |
2068 @cindex text properties in the mode line | |
2069 | |
2070 Certain text properties are meaningful in the | |
2071 mode line. The @code{face} property affects the appearance of text; the | |
2072 @code{help-echo} property associates help strings with the text, and | |
2073 @code{local-map} can make the text mouse-sensitive. | |
2074 | |
2075 There are four ways to specify text properties for text in the mode | |
2076 line: | |
2077 | |
2078 @enumerate | |
2079 @item | |
2080 Put a string with a text property directly into the mode-line data | |
2081 structure. | |
2082 | |
2083 @item | |
2084 Put a text property on a mode-line %-construct such as @samp{%12b}; then | |
2085 the expansion of the %-construct will have that same text property. | |
2086 | |
2087 @item | |
2088 Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to | |
2089 give @var{elt} a text property specified by @var{props}. | |
2090 | |
2091 @item | |
2092 Use a list containing @code{:eval @var{form}} in the mode-line data | |
2093 structure, and make @var{form} evaluate to a string that has a text | |
2094 property. | |
2095 @end enumerate | |
2096 | |
2097 You can use the @code{local-map} property to specify a keymap. This | |
2098 keymap only takes real effect for mouse clicks; binding character keys | |
2099 and function keys to it has no effect, since it is impossible to move | |
2100 point into the mode line. | |
2101 | |
2102 When the mode line refers to a variable which does not have a | |
2103 non-@code{nil} @code{risky-local-variable} property, any text | |
2104 properties given or specified within that variable's values are | |
2105 ignored. This is because such properties could otherwise specify | |
2106 functions to be called, and those functions could come from file | |
2107 local variables. | |
2108 | |
2109 @node Header Lines | |
2110 @subsection Window Header Lines | |
2111 @cindex header line (of a window) | |
2112 @cindex window header line | |
2113 | |
2114 A window can have a @dfn{header line} at the | |
2115 top, just as it can have a mode line at the bottom. The header line | |
2116 feature works just like the mode-line feature, except that it's | |
2117 controlled by different variables. | |
2118 | |
2119 @defvar header-line-format | |
2120 This variable, local in every buffer, specifies how to display the | |
2121 header line, for windows displaying the buffer. The format of the value | |
2122 is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). | |
2123 @end defvar | |
2124 | |
2125 @defvar default-header-line-format | |
2126 This variable holds the default @code{header-line-format} for buffers | |
2127 that do not override it. This is the same as @code{(default-value | |
2128 'header-line-format)}. | |
2129 | |
2130 It is normally @code{nil}, so that ordinary buffers have no header line. | |
2131 @end defvar | |
2132 | |
2133 A window that is just one line tall never displays a header line. A | |
2134 window that is two lines tall cannot display both a mode line and a | |
2135 header line at once; if it has a mode line, then it does not display a | |
2136 header line. | |
2137 | |
2138 @node Emulating Mode Line | |
2139 @subsection Emulating Mode-Line Formatting | |
2140 | |
2141 You can use the function @code{format-mode-line} to compute | |
2142 the text that would appear in a mode line or header line | |
2143 based on a certain mode-line specification. | |
2144 | |
2145 @defun format-mode-line format &optional face window buffer | |
2146 This function formats a line of text according to @var{format} as if | |
2147 it were generating the mode line for @var{window}, but instead of | |
2148 displaying the text in the mode line or the header line, it returns | |
2149 the text as a string. The argument @var{window} defaults to the | |
2150 selected window. If @var{buffer} is non-@code{nil}, all the | |
2151 information used is taken from @var{buffer}; by default, it comes from | |
2152 @var{window}'s buffer. | |
2153 | |
2154 The value string normally has text properties that correspond to the | |
2155 faces, keymaps, etc., that the mode line would have. And any character | |
2156 for which no @code{face} property is specified gets a default | |
2157 value which is usually @var{face}. (If @var{face} is @code{t}, | |
2158 that stands for either @code{mode-line} if @var{window} is selected, | |
2159 otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or | |
2160 omitted, that stands for no face property.) | |
2161 | |
2162 However, if @var{face} is an integer, the value has no text properties. | |
2163 | |
2164 For example, @code{(format-mode-line header-line-format)} returns the | |
2165 text that would appear in the selected window's header line (@code{""} | |
2166 if it has no header line). @code{(format-mode-line header-line-format | |
2167 'header-line)} returns the same text, with each character | |
2168 carrying the face that it will have in the header line itself. | |
2169 @end defun | |
2170 | |
2171 @node Imenu | |
2172 @section Imenu | |
2173 | |
2174 @cindex Imenu | |
2175 @dfn{Imenu} is a feature that lets users select a definition or | |
2176 section in the buffer, from a menu which lists all of them, to go | |
2177 directly to that location in the buffer. Imenu works by constructing | |
2178 a buffer index which lists the names and buffer positions of the | |
2179 definitions, or other named portions of the buffer; then the user can | |
2180 choose one of them and move point to it. Major modes can add a menu | |
2181 bar item to use Imenu using @code{imenu-add-to-menubar}. | |
2182 | |
2183 @defun imenu-add-to-menubar name | |
2184 This function defines a local menu bar item named @var{name} | |
2185 to run Imenu. | |
2186 @end defun | |
2187 | |
2188 The user-level commands for using Imenu are described in the Emacs | |
2189 Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section | |
2190 explains how to customize Imenu's method of finding definitions or | |
2191 buffer portions for a particular major mode. | |
2192 | |
2193 The usual and simplest way is to set the variable | |
2194 @code{imenu-generic-expression}: | |
2195 | |
2196 @defvar imenu-generic-expression | |
2197 This variable, if non-@code{nil}, is a list that specifies regular | |
2198 expressions for finding definitions for Imenu. Simple elements of | |
2199 @code{imenu-generic-expression} look like this: | |
2200 | |
2201 @example | |
2202 (@var{menu-title} @var{regexp} @var{index}) | |
2203 @end example | |
2204 | |
2205 Here, if @var{menu-title} is non-@code{nil}, it says that the matches | |
2206 for this element should go in a submenu of the buffer index; | |
2207 @var{menu-title} itself specifies the name for the submenu. If | |
2208 @var{menu-title} is @code{nil}, the matches for this element go directly | |
2209 in the top level of the buffer index. | |
2210 | |
2211 The second item in the list, @var{regexp}, is a regular expression | |
2212 (@pxref{Regular Expressions}); anything in the buffer that it matches | |
2213 is considered a definition, something to mention in the buffer index. | |
2214 The third item, @var{index}, is a non-negative integer that indicates | |
2215 which subexpression in @var{regexp} matches the definition's name. | |
2216 | |
2217 An element can also look like this: | |
2218 | |
2219 @example | |
2220 (@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) | |
2221 @end example | |
2222 | |
2223 Each match for this element creates an index item, and when the index | |
2224 item is selected by the user, it calls @var{function} with arguments | |
2225 consisting of the item name, the buffer position, and @var{arguments}. | |
2226 | |
2227 For Emacs Lisp mode, @code{imenu-generic-expression} could look like | |
2228 this: | |
2229 | |
2230 @c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] | |
2231 @example | |
2232 @group | |
2233 ((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\ | |
2234 \\s-+\\([-A-Za-z0-9+]+\\)" 2) | |
2235 @end group | |
2236 @group | |
2237 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\ | |
2238 \\s-+\\([-A-Za-z0-9+]+\\)" 2) | |
2239 @end group | |
2240 @group | |
2241 ("*Types*" | |
2242 "^\\s-*\ | |
2243 (def\\(type\\|struct\\|class\\|ine-condition\\)\ | |
2244 \\s-+\\([-A-Za-z0-9+]+\\)" 2)) | |
2245 @end group | |
2246 @end example | |
2247 | |
2248 Setting this variable makes it buffer-local in the current buffer. | |
2249 @end defvar | |
2250 | |
2251 @defvar imenu-case-fold-search | |
2252 This variable controls whether matching against the regular | |
2253 expressions in the value of @code{imenu-generic-expression} is | |
2254 case-sensitive: @code{t}, the default, means matching should ignore | |
2255 case. | |
2256 | |
2257 Setting this variable makes it buffer-local in the current buffer. | |
2258 @end defvar | |
2259 | |
2260 @defvar imenu-syntax-alist | |
2261 This variable is an alist of syntax table modifiers to use while | |
2262 processing @code{imenu-generic-expression}, to override the syntax table | |
2263 of the current buffer. Each element should have this form: | |
2264 | |
2265 @example | |
2266 (@var{characters} . @var{syntax-description}) | |
2267 @end example | |
2268 | |
2269 The @sc{car}, @var{characters}, can be either a character or a string. | |
2270 The element says to give that character or characters the syntax | |
2271 specified by @var{syntax-description}, which is passed to | |
2272 @code{modify-syntax-entry} (@pxref{Syntax Table Functions}). | |
2273 | |
2274 This feature is typically used to give word syntax to characters which | |
2275 normally have symbol syntax, and thus to simplify | |
2276 @code{imenu-generic-expression} and speed up matching. | |
2277 For example, Fortran mode uses it this way: | |
2278 | |
2279 @example | |
2280 (setq imenu-syntax-alist '(("_$" . "w"))) | |
2281 @end example | |
2282 | |
2283 The @code{imenu-generic-expression} regular expressions can then use | |
2284 @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this | |
2285 technique may be inconvenient when the mode needs to limit the initial | |
2286 character of a name to a smaller set of characters than are allowed in | |
2287 the rest of a name. | |
2288 | |
2289 Setting this variable makes it buffer-local in the current buffer. | |
2290 @end defvar | |
2291 | |
2292 Another way to customize Imenu for a major mode is to set the | |
2293 variables @code{imenu-prev-index-position-function} and | |
2294 @code{imenu-extract-index-name-function}: | |
2295 | |
2296 @defvar imenu-prev-index-position-function | |
2297 If this variable is non-@code{nil}, its value should be a function that | |
2298 finds the next ``definition'' to put in the buffer index, scanning | |
2299 backward in the buffer from point. It should return @code{nil} if it | |
2300 doesn't find another ``definition'' before point. Otherwise it should | |
2301 leave point at the place it finds a ``definition'' and return any | |
2302 non-@code{nil} value. | |
2303 | |
2304 Setting this variable makes it buffer-local in the current buffer. | |
2305 @end defvar | |
2306 | |
2307 @defvar imenu-extract-index-name-function | |
2308 If this variable is non-@code{nil}, its value should be a function to | |
2309 return the name for a definition, assuming point is in that definition | |
2310 as the @code{imenu-prev-index-position-function} function would leave | |
2311 it. | |
2312 | |
2313 Setting this variable makes it buffer-local in the current buffer. | |
2314 @end defvar | |
2315 | |
2316 The last way to customize Imenu for a major mode is to set the | |
2317 variable @code{imenu-create-index-function}: | |
2318 | |
2319 @defvar imenu-create-index-function | |
2320 This variable specifies the function to use for creating a buffer | |
2321 index. The function should take no arguments, and return an index | |
2322 alist for the current buffer. It is called within | |
2323 @code{save-excursion}, so where it leaves point makes no difference. | |
2324 | |
2325 The index alist can have three types of elements. Simple elements | |
2326 look like this: | |
2327 | |
2328 @example | |
2329 (@var{index-name} . @var{index-position}) | |
2330 @end example | |
2331 | |
2332 Selecting a simple element has the effect of moving to position | |
2333 @var{index-position} in the buffer. Special elements look like this: | |
2334 | |
2335 @example | |
2336 (@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) | |
2337 @end example | |
2338 | |
2339 Selecting a special element performs: | |
2340 | |
2341 @example | |
2342 (funcall @var{function} | |
2343 @var{index-name} @var{index-position} @var{arguments}@dots{}) | |
2344 @end example | |
2345 | |
2346 A nested sub-alist element looks like this: | |
2347 | |
2348 @example | |
2349 (@var{menu-title} @var{sub-alist}) | |
2350 @end example | |
2351 | |
2352 It creates the submenu @var{menu-title} specified by @var{sub-alist}. | |
2353 | |
2354 The default value of @code{imenu-create-index-function} is | |
2355 @code{imenu-default-create-index-function}. This function calls the | |
2356 value of @code{imenu-prev-index-position-function} and the value of | |
2357 @code{imenu-extract-index-name-function} to produce the index alist. | |
2358 However, if either of these two variables is @code{nil}, the default | |
2359 function uses @code{imenu-generic-expression} instead. | |
2360 | |
2361 Setting this variable makes it buffer-local in the current buffer. | |
2362 @end defvar | |
2363 | |
2364 @node Font Lock Mode | |
2365 @section Font Lock Mode | |
2366 @cindex Font Lock mode | |
2367 | |
2368 @dfn{Font Lock mode} is a feature that automatically attaches | |
2369 @code{face} properties to certain parts of the buffer based on their | |
2370 syntactic role. How it parses the buffer depends on the major mode; | |
2371 most major modes define syntactic criteria for which faces to use in | |
2372 which contexts. This section explains how to customize Font Lock for a | |
2373 particular major mode. | |
2374 | |
2375 Font Lock mode finds text to highlight in two ways: through | |
2376 syntactic parsing based on the syntax table, and through searching | |
2377 (usually for regular expressions). Syntactic fontification happens | |
2378 first; it finds comments and string constants and highlights them. | |
2379 Search-based fontification happens second. | |
2380 | |
2381 @menu | |
2382 * Font Lock Basics:: Overview of customizing Font Lock. | |
2383 * Search-based Fontification:: Fontification based on regexps. | |
2384 * Customizing Keywords:: Customizing search-based fontification. | |
2385 * Other Font Lock Variables:: Additional customization facilities. | |
2386 * Levels of Font Lock:: Each mode can define alternative levels | |
2387 so that the user can select more or less. | |
2388 * Precalculated Fontification:: How Lisp programs that produce the buffer | |
2389 contents can also specify how to fontify it. | |
2390 * Faces for Font Lock:: Special faces specifically for Font Lock. | |
2391 * Syntactic Font Lock:: Fontification based on syntax tables. | |
2392 * Setting Syntax Properties:: Defining character syntax based on context | |
2393 using the Font Lock mechanism. | |
2394 * Multiline Font Lock:: How to coerce Font Lock into properly | |
2395 highlighting multiline constructs. | |
2396 @end menu | |
2397 | |
2398 @node Font Lock Basics | |
2399 @subsection Font Lock Basics | |
2400 | |
2401 There are several variables that control how Font Lock mode highlights | |
2402 text. But major modes should not set any of these variables directly. | |
2403 Instead, they should set @code{font-lock-defaults} as a buffer-local | |
2404 variable. The value assigned to this variable is used, if and when Font | |
2405 Lock mode is enabled, to set all the other variables. | |
2406 | |
2407 @defvar font-lock-defaults | |
2408 This variable is set by major modes, as a buffer-local variable, to | |
2409 specify how to fontify text in that mode. It automatically becomes | |
2410 buffer-local when you set it. If its value is @code{nil}, Font-Lock | |
2411 mode does no highlighting, and you can use the @samp{Faces} menu | |
2412 (under @samp{Edit} and then @samp{Text Properties} in the menu bar) to | |
2413 assign faces explicitly to text in the buffer. | |
2414 | |
2415 If non-@code{nil}, the value should look like this: | |
2416 | |
2417 @example | |
2418 (@var{keywords} [@var{keywords-only} [@var{case-fold} | |
2419 [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) | |
2420 @end example | |
2421 | |
2422 The first element, @var{keywords}, indirectly specifies the value of | |
2423 @code{font-lock-keywords} which directs search-based fontification. | |
2424 It can be a symbol, a variable or a function whose value is the list | |
2425 to use for @code{font-lock-keywords}. It can also be a list of | |
2426 several such symbols, one for each possible level of fontification. | |
2427 The first symbol specifies how to do level 1 fontification, the second | |
2428 symbol how to do level 2, and so on. @xref{Levels of Font Lock}. | |
2429 | |
2430 The second element, @var{keywords-only}, specifies the value of the | |
2431 variable @code{font-lock-keywords-only}. If this is omitted or | |
2432 @code{nil}, syntactic fontification (of strings and comments) is also | |
2433 performed. If this is non-@code{nil}, such fontification is not | |
2434 performed. @xref{Syntactic Font Lock}. | |
2435 | |
2436 The third element, @var{case-fold}, specifies the value of | |
2437 @code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, | |
2438 Font Lock mode ignores case when searching as directed by | |
2439 @code{font-lock-keywords}. | |
2440 | |
2441 If the fourth element, @var{syntax-alist}, is non-@code{nil}, it | |
2442 should be a list of cons cells of the form @code{(@var{char-or-string} | |
2443 . @var{string})}. These are used to set up a syntax table for | |
2444 syntactic fontification (@pxref{Syntax Table Functions}). The | |
2445 resulting syntax table is stored in @code{font-lock-syntax-table}. | |
2446 | |
2447 The fifth element, @var{syntax-begin}, specifies the value of | |
2448 @code{font-lock-beginning-of-syntax-function}. We recommend setting | |
2449 this variable to @code{nil} and using @code{syntax-begin-function} | |
2450 instead. | |
2451 | |
2452 All the remaining elements (if any) are collectively called | |
2453 @var{other-vars}. Each of these elements should have the form | |
2454 @code{(@var{variable} . @var{value})}---which means, make | |
2455 @var{variable} buffer-local and then set it to @var{value}. You can | |
2456 use these @var{other-vars} to set other variables that affect | |
2457 fontification, aside from those you can control with the first five | |
2458 elements. @xref{Other Font Lock Variables}. | |
2459 @end defvar | |
2460 | |
2461 If your mode fontifies text explicitly by adding | |
2462 @code{font-lock-face} properties, it can specify @code{(nil t)} for | |
2463 @code{font-lock-defaults} to turn off all automatic fontification. | |
2464 However, this is not required; it is possible to fontify some things | |
2465 using @code{font-lock-face} properties and set up automatic | |
2466 fontification for other parts of the text. | |
2467 | |
2468 @node Search-based Fontification | |
2469 @subsection Search-based Fontification | |
2470 | |
2471 The most important variable for customizing Font Lock mode is | |
2472 @code{font-lock-keywords}. It specifies the search criteria for | |
2473 search-based fontification. You should specify the value of this | |
2474 variable with @var{keywords} in @code{font-lock-defaults}. | |
2475 | |
2476 @defvar font-lock-keywords | |
2477 This variable's value is a list of the keywords to highlight. Be | |
2478 careful when composing regular expressions for this list; a poorly | |
2479 written pattern can dramatically slow things down! | |
2480 @end defvar | |
2481 | |
2482 Each element of @code{font-lock-keywords} specifies how to find | |
2483 certain cases of text, and how to highlight those cases. Font Lock mode | |
2484 processes the elements of @code{font-lock-keywords} one by one, and for | |
2485 each element, it finds and handles all matches. Ordinarily, once | |
2486 part of the text has been fontified already, this cannot be overridden | |
2487 by a subsequent match in the same text; but you can specify different | |
2488 behavior using the @var{override} element of a @var{subexp-highlighter}. | |
2489 | |
2490 Each element of @code{font-lock-keywords} should have one of these | |
2491 forms: | |
2492 | |
2493 @table @code | |
2494 @item @var{regexp} | |
2495 Highlight all matches for @var{regexp} using | |
2496 @code{font-lock-keyword-face}. For example, | |
2497 | |
2498 @example | |
2499 ;; @r{Highlight occurrences of the word @samp{foo}} | |
2500 ;; @r{using @code{font-lock-keyword-face}.} | |
2501 "\\<foo\\>" | |
2502 @end example | |
2503 | |
2504 The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful | |
2505 for calculating optimal regular expressions to match a number of | |
2506 different keywords. | |
2507 | |
2508 @item @var{function} | |
2509 Find text by calling @var{function}, and highlight the matches | |
2510 it finds using @code{font-lock-keyword-face}. | |
2511 | |
2512 When @var{function} is called, it receives one argument, the limit of | |
2513 the search; it should begin searching at point, and not search beyond the | |
2514 limit. It should return non-@code{nil} if it succeeds, and set the | |
2515 match data to describe the match that was found. Returning @code{nil} | |
2516 indicates failure of the search. | |
2517 | |
2518 Fontification will call @var{function} repeatedly with the same limit, | |
2519 and with point where the previous invocation left it, until | |
2520 @var{function} fails. On failure, @var{function} need not reset point | |
2521 in any particular way. | |
2522 | |
2523 @item (@var{matcher} . @var{subexp}) | |
2524 In this kind of element, @var{matcher} is either a regular | |
2525 expression or a function, as described above. The @sc{cdr}, | |
2526 @var{subexp}, specifies which subexpression of @var{matcher} should be | |
2527 highlighted (instead of the entire text that @var{matcher} matched). | |
2528 | |
2529 @example | |
2530 ;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} | |
2531 ;; @r{using @code{font-lock-keyword-face}.} | |
2532 ("fu\\(bar\\)" . 1) | |
2533 @end example | |
2534 | |
2535 If you use @code{regexp-opt} to produce the regular expression | |
2536 @var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp | |
2537 Functions}) to calculate the value for @var{subexp}. | |
2538 | |
2539 @item (@var{matcher} . @var{facespec}) | |
2540 In this kind of element, @var{facespec} is an expression whose value | |
2541 specifies the face to use for highlighting. In the simplest case, | |
2542 @var{facespec} is a Lisp variable (a symbol) whose value is a face | |
2543 name. | |
2544 | |
2545 @example | |
2546 ;; @r{Highlight occurrences of @samp{fubar},} | |
2547 ;; @r{using the face which is the value of @code{fubar-face}.} | |
2548 ("fubar" . fubar-face) | |
2549 @end example | |
2550 | |
2551 However, @var{facespec} can also evaluate to a list of this form: | |
2552 | |
2553 @example | |
2554 (face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) | |
2555 @end example | |
2556 | |
2557 @noindent | |
2558 to specify the face @var{face} and various additional text properties | |
2559 to put on the text that matches. If you do this, be sure to add the | |
2560 other text property names that you set in this way to the value of | |
2561 @code{font-lock-extra-managed-props} so that the properties will also | |
2562 be cleared out when they are no longer appropriate. Alternatively, | |
2563 you can set the variable @code{font-lock-unfontify-region-function} to | |
2564 a function that clears these properties. @xref{Other Font Lock | |
2565 Variables}. | |
2566 | |
2567 @item (@var{matcher} . @var{subexp-highlighter}) | |
2568 In this kind of element, @var{subexp-highlighter} is a list | |
2569 which specifies how to highlight matches found by @var{matcher}. | |
2570 It has the form: | |
2571 | |
2572 @example | |
2573 (@var{subexp} @var{facespec} [[@var{override} [@var{laxmatch}]]) | |
2574 @end example | |
2575 | |
2576 The @sc{car}, @var{subexp}, is an integer specifying which subexpression | |
2577 of the match to fontify (0 means the entire matching text). The second | |
2578 subelement, @var{facespec}, is an expression whose value specifies the | |
2579 face, as described above. | |
2580 | |
2581 The last two values in @var{subexp-highlighter}, @var{override} and | |
2582 @var{laxmatch}, are optional flags. If @var{override} is @code{t}, | |
2583 this element can override existing fontification made by previous | |
2584 elements of @code{font-lock-keywords}. If it is @code{keep}, then | |
2585 each character is fontified if it has not been fontified already by | |
2586 some other element. If it is @code{prepend}, the face specified by | |
2587 @var{facespec} is added to the beginning of the @code{font-lock-face} | |
2588 property. If it is @code{append}, the face is added to the end of the | |
2589 @code{font-lock-face} property. | |
2590 | |
2591 If @var{laxmatch} is non-@code{nil}, it means there should be no error | |
2592 if there is no subexpression numbered @var{subexp} in @var{matcher}. | |
2593 Obviously, fontification of the subexpression numbered @var{subexp} will | |
2594 not occur. However, fontification of other subexpressions (and other | |
2595 regexps) will continue. If @var{laxmatch} is @code{nil}, and the | |
2596 specified subexpression is missing, then an error is signaled which | |
2597 terminates search-based fontification. | |
2598 | |
2599 Here are some examples of elements of this kind, and what they do: | |
2600 | |
2601 @smallexample | |
2602 ;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} | |
2603 ;; @r{@code{foo-bar-face}, even if they have already been highlighted.} | |
2604 ;; @r{@code{foo-bar-face} should be a variable whose value is a face.} | |
2605 ("foo\\|bar" 0 foo-bar-face t) | |
2606 | |
2607 ;; @r{Highlight the first subexpression within each occurrence} | |
2608 ;; @r{that the function @code{fubar-match} finds,} | |
2609 ;; @r{using the face which is the value of @code{fubar-face}.} | |
2610 (fubar-match 1 fubar-face) | |
2611 @end smallexample | |
2612 | |
2613 @item (@var{matcher} . @var{anchored-highlighter}) | |
2614 In this kind of element, @var{anchored-highlighter} specifies how to | |
2615 highlight text that follows a match found by @var{matcher}. So a | |
2616 match found by @var{matcher} acts as the anchor for further searches | |
2617 specified by @var{anchored-highlighter}. @var{anchored-highlighter} | |
2618 is a list of the following form: | |
2619 | |
2620 @example | |
2621 (@var{anchored-matcher} @var{pre-form} @var{post-form} | |
2622 @var{subexp-highlighters}@dots{}) | |
2623 @end example | |
2624 | |
2625 Here, @var{anchored-matcher}, like @var{matcher}, is either a regular | |
2626 expression or a function. After a match of @var{matcher} is found, | |
2627 point is at the end of the match. Now, Font Lock evaluates the form | |
2628 @var{pre-form}. Then it searches for matches of | |
2629 @var{anchored-matcher} and uses @var{subexp-highlighters} to highlight | |
2630 these. A @var{subexp-highlighter} is as described above. Finally, | |
2631 Font Lock evaluates @var{post-form}. | |
2632 | |
2633 The forms @var{pre-form} and @var{post-form} can be used to initialize | |
2634 before, and cleanup after, @var{anchored-matcher} is used. Typically, | |
2635 @var{pre-form} is used to move point to some position relative to the | |
2636 match of @var{matcher}, before starting with @var{anchored-matcher}. | |
2637 @var{post-form} might be used to move back, before resuming with | |
2638 @var{matcher}. | |
2639 | |
2640 After Font Lock evaluates @var{pre-form}, it does not search for | |
2641 @var{anchored-matcher} beyond the end of the line. However, if | |
2642 @var{pre-form} returns a buffer position that is greater than the | |
2643 position of point after @var{pre-form} is evaluated, then the position | |
2644 returned by @var{pre-form} is used as the limit of the search instead. | |
2645 It is generally a bad idea to return a position greater than the end | |
2646 of the line; in other words, the @var{anchored-matcher} search should | |
2647 not span lines. | |
2648 | |
2649 For example, | |
2650 | |
2651 @smallexample | |
2652 ;; @r{Highlight occurrences of the word @samp{item} following} | |
2653 ;; @r{an occurrence of the word @samp{anchor} (on the same line)} | |
2654 ;; @r{in the value of @code{item-face}.} | |
2655 ("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face)) | |
2656 @end smallexample | |
2657 | |
2658 Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore | |
2659 searching for @samp{item} starts at the end of the match of | |
2660 @samp{anchor}, and searching for subsequent instances of @samp{anchor} | |
2661 resumes from where searching for @samp{item} concluded. | |
2662 | |
2663 @item (@var{matcher} @var{highlighters}@dots{}) | |
2664 This sort of element specifies several @var{highlighter} lists for a | |
2665 single @var{matcher}. A @var{highlighter} list can be of the type | |
2666 @var{subexp-highlighter} or @var{anchored-highlighter} as described | |
2667 above. | |
2668 | |
2669 For example, | |
2670 | |
2671 @smallexample | |
2672 ;; @r{Highlight occurrences of the word @samp{anchor} in the value} | |
2673 ;; @r{of @code{anchor-face}, and subsequent occurrences of the word} | |
2674 ;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} | |
2675 ("\\<anchor\\>" (0 anchor-face) | |
2676 ("\\<item\\>" nil nil (0 item-face))) | |
2677 @end smallexample | |
2678 | |
2679 @item (eval . @var{form}) | |
2680 Here @var{form} is an expression to be evaluated the first time | |
2681 this value of @code{font-lock-keywords} is used in a buffer. | |
2682 Its value should have one of the forms described in this table. | |
2683 @end table | |
2684 | |
2685 @strong{Warning:} Do not design an element of @code{font-lock-keywords} | |
2686 to match text which spans lines; this does not work reliably. | |
2687 For details, see @xref{Multiline Font Lock}. | |
2688 | |
2689 You can use @var{case-fold} in @code{font-lock-defaults} to specify | |
2690 the value of @code{font-lock-keywords-case-fold-search} which says | |
2691 whether search-based fontification should be case-insensitive. | |
2692 | |
2693 @defvar font-lock-keywords-case-fold-search | |
2694 Non-@code{nil} means that regular expression matching for the sake of | |
2695 @code{font-lock-keywords} should be case-insensitive. | |
2696 @end defvar | |
2697 | |
2698 @node Customizing Keywords | |
2699 @subsection Customizing Search-Based Fontification | |
2700 | |
2701 You can use @code{font-lock-add-keywords} to add additional | |
2702 search-based fontification rules to a major mode, and | |
2703 @code{font-lock-remove-keywords} to removes rules. | |
2704 | |
2705 @defun font-lock-add-keywords mode keywords &optional how | |
2706 This function adds highlighting @var{keywords}, for the current buffer | |
2707 or for major mode @var{mode}. The argument @var{keywords} should be a | |
2708 list with the same format as the variable @code{font-lock-keywords}. | |
2709 | |
2710 If @var{mode} is a symbol which is a major mode command name, such as | |
2711 @code{c-mode}, the effect is that enabling Font Lock mode in | |
2712 @var{mode} will add @var{keywords} to @code{font-lock-keywords}. | |
2713 Calling with a non-@code{nil} value of @var{mode} is correct only in | |
2714 your @file{~/.emacs} file. | |
2715 | |
2716 If @var{mode} is @code{nil}, this function adds @var{keywords} to | |
2717 @code{font-lock-keywords} in the current buffer. This way of calling | |
2718 @code{font-lock-add-keywords} is usually used in mode hook functions. | |
2719 | |
2720 By default, @var{keywords} are added at the beginning of | |
2721 @code{font-lock-keywords}. If the optional argument @var{how} is | |
2722 @code{set}, they are used to replace the value of | |
2723 @code{font-lock-keywords}. If @var{how} is any other non-@code{nil} | |
2724 value, they are added at the end of @code{font-lock-keywords}. | |
2725 | |
2726 Some modes provide specialized support you can use in additional | |
2727 highlighting patterns. See the variables | |
2728 @code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, | |
2729 and @code{java-font-lock-extra-types}, for example. | |
2730 | |
2731 @strong{Warning:} major mode functions must not call | |
2732 @code{font-lock-add-keywords} under any circumstances, either directly | |
2733 or indirectly, except through their mode hooks. (Doing so would lead | |
2734 to incorrect behavior for some minor modes.) They should set up their | |
2735 rules for search-based fontification by setting | |
2736 @code{font-lock-keywords}. | |
2737 @end defun | |
2738 | |
2739 @defun font-lock-remove-keywords mode keywords | |
2740 This function removes @var{keywords} from @code{font-lock-keywords} | |
2741 for the current buffer or for major mode @var{mode}. As in | |
2742 @code{font-lock-add-keywords}, @var{mode} should be a major mode | |
2743 command name or @code{nil}. All the caveats and requirements for | |
2744 @code{font-lock-add-keywords} apply here too. | |
2745 @end defun | |
2746 | |
2747 For example, this code | |
2748 | |
2749 @smallexample | |
2750 (font-lock-add-keywords 'c-mode | |
2751 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) | |
2752 ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) | |
2753 @end smallexample | |
2754 | |
2755 @noindent | |
2756 adds two fontification patterns for C mode: one to fontify the word | |
2757 @samp{FIXME}, even in comments, and another to fontify the words | |
2758 @samp{and}, @samp{or} and @samp{not} as keywords. | |
2759 | |
2760 @noindent | |
2761 That example affects only C mode proper. To add the same patterns to | |
2762 C mode @emph{and} all modes derived from it, do this instead: | |
2763 | |
2764 @smallexample | |
2765 (add-hook 'c-mode-hook | |
2766 (lambda () | |
2767 (font-lock-add-keywords nil | |
2768 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) | |
2769 ("\\<\\(and\\|or\\|not\\)\\>" . | |
2770 font-lock-keyword-face))))) | |
2771 @end smallexample | |
2772 | |
2773 @node Other Font Lock Variables | |
2774 @subsection Other Font Lock Variables | |
2775 | |
2776 This section describes additional variables that a major mode can | |
2777 set by means of @var{other-vars} in @code{font-lock-defaults} | |
2778 (@pxref{Font Lock Basics}). | |
2779 | |
2780 @defvar font-lock-mark-block-function | |
2781 If this variable is non-@code{nil}, it should be a function that is | |
2782 called with no arguments, to choose an enclosing range of text for | |
2783 refontification for the command @kbd{M-o M-o} | |
2784 (@code{font-lock-fontify-block}). | |
2785 | |
2786 The function should report its choice by placing the region around it. | |
2787 A good choice is a range of text large enough to give proper results, | |
2788 but not too large so that refontification becomes slow. Typical values | |
2789 are @code{mark-defun} for programming modes or @code{mark-paragraph} for | |
2790 textual modes. | |
2791 @end defvar | |
2792 | |
2793 @defvar font-lock-extra-managed-props | |
2794 This variable specifies additional properties (other than | |
2795 @code{font-lock-face}) that are being managed by Font Lock mode. It | |
2796 is used by @code{font-lock-default-unfontify-region}, which normally | |
2797 only manages the @code{font-lock-face} property. If you want Font | |
2798 Lock to manage other properties as well, you must specify them in a | |
2799 @var{facespec} in @code{font-lock-keywords} as well as add them to | |
2800 this list. @xref{Search-based Fontification}. | |
2801 @end defvar | |
2802 | |
2803 @defvar font-lock-fontify-buffer-function | |
2804 Function to use for fontifying the buffer. The default value is | |
2805 @code{font-lock-default-fontify-buffer}. | |
2806 @end defvar | |
2807 | |
2808 @defvar font-lock-unfontify-buffer-function | |
2809 Function to use for unfontifying the buffer. This is used when | |
2810 turning off Font Lock mode. The default value is | |
2811 @code{font-lock-default-unfontify-buffer}. | |
2812 @end defvar | |
2813 | |
2814 @defvar font-lock-fontify-region-function | |
2815 Function to use for fontifying a region. It should take two | |
2816 arguments, the beginning and end of the region, and an optional third | |
2817 argument @var{verbose}. If @var{verbose} is non-@code{nil}, the | |
2818 function should print status messages. The default value is | |
2819 @code{font-lock-default-fontify-region}. | |
2820 @end defvar | |
2821 | |
2822 @defvar font-lock-unfontify-region-function | |
2823 Function to use for unfontifying a region. It should take two | |
2824 arguments, the beginning and end of the region. The default value is | |
2825 @code{font-lock-default-unfontify-region}. | |
2826 @end defvar | |
2827 | |
2828 @ignore | |
2829 @defvar font-lock-inhibit-thing-lock | |
2830 List of Font Lock mode related modes that should not be turned on. | |
2831 Currently, valid mode names are @code{fast-lock-mode}, | |
2832 @code{jit-lock-mode} and @code{lazy-lock-mode}. | |
2833 @end defvar | |
2834 @end ignore | |
2835 | |
2836 @node Levels of Font Lock | |
2837 @subsection Levels of Font Lock | |
2838 | |
2839 Many major modes offer three different levels of fontification. You | |
2840 can define multiple levels by using a list of symbols for @var{keywords} | |
2841 in @code{font-lock-defaults}. Each symbol specifies one level of | |
2842 fontification; it is up to the user to choose one of these levels. The | |
2843 chosen level's symbol value is used to initialize | |
2844 @code{font-lock-keywords}. | |
2845 | |
2846 Here are the conventions for how to define the levels of | |
2847 fontification: | |
2848 | |
2849 @itemize @bullet | |
2850 @item | |
2851 Level 1: highlight function declarations, file directives (such as include or | |
2852 import directives), strings and comments. The idea is speed, so only | |
2853 the most important and top-level components are fontified. | |
2854 | |
2855 @item | |
2856 Level 2: in addition to level 1, highlight all language keywords, | |
2857 including type names that act like keywords, as well as named constant | |
2858 values. The idea is that all keywords (either syntactic or semantic) | |
2859 should be fontified appropriately. | |
2860 | |
2861 @item | |
2862 Level 3: in addition to level 2, highlight the symbols being defined in | |
2863 function and variable declarations, and all builtin function names, | |
2864 wherever they appear. | |
2865 @end itemize | |
2866 | |
2867 @node Precalculated Fontification | |
2868 @subsection Precalculated Fontification | |
2869 | |
2870 In addition to using @code{font-lock-defaults} for search-based | |
2871 fontification, you may use the special character property | |
2872 @code{font-lock-face} (@pxref{Special Properties}). This property | |
2873 acts just like the explicit @code{face} property, but its activation | |
2874 is toggled when the user calls @kbd{M-x font-lock-mode}. Using | |
2875 @code{font-lock-face} is especially convenient for special modes | |
2876 which construct their text programmatically, such as | |
2877 @code{list-buffers} and @code{occur}. | |
2878 | |
2879 If your mode does not use any of the other machinery of Font Lock | |
2880 (i.e. it only uses the @code{font-lock-face} property), it should not | |
2881 set the variable @code{font-lock-defaults}. | |
2882 | |
2883 @node Faces for Font Lock | |
2884 @subsection Faces for Font Lock | |
2885 @cindex faces for font lock | |
2886 @cindex font lock faces | |
2887 | |
2888 You can make Font Lock mode use any face, but several faces are | |
2889 defined specifically for Font Lock mode. Each of these symbols is both | |
2890 a face name, and a variable whose default value is the symbol itself. | |
2891 Thus, the default value of @code{font-lock-comment-face} is | |
2892 @code{font-lock-comment-face}. This means you can write | |
2893 @code{font-lock-comment-face} in a context such as | |
2894 @code{font-lock-keywords} where a face-name-valued expression is used. | |
2895 | |
2896 @table @code | |
2897 @item font-lock-comment-face | |
2898 @vindex font-lock-comment-face | |
2899 Used (typically) for comments. | |
2900 | |
2901 @item font-lock-comment-delimiter-face | |
2902 @vindex font-lock-comment-delimiter-face | |
2903 Used (typically) for comments delimiters. | |
2904 | |
2905 @item font-lock-doc-face | |
2906 @vindex font-lock-doc-face | |
2907 Used (typically) for documentation strings in the code. | |
2908 | |
2909 @item font-lock-string-face | |
2910 @vindex font-lock-string-face | |
2911 Used (typically) for string constants. | |
2912 | |
2913 @item font-lock-keyword-face | |
2914 @vindex font-lock-keyword-face | |
2915 Used (typically) for keywords---names that have special syntactic | |
2916 significance, like @code{for} and @code{if} in C. | |
2917 | |
2918 @item font-lock-builtin-face | |
2919 @vindex font-lock-builtin-face | |
2920 Used (typically) for built-in function names. | |
2921 | |
2922 @item font-lock-function-name-face | |
2923 @vindex font-lock-function-name-face | |
2924 Used (typically) for the name of a function being defined or declared, | |
2925 in a function definition or declaration. | |
2926 | |
2927 @item font-lock-variable-name-face | |
2928 @vindex font-lock-variable-name-face | |
2929 Used (typically) for the name of a variable being defined or declared, | |
2930 in a variable definition or declaration. | |
2931 | |
2932 @item font-lock-type-face | |
2933 @vindex font-lock-type-face | |
2934 Used (typically) for names of user-defined data types, | |
2935 where they are defined and where they are used. | |
2936 | |
2937 @item font-lock-constant-face | |
2938 @vindex font-lock-constant-face | |
2939 Used (typically) for constant names. | |
2940 | |
2941 @item font-lock-preprocessor-face | |
2942 @vindex font-lock-preprocessor-face | |
2943 Used (typically) for preprocessor commands. | |
2944 | |
2945 @item font-lock-negation-char-face | |
2946 @vindex font-lock-negation-char-face | |
2947 Used (typically) for easily-overlooked negation characters. | |
2948 | |
2949 @item font-lock-warning-face | |
2950 @vindex font-lock-warning-face | |
2951 Used (typically) for constructs that are peculiar, or that greatly | |
2952 change the meaning of other text. For example, this is used for | |
2953 @samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error} | |
2954 directives in C. | |
2955 @end table | |
2956 | |
2957 @node Syntactic Font Lock | |
2958 @subsection Syntactic Font Lock | |
2959 @cindex syntactic font lock | |
2960 | |
2961 Syntactic fontification uses the syntax table to find comments and | |
2962 string constants (@pxref{Syntax Tables}). It highlights them using | |
2963 @code{font-lock-comment-face} and @code{font-lock-string-face} | |
2964 (@pxref{Faces for Font Lock}), or whatever | |
2965 @code{font-lock-syntactic-face-function} chooses. There are several | |
2966 variables that affect syntactic fontification; you should set them by | |
2967 means of @code{font-lock-defaults} (@pxref{Font Lock Basics}). | |
2968 | |
2969 @defvar font-lock-keywords-only | |
2970 Non-@code{nil} means Font Lock should not do syntactic fontification; | |
2971 it should only fontify based on @code{font-lock-keywords}. The normal | |
2972 way for a mode to set this variable to @code{t} is with | |
2973 @var{keywords-only} in @code{font-lock-defaults}. | |
2974 @end defvar | |
2975 | |
2976 @defvar font-lock-syntax-table | |
2977 This variable holds the syntax table to use for fontification of | |
2978 comments and strings. Specify it using @var{syntax-alist} in | |
2979 @code{font-lock-defaults}. If this is @code{nil}, fontification uses | |
2980 the buffer's syntax table. | |
2981 @end defvar | |
2982 | |
2983 @defvar font-lock-beginning-of-syntax-function | |
2984 If this variable is non-@code{nil}, it should be a function to move | |
2985 point back to a position that is syntactically at ``top level'' and | |
2986 outside of strings or comments. Font Lock uses this when necessary | |
2987 to get the right results for syntactic fontification. | |
2988 | |
2989 This function is called with no arguments. It should leave point at | |
2990 the beginning of any enclosing syntactic block. Typical values are | |
2991 @code{beginning-of-line} (used when the start of the line is known to | |
2992 be outside a syntactic block), or @code{beginning-of-defun} for | |
2993 programming modes, or @code{backward-paragraph} for textual modes. | |
2994 | |
2995 If the value is @code{nil}, Font Lock uses | |
2996 @code{syntax-begin-function} to move back outside of any comment, | |
2997 string, or sexp. This variable is semi-obsolete; we recommend setting | |
2998 @code{syntax-begin-function} instead. | |
2999 | |
3000 Specify this variable using @var{syntax-begin} in | |
3001 @code{font-lock-defaults}. | |
3002 @end defvar | |
3003 | |
3004 @defvar font-lock-syntactic-face-function | |
3005 A function to determine which face to use for a given syntactic | |
3006 element (a string or a comment). The function is called with one | |
3007 argument, the parse state at point returned by | |
3008 @code{parse-partial-sexp}, and should return a face. The default | |
3009 value returns @code{font-lock-comment-face} for comments and | |
3010 @code{font-lock-string-face} for strings. | |
3011 | |
3012 This can be used to highlighting different kinds of strings or | |
3013 comments differently. It is also sometimes abused together with | |
3014 @code{font-lock-syntactic-keywords} to highlight constructs that span | |
3015 multiple lines, but this is too esoteric to document here. | |
3016 | |
3017 Specify this variable using @var{other-vars} in | |
3018 @code{font-lock-defaults}. | |
3019 @end defvar | |
3020 | |
3021 @node Setting Syntax Properties | |
3022 @subsection Setting Syntax Properties | |
3023 | |
3024 Font Lock mode can be used to update @code{syntax-table} properties | |
3025 automatically (@pxref{Syntax Properties}). This is useful in | |
3026 languages for which a single syntax table by itself is not sufficient. | |
3027 | |
3028 @defvar font-lock-syntactic-keywords | |
3029 This variable enables and controls updating @code{syntax-table} | |
3030 properties by Font Lock. Its value should be a list of elements of | |
3031 this form: | |
3032 | |
3033 @example | |
3034 (@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch}) | |
3035 @end example | |
3036 | |
3037 The parts of this element have the same meanings as in the corresponding | |
3038 sort of element of @code{font-lock-keywords}, | |
3039 | |
3040 @example | |
3041 (@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch}) | |
3042 @end example | |
3043 | |
3044 However, instead of specifying the value @var{facespec} to use for the | |
3045 @code{face} property, it specifies the value @var{syntax} to use for | |
3046 the @code{syntax-table} property. Here, @var{syntax} can be a string | |
3047 (as taken by @code{modify-syntax-entry}), a syntax table, a cons cell | |
3048 (as returned by @code{string-to-syntax}), or an expression whose value | |
3049 is one of those two types. @var{override} cannot be @code{prepend} or | |
3050 @code{append}. | |
3051 | |
3052 For example, an element of the form: | |
3053 | |
3054 @example | |
3055 ("\\$\\(#\\)" 1 ".") | |
3056 @end example | |
3057 | |
3058 highlights syntactically a hash character when following a dollar | |
3059 character, with a SYNTAX of @code{"."} (meaning punctuation syntax). | |
3060 Assuming that the buffer syntax table specifies hash characters to | |
3061 have comment start syntax, the element will only highlight hash | |
3062 characters that do not follow dollar characters as comments | |
3063 syntactically. | |
3064 | |
3065 An element of the form: | |
3066 | |
3067 @example | |
3068 ("\\('\\).\\('\\)" | |
3069 (1 "\"") | |
3070 (2 "\"")) | |
3071 @end example | |
3072 | |
3073 highlights syntactically both single quotes which surround a single | |
3074 character, with a SYNTAX of @code{"\""} (meaning string quote syntax). | |
3075 Assuming that the buffer syntax table does not specify single quotes | |
3076 to have quote syntax, the element will only highlight single quotes of | |
3077 the form @samp{'@var{c}'} as strings syntactically. Other forms, such | |
3078 as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as | |
3079 strings. | |
3080 | |
3081 Major modes normally set this variable with @var{other-vars} in | |
3082 @code{font-lock-defaults}. | |
3083 @end defvar | |
3084 | |
3085 @node Multiline Font Lock | |
3086 @subsection Multiline Font Lock Constructs | |
3087 @cindex multiline font lock | |
3088 | |
3089 Normally, elements of @code{font-lock-keywords} should not match | |
3090 across multiple lines; that doesn't work reliably, because Font Lock | |
3091 usually scans just part of the buffer, and it can miss a multi-line | |
3092 construct that crosses the line boundary where the scan starts. (The | |
3093 scan normally starts at the beginning of a line.) | |
3094 | |
3095 Making elements that match multiline constructs work properly has | |
3096 two aspects: correct @emph{identification} and correct | |
3097 @emph{rehighlighting}. The first means that Font Lock finds all | |
3098 multiline constructs. The second means that Font Lock will correctly | |
3099 rehighlight all the relevant text when a multiline construct is | |
3100 changed---for example, if some of the text that was previously part of | |
3101 a multiline construct ceases to be part of it. The two aspects are | |
3102 closely related, and often getting one of them to work will appear to | |
3103 make the other also work. However, for reliable results you must | |
3104 attend explicitly to both aspects. | |
3105 | |
3106 There are three ways to ensure correct identification of multiline | |
3107 constructs: | |
3108 | |
3109 @itemize | |
3110 @item | |
3111 Add a function to @code{font-lock-extend-region-functions} that does | |
3112 the @emph{identification} and extends the scan so that the scanned | |
3113 text never starts or ends in the middle of a multiline construct. | |
3114 @item | |
3115 Use the @code{font-lock-fontify-region-function} hook similarly to | |
3116 extend the scan so that the scanned text never starts or ends in the | |
3117 middle of a multiline construct. | |
3118 @item | |
3119 Somehow identify the multiline construct right when it gets inserted | |
3120 into the buffer (or at any point after that but before font-lock | |
3121 tries to highlight it), and mark it with a @code{font-lock-multiline} | |
3122 which will instruct font-lock not to start or end the scan in the | |
3123 middle of the construct. | |
3124 @end itemize | |
3125 | |
3126 There are three ways to do rehighlighting of multiline constructs: | |
3127 | |
3128 @itemize | |
3129 @item | |
3130 Place a @code{font-lock-multiline} property on the construct. This | |
3131 will rehighlight the whole construct if any part of it is changed. In | |
3132 some cases you can do this automatically by setting the | |
3133 @code{font-lock-multiline} variable, which see. | |
3134 @item | |
3135 Make sure @code{jit-lock-contextually} is set and rely on it doing its | |
3136 job. This will only rehighlight the part of the construct that | |
3137 follows the actual change, and will do it after a short delay. | |
3138 This only works if the highlighting of the various parts of your | |
3139 multiline construct never depends on text in subsequent lines. | |
3140 Since @code{jit-lock-contextually} is activated by default, this can | |
3141 be an attractive solution. | |
3142 @item | |
3143 Place a @code{jit-lock-defer-multiline} property on the construct. | |
3144 This works only if @code{jit-lock-contextually} is used, and with the | |
3145 same delay before rehighlighting, but like @code{font-lock-multiline}, | |
3146 it also handles the case where highlighting depends on | |
3147 subsequent lines. | |
3148 @end itemize | |
3149 | |
3150 @menu | |
3151 * Font Lock Multiline:: Marking multiline chunks with a text property | |
3152 * Region to Fontify:: Controlling which region gets refontified | |
3153 after a buffer change. | |
3154 @end menu | |
3155 | |
3156 @node Font Lock Multiline | |
3157 @subsubsection Font Lock Multiline | |
3158 | |
3159 One way to ensure reliable rehighlighting of multiline Font Lock | |
3160 constructs is to put on them the text property @code{font-lock-multiline}. | |
3161 It should be present and non-@code{nil} for text that is part of a | |
3162 multiline construct. | |
3163 | |
3164 When Font Lock is about to highlight a range of text, it first | |
3165 extends the boundaries of the range as necessary so that they do not | |
3166 fall within text marked with the @code{font-lock-multiline} property. | |
3167 Then it removes any @code{font-lock-multiline} properties from the | |
3168 range, and highlights it. The highlighting specification (mostly | |
3169 @code{font-lock-keywords}) must reinstall this property each time, | |
3170 whenever it is appropriate. | |
3171 | |
3172 @strong{Warning:} don't use the @code{font-lock-multiline} property | |
3173 on large ranges of text, because that will make rehighlighting slow. | |
3174 | |
3175 @defvar font-lock-multiline | |
3176 If the @code{font-lock-multiline} variable is set to @code{t}, Font | |
3177 Lock will try to add the @code{font-lock-multiline} property | |
3178 automatically on multiline constructs. This is not a universal | |
3179 solution, however, since it slows down Font Lock somewhat. It can | |
3180 miss some multiline constructs, or make the property larger or smaller | |
3181 than necessary. | |
3182 | |
3183 For elements whose @var{matcher} is a function, the function should | |
3184 ensure that submatch 0 covers the whole relevant multiline construct, | |
3185 even if only a small subpart will be highlighted. It is often just as | |
3186 easy to add the @code{font-lock-multiline} property by hand. | |
3187 @end defvar | |
3188 | |
3189 The @code{font-lock-multiline} property is meant to ensure proper | |
3190 refontification; it does not automatically identify new multiline | |
3191 constructs. Identifying the requires that Font-Lock operate on large | |
3192 enough chunks at a time. This will happen by accident on many cases, | |
3193 which may give the impression that multiline constructs magically work. | |
3194 If you set the @code{font-lock-multiline} variable non-@code{nil}, | |
3195 this impression will be even stronger, since the highlighting of those | |
3196 constructs which are found will be properly updated from then on. | |
3197 But that does not work reliably. | |
3198 | |
3199 To find multiline constructs reliably, you must either manually | |
3200 place the @code{font-lock-multiline} property on the text before | |
3201 Font-Lock looks at it, or use | |
3202 @code{font-lock-fontify-region-function}. | |
3203 | |
3204 @node Region to Fontify | |
3205 @subsubsection Region to Fontify after a Buffer Change | |
3206 | |
3207 When a buffer is changed, the region that Font Lock refontifies is | |
3208 by default the smallest sequence of whole lines that spans the change. | |
3209 While this works well most of the time, sometimes it doesn't---for | |
3210 example, when a change alters the syntactic meaning of text on an | |
3211 earlier line. | |
3212 | |
3213 You can enlarge (or even reduce) the region to fontify by setting | |
3214 one the following variables: | |
3215 | |
3216 @defvar font-lock-extend-after-change-region-function | |
3217 This buffer-local variable is either @code{nil} or a function for | |
3218 Font-Lock to call to determine the region to scan and fontify. | |
3219 | |
3220 The function is given three parameters, the standard @var{beg}, | |
3221 @var{end}, and @var{old-len} from after-change-functions | |
3222 (@pxref{Change Hooks}). It should return either a cons of the | |
3223 beginning and end buffer positions (in that order) of the region to | |
3224 fontify, or @code{nil} (which means choose the region in the standard | |
3225 way). This function needs to preserve point, the match-data, and the | |
3226 current restriction. The region it returns may start or end in the | |
3227 middle of a line. | |
3228 | |
3229 Since this function is called after every buffer change, it should be | |
3230 reasonably fast. | |
3231 @end defvar | |
3232 | |
3233 @node Desktop Save Mode | |
3234 @section Desktop Save Mode | |
3235 @cindex desktop save mode | |
3236 | |
3237 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from | |
3238 one session to another. The user-level commands for using Desktop | |
3239 Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs | |
3240 Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit | |
3241 a file, don't have to do anything to use this feature. | |
3242 | |
3243 For buffers not visiting a file to have their state saved, the major | |
3244 mode must bind the buffer local variable @code{desktop-save-buffer} to | |
3245 a non-@code{nil} value. | |
3246 | |
3247 @defvar desktop-save-buffer | |
3248 If this buffer-local variable is non-@code{nil}, the buffer will have | |
3249 its state saved in the desktop file at desktop save. If the value is | |
3250 a function, it is called at desktop save with argument | |
3251 @var{desktop-dirname}, and its value is saved in the desktop file along | |
3252 with the state of the buffer for which it was called. When file names | |
3253 are returned as part of the auxiliary information, they should be | |
3254 formatted using the call | |
3255 | |
3256 @example | |
3257 (desktop-file-name @var{file-name} @var{desktop-dirname}) | |
3258 @end example | |
3259 | |
3260 @end defvar | |
3261 | |
3262 For buffers not visiting a file to be restored, the major mode must | |
3263 define a function to do the job, and that function must be listed in | |
3264 the alist @code{desktop-buffer-mode-handlers}. | |
3265 | |
3266 @defvar desktop-buffer-mode-handlers | |
3267 Alist with elements | |
3268 | |
3269 @example | |
3270 (@var{major-mode} . @var{restore-buffer-function}) | |
3271 @end example | |
3272 | |
3273 The function @var{restore-buffer-function} will be called with | |
3274 argument list | |
3275 | |
3276 @example | |
3277 (@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc}) | |
3278 @end example | |
3279 | |
3280 and it should return the restored buffer. | |
3281 Here @var{desktop-buffer-misc} is the value returned by the function | |
3282 optionally bound to @code{desktop-save-buffer}. | |
3283 @end defvar | |
3284 | |
3285 @ignore | |
3286 arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e | |
3287 @end ignore |