Adding Rainbow Bracket Queries

Helix uses rainbows.scm tree-sitter query files to provide rainbow bracket -functionality.

Tree-sitter queries are documented in the tree-sitter online documentation. -If you're writing queries for the first time, be sure to check out the section -on syntax highlighting queries and on query syntax.

Rainbow queries have two captures: @rainbow.scope and @rainbow.bracket. -@rainbow.scope should capture any node that increases the nesting level -while @rainbow.bracket should capture any bracket nodes. Put another way: -@rainbow.scope switches to the next rainbow color for all nodes in the tree -under it while @rainbow.bracket paints captured nodes with the current -rainbow color.

For an example, let's add rainbow queries for the tree-sitter query (TSQ) -language itself. These queries will go into a -runtime/queries/tsq/rainbows.scm file in the repository root.

First we'll add the @rainbow.bracket captures. TSQ only has parentheses and -square brackets:

["(" ")" "[" "]"] @rainbow.bracket
-

The ordering of the nodes within the alternation (square brackets) is not -taken into consideration.

-
Note: Why are these nodes quoted? Most syntax highlights capture text -surrounded by parentheses. These are named nodes and correspond to the -names of rules in the grammar. Brackets are usually written in tree-sitter -grammars as literal strings, for example:
-
{
-  // ...
-  arguments: seq("(", repeat($.argument), ")"),
-  // ...
-}
-
-
Nodes written as literal strings in tree-sitter grammars may be captured -in queries with those same literal strings.
-

Then we'll add @rainbow.scope captures. The easiest way to do this is to -view the grammar.js file in the tree-sitter grammar's repository. For TSQ, -that file is here. As we scroll down the grammar.js, we -see that the (alternation), (L36) (group) (L57), (named_node) (L59), -(predicate) (L87) and (wildcard_node) (L97) nodes all contain literal -parentheses or square brackets in their definitions. These nodes are all -direct parents of brackets and happen to also be the nodes we want to change -to the next rainbow color, so we capture them as @rainbow.scope.

[
-  (group)
-  (named_node)
-  (wildcard_node)
-  (predicate)
-  (alternation)
-] @rainbow.scope
-

This strategy works as a rule of thumb for most programming and configuration -languages. Markup languages can be trickier and may take additional -experimentation to find the correct nodes to use for scopes and brackets.

The :tree-sitter-subtree command shows the syntax tree under the primary -selection in S-expression format and can be a useful tool for determining how -to write a query.

Properties

The rainbow.include-children property may be applied to @rainbow.scope -captures. By default, all @rainbow.bracket captures must be direct descendant -of a node captured with @rainbow.scope in a syntax tree in order to be -highlighted. The rainbow.include-children property disables that check and -allows @rainbow.bracket captures to be highlighted if they are direct or -indirect descendants of some node captured with @rainbow.scope.

For example, this property is used in the HTML rainbow queries.

For a document like <a>link</a>, the syntax tree is:

(element                   ; <a>link</a>
-  (start_tag               ; <a>
-    (tag_name))            ; a
-  (text)                   ; link
-  (end_tag                 ; </a>
-    (tag_name)))           ; a
-

If we want to highlight the <, > and </ nodes with rainbow colors, we -capture them as @rainbow.bracket:

["<" ">" "</"] @rainbow.bracket
-

And we capture (element) as @rainbow.scope because (element) nodes nest -within each other: they increment the nesting level and switch to the next -color in the rainbow.

(element) @rainbow.scope
-

But this combination of @rainbow.scope and @rainbow.bracket will not -highlight any nodes. <, > and </ are children of the (start_tag) and -(end_tag) nodes. We can't capture (start_tag) and (end_tag) as -@rainbow.scope because they don't nest other elements. We can fix this case -by removing the requirement that <, > and </ are direct descendants of -(element) using the rainbow.include-children property.

((element) @rainbow.scope
- (#set! rainbow.include-children))
-

With this property set, <, >, and </ will highlight with rainbow colors -even though they aren't direct descendents of the (element) node.

rainbow.include-children is not necessary for the vast majority of programming -languages. It is only necessary when the node that increments the nesting level -(changes rainbow color) is not the direct parent of the bracket node.

- -