diff options
author | Timothy DeHerrera | 2023-04-28 09:21:34 +0000 |
---|---|---|
committer | GitHub | 2023-04-28 09:21:34 +0000 |
commit | 9c6c63a2be30252a6207f4aebb5e0f76f746b4c8 (patch) | |
tree | cb1882ee0b719e2bf5fc8444b494ba0948dea178 /book/src/guides/injection.md | |
parent | 204d1eba4b1bb09d2e861986d6b6e8b868d16afe (diff) |
inject language based on file extension & shebang (#3970)
* inject language based on file extension
Nodes can now be captured with "injection.filename". If this capture
contains a valid file extension known to Helix, then the content will
be highlighted as that language.
* inject language by shebang
Nodes can now be captured with "injection.shebang". If this capture
contains a valid shebang line known to Helix, then the content will
be highlighted as the language the shebang calls for.
* add documentation for language injection
* nix: fix highlights
The `@` is now highlighted properly on either side of the function arg.
Also, extending the phases with `buildPhase = prev.buildPhase + ''''`
is now highlighted properly.
Fix highlighting of `''$` style escapes (requires tree-sitter-nix bump)
Fix `inherit` highlighting.
* simplify injection_for_match
Split out injection pair logic into its own method to make the overall
flow easier to follow.
Also transform the top-level function into a method on a
HighlightConfiguration.
* markdown: add shebang injection query
Diffstat (limited to 'book/src/guides/injection.md')
-rw-r--r-- | book/src/guides/injection.md | 57 |
1 files changed, 57 insertions, 0 deletions
diff --git a/book/src/guides/injection.md b/book/src/guides/injection.md new file mode 100644 index 00000000..18c474cf --- /dev/null +++ b/book/src/guides/injection.md @@ -0,0 +1,57 @@ +# Adding Injection Queries + +Writing language injection queries allows one to highlight a specific node as a different language. +In addition to the [standard](upstream-docs) language injection options used by tree-sitter, there +are a few Helix specific extensions that allow for more control. + +And example of a simple query that would highlight all strings as bash in Nix: +```scm +((string_expression (string_fragment) @injection.content) + (#set! injection.language "bash")) +``` + +## Capture Types + +- `@injection.language` (standard): +The captured node may contain the language name used to highlight the node captured by +`@injection.content`. + +- `@injection.content` (standard): +Marks the content to be highlighted as the language captured with `@injection.language` _et al_. + +- `@injection.filename` (extension): +The captured node may contain a filename with a file-extension known to Helix, +highlighting `@injection.content` as that language. This uses the language extensions defined in +both the default languages.toml distributed with Helix, as well as user defined languages. + +- `@injection.shebang` (extension): +The captured node may contain a shebang used to choose a language to highlight as. This also uses +the shebangs defined in the default and user `languages.toml`. + +## Settings + +- `injection.combined` (standard): +Indicates that all the matching nodes in the tree should have their content parsed as one +nested document. + +- `injection.language` (standard): +Forces the captured content to be highlighted as the given language + +- `injection.include-children` (standard): +Indicates that the content node’s entire text should be re-parsed, including the text of its child +nodes. By default, child nodes’ text will be excluded from the injected document. + +- `injection.include-unnamed-children` (extension): +Same as `injection.include-children` but only for unnamed child nodes. + +## Predicates + +- `#eq?` (standard): +The first argument (a capture) must be equal to the second argument +(a capture or a string). + +- `#match?` (standard): +The first argument (a capture) must match the regex given in the +second argument (a string). + +[upstream-docs]: http://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection |