diff options
Diffstat (limited to 'devdocs/elisp/smie-indentation.html')
| -rw-r--r-- | devdocs/elisp/smie-indentation.html | 15 |
1 files changed, 15 insertions, 0 deletions
diff --git a/devdocs/elisp/smie-indentation.html b/devdocs/elisp/smie-indentation.html new file mode 100644 index 00000000..3a2033df --- /dev/null +++ b/devdocs/elisp/smie-indentation.html @@ -0,0 +1,15 @@ + <h4 class="subsubsection">Specifying Indentation Rules</h4> <p>Based on the provided grammar, SMIE will be able to provide automatic indentation without any extra effort. But in practice, this default indentation style will probably not be good enough. You will want to tweak it in many different cases. </p> <p>SMIE indentation is based on the idea that indentation rules should be as local as possible. To this end, it relies on the idea of <em>virtual</em> indentation, which is the indentation that a particular program point would have if it were at the beginning of a line. Of course, if that program point is indeed at the beginning of a line, its virtual indentation is its current indentation. But if not, then SMIE uses the indentation algorithm to compute the virtual indentation of that point. Now in practice, the virtual indentation of a program point does not have to be identical to the indentation it would have if we inserted a newline before it. To see how this works, the SMIE rule for indentation after a <code>{</code> in C does not care whether the <code>{</code> is standing on a line of its own or is at the end of the preceding line. Instead, these different cases are handled in the indentation rule that decides how to indent before a <code>{</code>. </p> <p>Another important concept is the notion of <em>parent</em>: The <em>parent</em> of a token, is the head token of the nearest enclosing syntactic construct. For example, the parent of an <code>else</code> is the <code>if</code> to which it belongs, and the parent of an <code>if</code>, in turn, is the lead token of the surrounding construct. The command <code>backward-sexp</code> jumps from a token to its parent, but there are some caveats: for <em>openers</em> (tokens which start a construct, like <code>if</code>), you need to start with point before the token, while for others you need to start with point after the token. <code>backward-sexp</code> stops with point before the parent token if that is the <em>opener</em> of the token of interest, and otherwise it stops with point after the parent token. </p> <p>SMIE indentation rules are specified using a function that takes two arguments <var>method</var> and <var>arg</var> where the meaning of <var>arg</var> and the expected return value depend on <var>method</var>. </p> <p><var>method</var> can be: </p> +<ul> <li> <code>:after</code>, in which case <var>arg</var> is a token and the function should return the <var>offset</var> to use for indentation after <var>arg</var>. </li> +<li> <code>:before</code>, in which case <var>arg</var> is a token and the function should return the <var>offset</var> to use to indent <var>arg</var> itself. </li> +<li> <code>:elem</code>, in which case the function should return either the offset to use to indent function arguments (if <var>arg</var> is the symbol <code>arg</code>) or the basic indentation step (if <var>arg</var> is the symbol <code>basic</code>). </li> +<li> <code>:list-intro</code>, in which case <var>arg</var> is a token and the function should return non-<code>nil</code> if the token is followed by a list of expressions (not separated by any token) rather than an expression. </li> +</ul> <p>When <var>arg</var> is a token, the function is called with point just before that token. A return value of <code>nil</code> always means to fallback on the default behavior, so the function should return <code>nil</code> for arguments it does not expect. </p> <p><var>offset</var> can be: </p> +<ul> <li> <code>nil</code>: use the default indentation rule. </li> +<li> <code>(column . <var>column</var>)</code>: indent to column <var>column</var>. </li> +<li> <var>number</var>: offset by <var>number</var>, relative to a base token which is the current token for <code>:after</code> and its parent for <code>:before</code>. </li> +</ul><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/SMIE-Indentation.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/SMIE-Indentation.html</a> + </p> +</div> |