Mercurial > emacs
comparison doc/lispref/modes.texi @ 111945:c00190a8c8ef
Merge from emacs-23
author | Stefan Monnier <monnier@iro.umontreal.ca> |
---|---|
date | Mon, 13 Dec 2010 10:27:36 -0500 |
parents | e71e87e08d5f |
children | b4939a7142b0 |
comparison
equal
deleted
inserted
replaced
111884:9b5cce10c8e2 | 111945:c00190a8c8ef |
---|---|
18 indicate them in the mode line, and how they run hooks supplied by the | 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 | 19 user. For related topics such as keymaps and syntax tables, see |
20 @ref{Keymaps}, and @ref{Syntax Tables}. | 20 @ref{Keymaps}, and @ref{Syntax Tables}. |
21 | 21 |
22 @menu | 22 @menu |
23 * Hooks:: How to use hooks; how to write code that provides hooks. | 23 * Hooks:: How to use hooks; how to write code that provides hooks. |
24 * Major Modes:: Defining major modes. | 24 * Major Modes:: Defining major modes. |
25 * Minor Modes:: Defining minor modes. | 25 * Minor Modes:: Defining minor modes. |
26 * Mode Line Format:: Customizing the text that appears in the mode line. | 26 * Mode Line Format:: Customizing the text that appears in the mode line. |
27 * Imenu:: How a mode can provide a menu | 27 * Imenu:: How a mode can provide a menu |
28 of definitions in the buffer. | 28 of definitions in the buffer. |
29 * Font Lock Mode:: How modes can highlight text according to syntax. | 29 * Font Lock Mode:: How modes can highlight text according to syntax. |
30 * Desktop Save Mode:: How modes can have buffer state saved between | 30 * Auto-Indentation:: How to teach Emacs to indent for a major mode. |
31 * Desktop Save Mode:: How modes can have buffer state saved between | |
31 Emacs sessions. | 32 Emacs sessions. |
32 @end menu | 33 @end menu |
33 | 34 |
34 @node Hooks | 35 @node Hooks |
35 @section Hooks | 36 @section Hooks |
76 By convention, abnormal hook names end in @samp{-functions} or | 77 By convention, abnormal hook names end in @samp{-functions} or |
77 @samp{-hooks}. If the variable's name ends in @samp{-function}, then | 78 @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 its value is just a single function, not a list of functions. |
79 | 80 |
80 @menu | 81 @menu |
81 * Running Hooks:: How to run a hook. | 82 * Running Hooks:: How to run a hook. |
82 * Setting Hooks:: How to put functions on a hook, or remove them. | 83 * Setting Hooks:: How to put functions on a hook, or remove them. |
83 @end menu | 84 @end menu |
84 | 85 |
85 @node Running Hooks | 86 @node Running Hooks |
86 @subsection Running Hooks | 87 @subsection Running Hooks |
87 | 88 |
197 buffer-local variable bindings and other data associated with the | 198 buffer-local variable bindings and other data associated with the |
198 buffer, such as a local keymap. The effect lasts until you switch | 199 buffer, such as a local keymap. The effect lasts until you switch |
199 to another major mode in the same buffer. | 200 to another major mode in the same buffer. |
200 | 201 |
201 @menu | 202 @menu |
202 * Major Mode Basics:: | 203 * Major Mode Basics:: |
203 * Major Mode Conventions:: Coding conventions for keymaps, etc. | 204 * Major Mode Conventions:: Coding conventions for keymaps, etc. |
204 * Auto Major Mode:: How Emacs chooses the major mode automatically. | 205 * Auto Major Mode:: How Emacs chooses the major mode automatically. |
205 * Mode Help:: Finding out how to use a mode. | 206 * Mode Help:: Finding out how to use a mode. |
206 * Derived Modes:: Defining a new major mode based on another major | 207 * Derived Modes:: Defining a new major mode based on another major |
207 mode. | 208 mode. |
208 * Generic Modes:: Defining a simple major mode that supports | 209 * Generic Modes:: Defining a simple major mode that supports |
209 comment syntax and Font Lock mode. | 210 comment syntax and Font Lock mode. |
210 * Mode Hooks:: Hooks run at the end of major mode functions. | 211 * Mode Hooks:: Hooks run at the end of major mode functions. |
211 * Example Major Modes:: Text mode and Lisp modes. | 212 * Example Major Modes:: Text mode and Lisp modes. |
212 @end menu | 213 @end menu |
213 | 214 |
214 @node Major Mode Basics | 215 @node Major Mode Basics |
215 @subsection Major Mode Basics | 216 @subsection Major Mode Basics |
216 @cindex Fundamental mode | 217 @cindex Fundamental mode |
236 example, Rmail Edit mode is a major mode that is very similar to Text | 237 example, Rmail Edit mode is a major mode that is very similar to Text |
237 mode except that it provides two additional commands. Its definition | 238 mode except that it provides two additional commands. Its definition |
238 is distinct from that of Text mode, but uses that of Text mode. | 239 is distinct from that of Text mode, but uses that of Text mode. |
239 | 240 |
240 Even if the new mode is not an obvious derivative of any other mode, | 241 Even if the new mode is not an obvious derivative of any other mode, |
241 it is convenient to use @code{define-derived-mode} with a @code{nil} | 242 we recommend to use @code{define-derived-mode}, since it automatically |
242 parent argument, since it automatically enforces the most important | 243 enforces the most important coding conventions for you. |
243 coding conventions for you. | |
244 | 244 |
245 For a very simple programming language major mode that handles | 245 For a very simple programming language major mode that handles |
246 comments and fontification, you can use @code{define-generic-mode}. | 246 comments and fontification, you can use @code{define-generic-mode}. |
247 @xref{Generic Modes}. | 247 @xref{Generic Modes}. |
248 | 248 |
331 @item | 331 @item |
332 In a major mode for editing some kind of structured text, such as a | 332 In a major mode for editing some kind of structured text, such as a |
333 programming language, indentation of text according to structure is | 333 programming language, indentation of text according to structure is |
334 probably useful. So the mode should set @code{indent-line-function} | 334 probably useful. So the mode should set @code{indent-line-function} |
335 to a suitable function, and probably customize other variables | 335 to a suitable function, and probably customize other variables |
336 for indentation. | 336 for indentation. @xref{Auto-Indentation}. |
337 | 337 |
338 @item | 338 @item |
339 @cindex keymaps in modes | 339 @cindex keymaps in modes |
340 The major mode should usually have its own keymap, which is used as the | 340 The major mode should usually have its own keymap, which is used as the |
341 local keymap in all buffers in that mode. The major mode command should | 341 local keymap in all buffers in that mode. The major mode command should |
425 | 425 |
426 @item | 426 @item |
427 The mode can specify a local value for | 427 The mode can specify a local value for |
428 @code{eldoc-documentation-function} to tell ElDoc mode how to handle | 428 @code{eldoc-documentation-function} to tell ElDoc mode how to handle |
429 this mode. | 429 this mode. |
430 | |
431 @item | |
432 The mode can specify how to complete various keywords by adding | |
433 to the special hook @code{completion-at-point-functions}. | |
430 | 434 |
431 @item | 435 @item |
432 Use @code{defvar} or @code{defcustom} to set mode-related variables, so | 436 Use @code{defvar} or @code{defcustom} to set mode-related variables, so |
433 that they are not reinitialized if they already have a value. (Such | 437 that they are not reinitialized if they already have a value. (Such |
434 reinitialization could discard customizations made by the user.) | 438 reinitialization could discard customizations made by the user.) |
490 | 494 |
491 The @code{define-derived-mode} macro automatically marks the derived | 495 The @code{define-derived-mode} macro automatically marks the derived |
492 mode as special if the parent mode is special. The special mode | 496 mode as special if the parent mode is special. The special mode |
493 @code{special-mode} provides a convenient parent for other special | 497 @code{special-mode} provides a convenient parent for other special |
494 modes to inherit from; it sets @code{buffer-read-only} to @code{t}, | 498 modes to inherit from; it sets @code{buffer-read-only} to @code{t}, |
495 and does nothing else. | 499 and does little else. |
496 | 500 |
497 @item | 501 @item |
498 If you want to make the new mode the default for files with certain | 502 If you want to make the new mode the default for files with certain |
499 recognizable names, add an element to @code{auto-mode-alist} to select | 503 recognizable names, add an element to @code{auto-mode-alist} to select |
500 the mode for those file names (@pxref{Auto Major Mode}). If you | 504 the mode for those file names (@pxref{Auto Major Mode}). If you |
735 | 739 |
736 @node Derived Modes | 740 @node Derived Modes |
737 @subsection Defining Derived Modes | 741 @subsection Defining Derived Modes |
738 @cindex derived mode | 742 @cindex derived mode |
739 | 743 |
740 It's often useful to define a new major mode in terms of an existing | 744 The recommended way to define a new major mode is to derive it |
741 one. An easy way to do this is to use @code{define-derived-mode}. | 745 from an existing one using @code{define-derived-mode}. If there is no |
746 closely related mode, you can inherit from @code{text-mode}, | |
747 @code{special-mode}, or in the worst case @code{fundamental-mode}. | |
742 | 748 |
743 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} | 749 @defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} |
744 This macro defines @var{variant} as a major mode command, using | 750 This macro defines @var{variant} as a major mode command, using |
745 @var{name} as the string form of the mode name. @var{variant} and | 751 @var{name} as the string form of the mode name. @var{variant} and |
746 @var{parent} should be unquoted symbols. | 752 @var{parent} should be unquoted symbols. |
977 (see the variable `adaptive-fill-mode'). | 983 (see the variable `adaptive-fill-mode'). |
978 \\@{text-mode-map@} | 984 \\@{text-mode-map@} |
979 Turning on Text mode runs the normal hook `text-mode-hook'." | 985 Turning on Text mode runs the normal hook `text-mode-hook'." |
980 @end group | 986 @end group |
981 @group | 987 @group |
982 (make-local-variable 'text-mode-variant) | 988 (set (make-local-variable 'text-mode-variant) t) |
983 (setq text-mode-variant t) | |
984 ;; @r{These two lines are a feature added recently.} | 989 ;; @r{These two lines are a feature added recently.} |
985 (set (make-local-variable 'require-final-newline) | 990 (set (make-local-variable 'require-final-newline) |
986 mode-require-final-newline) | 991 mode-require-final-newline) |
987 (set (make-local-variable 'indent-line-function) 'indent-relative)) | 992 (set (make-local-variable 'indent-line-function) 'indent-relative)) |
988 @end group | 993 @end group |
996 @code{define-derived-mode} existed: | 1001 @code{define-derived-mode} existed: |
997 | 1002 |
998 @smallexample | 1003 @smallexample |
999 @group | 1004 @group |
1000 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} | 1005 ;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} |
1001 (defvar text-mode-abbrev-table nil | 1006 (define-abbrev-table 'text-mode-abbrev-table () |
1002 "Abbrev table used while in text mode.") | 1007 "Abbrev table used while in text mode.") |
1003 (define-abbrev-table 'text-mode-abbrev-table ()) | |
1004 @end group | 1008 @end group |
1005 | 1009 |
1006 @group | 1010 @group |
1007 (defun text-mode () | 1011 (defun text-mode () |
1008 "Major mode for editing text intended for humans to read... | 1012 "Major mode for editing text intended for humans to read... |
1020 @end group | 1024 @end group |
1021 @group | 1025 @group |
1022 ;; @r{These four lines are absent from the current version} | 1026 ;; @r{These four lines are absent from the current version} |
1023 ;; @r{not because this is done some other way, but rather} | 1027 ;; @r{not because this is done some other way, but rather} |
1024 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} | 1028 ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} |
1025 (make-local-variable 'paragraph-start) | 1029 (set (make-local-variable 'paragraph-start) |
1026 (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) | 1030 (concat "[ \t]*$\\|" page-delimiter)) |
1027 (make-local-variable 'paragraph-separate) | 1031 (set (make-local-variable 'paragraph-separate) paragraph-start) |
1028 (setq paragraph-separate paragraph-start) | 1032 (set (make-local-variable 'indent-line-function) 'indent-relative-maybe) |
1029 (make-local-variable 'indent-line-function) | |
1030 (setq indent-line-function 'indent-relative-maybe) | |
1031 @end group | 1033 @end group |
1032 @group | 1034 @group |
1033 (setq mode-name "Text") | 1035 (setq mode-name "Text") |
1034 (setq major-mode 'text-mode) | 1036 (setq major-mode 'text-mode) |
1035 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} | 1037 (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} |
1113 modes should understand the Lisp conventions for comments. The rest of | 1115 modes should understand the Lisp conventions for comments. The rest of |
1114 @code{lisp-mode-variables} sets this up: | 1116 @code{lisp-mode-variables} sets this up: |
1115 | 1117 |
1116 @smallexample | 1118 @smallexample |
1117 @group | 1119 @group |
1118 (make-local-variable 'paragraph-start) | 1120 (set (make-local-variable 'paragraph-start) (concat page-delimiter "\\|$" )) |
1119 (setq paragraph-start (concat page-delimiter "\\|$" )) | 1121 (set (make-local-variable 'paragraph-separate) paragraph-start) |
1120 (make-local-variable 'paragraph-separate) | |
1121 (setq paragraph-separate paragraph-start) | |
1122 @dots{} | 1122 @dots{} |
1123 @end group | 1123 @end group |
1124 @group | 1124 @group |
1125 (make-local-variable 'comment-indent-function) | 1125 (set (make-local-variable 'comment-indent-function) 'lisp-comment-indent)) |
1126 (setq comment-indent-function 'lisp-comment-indent)) | |
1127 @dots{} | 1126 @dots{} |
1128 @end group | 1127 @end group |
1129 @end smallexample | 1128 @end smallexample |
1130 | 1129 |
1131 Each of the different Lisp modes has a slightly different keymap. For | 1130 Each of the different Lisp modes has a slightly different keymap. For |
1133 Lisp modes do not. However, all Lisp modes have some commands in | 1132 Lisp modes do not. However, all Lisp modes have some commands in |
1134 common. The following code sets up the common commands: | 1133 common. The following code sets up the common commands: |
1135 | 1134 |
1136 @smallexample | 1135 @smallexample |
1137 @group | 1136 @group |
1138 (defvar shared-lisp-mode-map () | 1137 (defvar shared-lisp-mode-map |
1138 (let ((map (make-sparse-keymap))) | |
1139 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) | |
1140 (define-key shared-lisp-mode-map "\177" | |
1141 'backward-delete-char-untabify) | |
1142 map) | |
1139 "Keymap for commands shared by all sorts of Lisp modes.") | 1143 "Keymap for commands shared by all sorts of Lisp modes.") |
1140 | |
1141 ;; @r{Putting this @code{if} after the @code{defvar} is an older style.} | |
1142 (if shared-lisp-mode-map | |
1143 () | |
1144 (setq shared-lisp-mode-map (make-sparse-keymap)) | |
1145 (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) | |
1146 (define-key shared-lisp-mode-map "\177" | |
1147 'backward-delete-char-untabify)) | |
1148 @end group | 1144 @end group |
1149 @end smallexample | 1145 @end smallexample |
1150 | 1146 |
1151 @noindent | 1147 @noindent |
1152 And here is the code to set up the keymap for Lisp mode: | 1148 And here is the code to set up the keymap for Lisp mode: |
1153 | 1149 |
1154 @smallexample | 1150 @smallexample |
1155 @group | 1151 @group |
1156 (defvar lisp-mode-map () | 1152 (defvar lisp-mode-map |
1153 (let ((map (make-sparse-keymap))) | |
1154 (set-keymap-parent map shared-lisp-mode-map) | |
1155 (define-key map "\e\C-x" 'lisp-eval-defun) | |
1156 (define-key map "\C-c\C-z" 'run-lisp) | |
1157 map) | |
1157 "Keymap for ordinary Lisp mode...") | 1158 "Keymap for ordinary Lisp mode...") |
1158 | |
1159 (if lisp-mode-map | |
1160 () | |
1161 (setq lisp-mode-map (make-sparse-keymap)) | |
1162 (set-keymap-parent lisp-mode-map shared-lisp-mode-map) | |
1163 (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun) | |
1164 (define-key lisp-mode-map "\C-c\C-z" 'run-lisp)) | |
1165 @end group | 1159 @end group |
1166 @end smallexample | 1160 @end smallexample |
1167 | 1161 |
1168 Finally, here is the complete major mode function definition for | 1162 Finally, here is the complete major mode function definition for |
1169 Lisp mode. | 1163 Lisp mode. |
1190 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} | 1184 (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} |
1191 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} | 1185 (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} |
1192 ; @r{finds out what to describe.} | 1186 ; @r{finds out what to describe.} |
1193 (setq mode-name "Lisp") ; @r{This goes into the mode line.} | 1187 (setq mode-name "Lisp") ; @r{This goes into the mode line.} |
1194 (lisp-mode-variables t) ; @r{This defines various variables.} | 1188 (lisp-mode-variables t) ; @r{This defines various variables.} |
1195 (make-local-variable 'comment-start-skip) | 1189 (set (make-local-variable 'comment-start-skip) |
1196 (setq comment-start-skip | 1190 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") |
1197 "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") | 1191 (set (make-local-variable 'font-lock-keywords-case-fold-search) t) |
1198 (make-local-variable 'font-lock-keywords-case-fold-search) | |
1199 (setq font-lock-keywords-case-fold-search t) | |
1200 @end group | 1192 @end group |
1201 @group | 1193 @group |
1202 (setq imenu-case-fold-search t) | 1194 (setq imenu-case-fold-search t) |
1203 (set-syntax-table lisp-mode-syntax-table) | 1195 (set-syntax-table lisp-mode-syntax-table) |
1204 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} | 1196 (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} |
1578 and header line. We include it in this chapter because much of the | 1570 and header line. We include it in this chapter because much of the |
1579 information displayed in the mode line relates to the enabled major and | 1571 information displayed in the mode line relates to the enabled major and |
1580 minor modes. | 1572 minor modes. |
1581 | 1573 |
1582 @menu | 1574 @menu |
1583 * Base: Mode Line Basics. Basic ideas of mode line control. | 1575 * Base: Mode Line Basics. Basic ideas of mode line control. |
1584 * Data: Mode Line Data. The data structure that controls the mode line. | 1576 * Data: Mode Line Data. The data structure that controls the mode line. |
1585 * Top: Mode Line Top. The top level variable, mode-line-format. | 1577 * Top: Mode Line Top. The top level variable, mode-line-format. |
1586 * Mode Line Variables:: Variables used in that data structure. | 1578 * Mode Line Variables:: Variables used in that data structure. |
1587 * %-Constructs:: Putting information into a mode line. | 1579 * %-Constructs:: Putting information into a mode line. |
1588 * Properties in Mode:: Using text properties in the mode line. | 1580 * Properties in Mode:: Using text properties in the mode line. |
1589 * Header Lines:: Like a mode line, but at the top. | 1581 * Header Lines:: Like a mode line, but at the top. |
1590 * Emulating Mode Line:: Formatting text as the mode line would. | 1582 * Emulating Mode Line:: Formatting text as the mode line would. |
1591 @end menu | 1583 @end menu |
1592 | 1584 |
1593 @node Mode Line Basics | 1585 @node Mode Line Basics |
1594 @subsection Mode Line Basics | 1586 @subsection Mode Line Basics |
1595 | 1587 |
2359 * Search-based Fontification:: Fontification based on regexps. | 2351 * Search-based Fontification:: Fontification based on regexps. |
2360 * Customizing Keywords:: Customizing search-based fontification. | 2352 * Customizing Keywords:: Customizing search-based fontification. |
2361 * Other Font Lock Variables:: Additional customization facilities. | 2353 * Other Font Lock Variables:: Additional customization facilities. |
2362 * Levels of Font Lock:: Each mode can define alternative levels | 2354 * Levels of Font Lock:: Each mode can define alternative levels |
2363 so that the user can select more or less. | 2355 so that the user can select more or less. |
2364 * Precalculated Fontification:: How Lisp programs that produce the buffer | 2356 * Precalculated Fontification:: How Lisp programs that produce the buffer |
2365 contents can also specify how to fontify it. | 2357 contents can also specify how to fontify it. |
2366 * Faces for Font Lock:: Special faces specifically for Font Lock. | 2358 * Faces for Font Lock:: Special faces specifically for Font Lock. |
2367 * Syntactic Font Lock:: Fontification based on syntax tables. | 2359 * Syntactic Font Lock:: Fontification based on syntax tables. |
2368 * Setting Syntax Properties:: Defining character syntax based on context | 2360 * Setting Syntax Properties:: Defining character syntax based on context |
2369 using the Font Lock mechanism. | 2361 using the Font Lock mechanism. |
3221 | 3213 |
3222 Since this function is called after every buffer change, it should be | 3214 Since this function is called after every buffer change, it should be |
3223 reasonably fast. | 3215 reasonably fast. |
3224 @end defvar | 3216 @end defvar |
3225 | 3217 |
3218 @node Auto-Indentation | |
3219 @section Auto-indention of code | |
3220 | |
3221 For programming languages, an important feature of a major mode is to | |
3222 provide automatic indentation. This is controlled in Emacs by | |
3223 @code{indent-line-function} (@pxref{Mode-Specific Indent}). | |
3224 Writing a good indentation function can be difficult and to a large | |
3225 extent it is still a black art. | |
3226 | |
3227 Many major mode authors will start by writing a simple indentation | |
3228 function that works for simple cases, for example by comparing with the | |
3229 indentation of the previous text line. For most programming languages | |
3230 that are not really line-based, this tends to scale very poorly: | |
3231 improving such a function to let it handle more diverse situations tends | |
3232 to become more and more difficult, resulting in the end with a large, | |
3233 complex, unmaintainable indentation function which nobody dares to touch. | |
3234 | |
3235 A good indentation function will usually need to actually parse the | |
3236 text, according to the syntax of the language. Luckily, it is not | |
3237 necessary to parse the text in as much detail as would be needed | |
3238 for a compiler, but on the other hand, the parser embedded in the | |
3239 indentation code will want to be somewhat friendly to syntactically | |
3240 incorrect code. | |
3241 | |
3242 Good maintainable indentation functions usually fall into 2 categories: | |
3243 either parsing forward from some ``safe'' starting point until the | |
3244 position of interest, or parsing backward from the position of interest. | |
3245 Neither of the two is a clearly better choice than the other: parsing | |
3246 backward is often more difficult than parsing forward because | |
3247 programming languages are designed to be parsed forward, but for the | |
3248 purpose of indentation it has the advantage of not needing to | |
3249 guess a ``safe'' starting point, and it generally enjoys the property | |
3250 that only a minimum of text will be analyzed to decide the indentation | |
3251 of a line, so indentation will tend to be unaffected by syntax errors in | |
3252 some earlier unrelated piece of code. Parsing forward on the other hand | |
3253 is usually easier and has the advantage of making it possible to | |
3254 reindent efficiently a whole region at a time, with a single parse. | |
3255 | |
3256 Rather than write your own indentation function from scratch, it is | |
3257 often preferable to try and reuse some existing ones or to rely | |
3258 on a generic indentation engine. There are sadly few such | |
3259 engines. The CC-mode indentation code (used with C, C++, Java, Awk | |
3260 and a few other such modes) has been made more generic over the years, | |
3261 so if your language seems somewhat similar to one of those languages, | |
3262 you might try to use that engine. @c FIXME: documentation? | |
3263 Another one is SMIE which takes an approach in the spirit | |
3264 of Lisp sexps and adapts it to non-Lisp languages. | |
3265 | |
3266 @menu | |
3267 * SMIE:: A simple minded indentation engine | |
3268 @end menu | |
3269 | |
3270 @node SMIE | |
3271 @subsection Simple Minded Indentation Engine | |
3272 | |
3273 SMIE is a package that provides a generic navigation and indentation | |
3274 engine. Based on a very simple parser using an ``operator precedence | |
3275 grammar'', it lets major modes extend the sexp-based navigation of Lisp | |
3276 to non-Lisp languages as well as provide a simple to use but reliable | |
3277 auto-indentation. | |
3278 | |
3279 Operator precedence grammar is a very primitive technology for parsing | |
3280 compared to some of the more common techniques used in compilers. | |
3281 It has the following characteristics: its parsing power is very limited, | |
3282 and it is largely unable to detect syntax errors, but it has the | |
3283 advantage of being algorithmically efficient and able to parse forward | |
3284 just as well as backward. In practice that means that SMIE can use it | |
3285 for indentation based on backward parsing, that it can provide both | |
3286 @code{forward-sexp} and @code{backward-sexp} functionality, and that it | |
3287 will naturally work on syntactically incorrect code without any extra | |
3288 effort. The downside is that it also means that most programming | |
3289 languages cannot be parsed correctly using SMIE, at least not without | |
3290 resorting to some special tricks (@pxref{SMIE Tricks}). | |
3291 | |
3292 @menu | |
3293 * SMIE setup:: SMIE setup and features | |
3294 * Operator Precedence Grammars:: A very simple parsing technique | |
3295 * SMIE Grammar:: Defining the grammar of a language | |
3296 * SMIE Lexer:: Defining tokens | |
3297 * SMIE Tricks:: Working around the parser's limitations | |
3298 * SMIE Indentation:: Specifying indentation rules | |
3299 * SMIE Indentation Helpers:: Helper functions for indentation rules | |
3300 * SMIE Indentation Example:: Sample indentation rules | |
3301 @end menu | |
3302 | |
3303 @node SMIE setup | |
3304 @subsubsection SMIE Setup and Features | |
3305 | |
3306 SMIE is meant to be a one-stop shop for structural navigation and | |
3307 various other features which rely on the syntactic structure of code, in | |
3308 particular automatic indentation. The main entry point is | |
3309 @code{smie-setup} which is a function typically called while setting | |
3310 up a major mode. | |
3311 | |
3312 @defun smie-setup grammar rules-function &rest keywords | |
3313 Setup SMIE navigation and indentation. | |
3314 @var{grammar} is a grammar table generated by @code{smie-prec2->grammar}. | |
3315 @var{rules-function} is a set of indentation rules for use on | |
3316 @code{smie-rules-function}. | |
3317 @var{keywords} are additional arguments, which can include the following | |
3318 keywords: | |
3319 @itemize | |
3320 @item | |
3321 @code{:forward-token} @var{fun}: Specify the forward lexer to use. | |
3322 @item | |
3323 @code{:backward-token} @var{fun}: Specify the backward lexer to use. | |
3324 @end itemize | |
3325 @end defun | |
3326 | |
3327 Calling this function is sufficient to make commands such as | |
3328 @code{forward-sexp}, @code{backward-sexp}, and @code{transpose-sexps} be | |
3329 able to properly handle structural elements other than just the paired | |
3330 parentheses already handled by syntax tables. For example, if the | |
3331 provided grammar is precise enough, @code{transpose-sexps} can correctly | |
3332 transpose the two arguments of a @code{+} operator, taking into account | |
3333 the precedence rules of the language. | |
3334 | |
3335 Calling `smie-setup' is also sufficient to make TAB indentation work in | |
3336 the expected way, extends @code{blink-matching-paren} to apply to | |
3337 elements like @code{begin...end}, and provides some commands that you | |
3338 can bind in the major mode keymap. | |
3339 | |
3340 @deffn Command smie-close-block | |
3341 This command closes the most recently opened (and not yet closed) block. | |
3342 @end deffn | |
3343 | |
3344 @deffn Command smie-down-list &optional arg | |
3345 This command is like @code{down-list} but it also pays attention to | |
3346 nesting of tokens other than parentheses, such as @code{begin...end}. | |
3347 @end deffn | |
3348 | |
3349 @node Operator Precedence Grammars | |
3350 @subsubsection Operator Precedence Grammars | |
3351 | |
3352 SMIE's precedence grammars simply give to each token a pair of | |
3353 precedences: the left-precedence and the right-precedence. We say | |
3354 @code{T1 < T2} if the right-precedence of token @code{T1} is less than | |
3355 the left-precedence of token @code{T2}. A good way to read this | |
3356 @code{<} is as a kind of parenthesis: if we find @code{... T1 something | |
3357 T2 ...} then that should be parsed as @code{... T1 (something T2 ...} | |
3358 rather than as @code{... T1 something) T2 ...}. The latter | |
3359 interpretation would be the case if we had @code{T1 > T2}. If we have | |
3360 @code{T1 = T2}, it means that token T2 follows token T1 in the same | |
3361 syntactic construction, so typically we have @code{"begin" = "end"}. | |
3362 Such pairs of precedences are sufficient to express left-associativity | |
3363 or right-associativity of infix operators, nesting of tokens like | |
3364 parentheses and many other cases. | |
3365 | |
3366 @c ¡Let's leave this undocumented to leave it more open for change! | |
3367 @c @defvar smie-grammar | |
3368 @c The value of this variable is an alist specifying the left and right | |
3369 @c precedence of each token. It is meant to be initialized by using one of | |
3370 @c the functions below. | |
3371 @c @end defvar | |
3372 | |
3373 @defun smie-prec2->grammar table | |
3374 This function takes a @emph{prec2} grammar @var{table} and returns an | |
3375 alist suitable for use in @code{smie-setup}. The @emph{prec2} | |
3376 @var{table} is itself meant to be built by one of the functions below. | |
3377 @end defun | |
3378 | |
3379 @defun smie-merge-prec2s &rest tables | |
3380 This function takes several @emph{prec2} @var{tables} and merges them | |
3381 into a new @emph{prec2} table. | |
3382 @end defun | |
3383 | |
3384 @defun smie-precs->prec2 precs | |
3385 This function builds a @emph{prec2} table from a table of precedences | |
3386 @var{precs}. @var{precs} should be a list, sorted by precedence (for | |
3387 example @code{"+"} will come before @code{"*"}), of elements of the form | |
3388 @code{(@var{assoc} @var{op} ...)}, where each @var{op} is a token that | |
3389 acts as an operator; @var{assoc} is their associativity, which can be | |
3390 either @code{left}, @code{right}, @code{assoc}, or @code{nonassoc}. | |
3391 All operators in a given element share the same precedence level | |
3392 and associativity. | |
3393 @end defun | |
3394 | |
3395 @defun smie-bnf->prec2 bnf &rest resolvers | |
3396 This function lets you specify the grammar using a BNF notation. | |
3397 It accepts a @var{bnf} description of the grammar along with a set of | |
3398 conflict resolution rules @var{resolvers}, and | |
3399 returns a @emph{prec2} table. | |
3400 | |
3401 @var{bnf} is a list of nonterminal definitions of the form | |
3402 @code{(@var{nonterm} @var{rhs1} @var{rhs2} ...)} where each @var{rhs} | |
3403 is a (non-empty) list of terminals (aka tokens) or non-terminals. | |
3404 | |
3405 Not all grammars are accepted: | |
3406 @itemize | |
3407 @item | |
3408 An @var{rhs} cannot be an empty list (an empty list is never needed, | |
3409 since SMIE allows all non-terminals to match the empty string anyway). | |
3410 @item | |
3411 An @var{rhs} cannot have 2 consecutive non-terminals: each pair of | |
3412 non-terminals needs to be separated by a terminal (aka token). | |
3413 This is a fundamental limitation of operator precedence grammars. | |
3414 @end itemize | |
3415 | |
3416 Additionally, conflicts can occur: | |
3417 @itemize | |
3418 @item | |
3419 The returned @emph{prec2} table holds constraints between pairs of tokens, and | |
3420 for any given pair only one constraint can be present: T1 < T2, | |
3421 T1 = T2, or T1 > T2. | |
3422 @item | |
3423 A token can be an @code{opener} (something similar to an open-paren), | |
3424 a @code{closer} (like a close-paren), or @code{neither} of the two | |
3425 (e.g. an infix operator, or an inner token like @code{"else"}). | |
3426 @end itemize | |
3427 | |
3428 Precedence conflicts can be resolved via @var{resolvers}, which | |
3429 is a list of @emph{precs} tables (see @code{smie-precs->prec2}): for | |
3430 each precedence conflict, if those @code{precs} tables | |
3431 specify a particular constraint, then the conflict is resolved by using | |
3432 this constraint instead, else a conflict is reported and one of the | |
3433 conflicting constraints is picked arbitrarily and the others are | |
3434 simply ignored. | |
3435 @end defun | |
3436 | |
3437 @node SMIE Grammar | |
3438 @subsubsection Defining the Grammar of a Language | |
3439 | |
3440 The usual way to define the SMIE grammar of a language is by | |
3441 defining a new global variable that holds the precedence table by | |
3442 giving a set of BNF rules. | |
3443 For example, the grammar definition for a small Pascal-like language | |
3444 could look like: | |
3445 @example | |
3446 @group | |
3447 (require 'smie) | |
3448 (defvar sample-smie-grammar | |
3449 (smie-prec2->grammar | |
3450 (smie-bnf->prec2 | |
3451 @end group | |
3452 @group | |
3453 '((id) | |
3454 (inst ("begin" insts "end") | |
3455 ("if" exp "then" inst "else" inst) | |
3456 (id ":=" exp) | |
3457 (exp)) | |
3458 (insts (insts ";" insts) (inst)) | |
3459 (exp (exp "+" exp) | |
3460 (exp "*" exp) | |
3461 ("(" exps ")")) | |
3462 (exps (exps "," exps) (exp))) | |
3463 @end group | |
3464 @group | |
3465 '((assoc ";")) | |
3466 '((assoc ",")) | |
3467 '((assoc "+") (assoc "*"))))) | |
3468 @end group | |
3469 @end example | |
3470 | |
3471 @noindent | |
3472 A few things to note: | |
3473 | |
3474 @itemize | |
3475 @item | |
3476 The above grammar does not explicitly mention the syntax of function | |
3477 calls: SMIE will automatically allow any sequence of sexps, such as | |
3478 identifiers, balanced parentheses, or @code{begin ... end} blocks | |
3479 to appear anywhere anyway. | |
3480 @item | |
3481 The grammar category @code{id} has no right hand side: this does not | |
3482 mean that it can match only the empty string, since as mentioned any | |
3483 sequence of sexps can appear anywhere anyway. | |
3484 @item | |
3485 Because non terminals cannot appear consecutively in the BNF grammar, it | |
3486 is difficult to correctly handle tokens that act as terminators, so the | |
3487 above grammar treats @code{";"} as a statement @emph{separator} instead, | |
3488 which SMIE can handle very well. | |
3489 @item | |
3490 Separators used in sequences (such as @code{","} and @code{";"} above) | |
3491 are best defined with BNF rules such as @code{(foo (foo "separator" foo) ...)} | |
3492 which generate precedence conflicts which are then resolved by giving | |
3493 them an explicit @code{(assoc "separator")}. | |
3494 @item | |
3495 The @code{("(" exps ")")} rule was not needed to pair up parens, since | |
3496 SMIE will pair up any characters that are marked as having paren syntax | |
3497 in the syntax table. What this rule does instead (together with the | |
3498 definition of @code{exps}) is to make it clear that @code{","} should | |
3499 not appear outside of parentheses. | |
3500 @item | |
3501 Rather than have a single @emph{precs} table to resolve conflicts, it is | |
3502 preferable to have several tables, so as to let the BNF part of the | |
3503 grammar specify relative precedences where possible. | |
3504 @item | |
3505 Unless there is a very good reason to prefer @code{left} or | |
3506 @code{right}, it is usually preferable to mark operators as associative, | |
3507 using @code{assoc}. For that reason @code{"+"} and @code{"*"} are | |
3508 defined above as @code{assoc}, although the language defines them | |
3509 formally as left associative. | |
3510 @end itemize | |
3511 | |
3512 @node SMIE Lexer | |
3513 @subsubsection Defining Tokens | |
3514 | |
3515 SMIE comes with a predefined lexical analyzer which uses syntax tables | |
3516 in the following way: any sequence of characters that have word or | |
3517 symbol syntax is considered a token, and so is any sequence of | |
3518 characters that have punctuation syntax. This default lexer is | |
3519 often a good starting point but is rarely actually correct for any given | |
3520 language. For example, it will consider @code{"2,+3"} to be composed | |
3521 of 3 tokens: @code{"2"}, @code{",+"}, and @code{"3"}. | |
3522 | |
3523 To describe the lexing rules of your language to SMIE, you need | |
3524 2 functions, one to fetch the next token, and another to fetch the | |
3525 previous token. Those functions will usually first skip whitespace and | |
3526 comments and then look at the next chunk of text to see if it | |
3527 is a special token. If so it should skip the token and | |
3528 return a description of this token. Usually this is simply the string | |
3529 extracted from the buffer, but it can be anything you want. | |
3530 For example: | |
3531 @example | |
3532 @group | |
3533 (defvar sample-keywords-regexp | |
3534 (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "="))) | |
3535 @end group | |
3536 @group | |
3537 (defun sample-smie-forward-token () | |
3538 (forward-comment (point-max)) | |
3539 (cond | |
3540 ((looking-at sample-keywords-regexp) | |
3541 (goto-char (match-end 0)) | |
3542 (match-string-no-properties 0)) | |
3543 (t (buffer-substring-no-properties | |
3544 (point) | |
3545 (progn (skip-syntax-forward "w_") | |
3546 (point)))))) | |
3547 @end group | |
3548 @group | |
3549 (defun sample-smie-backward-token () | |
3550 (forward-comment (- (point))) | |
3551 (cond | |
3552 ((looking-back sample-keywords-regexp (- (point) 2) t) | |
3553 (goto-char (match-beginning 0)) | |
3554 (match-string-no-properties 0)) | |
3555 (t (buffer-substring-no-properties | |
3556 (point) | |
3557 (progn (skip-syntax-backward "w_") | |
3558 (point)))))) | |
3559 @end group | |
3560 @end example | |
3561 | |
3562 Notice how those lexers return the empty string when in front of | |
3563 parentheses. This is because SMIE automatically takes care of the | |
3564 parentheses defined in the syntax table. More specifically if the lexer | |
3565 returns nil or an empty string, SMIE tries to handle the corresponding | |
3566 text as a sexp according to syntax tables. | |
3567 | |
3568 @node SMIE Tricks | |
3569 @subsubsection Living With a Weak Parser | |
3570 | |
3571 The parsing technique used by SMIE does not allow tokens to behave | |
3572 differently in different contexts. For most programming languages, this | |
3573 manifests itself by precedence conflicts when converting the | |
3574 BNF grammar. | |
3575 | |
3576 Sometimes, those conflicts can be worked around by expressing the | |
3577 grammar slightly differently. For example, for Modula-2 it might seem | |
3578 natural to have a BNF grammar that looks like this: | |
3579 | |
3580 @example | |
3581 ... | |
3582 (inst ("IF" exp "THEN" insts "ELSE" insts "END") | |
3583 ("CASE" exp "OF" cases "END") | |
3584 ...) | |
3585 (cases (cases "|" cases) (caselabel ":" insts) ("ELSE" insts)) | |
3586 ... | |
3587 @end example | |
3588 | |
3589 But this will create conflicts for @code{"ELSE"}: on the one hand, the | |
3590 IF rule implies (among many other things) that @code{"ELSE" = "END"}; | |
3591 but on the other hand, since @code{"ELSE"} appears within @code{cases}, | |
3592 which appears left of @code{"END"}, we also have @code{"ELSE" > "END"}. | |
3593 We can solve the conflict either by using: | |
3594 @example | |
3595 ... | |
3596 (inst ("IF" exp "THEN" insts "ELSE" insts "END") | |
3597 ("CASE" exp "OF" cases "END") | |
3598 ("CASE" exp "OF" cases "ELSE" insts "END") | |
3599 ...) | |
3600 (cases (cases "|" cases) (caselabel ":" insts)) | |
3601 ... | |
3602 @end example | |
3603 or | |
3604 @example | |
3605 ... | |
3606 (inst ("IF" exp "THEN" else "END") | |
3607 ("CASE" exp "OF" cases "END") | |
3608 ...) | |
3609 (else (insts "ELSE" insts)) | |
3610 (cases (cases "|" cases) (caselabel ":" insts) (else)) | |
3611 ... | |
3612 @end example | |
3613 | |
3614 Reworking the grammar to try and solve conflicts has its downsides, tho, | |
3615 because SMIE assumes that the grammar reflects the logical structure of | |
3616 the code, so it is preferable to keep the BNF closer to the intended | |
3617 abstract syntax tree. | |
3618 | |
3619 Other times, after careful consideration you may conclude that those | |
3620 conflicts are not serious and simply resolve them via the | |
3621 @var{resolvers} argument of @code{smie-bnf->prec2}. Usually this is | |
3622 because the grammar is simply ambiguous: the conflict does not affect | |
3623 the set of programs described by the grammar, but only the way those | |
3624 programs are parsed. This is typically the case for separators and | |
3625 associative infix operators, where you want to add a resolver like | |
3626 @code{'((assoc "|"))}. Another case where this can happen is for the | |
3627 classic @emph{dangling else} problem, where you will use @code{'((assoc | |
3628 "else" "then"))}. It can also happen for cases where the conflict is | |
3629 real and cannot really be resolved, but it is unlikely to pose a problem | |
3630 in practice. | |
3631 | |
3632 Finally, in many cases some conflicts will remain despite all efforts to | |
3633 restructure the grammar. Do not despair: while the parser cannot be | |
3634 made more clever, you can make the lexer as smart as you want. So, the | |
3635 solution is then to look at the tokens involved in the conflict and to | |
3636 split one of those tokens into 2 (or more) different tokens. E.g. if | |
3637 the grammar needs to distinguish between two incompatible uses of the | |
3638 token @code{"begin"}, make the lexer return different tokens (say | |
3639 @code{"begin-fun"} and @code{"begin-plain"}) depending on which kind of | |
3640 @code{"begin"} it finds. This pushes the work of distinguishing the | |
3641 different cases to the lexer, which will thus have to look at the | |
3642 surrounding text to find ad-hoc clues. | |
3643 | |
3644 @node SMIE Indentation | |
3645 @subsubsection Specifying Indentation Rules | |
3646 | |
3647 Based on the provided grammar, SMIE will be able to provide automatic | |
3648 indentation without any extra effort. But in practice, this default | |
3649 indentation style will probably not be good enough. You will want to | |
3650 tweak it in many different cases. | |
3651 | |
3652 SMIE indentation is based on the idea that indentation rules should be | |
3653 as local as possible. To this end, it relies on the idea of | |
3654 @emph{virtual} indentation, which is the indentation that a particular | |
3655 program point would have if it were at the beginning of a line. | |
3656 Of course, if that program point is indeed at the beginning of a line, | |
3657 its virtual indentation is its current indentation. But if not, then | |
3658 SMIE uses the indentation algorithm to compute the virtual indentation | |
3659 of that point. Now in practice, the virtual indentation of a program | |
3660 point does not have to be identical to the indentation it would have if | |
3661 we inserted a newline before it. To see how this works, the SMIE rule | |
3662 for indentation after a @code{@{} in C does not care whether the | |
3663 @code{@{} is standing on a line of its own or is at the end of the | |
3664 preceding line. Instead, these different cases are handled in the | |
3665 indentation rule that decides how to indent before a @code{@{}. | |
3666 | |
3667 Another important concept is the notion of @emph{parent}: The | |
3668 @emph{parent} of a token, is the head token of the nearest enclosing | |
3669 syntactic construct. For example, the parent of an @code{else} is the | |
3670 @code{if} to which it belongs, and the parent of an @code{if}, in turn, | |
3671 is the lead token of the surrounding construct. The command | |
3672 @code{backward-sexp} jumps from a token to its parent, but there are | |
3673 some caveats: for @emph{openers} (tokens which start a construct, like | |
3674 @code{if}), you need to start with point before the token, while for | |
3675 others you need to start with point after the token. | |
3676 @code{backward-sexp} stops with point before the parent token if that is | |
3677 the @emph{opener} of the token of interest, and otherwise it stops with | |
3678 point after the parent token. | |
3679 | |
3680 SMIE indentation rules are specified using a function that takes two | |
3681 arguments @var{method} and @var{arg} where the meaning of @var{arg} and the | |
3682 expected return value depend on @var{method}. | |
3683 | |
3684 @var{method} can be: | |
3685 @itemize | |
3686 @item | |
3687 @code{:after}, in which case @var{arg} is a token and the function | |
3688 should return the @var{offset} to use for indentation after @var{arg}. | |
3689 @item | |
3690 @code{:before}, in which case @var{arg} is a token and the function | |
3691 should return the @var{offset} to use to indent @var{arg} itself. | |
3692 @item | |
3693 @code{:elem}, in which case the function should return either the offset | |
3694 to use to indent function arguments (if @var{arg} is the symbol | |
3695 @code{arg}) or the basic indentation step (if @var{arg} is the symbol | |
3696 @code{basic}). | |
3697 @item | |
3698 @code{:list-intro}, in which case @var{arg} is a token and the function | |
3699 should return non-@code{nil} if the token is followed by a list of | |
3700 expressions (not separated by any token) rather than an expression. | |
3701 @end itemize | |
3702 | |
3703 When @var{arg} is a token, the function is called with point just before | |
3704 that token. A return value of nil always means to fallback on the | |
3705 default behavior, so the function should return nil for arguments it | |
3706 does not expect. | |
3707 | |
3708 @var{offset} can be: | |
3709 @itemize | |
3710 @item | |
3711 @code{nil}: use the default indentation rule. | |
3712 @item | |
3713 @code{(column . @var{column})}: indent to column @var{column}. | |
3714 @item | |
3715 @var{number}: offset by @var{number}, relative to a base token which is | |
3716 the current token for @code{:after} and its parent for @code{:before}. | |
3717 @end itemize | |
3718 | |
3719 @node SMIE Indentation Helpers | |
3720 @subsubsection Helper Functions for Indentation Rules | |
3721 | |
3722 SMIE provides various functions designed specifically for use in the | |
3723 indentation rules function (several of those functions break if used in | |
3724 another context). These functions all start with the prefix | |
3725 @code{smie-rule-}. | |
3726 | |
3727 @defun smie-rule-bolp | |
3728 Return non-@code{nil} if the current token is the first on the line. | |
3729 @end defun | |
3730 | |
3731 @defun smie-rule-hanging-p | |
3732 Return non-@code{nil} if the current token is @emph{hanging}. | |
3733 A token is @emph{hanging} if it is the last token on the line | |
3734 and if it is preceded by other tokens: a lone token on a line is not | |
3735 hanging. | |
3736 @end defun | |
3737 | |
3738 @defun smie-rule-next-p &rest tokens | |
3739 Return non-@code{nil} if the next token is among @var{tokens}. | |
3740 @end defun | |
3741 | |
3742 @defun smie-rule-prev-p &rest tokens | |
3743 Return non-@code{nil} if the previous token is among @var{tokens}. | |
3744 @end defun | |
3745 | |
3746 @defun smie-rule-parent-p &rest parents | |
3747 Return non-@code{nil} if the current token's parent is among @var{parents}. | |
3748 @end defun | |
3749 | |
3750 @defun smie-rule-sibling-p | |
3751 Return non-nil if the current token's parent is actually a sibling. | |
3752 This is the case for example when the parent of a @code{","} is just the | |
3753 previous @code{","}. | |
3754 @end defun | |
3755 | |
3756 @defun smie-rule-parent &optional offset | |
3757 Return the proper offset to align the current token with the parent. | |
3758 If non-@code{nil}, @var{offset} should be an integer giving an | |
3759 additional offset to apply. | |
3760 @end defun | |
3761 | |
3762 @defun smie-rule-separator method | |
3763 Indent current token as a @emph{separator}. | |
3764 | |
3765 By @emph{separator}, we mean here a token whose sole purpose is to | |
3766 separate various elements within some enclosing syntactic construct, and | |
3767 which does not have any semantic significance in itself (i.e. it would | |
3768 typically not exist as a node in an abstract syntax tree). | |
3769 | |
3770 Such a token is expected to have an associative syntax and be closely | |
3771 tied to its syntactic parent. Typical examples are @code{","} in lists | |
3772 of arguments (enclosed inside parentheses), or @code{";"} in sequences | |
3773 of instructions (enclosed in a @code{@{...@}} or @code{begin...end} | |
3774 block). | |
3775 | |
3776 @var{method} should be the method name that was passed to | |
3777 `smie-rules-function'. | |
3778 @end defun | |
3779 | |
3780 @node SMIE Indentation Example | |
3781 @subsubsection Sample Indentation Rules | |
3782 | |
3783 Here is an example of an indentation function: | |
3784 | |
3785 @example | |
3786 (defun sample-smie-rules (kind token) | |
3787 (pcase (cons kind token) | |
3788 (`(:elem . basic) sample-indent-basic) | |
3789 (`(,_ . ",") (smie-rule-separator kind)) | |
3790 (`(:after . ":=") sample-indent-basic) | |
3791 (`(:before . ,(or `"begin" `"(" `"@{"))) | |
3792 (if (smie-rule-hanging-p) (smie-rule-parent))) | |
3793 (`(:before . "if") | |
3794 (and (not (smie-rule-bolp)) (smie-rule-prev-p "else") | |
3795 (smie-rule-parent))))) | |
3796 @end example | |
3797 | |
3798 @noindent | |
3799 A few things to note: | |
3800 | |
3801 @itemize | |
3802 @item | |
3803 The first case indicates the basic indentation increment to use. | |
3804 If @code{sample-indent-basic} is nil, then SMIE uses the global | |
3805 setting @code{smie-indent-basic}. The major mode could have set | |
3806 @code{smie-indent-basic} buffer-locally instead, but that | |
3807 is discouraged. | |
3808 | |
3809 @item | |
3810 The rule for the token @code{","} make SMIE try to be more clever when | |
3811 the comma separator is placed at the beginning of lines. It tries to | |
3812 outdent the separator so as to align the code after the comma; for | |
3813 example: | |
3814 | |
3815 @example | |
3816 x = longfunctionname ( | |
3817 arg1 | |
3818 , arg2 | |
3819 ); | |
3820 @end example | |
3821 | |
3822 @item | |
3823 The rule for indentation after @code{":="} exists because otherwise | |
3824 SMIE would treat @code{":="} as an infix operator and would align the | |
3825 right argument with the left one. | |
3826 | |
3827 @item | |
3828 The rule for indentation before @code{"begin"} is an example of the use | |
3829 of virtual indentation: This rule is used only when @code{"begin"} is | |
3830 hanging, which can happen only when @code{"begin"} is not at the | |
3831 beginning of a line. So this is not used when indenting | |
3832 @code{"begin"} itself but only when indenting something relative to this | |
3833 @code{"begin"}. Concretely, this rule changes the indentation from: | |
3834 | |
3835 @example | |
3836 if x > 0 then begin | |
3837 dosomething(x); | |
3838 end | |
3839 @end example | |
3840 to | |
3841 @example | |
3842 if x > 0 then begin | |
3843 dosomething(x); | |
3844 end | |
3845 @end example | |
3846 | |
3847 @item | |
3848 The rule for indentation before @code{"if"} is similar to the one for | |
3849 @code{"begin"}, but where the purpose is to treat @code{"else if"} | |
3850 as a single unit, so as to align a sequence of tests rather than indent | |
3851 each test further to the right. This function does this only in the | |
3852 case where the @code{"if"} is not placed on a separate line, hence the | |
3853 @code{smie-rule-bolp} test. | |
3854 | |
3855 If we know that the @code{"else"} is always aligned with its @code{"if"} | |
3856 and is always at the beginning of a line, we can use a more efficient | |
3857 rule: | |
3858 @example | |
3859 ((equal token "if") | |
3860 (and (not (smie-rule-bolp)) (smie-rule-prev-p "else") | |
3861 (save-excursion | |
3862 (sample-smie-backward-token) ;Jump before the "else". | |
3863 (cons 'column (current-column))))) | |
3864 @end example | |
3865 | |
3866 The advantage of this formulation is that it reuses the indentation of | |
3867 the previous @code{"else"}, rather than going all the way back to the | |
3868 first @code{"if"} of the sequence. | |
3869 @end itemize | |
3870 | |
3226 @node Desktop Save Mode | 3871 @node Desktop Save Mode |
3227 @section Desktop Save Mode | 3872 @section Desktop Save Mode |
3228 @cindex desktop save mode | 3873 @cindex desktop save mode |
3229 | 3874 |
3230 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from | 3875 @dfn{Desktop Save Mode} is a feature to save the state of Emacs from |
3274 Here @var{desktop-buffer-misc} is the value returned by the function | 3919 Here @var{desktop-buffer-misc} is the value returned by the function |
3275 optionally bound to @code{desktop-save-buffer}. | 3920 optionally bound to @code{desktop-save-buffer}. |
3276 @end defvar | 3921 @end defvar |
3277 | 3922 |
3278 @ignore | 3923 @ignore |
3279 arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e | 3924 Local Variables: |
3925 fill-column: 72 | |
3926 End: | |
3280 @end ignore | 3927 @end ignore |