-
-Helix uses tree-sitter to correctly indent new lines. This requires a tree-
-sitter grammar and an indent.scm query file placed in runtime/queries/ {language}/indents.scm. The indentation for a line is calculated by traversing
-the syntax tree from the lowest node at the beginning of the new line (see
-Indent queries). Each of these nodes contributes to the total
-indent when it is captured by the query (in what way depends on the name of
-the capture.
-Note that it matters where these added indents begin. For example,
-multiple indent level increases that start on the same line only increase
-the total indent level by 1. See Capture types.
-By default, Helix uses the hybrid indentation heuristic. This means that
-indent queries are not used to compute the expected absolute indentation of a
-line but rather the expected difference in indentation between the new and an
-already existing line. This difference is then added to the actual indentation
-of the already existing line. Since this makes errors in the indent queries
-harder to find, it is recommended to disable it when testing via
-:set indent-heuristic tree-sitter. The rest of this guide assumes that
-the tree-sitter heuristic is used.
-
-When Helix is inserting a new line through o, O, or <ret>, to determine
-the indent level for the new line, the query in indents.scm is run on the
-document. The starting position of the query is the end of the line above where
-a new line will be inserted.
-For o, the inserted line is the line below the cursor, so that starting
-position of the query is the end of the current line.
-#![allow(unused)]
-fn main() {
-fn need_hero(some_hero: Hero, life: Life) -> {
- matches!(some_hero, Hero { // ←─────────────────╮
- strong: true,//←╮ ↑ ↑ │
- fast: true, // │ │ ╰── query start │
- sure: true, // │ ╰───── cursor ├─ traversal
- soon: true, // ╰──────── new line inserted │ start node
- }) && // │
-// ↑ │
-// ╰───────────────────────────────────────────────╯
- some_hero > life
-}
-}
-For O, the newly inserted line is the current line, so the starting position
-of the query is the end of the line above the cursor.
-#![allow(unused)]
-fn main() {
-fn need_hero(some_hero: Hero, life: Life) -> { // ←─╮
- matches!(some_hero, Hero { // ←╮ ↑ │
- strong: true,// ↑ ╭───╯ │ │
- fast: true, // │ │ query start ─╯ │
- sure: true, // ╰───┼ cursor ├─ traversal
- soon: true, // ╰ new line inserted │ start node
- }) && // │
- some_hero > life // │
-} // ←──────────────────────────────────────────────╯
-}
-From this starting node, the syntax tree is traversed up until the root node.
-Each indent capture is collected along the way, and then combined according to
-their capture types and scopes to a final indent
-level for the line.
-
-
-@indent (default scope tail):
-Increase the indent level by 1. Multiple occurrences in the same line do not
-stack. If there is at least one @indent and one @outdent capture on the
-same line, the indent level isn't changed at all.@outdent (default scope all):
-Decrease the indent level by 1. The same rules as for @indent apply.@indent.always (default scope tail):
-Increase the indent level by 1. Multiple occurrences on the same line do
-stack. The final indent level is @indent.always – @outdent.always. If
-an @indent and an @indent.always are on the same line, the @indent is
-ignored.@outdent.always (default scope all):
-Decrease the indent level by 1. The same rules as for @indent.always apply.@align (default scope all):
-Align everything inside this node to some anchor. The anchor is given
-by the start of the node captured by @anchor in the same pattern.
-Every pattern with an @align should contain exactly one @anchor.
-Indent (and outdent) for nodes below (in terms of their starting line)
-the @align node is added to the indentation required for alignment.@extend:
-Extend the range of this node to the end of the line and to lines that are
-indented more than the line that this node starts on. This is useful for
-languages like Python, where for the purpose of indentation some nodes (like
-functions or classes) should also contain indented lines that follow them.@extend.prevent-once:
-Prevents the first extension of an ancestor of this node. For example, in Python
-a return expression always ends the block that it is in. Note that this only
-stops the extension of the next @extend capture. If multiple ancestors are
-captured, only the extension of the innermost one is prevented. All other
-ancestors are unaffected (regardless of whether the innermost ancestor would
-actually have been extended).
-
-Consider this example:
-#![allow(unused)]
-fn main() {
-fn shout(things: Vec<Thing>) {
- // ↑
- // ├───────────────────────╮ indent level
- // @indent ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄
- // │
- let it_all = |out| { things.filter(|thing| { // │ 1
- // ↑ ↑ │
- // ├───────────────────────┼─────┼┄┄┄┄┄┄┄┄┄┄┄┄┄┄
- // @indent @indent │
- // │ 2
- thing.can_do_with(out) // │
- })}; // ├┄┄┄┄┄┄┄┄┄┄┄┄┄┄
- //↑↑↑ │ 1
-} //╰┼┴──────────────────────────────────────────────┴┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-// 3x @outdent
-}
-((block) @indent)
-["}" ")"] @outdent
-
-Note how on the second line, we have two blocks begin on the same line. In this
-case, since both captures occur on the same line, they are combined and only
-result in a net increase of 1. Also note that the closing }s are part of the
-@indent captures, but the 3 @outdents also combine into 1 and result in that
-line losing one indent level.
-
-For an example of where @extend can be useful, consider Python, which is
-whitespace-sensitive.
-]
- (parenthesized_expression)
- (function_definition)
- (class_definition)
-] @indent
-
-
-class Hero:
- def __init__(self, strong, fast, sure, soon):# ←─╮
- self.is_strong = strong # │
- self.is_fast = fast # ╭─── query start │
- self.is_sure = sure # │ ╭─ cursor │
- self.is_soon = soon # │ │ │
- # ↑ ↑ │ │ │
- # │ ╰──────╯ │ │
- # ╰─────────────────────╯ │
- # ├─ traversal
- def need_hero(self, life): # │ start node
- return ( # │
- self.is_strong # │
- and self.is_fast # │
- and self.is_sure # │
- and self.is_soon # │
- and self > life # │
- ) # ←─────────────────────────────────────────╯
-
-Without braces to catch the scope of the function, the smallest descendant of
-the cursor on a line feed ends up being the entire inside of the class. Because
-of this, it will miss the entire function node and its indent capture, leading
-to an indent level one too small.
-To address this case, @extend tells helix to "extend" the captured node's span
-to the line feed and every consecutive line that has a greater indent level than
-the line of the node.
-(parenthesized_expression) @indent
-
-]
- (function_definition)
- (class_definition)
-] @indent @extend
-
-
-class Hero:
- def __init__(self, strong, fast, sure, soon):# ←─╮
- self.is_strong = strong # │
- self.is_fast = fast # ╭─── query start ├─ traversal
- self.is_sure = sure # │ ╭─ cursor │ start node
- self.is_soon = soon # │ │ ←───────────────╯
- # ↑ ↑ │ │
- # │ ╰──────╯ │
- # ╰─────────────────────╯
- def need_hero(self, life):
- return (
- self.is_strong
- and self.is_fast
- and self.is_sure
- and self.is_soon
- and self > life
- )
-
-Furthermore, there are some cases where extending to everything with a greater
-indent level may not be desirable. Consider the need_hero function above. If
-our cursor is on the last line of the returned expression.
-class Hero:
- def __init__(self, strong, fast, sure, soon):
- self.is_strong = strong
- self.is_fast = fast
- self.is_sure = sure
- self.is_soon = soon
-
- def need_hero(self, life):
- return (
- self.is_strong
- and self.is_fast
- and self.is_sure
- and self.is_soon
- and self > life
- ) # ←─── cursor
- #←────────── where cursor should go on new line
-
-In Python, the are a few tokens that will always end a scope, such as a return
-statement. Since the scope ends, so should the indent level. But because the
-function span is extended to every line with a greater indent level, a new line
-would just continue on the same level. And an @outdent would not help us here
-either, since it would cause everything in the parentheses to become outdented
-as well.
-To help, we need to signal an end to the extension. We can do this with
-@extend.prevent-once.
-(parenthesized_expression) @indent
-
-]
- (function_definition)
- (class_definition)
-] @indent @extend
-
-(return_statement) @extend.prevent-once
-
-
-As mentioned before, normally if there is more than one @indent or @outdent
-capture on the same line, they are combined.
-Sometimes, there are cases when you may want to ensure that every indent capture
-is additive, regardless of how many occur on the same line. Consider this
-example in YAML.
- - foo: bar
-# ↑ ↑
-# │ ╰─────────────── start of map
-# ╰───────────────── start of list element
- baz: quux # ←─── cursor
- # ←───────────── where the cursor should go on a new line
- garply: waldo
- - quux:
- bar: baz
- xyzzy: thud
- fred: plugh
-
-In YAML, you often have lists of maps. In these cases, the syntax is such that
-the list element and the map both start on the same line. But we really do want
-to start an indentation for each of these so that subsequent keys in the map
-hang over the list and align properly. This is where @indent.always helps.
-((block_sequence_item) @item @indent.always @extend
- (#not-one-line? @item))
-
-((block_mapping_pair
- key: (_) @key
- value: (_) @val
- (#not-same-line? @key @val)
- ) @indent.always @extend
-)
-
-
-In some cases, an S-expression cannot express exactly what pattern should be matched.
-For that, tree-sitter allows for predicates to appear anywhere within a pattern,
-similar to how #set! declarations work:
-(some_kind
- (child_kind) @indent
- (#predicate? arg1 arg2 ...)
-)
-
-The number of arguments depends on the predicate that's used.
-Each argument is either a capture (@name) or a string ("some string").
-The following predicates are supported by tree-sitter:
-
--
-
#eq?/#not-eq?:
-The first argument (a capture) must/must not be equal to the second argument
-(a capture or a string).
-
--
-
#match?/#not-match?:
-The first argument (a capture) must/must not match the regex given in the
-second argument (a string).
-
--
-
#any-of?/#not-any-of?:
-The first argument (a capture) must/must not be one of the other arguments
-(strings).
-
-
-Additionally, we support some custom predicates for indent queries:
-
--
-
#not-kind-eq?:
-The kind of the first argument (a capture) must not be equal to the second
-argument (a string).
-
--
-
#same-line?/#not-same-line?:
-The captures given by the 2 arguments must/must not start on the same line.
-
--
-
#one-line?/#not-one-line?:
-The captures given by the fist argument must/must span a total of one line.
-
-
-
-Added indents don't always apply to the whole node. For example, in most
-cases when a node should be indented, we actually only want everything
-except for its first line to be indented. For this, there are several
-scopes (more scopes may be added in the future if required):
-
-tail:
-This scope applies to everything except for the first line of the
-captured node.all:
-This scope applies to the whole captured node. This is only different from
-tail when the captured node is the first node on its line.
-For example, imagine we have the following function
-#![allow(unused)]
-fn main() {
-fn aha() { // ←─────────────────────────────────────╮
- let take = "on me"; // ←──────────────╮ scope: │
- let take = "me on"; // ├─ "tail" ├─ (block) @indent
- let ill = be_gone_days(1 || 2); // │ │
-} // ←───────────────────────────────────┴──────────┴─ "}" @outdent
- // scope: "all"
-}
-We can write the following query with the #set! declaration:
-((block) @indent
- (#set! "scope" "tail"))
-("}" @outdent
- (#set! "scope" "all"))
-
-As we can see, the "tail" scope covers the node, except for the first line.
-Everything up to and including the closing brace gets an indent level of 1.
-Then, on the closing brace, we encounter an outdent with a scope of "all", which
-means the first line is included, and the indent level is cancelled out on this
-line. (Note these scopes are the defaults for @indent and @outdent—they are
-written explicitly for demonstration.)
-
-