diff options
| -rw-r--r-- | book/src/guides/indent.md | 347 |
1 files changed, 304 insertions, 43 deletions
diff --git a/book/src/guides/indent.md b/book/src/guides/indent.md index b660d785..0b0e3938 100644 --- a/book/src/guides/indent.md +++ b/book/src/guides/indent.md @@ -1,76 +1,293 @@ # Adding indent queries -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. 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). +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](#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. +the total indent level by 1. See [Capture types](#capture-types). -## Scopes +## Indent queries -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): +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. -- `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 `o`, the inserted line is the line below the cursor, so that starting +position of the query is the end of the current line. -- `tail`: -This scope applies to everything except for the first line of the -captured node. +```rust +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 +} +``` -Every capture type has a default scope which should do the right thing -in most situations. When a different scope is required, this can be -changed by using a `#set!` declaration anywhere in the pattern: -```scm -(assignment_expression - right: (_) @indent - (#set! "scope" "all")) +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. + +```rust +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 // │ +} // ←──────────────────────────────────────────────╯ ``` -## Capture types +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](#capture-types) and [scopes](#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 -don't stack. If there is at least one `@indent` and one `@outdent` -capture on the same line, the indent level isn't changed at all. +### Capture types +- `@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. - + 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. - `@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 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). + 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). + +#### `@indent` / `@outdent` + +Consider this example: + +```rust +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 +``` + +```scm +((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 `@outdent`s also combine into 1 and result in that +line losing one indent level. + +#### `@extend` / `@extend.prevent-once` + +For an example of where `@extend` can be useful, consider Python, which is +whitespace-sensitive. + +```scm +] + (parenthesized_expression) + (function_definition) + (class_definition) +] @indent + +``` + +```python +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. + +```scm +(parenthesized_expression) @indent + +] + (function_definition) + (class_definition) +] @indent @extend + +``` + +```python +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. +```python +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`. + +```scm +(parenthesized_expression) @indent + +] + (function_definition) + (class_definition) +] @indent @extend + +(return_statement) @extend.prevent-once +``` + +#### `@indent.always` / `@outdent.always` + +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. + +```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. + +```scm +((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 +) +``` ## Predicates 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: + ```scm (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: @@ -91,3 +308,47 @@ 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. + +### Scopes + +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 + +```rust +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: + + ```scm + ((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.)
\ No newline at end of file |