1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This is the GNU Emacs Lisp Reference Manual
corresponding to Emacs version 29.0.50.
Copyright © 1990-1996, 1998-2022 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "GNU General Public License," with the
Front-Cover Texts being "A GNU Manual," and with the Back-Cover
Texts as in (a) below. A copy of the license is included in the
section entitled "GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom." -->
<title>Parser-based Indentation (GNU Emacs Lisp Reference Manual)</title>
<meta name="description" content="Parser-based Indentation (GNU Emacs Lisp Reference Manual)">
<meta name="keywords" content="Parser-based Indentation (GNU Emacs Lisp Reference Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Index.html" rel="index" title="Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Auto_002dIndentation.html" rel="up" title="Auto-Indentation">
<link href="SMIE.html" rel="prev" title="SMIE">
<style type="text/css">
<!--
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="./manual.css">
</head>
<body lang="en">
<div class="subsection" id="Parser_002dbased-Indentation">
<div class="header">
<p>
Previous: <a href="SMIE.html" accesskey="p" rel="prev">Simple Minded Indentation Engine</a>, Up: <a href="Auto_002dIndentation.html" accesskey="u" rel="up">Automatic Indentation of code</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<span id="Parser_002dbased-Indentation-1"></span><h4 class="subsection">24.7.2 Parser-based Indentation</h4>
<span id="index-parser_002dbased-indentation"></span>
<p>When built with the tree-sitter library (see <a href="Parsing-Program-Source.html">Parsing Program Source</a>), Emacs is capable of parsing the program source and producing
a syntax tree. This syntax tree can be used for guiding the program
source indentation commands. For maximum flexibility, it is possible
to write a custom indentation function that queries the syntax tree
and indents accordingly for each language, but that is a lot of work.
It is more convenient to use the simple indentation engine described
below: then the major mode needs only to write some indentation rules
and the engine takes care of the rest.
</p>
<p>To enable the parser-based indentation engine, either set
<var>treesit-simple-indent-rules</var> and call
<code>treesit-major-mode-setup</code>, or equivalently, set the value of
<code>indent-line-function</code> to <code>treesit-indent</code>.
</p>
<dl class="def">
<dt id="index-treesit_002dindent_002dfunction"><span class="category">Variable: </span><span><strong>treesit-indent-function</strong><a href='#index-treesit_002dindent_002dfunction' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This variable stores the actual function called by
<code>treesit-indent</code>. By default, its value is
<code>treesit-simple-indent</code>. In the future we might add other,
more complex indentation engines.
</p></dd></dl>
<span id="Writing-indentation-rules"></span><h3 class="heading">Writing indentation rules</h3>
<span id="index-indentation-rules_002c-for-parser_002dbased-indentation"></span>
<dl class="def">
<dt id="index-treesit_002dsimple_002dindent_002drules"><span class="category">Variable: </span><span><strong>treesit-simple-indent-rules</strong><a href='#index-treesit_002dsimple_002dindent_002drules' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This local variable stores indentation rules for every language. It is
a list of the form: <code>(<var>language</var> . <var>rules</var>)</code><!-- /@w -->, where
<var>language</var> is a language symbol, and <var>rules</var> is a list of the
form <code>(<var>matcher</var> <var>anchor</var> <var>offset</var>)</code><!-- /@w -->.
</p>
<p>First, Emacs passes the smallest tree-sitter node at the beginning of
the current line to <var>matcher</var>; if it returns non-<code>nil</code>, this
rule is applicable. Then Emacs passes the node to <var>anchor</var>, which
returns a buffer position. Emacs takes the column number of that
position, adds <var>offset</var> to it, and the result is the indentation
column for the current line. <var>offset</var> can be an integer or a
variable whose value is an integer.
</p>
<p>The <var>matcher</var> and <var>anchor</var> are functions, and Emacs provides
convenient defaults for them.
</p>
<p>Each <var>matcher</var> or <var>anchor</var> is a function that takes three
arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>. The argument
<var>bol</var> is the buffer position whose indentation is required: the
position of the first non-whitespace character after the beginning of
the line. The argument <var>node</var> is the largest (highest-in-tree)
node that starts at that position; and <var>parent</var> is the parent of
<var>node</var>. However, when that position is in a whitespace or inside
a multi-line string, no node can start at that position, so
<var>node</var> is <code>nil</code>. In that case, <var>parent</var> would be the
smallest node that spans that position.
</p>
<p>Emacs finds <var>bol</var>, <var>node</var> and <var>parent</var> and
passes them to each <var>matcher</var> and <var>anchor</var>. <var>matcher</var>
should return non-<code>nil</code> if the rule is applicable, and
<var>anchor</var> should return a buffer position.
</p></dd></dl>
<dl class="def">
<dt id="index-treesit_002dsimple_002dindent_002dpresets"><span class="category">Variable: </span><span><strong>treesit-simple-indent-presets</strong><a href='#index-treesit_002dsimple_002dindent_002dpresets' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This is a list of defaults for <var>matcher</var>s and <var>anchor</var>s in
<code>treesit-simple-indent-rules</code>. Each of them represents a function
that takes 3 arguments: <var>node</var>, <var>parent</var> and <var>bol</var>. The
available default functions are:
</p>
<dl compact="compact">
<dt id='index-no_002dnode'><span><code>no-node</code><a href='#index-no_002dnode' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This matcher is a function that is called with 3 arguments:
<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code>,
indicating a match, if <var>node</var> is <code>nil</code>, i.e., there is no
node that starts at <var>bol</var>. This is the case when <var>bol</var> is on
an empty line or inside a multi-line string, etc.
</p>
</dd>
<dt id='index-parent_002dis'><span><code>parent-is</code><a href='#index-parent_002dis' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
and <var>bol</var>, and returns non-<code>nil</code> (i.e., a match) if
<var>parent</var>’s type matches regexp <var>type</var>.
</p>
</dd>
<dt id='index-node_002dis'><span><code>node-is</code><a href='#index-node_002dis' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This matcher is a function of one argument, <var>type</var>; it returns a
function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
and <var>bol</var>, and returns non-<code>nil</code> if <var>node</var>’s type matches
regexp <var>type</var>.
</p>
</dd>
<dt id='index-query'><span><code>query</code><a href='#index-query' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This matcher is a function of one argument, <var>query</var>; it returns a
function that is called with 3 arguments: <var>node</var>, <var>parent</var>,
and <var>bol</var>, and returns non-<code>nil</code> if querying <var>parent</var>
with <var>query</var> captures <var>node</var> (see <a href="Pattern-Matching.html">Pattern Matching Tree-sitter Nodes</a>).
</p>
</dd>
<dt id='index-match'><span><code>match</code><a href='#index-match' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This matcher is a function of 5 arguments: <var>node-type</var>,
<var>parent-type</var>, <var>node-field</var>, <var>node-index-min</var>, and
<var>node-index-max</var>). It returns a function that is called with 3
arguments: <var>node</var>, <var>parent</var>, and <var>bol</var>, and returns
non-<code>nil</code> if <var>node</var>’s type matches regexp <var>node-type</var>,
<var>parent</var>’s type matches regexp <var>parent-type</var>, <var>node</var>’s
field name in <var>parent</var> matches regexp <var>node-field</var>, and
<var>node</var>’s index among its siblings is between <var>node-index-min</var>
and <var>node-index-max</var>. If the value of an argument is <code>nil</code>,
this matcher doesn’t check that argument. For example, to match the
first child where parent is <code>argument_list</code>, use
</p>
<div class="example">
<pre class="example">(match nil "argument_list" nil nil 0 0)
</pre></div>
</dd>
<dt id='index-comment_002dend'><span><code>comment-end</code><a href='#index-comment_002dend' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This matcher is a function that is called with 3 arguments:
<var>node</var>, <var>parent</var>, and <var>bol</var>, and returns non-<code>nil</code> if
point is before a comment ending token. Comment ending tokens are
defined by regular expression <code>treesit-comment-end</code>
(see <a href="Tree_002dsitter-major-modes.html">treesit-comment-end</a>).
</p>
</dd>
<dt id='index-first_002dsibling'><span><code>first-sibling</code><a href='#index-first_002dsibling' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of the first child
of <var>parent</var>.
</p>
</dd>
<dt id='index-parent'><span><code>parent</code><a href='#index-parent' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of <var>parent</var>.
</p>
</dd>
<dt id='index-parent_002dbol'><span><code>parent-bol</code><a href='#index-parent_002dbol' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the first non-space character
on the line of <var>parent</var>.
</p>
</dd>
<dt id='index-prev_002dsibling'><span><code>prev-sibling</code><a href='#index-prev_002dsibling' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of the previous
sibling of <var>node</var>.
</p>
</dd>
<dt id='index-no_002dindent'><span><code>no-indent</code><a href='#index-no_002dindent' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the start of <var>node</var>.
</p>
</dd>
<dt id='index-prev_002dline'><span><code>prev-line</code><a href='#index-prev_002dline' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the first non-whitespace
character on the previous line.
</p>
</dd>
<dt id='index-point_002dmin'><span><code>point-min</code><a href='#index-point_002dmin' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the beginning of the buffer.
This is useful as the beginning of the buffer is always at column 0.
</p>
</dd>
<dt id='index-comment_002dstart'><span><code>comment-start</code><a href='#index-comment_002dstart' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the position right after the
comment-start token. Comment-start tokens are defined by regular
expression <code>treesit-comment-start</code> (see <a href="Tree_002dsitter-major-modes.html">treesit-comment-start</a>). This function assumes <var>parent</var> is
the comment node.
</p>
</dd>
<dt id='index-coment_002dstart_002dskip'><span><code>coment-start-skip</code><a href='#index-coment_002dstart_002dskip' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This anchor is a function that is called with 3 arguments: <var>node</var>,
<var>parent</var>, and <var>bol</var>, and returns the position after the
comment-start token and any whitespace characters following that
token. Comment-start tokens are defined by regular expression
<code>treesit-comment-start</code>. This function assumes <var>parent</var> is
the comment node.
</p></dd>
</dl>
</dd></dl>
<span id="Indentation-utilities"></span><h3 class="heading">Indentation utilities</h3>
<span id="index-utility-functions-for-parser_002dbased-indentation"></span>
<p>Here are some utility functions that can help writing parser-based
indentation rules.
</p>
<dl class="def">
<dt id="index-treesit_002dcheck_002dindent"><span class="category">Function: </span><span><strong>treesit-check-indent</strong> <em>mode</em><a href='#index-treesit_002dcheck_002dindent' class='copiable-anchor'> ¶</a></span></dt>
<dd><p>This function checks the current buffer’s indentation against major
mode <var>mode</var>. It indents the current buffer according to
<var>mode</var> and compares the results with the current indentation.
Then it pops up a buffer showing the differences. Correct
indentation (target) is shown in green color, current indentation is
shown in red color. </p></dd></dl>
<p>It is also helpful to use <code>treesit-inspect-mode</code> (see <a href="Language-Definitions.html">Tree-sitter Language Definitions</a>) when writing indentation rules.
</p>
</div>
<hr>
<div class="header">
<p>
Previous: <a href="SMIE.html">Simple Minded Indentation Engine</a>, Up: <a href="Auto_002dIndentation.html">Automatic Indentation of code</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
