Previous: Simple Minded Indentation Engine, Up: Automatic Indentation of code [Contents][Index]
When built with the tree-sitter library (see Parsing Program Source), 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.
To enable the parser-based indentation engine, either set
treesit-simple-indent-rules and call
treesit-major-mode-setup, or equivalently, set the value of
indent-line-function to treesit-indent.
This variable stores the actual function called by
treesit-indent. By default, its value is
treesit-simple-indent. In the future we might add other,
more complex indentation engines.
This local variable stores indentation rules for every language. It is
a list of the form: (language . rules), where
language is a language symbol, and rules is a list of the
form (matcher anchor offset).
First, Emacs passes the smallest tree-sitter node at the beginning of
the current line to matcher; if it returns non-nil, this
rule is applicable. Then Emacs passes the node to anchor, which
returns a buffer position. Emacs takes the column number of that
position, adds offset to it, and the result is the indentation
column for the current line. offset can be an integer or a
variable whose value is an integer.
The matcher and anchor are functions, and Emacs provides convenient defaults for them.
Each matcher or anchor is a function that takes three
arguments: node, parent, and bol. The argument
bol is the buffer position whose indentation is required: the
position of the first non-whitespace character after the beginning of
the line. The argument node is the largest (highest-in-tree)
node that starts at that position; and parent is the parent of
node. However, when that position is in a whitespace or inside
a multi-line string, no node can start at that position, so
node is nil. In that case, parent would be the
smallest node that spans that position.
Emacs finds bol, node and parent and
passes them to each matcher and anchor. matcher
should return non-nil if the rule is applicable, and
anchor should return a buffer position.
This is a list of defaults for matchers and anchors in
treesit-simple-indent-rules. Each of them represents a function
that takes 3 arguments: node, parent and bol. The
available default functions are:
no-node ¶This matcher is a function that is called with 3 arguments:
node, parent, and bol, and returns non-nil,
indicating a match, if node is nil, i.e., there is no
node that starts at bol. This is the case when bol is on
an empty line or inside a multi-line string, etc.
parent-is ¶This matcher is a function of one argument, type; it returns a
function that is called with 3 arguments: node, parent,
and bol, and returns non-nil (i.e., a match) if
parent’s type matches regexp type.
node-is ¶This matcher is a function of one argument, type; it returns a
function that is called with 3 arguments: node, parent,
and bol, and returns non-nil if node’s type matches
regexp type.
query ¶This matcher is a function of one argument, query; it returns a
function that is called with 3 arguments: node, parent,
and bol, and returns non-nil if querying parent
with query captures node (see Pattern Matching Tree-sitter Nodes).
match ¶This matcher is a function of 5 arguments: node-type,
parent-type, node-field, node-index-min, and
node-index-max). It returns a function that is called with 3
arguments: node, parent, and bol, and returns
non-nil if node’s type matches regexp node-type,
parent’s type matches regexp parent-type, node’s
field name in parent matches regexp node-field, and
node’s index among its siblings is between node-index-min
and node-index-max. If the value of an argument is nil,
this matcher doesn’t check that argument. For example, to match the
first child where parent is argument_list, use
(match nil "argument_list" nil nil 0 0)
comment-end ¶This matcher is a function that is called with 3 arguments:
node, parent, and bol, and returns non-nil if
point is before a comment ending token. Comment ending tokens are
defined by regular expression treesit-comment-end
(see treesit-comment-end).
first-sibling ¶This anchor is a function that is called with 3 arguments: node, parent, and bol, and returns the start of the first child of parent.
parent ¶This anchor is a function that is called with 3 arguments: node, parent, and bol, and returns the start of parent.
parent-bol ¶This anchor is a function that is called with 3 arguments: node, parent, and bol, and returns the first non-space character on the line of parent.
prev-sibling ¶This anchor is a function that is called with 3 arguments: node, parent, and bol, and returns the start of the previous sibling of node.
no-indent ¶This anchor is a function that is called with 3 arguments: node, parent, and bol, and returns the start of node.
prev-line ¶This anchor is a function that is called with 3 arguments: node, parent, and bol, and returns the first non-whitespace charater on the previous line.
point-min ¶This anchor is a function that is called with 3 arguments: node, parent, and bol, and returns the beginning of the buffer. This is useful as the beginning of the buffer is always at column 0.
comment-start ¶This anchor is a function that is called with 3 arguments: node,
parent, and bol, and returns the position right after the
comment-start token. Comment-start tokens are defined by regular
expression treesit-comment-start (see treesit-comment-start). This function assumes parent is
the comment node.
coment-start-skip ¶This anchor is a function that is called with 3 arguments: node,
parent, and bol, and returns the position after the
comment-start token and any whitespace characters following that
token. Comment-start tokens are defined by regular expression
treesit-comment-start. This function assumes parent is
the comment node.
Here are some utility functions that can help writing parser-based indentation rules.
This function checks the current buffer’s indentation against major mode mode. It indents the current buffer according to mode 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.
It is also helpful to use treesit-inspect-mode (see Tree-sitter Language Definitions) when writing indentation rules.
Previous: Simple Minded Indentation Engine, Up: Automatic Indentation of code [Contents][Index]