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