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.