From 9a3f23b0661f7a37a0dab885fe5eb844b615a22b Mon Sep 17 00:00:00 2001 From: Michael Davis Date: Wed, 1 May 2024 15:52:02 -0700 Subject: Add rainbow tree-sitter highlights ref: https://github.com/helix-editor/helix/issues/695 ref: https://github.com/helix-editor/helix/pull/2857 --- book/src/SUMMARY.md | 1 + book/src/configuration.md | 1 + book/src/generated/lang-support.md | 430 ++++++++++++++--------------- book/src/guides/README.md | 2 +- book/src/guides/rainbow_bracket_queries.md | 132 +++++++++ book/src/languages.md | 2 + book/src/themes.md | 11 + 7 files changed, 363 insertions(+), 216 deletions(-) create mode 100644 book/src/guides/rainbow_bracket_queries.md (limited to 'book/src') diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index ba330cf7..dcd128de 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -17,3 +17,4 @@ - [Adding textobject queries](./guides/textobject.md) - [Adding indent queries](./guides/indent.md) - [Adding injection queries](./guides/injection.md) + - [Adding rainbow bracket queries](./guides/rainbow_bracket_queries.md) diff --git a/book/src/configuration.md b/book/src/configuration.md index 63c20334..22531868 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -70,6 +70,7 @@ Its settings will be merged with the configuration directory `config.toml` and t | `indent-heuristic` | How the indentation for a newly inserted line is computed: `simple` just copies the indentation level from the previous line, `tree-sitter` computes the indentation based on the syntax tree and `hybrid` combines both approaches. If the chosen heuristic is not available, a different one will be used as a fallback (the fallback order being `hybrid` -> `tree-sitter` -> `simple`). | `hybrid` | `jump-label-alphabet` | The characters that are used to generate two character jump labels. Characters at the start of the alphabet are used first. | `"abcdefghijklmnopqrstuvwxyz"` | `initial-mode` | The initial mode for newly opened editors. | `"normal"` | +| `rainbow-brackets` | Whether to render rainbow colors for matching brackets. Requires tree-sitter `rainbows.scm` queries for the language. | `false` | ### `[editor.statusline]` Section diff --git a/book/src/generated/lang-support.md b/book/src/generated/lang-support.md index 9acab0de..05bdbd59 100644 --- a/book/src/generated/lang-support.md +++ b/book/src/generated/lang-support.md @@ -1,215 +1,215 @@ -| Language | Syntax Highlighting | Treesitter Textobjects | Auto Indent | Default LSP | -| --- | --- | --- | --- | --- | -| ada | ✓ | ✓ | | `ada_language_server`, `ada_language_server` | -| agda | ✓ | | | | -| astro | ✓ | | | | -| awk | ✓ | ✓ | | `awk-language-server` | -| bash | ✓ | ✓ | ✓ | `bash-language-server` | -| bass | ✓ | | | `bass` | -| beancount | ✓ | | | | -| bibtex | ✓ | | | `texlab` | -| bicep | ✓ | | | `bicep-langserver` | -| blade | ✓ | | | | -| blueprint | ✓ | | | `blueprint-compiler` | -| c | ✓ | ✓ | ✓ | `clangd` | -| c-sharp | ✓ | ✓ | | `OmniSharp` | -| cabal | | | | `haskell-language-server-wrapper` | -| cairo | ✓ | ✓ | ✓ | `cairo-language-server` | -| capnp | ✓ | | ✓ | | -| cel | ✓ | | | | -| clojure | ✓ | | | `clojure-lsp` | -| cmake | ✓ | ✓ | ✓ | `cmake-language-server` | -| comment | ✓ | | | | -| common-lisp | ✓ | | ✓ | `cl-lsp` | -| cpon | ✓ | | ✓ | | -| cpp | ✓ | ✓ | ✓ | `clangd` | -| crystal | ✓ | ✓ | | `crystalline` | -| css | ✓ | | ✓ | `vscode-css-language-server` | -| cue | ✓ | | | `cuelsp` | -| d | ✓ | ✓ | ✓ | `serve-d` | -| dart | ✓ | ✓ | ✓ | `dart` | -| dbml | ✓ | | | | -| devicetree | ✓ | | | | -| dhall | ✓ | ✓ | | `dhall-lsp-server` | -| diff | ✓ | | | | -| docker-compose | ✓ | | ✓ | `docker-compose-langserver`, `yaml-language-server` | -| dockerfile | ✓ | | | `docker-langserver` | -| dot | ✓ | | | `dot-language-server` | -| dtd | ✓ | | | | -| edoc | ✓ | | | | -| eex | ✓ | | | | -| ejs | ✓ | | | | -| elixir | ✓ | ✓ | ✓ | `elixir-ls` | -| elm | ✓ | ✓ | | `elm-language-server` | -| elvish | ✓ | | | `elvish` | -| env | ✓ | | | | -| erb | ✓ | | | | -| erlang | ✓ | ✓ | | `erlang_ls` | -| esdl | ✓ | | | | -| fidl | ✓ | | | | -| fish | ✓ | ✓ | ✓ | | -| forth | ✓ | | | `forth-lsp` | -| fortran | ✓ | | ✓ | `fortls` | -| fsharp | ✓ | | | `fsautocomplete` | -| gas | ✓ | ✓ | | | -| gdscript | ✓ | ✓ | ✓ | | -| gemini | ✓ | | | | -| git-attributes | ✓ | | | | -| git-commit | ✓ | ✓ | | | -| git-config | ✓ | | | | -| git-ignore | ✓ | | | | -| git-rebase | ✓ | | | | -| gleam | ✓ | ✓ | | `gleam` | -| glimmer | ✓ | | | `ember-language-server` | -| glsl | ✓ | ✓ | ✓ | | -| gn | ✓ | | | | -| go | ✓ | ✓ | ✓ | `gopls`, `golangci-lint-langserver` | -| godot-resource | ✓ | | | | -| gomod | ✓ | | | `gopls` | -| gotmpl | ✓ | | | `gopls` | -| gowork | ✓ | | | `gopls` | -| graphql | ✓ | | | `graphql-lsp` | -| groovy | ✓ | | | | -| hare | ✓ | | | | -| haskell | ✓ | ✓ | | `haskell-language-server-wrapper` | -| haskell-persistent | ✓ | | | | -| hcl | ✓ | ✓ | ✓ | `terraform-ls` | -| heex | ✓ | ✓ | | `elixir-ls` | -| helm | ✓ | | | `helm_ls` | -| hocon | ✓ | | ✓ | | -| hoon | ✓ | | | | -| hosts | ✓ | | | | -| html | ✓ | | | `vscode-html-language-server` | -| hurl | ✓ | | ✓ | | -| hyprlang | ✓ | | ✓ | | -| idris | | | | `idris2-lsp` | -| iex | ✓ | | | | -| ini | ✓ | | | | -| janet | ✓ | | | | -| java | ✓ | ✓ | ✓ | `jdtls` | -| javascript | ✓ | ✓ | ✓ | `typescript-language-server` | -| jinja | ✓ | | | | -| jsdoc | ✓ | | | | -| json | ✓ | | ✓ | `vscode-json-language-server` | -| json5 | ✓ | | | | -| jsonc | ✓ | | ✓ | `vscode-json-language-server` | -| jsonnet | ✓ | | | `jsonnet-language-server` | -| jsx | ✓ | ✓ | ✓ | `typescript-language-server` | -| julia | ✓ | ✓ | ✓ | `julia` | -| just | ✓ | ✓ | ✓ | | -| kdl | ✓ | ✓ | ✓ | | -| koka | ✓ | | ✓ | `koka` | -| kotlin | ✓ | | | `kotlin-language-server` | -| latex | ✓ | ✓ | | `texlab` | -| ld | ✓ | | ✓ | | -| lean | ✓ | | | `lean` | -| ledger | ✓ | | | | -| llvm | ✓ | ✓ | ✓ | | -| llvm-mir | ✓ | ✓ | ✓ | | -| llvm-mir-yaml | ✓ | | ✓ | | -| log | ✓ | | | | -| lpf | ✓ | | | | -| lua | ✓ | ✓ | ✓ | `lua-language-server` | -| make | ✓ | | ✓ | | -| markdoc | ✓ | | | `markdoc-ls` | -| markdown | ✓ | | | `marksman`, `markdown-oxide` | -| markdown.inline | ✓ | | | | -| matlab | ✓ | ✓ | ✓ | | -| mermaid | ✓ | | | | -| meson | ✓ | | ✓ | | -| mint | | | | `mint` | -| msbuild | ✓ | | ✓ | | -| nasm | ✓ | ✓ | | | -| nickel | ✓ | | ✓ | `nls` | -| nim | ✓ | ✓ | ✓ | `nimlangserver` | -| nix | ✓ | ✓ | | `nil` | -| nu | ✓ | | | `nu` | -| nunjucks | ✓ | | | | -| ocaml | ✓ | | ✓ | `ocamllsp` | -| ocaml-interface | ✓ | | | `ocamllsp` | -| odin | ✓ | | ✓ | `ols` | -| ohm | ✓ | ✓ | ✓ | | -| opencl | ✓ | ✓ | ✓ | `clangd` | -| openscad | ✓ | | | `openscad-lsp` | -| org | ✓ | | | | -| pascal | ✓ | ✓ | | `pasls` | -| passwd | ✓ | | | | -| pem | ✓ | | | | -| perl | ✓ | ✓ | ✓ | `perlnavigator` | -| php | ✓ | ✓ | ✓ | `intelephense` | -| php-only | ✓ | | | | -| pkgbuild | ✓ | ✓ | ✓ | `pkgbuild-language-server`, `bash-language-server` | -| pkl | ✓ | | ✓ | | -| po | ✓ | ✓ | | | -| pod | ✓ | | | | -| ponylang | ✓ | ✓ | ✓ | | -| powershell | ✓ | | | | -| prisma | ✓ | | | `prisma-language-server` | -| prolog | | | | `swipl` | -| protobuf | ✓ | ✓ | ✓ | `bufls`, `pb` | -| prql | ✓ | | | | -| purescript | ✓ | ✓ | | `purescript-language-server` | -| python | ✓ | ✓ | ✓ | `pylsp` | -| qml | ✓ | | ✓ | `qmlls` | -| r | ✓ | | | `R` | -| racket | ✓ | | ✓ | `racket` | -| regex | ✓ | | | | -| rego | ✓ | | | `regols` | -| rescript | ✓ | ✓ | | `rescript-language-server` | -| rmarkdown | ✓ | | ✓ | `R` | -| robot | ✓ | | | `robotframework_ls` | -| ron | ✓ | | ✓ | | -| rst | ✓ | | | | -| ruby | ✓ | ✓ | ✓ | `solargraph` | -| rust | ✓ | ✓ | ✓ | `rust-analyzer` | -| sage | ✓ | ✓ | | | -| scala | ✓ | ✓ | ✓ | `metals` | -| scheme | ✓ | | ✓ | | -| scss | ✓ | | | `vscode-css-language-server` | -| slint | ✓ | ✓ | ✓ | `slint-lsp` | -| smali | ✓ | | ✓ | | -| smithy | ✓ | | | `cs` | -| sml | ✓ | | | | -| solidity | ✓ | | | `solc` | -| spicedb | ✓ | | | | -| sql | ✓ | | | | -| sshclientconfig | ✓ | | | | -| starlark | ✓ | ✓ | | | -| strace | ✓ | | | | -| supercollider | ✓ | | | | -| svelte | ✓ | | ✓ | `svelteserver` | -| sway | ✓ | ✓ | ✓ | `forc` | -| swift | ✓ | | | `sourcekit-lsp` | -| t32 | ✓ | | | | -| tablegen | ✓ | ✓ | ✓ | | -| tact | ✓ | ✓ | ✓ | | -| task | ✓ | | | | -| templ | ✓ | | | `templ` | -| tfvars | ✓ | | ✓ | `terraform-ls` | -| todotxt | ✓ | | | | -| toml | ✓ | | | `taplo` | -| tsq | ✓ | | | | -| tsx | ✓ | ✓ | ✓ | `typescript-language-server` | -| twig | ✓ | | | | -| typescript | ✓ | ✓ | ✓ | `typescript-language-server` | -| typst | ✓ | | | `typst-lsp` | -| ungrammar | ✓ | | | | -| unison | ✓ | | ✓ | | -| uxntal | ✓ | | | | -| v | ✓ | ✓ | ✓ | `v-analyzer` | -| vala | ✓ | ✓ | | `vala-language-server` | -| verilog | ✓ | ✓ | | `svlangserver` | -| vhdl | ✓ | | | `vhdl_ls` | -| vhs | ✓ | | | | -| vue | ✓ | | | `vue-language-server` | -| wast | ✓ | | | | -| wat | ✓ | | | | -| webc | ✓ | | | | -| wgsl | ✓ | | | `wgsl_analyzer` | -| wit | ✓ | | ✓ | | -| wren | ✓ | ✓ | ✓ | | -| xit | ✓ | | | | -| xml | ✓ | | ✓ | | -| yaml | ✓ | | ✓ | `yaml-language-server`, `ansible-language-server` | -| yuck | ✓ | | | | -| zig | ✓ | ✓ | ✓ | `zls` | +| Language | Syntax Highlighting | Treesitter Textobjects | Auto Indent | Rainbow Brackets | Default LSP | +| --- | --- | --- | --- | --- | --- | +| ada | ✓ | ✓ | | | `ada_language_server`, `ada_language_server` | +| agda | ✓ | | | | | +| astro | ✓ | | | | | +| awk | ✓ | ✓ | | | `awk-language-server` | +| bash | ✓ | ✓ | ✓ | ✓ | `bash-language-server` | +| bass | ✓ | | | | `bass` | +| beancount | ✓ | | | | | +| bibtex | ✓ | | | | `texlab` | +| bicep | ✓ | | | | `bicep-langserver` | +| blade | ✓ | | | | | +| blueprint | ✓ | | | | `blueprint-compiler` | +| c | ✓ | ✓ | ✓ | ✓ | `clangd` | +| c-sharp | ✓ | ✓ | | | `OmniSharp` | +| cabal | | | | | `haskell-language-server-wrapper` | +| cairo | ✓ | ✓ | ✓ | | `cairo-language-server` | +| capnp | ✓ | | ✓ | | | +| cel | ✓ | | | | | +| clojure | ✓ | | | ✓ | `clojure-lsp` | +| cmake | ✓ | ✓ | ✓ | | `cmake-language-server` | +| comment | ✓ | | | | | +| common-lisp | ✓ | | ✓ | ✓ | `cl-lsp` | +| cpon | ✓ | | ✓ | | | +| cpp | ✓ | ✓ | ✓ | ✓ | `clangd` | +| crystal | ✓ | ✓ | | | `crystalline` | +| css | ✓ | | ✓ | ✓ | `vscode-css-language-server` | +| cue | ✓ | | | | `cuelsp` | +| d | ✓ | ✓ | ✓ | | `serve-d` | +| dart | ✓ | ✓ | ✓ | | `dart` | +| dbml | ✓ | | | | | +| devicetree | ✓ | | | | | +| dhall | ✓ | ✓ | | | `dhall-lsp-server` | +| diff | ✓ | | | | | +| docker-compose | ✓ | | ✓ | | `docker-compose-langserver`, `yaml-language-server` | +| dockerfile | ✓ | | | | `docker-langserver` | +| dot | ✓ | | | | `dot-language-server` | +| dtd | ✓ | | | | | +| edoc | ✓ | | | | | +| eex | ✓ | | | | | +| ejs | ✓ | | | | | +| elixir | ✓ | ✓ | ✓ | ✓ | `elixir-ls` | +| elm | ✓ | ✓ | | | `elm-language-server` | +| elvish | ✓ | | | | `elvish` | +| env | ✓ | | | | | +| erb | ✓ | | | | | +| erlang | ✓ | ✓ | | ✓ | `erlang_ls` | +| esdl | ✓ | | | | | +| fidl | ✓ | | | | | +| fish | ✓ | ✓ | ✓ | | | +| forth | ✓ | | | | `forth-lsp` | +| fortran | ✓ | | ✓ | | `fortls` | +| fsharp | ✓ | | | | `fsautocomplete` | +| gas | ✓ | ✓ | | | | +| gdscript | ✓ | ✓ | ✓ | | | +| gemini | ✓ | | | | | +| git-attributes | ✓ | | | | | +| git-commit | ✓ | ✓ | | | | +| git-config | ✓ | | | | | +| git-ignore | ✓ | | | | | +| git-rebase | ✓ | | | | | +| gleam | ✓ | ✓ | | ✓ | `gleam` | +| glimmer | ✓ | | | | `ember-language-server` | +| glsl | ✓ | ✓ | ✓ | | | +| gn | ✓ | | | | | +| go | ✓ | ✓ | ✓ | ✓ | `gopls`, `golangci-lint-langserver` | +| godot-resource | ✓ | | | | | +| gomod | ✓ | | | | `gopls` | +| gotmpl | ✓ | | | | `gopls` | +| gowork | ✓ | | | | `gopls` | +| graphql | ✓ | | | | `graphql-lsp` | +| groovy | ✓ | | | | | +| hare | ✓ | | | | | +| haskell | ✓ | ✓ | | | `haskell-language-server-wrapper` | +| haskell-persistent | ✓ | | | | | +| hcl | ✓ | ✓ | ✓ | | `terraform-ls` | +| heex | ✓ | ✓ | | | `elixir-ls` | +| helm | ✓ | | | | `helm_ls` | +| hocon | ✓ | | ✓ | | | +| hoon | ✓ | | | | | +| hosts | ✓ | | | | | +| html | ✓ | | | ✓ | `vscode-html-language-server` | +| hurl | ✓ | | ✓ | | | +| hyprlang | ✓ | | ✓ | | | +| idris | | | | | `idris2-lsp` | +| iex | ✓ | | | | | +| ini | ✓ | | | | | +| janet | ✓ | | | | | +| java | ✓ | ✓ | ✓ | ✓ | `jdtls` | +| javascript | ✓ | ✓ | ✓ | ✓ | `typescript-language-server` | +| jinja | ✓ | | | | | +| jsdoc | ✓ | | | | | +| json | ✓ | | ✓ | ✓ | `vscode-json-language-server` | +| json5 | ✓ | | | | | +| jsonc | ✓ | | ✓ | | `vscode-json-language-server` | +| jsonnet | ✓ | | | | `jsonnet-language-server` | +| jsx | ✓ | ✓ | ✓ | ✓ | `typescript-language-server` | +| julia | ✓ | ✓ | ✓ | | `julia` | +| just | ✓ | ✓ | ✓ | | | +| kdl | ✓ | ✓ | ✓ | | | +| koka | ✓ | | ✓ | | `koka` | +| kotlin | ✓ | | | | `kotlin-language-server` | +| latex | ✓ | ✓ | | | `texlab` | +| ld | ✓ | | ✓ | | | +| lean | ✓ | | | | `lean` | +| ledger | ✓ | | | | | +| llvm | ✓ | ✓ | ✓ | | | +| llvm-mir | ✓ | ✓ | ✓ | | | +| llvm-mir-yaml | ✓ | | ✓ | | | +| log | ✓ | | | | | +| lpf | ✓ | | | | | +| lua | ✓ | ✓ | ✓ | | `lua-language-server` | +| make | ✓ | | ✓ | | | +| markdoc | ✓ | | | | `markdoc-ls` | +| markdown | ✓ | | | | `marksman`, `markdown-oxide` | +| markdown.inline | ✓ | | | | | +| matlab | ✓ | ✓ | ✓ | | | +| mermaid | ✓ | | | | | +| meson | ✓ | | ✓ | | | +| mint | | | | | `mint` | +| msbuild | ✓ | | ✓ | | | +| nasm | ✓ | ✓ | | | | +| nickel | ✓ | | ✓ | | `nls` | +| nim | ✓ | ✓ | ✓ | | `nimlangserver` | +| nix | ✓ | ✓ | | ✓ | `nil` | +| nu | ✓ | | | | `nu` | +| nunjucks | ✓ | | | | | +| ocaml | ✓ | | ✓ | | `ocamllsp` | +| ocaml-interface | ✓ | | | | `ocamllsp` | +| odin | ✓ | | ✓ | | `ols` | +| ohm | ✓ | ✓ | ✓ | | | +| opencl | ✓ | ✓ | ✓ | | `clangd` | +| openscad | ✓ | | | | `openscad-lsp` | +| org | ✓ | | | | | +| pascal | ✓ | ✓ | | | `pasls` | +| passwd | ✓ | | | | | +| pem | ✓ | | | | | +| perl | ✓ | ✓ | ✓ | | `perlnavigator` | +| php | ✓ | ✓ | ✓ | | `intelephense` | +| php-only | ✓ | | | | | +| pkgbuild | ✓ | ✓ | ✓ | | `pkgbuild-language-server`, `bash-language-server` | +| pkl | ✓ | | ✓ | | | +| po | ✓ | ✓ | | | | +| pod | ✓ | | | | | +| ponylang | ✓ | ✓ | ✓ | | | +| powershell | ✓ | | | | | +| prisma | ✓ | | | | `prisma-language-server` | +| prolog | | | | | `swipl` | +| protobuf | ✓ | ✓ | ✓ | | `bufls`, `pb` | +| prql | ✓ | | | | | +| purescript | ✓ | ✓ | | | `purescript-language-server` | +| python | ✓ | ✓ | ✓ | ✓ | `pylsp` | +| qml | ✓ | | ✓ | | `qmlls` | +| r | ✓ | | | | `R` | +| racket | ✓ | | ✓ | ✓ | `racket` | +| regex | ✓ | | | ✓ | | +| rego | ✓ | | | | `regols` | +| rescript | ✓ | ✓ | | | `rescript-language-server` | +| rmarkdown | ✓ | | ✓ | | `R` | +| robot | ✓ | | | | `robotframework_ls` | +| ron | ✓ | | ✓ | | | +| rst | ✓ | | | | | +| ruby | ✓ | ✓ | ✓ | ✓ | `solargraph` | +| rust | ✓ | ✓ | ✓ | ✓ | `rust-analyzer` | +| sage | ✓ | ✓ | | | | +| scala | ✓ | ✓ | ✓ | | `metals` | +| scheme | ✓ | | ✓ | ✓ | | +| scss | ✓ | | | ✓ | `vscode-css-language-server` | +| slint | ✓ | ✓ | ✓ | | `slint-lsp` | +| smali | ✓ | | ✓ | | | +| smithy | ✓ | | | | `cs` | +| sml | ✓ | | | | | +| solidity | ✓ | | | | `solc` | +| spicedb | ✓ | | | | | +| sql | ✓ | | | | | +| sshclientconfig | ✓ | | | | | +| starlark | ✓ | ✓ | | ✓ | | +| strace | ✓ | | | | | +| supercollider | ✓ | | | | | +| svelte | ✓ | | ✓ | | `svelteserver` | +| sway | ✓ | ✓ | ✓ | | `forc` | +| swift | ✓ | | | | `sourcekit-lsp` | +| t32 | ✓ | | | | | +| tablegen | ✓ | ✓ | ✓ | | | +| tact | ✓ | ✓ | ✓ | | | +| task | ✓ | | | | | +| templ | ✓ | | | | `templ` | +| tfvars | ✓ | | ✓ | | `terraform-ls` | +| todotxt | ✓ | | | | | +| toml | ✓ | | | ✓ | `taplo` | +| tsq | ✓ | | | ✓ | | +| tsx | ✓ | ✓ | ✓ | ✓ | `typescript-language-server` | +| twig | ✓ | | | | | +| typescript | ✓ | ✓ | ✓ | ✓ | `typescript-language-server` | +| typst | ✓ | | | | `typst-lsp` | +| ungrammar | ✓ | | | | | +| unison | ✓ | | ✓ | | | +| uxntal | ✓ | | | | | +| v | ✓ | ✓ | ✓ | | `v-analyzer` | +| vala | ✓ | ✓ | | | `vala-language-server` | +| verilog | ✓ | ✓ | | | `svlangserver` | +| vhdl | ✓ | | | | `vhdl_ls` | +| vhs | ✓ | | | | | +| vue | ✓ | | | | `vue-language-server` | +| wast | ✓ | | | | | +| wat | ✓ | | | | | +| webc | ✓ | | | | | +| wgsl | ✓ | | | | `wgsl_analyzer` | +| wit | ✓ | | ✓ | | | +| wren | ✓ | ✓ | ✓ | | | +| xit | ✓ | | | | | +| xml | ✓ | | ✓ | ✓ | | +| yaml | ✓ | | ✓ | ✓ | `yaml-language-server`, `ansible-language-server` | +| yuck | ✓ | | | | | +| zig | ✓ | ✓ | ✓ | ✓ | `zls` | diff --git a/book/src/guides/README.md b/book/src/guides/README.md index c25768e6..e53983d6 100644 --- a/book/src/guides/README.md +++ b/book/src/guides/README.md @@ -1,4 +1,4 @@ # Guides This section contains guides for adding new language server configurations, -tree-sitter grammars, textobject queries, and other similar items. +tree-sitter grammars, textobject and rainbow bracket queries, and other similar items. diff --git a/book/src/guides/rainbow_bracket_queries.md b/book/src/guides/rainbow_bracket_queries.md new file mode 100644 index 00000000..1cba6a99 --- /dev/null +++ b/book/src/guides/rainbow_bracket_queries.md @@ -0,0 +1,132 @@ +# 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: + +```tsq +["(" ")" "[" "]"] @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: +> +> ```js +> { +> // ... +> 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][tsq grammar.js]. 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`. + +```tsq +[ + (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 `link`, the syntax tree is: + +```tsq +(element ; link + (start_tag ; + (tag_name)) ; a + (text) ; link + (end_tag ; + (tag_name))) ; a +``` + +If we want to highlight the `<`, `>` and `" "` and `` and ``, and `