From 1ae9b0e4558fe7868f8cda2db65239cfb14836d0 Mon Sep 17 00:00:00 2001 From: Christian Clason Date: Sun, 24 Dec 2023 10:00:20 +0100 Subject: feat!: align standard captures with upstream Problem: Sharing highlight queries with upstream tree-sitter and Helix is difficult. Solution: Where reasonable, use capture names in tree-sitter's standard list or Helix's Atom-style hierarchy. Specifically: * tree-sitter "standard capture names" (https://github.com/tree-sitter/tree-sitter/blob/3f44b896852eb7daaa6df4fb778c9bb52c70c815/highlight/src/lib.rs#L20-L72): - `@parameter` -> `@variable.parameter` - `@field` -> `@variable.member` - `@namespace` -> `@module` - `@float` -> `@number.float` - `@symbol` -> `@string.special.symbol` - `@string.regex` -> `@string.regexp` - `@text.*` -> `@markup.*` (`strong`, `italic`, `link`, `strikethrough`; with exceptions; see below) - `@text.title` -> `@markup.heading` - `@text.literal` -> `@markup.raw` - `@text.reference` -> `@markup.link` - `@text.uri` -> `@markup.link.url` (in markup links) - `@string.special` -> `@markup.link.label` (non-url links) - `@punctuation.special` -> `@markup.list` (markdown lists only; move subitems from `@text.todo`) * Helix captures (https://docs.helix-editor.com/master/themes.html#syntax-highlighting): - `@method` -> `@function.method` - `@method.call` -> `@function.method.call` - `@text.{todo,warning,note,danger}` -> `@comment.{error,warning,hint,info,todo}` - `@text.diff.{add,delete,}` -> `@diff.{plus,minus,delta}` - `@text.uri` -> `@string.special.url` (outside markup) - `@preproc` -> `@keyword.directive` - `@define` -> `@keyword.directive`(`.define`?) - `@storageclass` -> `@keyword.storage` - `@conditional` -> `@keyword.conditional` - `@debug` -> `@keyword.debug` - `@exception` -> `@keyword.exception` - `@include` -> `@keyword.import` - `@repeat` -> `@keyword.repeat` * cleanup - remove some redundant `@conceal` (but still allow it for conceal-only patterns) - remove obsolete `@error` (syntax linting is out of scope for this repo) - sort, cleanup capture list in `CONTRIBUTING.md` --- CONTRIBUTING.md | 238 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 130 insertions(+), 108 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 209886d54..8c98c46b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,139 +84,145 @@ you can mark the language as optional (by putting it between parenthesis). As languages differ quite a lot, here is a set of captures available to you when building a `highlights.scm` query. Note that your colorscheme needs to define (or link) these captures as highlight groups. -#### Misc +#### Identifiers -```scheme -@comment ; line and block comments -@comment.documentation ; comments documenting code -@error ; syntax/parser errors -@none ; completely disable the highlight -@preproc ; various preprocessor directives & shebangs -@define ; preprocessor definition directives -@operator ; symbolic operators (e.g. `+` / `*`) +```query +@variable ; various variable names +@variable.builtin ; built-in variable names (e.g. `this`) +@variable.parameter ; parameters of a function +@variable.member ; object and struct fields + +@constant ; constant identifiers +@constant.builtin ; built-in constant values +@constant.macro ; constants defined by the preprocessor + +@module ; modules or namespaces +@module.builtin ; built-in modules or namespaces +@label ; GOTO and other labels (e.g. `label:` in C), including heredoc labels ``` +#### Literals -#### Punctuation - -```scheme -@punctuation.delimiter ; delimiters (e.g. `;` / `.` / `,`) -@punctuation.bracket ; brackets (e.g. `()` / `{}` / `[]`) -@punctuation.special ; special symbols (e.g. `{}` in string interpolation) +```query +@string ; string literals +@string.documentation ; string documenting code (e.g. Python docstrings) +@string.regexp ; regular expressions +@string.escape ; escape sequences +@string.special ; other special strings (e.g. dates) +@string.special.symbol ; symbols or atoms +@string.special.url ; URIs (e.g. hyperlinks) +@string.special.path ; filenames + +@character ; character literals +@character.special ; special characters (e.g. wildcards) + +@boolean ; boolean literals +@number ; numeric literals +@number.float ; floating-point number literals ``` -#### Literals +#### Types -```scheme -@string ; string literals -@string.documentation ; string documenting code (e.g. Python docstrings) -@string.regex ; regular expressions -@string.escape ; escape sequences -@string.special ; other special strings (e.g. dates) - -@character ; character literals -@character.special ; special characters (e.g. wildcards) - -@boolean ; boolean literals -@number ; numeric literals -@float ; floating-point number literals +```query +@type ; type or class definitions and annotations +@type.builtin ; built-in types +@type.definition ; identifiers in type definitions (e.g. `typedef ` in C) +@type.qualifier ; type qualifiers (e.g. `const`) + +@attribute ; attribute annotations (e.g. Python decorators) +@property ; the key in key/value pairs ``` #### Functions -```scheme -@function ; function definitions -@function.builtin ; built-in functions -@function.call ; function calls -@function.macro ; preprocessor macros +```query +@function ; function definitions +@function.builtin ; built-in functions +@function.call ; function calls +@function.macro ; preprocessor macros -@method ; method definitions -@method.call ; method calls +@function.method ; method definitions +@function.method.call ; method calls -@constructor ; constructor calls and definitions -@parameter ; parameters of a function +@constructor ; constructor calls and definitions +@operator ; symbolic operators (e.g. `+` / `*`) ``` #### Keywords -```scheme -@keyword ; various keywords -@keyword.coroutine ; keywords related to coroutines (e.g. `go` in Go, `async/await` in Python) -@keyword.function ; keywords that define a function (e.g. `func` in Go, `def` in Python) -@keyword.operator ; operators that are English words (e.g. `and` / `or`) -@keyword.return ; keywords like `return` and `yield` - -@conditional ; keywords related to conditionals (e.g. `if` / `else`) -@conditional.ternary ; ternary operator (e.g. `?` / `:`) - -@repeat ; keywords related to loops (e.g. `for` / `while`) -@debug ; keywords related to debugging -@label ; GOTO and other labels (e.g. `label:` in C) -@include ; keywords for including modules (e.g. `import` / `from` in Python) -@exception ; keywords related to exceptions (e.g. `throw` / `catch`) +```query +@keyword ; keywords not fitting into specific categories +@keyword.coroutine ; keywords related to coroutines (e.g. `go` in Go, `async/await` in Python) +@keyword.function ; keywords that define a function (e.g. `func` in Go, `def` in Python) +@keyword.operator ; operators that are English words (e.g. `and` / `or`) +@keyword.import ; keywords for including modules (e.g. `import` / `from` in Python) +@keyword.storage ; modifiers that affect storage in memory or life-time +@keyword.repeat ; keywords related to loops (e.g. `for` / `while`) +@keyword.return ; keywords like `return` and `yield` +@keyword.debug ; keywords related to debugging +@keyword.exception ; keywords related to exceptions (e.g. `throw` / `catch`) + +@keyword.conditional ; keywords related to conditionals (e.g. `if` / `else`) +@keyword.conditional.ternary ; ternary operator (e.g. `?` / `:`) + +@keyword.directive ; various preprocessor directives & shebangs +@keyword.directive.define ; preprocessor definition directives ``` -#### Types +#### Punctuation ```scheme -@type ; type or class definitions and annotations -@type.builtin ; built-in types -@type.definition ; identifiers in type definitions (e.g. `typedef ` in C) -@type.qualifier ; type qualifiers (e.g. `const`) - -@storageclass ; modifiers that affect storage in memory or life-time -@attribute ; attribute annotations (e.g. Python decorators) -@field ; object and struct fields -@property ; similar to `@field` +@punctuation.delimiter ; delimiters (e.g. `;` / `.` / `,`) +@punctuation.bracket ; brackets (e.g. `()` / `{}` / `[]`) +@punctuation.special ; special symbols (e.g. `{}` in string interpolation) ``` -#### Identifiers - -```scheme -@variable ; various variable names -@variable.builtin ; built-in variable names (e.g. `this`) +#### Comments -@constant ; constant identifiers -@constant.builtin ; built-in constant values -@constant.macro ; constants defined by the preprocessor +```query +@comment ; line and block comments +@comment.documentation ; comments documenting code -@namespace ; modules or namespaces -@symbol ; symbols or atoms +@comment.error ; error-type comments (e.g., `DEPRECATED:`) +@comment.warning ; warning-type comments (e.g., `WARNING:`, `FIX:`) +@comment.hint ; note-type comments (e.g., `NOTE:`) +@comment.info ; info-type comments +@comment.todo ; todo-type comments (e.g-, `TODO:`, `WIP:`) ``` -#### Text +#### Markup Mainly for markup languages. -```scheme -@text ; non-structured text -@text.strong ; bold text -@text.emphasis ; text with emphasis -@text.underline ; underlined text -@text.strike ; strikethrough text -@text.title ; text that is part of a title -@text.quote ; text quotations -@text.uri ; URIs (e.g. hyperlinks) -@text.math ; math environments (e.g. `$ ... $` in LaTeX) -@text.environment ; text environments of markup languages -@text.environment.name ; text indicating the type of an environment -@text.reference ; text references, footnotes, citations, etc. - -@text.literal ; literal or verbatim text (e.g., inline code) -@text.literal.block ; literal or verbatim text as a stand-alone block - ; (use priority 90 for blocks with injections) +```query +@markup.strong ; bold text +@markup.italic ; text with emphasis +@markup.strikethrough ; strikethrough text +@markup.underline ; underlined text (only for literal underline markup!) -@text.todo ; todo notes -@text.note ; info notes -@text.warning ; warning notes -@text.danger ; danger/error notes +@markup.heading ; headings, titles (including markers) -@text.diff.add ; added text (for diff files) -@text.diff.delete ; deleted text (for diff files) -``` +@markup.quote ; block quotes +@markup.math ; math environments (e.g. `$ ... $` in LaTeX) +@markup.environment ; environments (e.g. in LaTeX) -#### Tags +@markup.link ; text references, footnotes, citations, etc. +@markup.link.label ; link, reference descriptions +@markup.link.url ; URL-style links -Used for XML-like tags. +@markup.raw ; literal or verbatim text (e.g., inline code) +@markup.raw.block ; literal or verbatim text as a stand-alone block + ; (use priority 90 for blocks with injections) + +@markup.list ; list markers +@markup.list.checked ; checked todo-style list markers +@markup.list.unchecked ; unchecked todo-style list markers +``` + +```query +@diff.plus ; added text (for diff files) +@diff.minus ; deleted text (for diff files) +@diff.delta ; changed text (for diff files) +``` ```scheme @tag ; XML tag names @@ -224,17 +230,14 @@ Used for XML-like tags. @tag.delimiter ; XML tag delimiters ``` -#### Conceal +#### Non-highlighting captures -```scheme -@conceal ; for captures that are only used for concealing +```query +@none ; completely disable the highlight +@conceal ; captures that are only meant to be concealed ``` -`@conceal` must be followed by `(#set! conceal "")`. - -#### Spell - -```scheme +```query @spell ; for defining regions to be spellchecked @nospell ; for defining regions that should NOT be spellchecked ``` @@ -243,6 +246,25 @@ The main types of nodes which are spell checked are: - Comments - Strings; where it makes sense. Strings that have interpolation or are typically used for non text purposes are not spell checked (e.g. bash). +#### Predicates + +Captures can be restricted according to node contents using [predicates](https://neovim.io/doc/user/treesitter.html#treesitter-predicates). For performance reasons, prefer earlier predicates in this list: + +1. `#eq?` (literal match) +2. `#any-of?` (one of several literal matches) +3. `#lua-match?` (match against a [Lua pattern](https://neovim.io/doc/user/luaref.html#lua-pattern)) +4. `#match?`/`#vim-match?` (match against a [Vim regular expression](https://neovim.io/doc/user/pattern.html#regexp) + +#### Conceal + +Captures can be concealed by setting the [`conceal` metadata](https://neovim.io/doc/user/treesitter.html#treesitter-highlight-conceal), e.g.., +```query + (fenced_code_block_delimiter @markup.raw.block (#set! conceal "")) +``` +The capture should be meaningful to allow proper highlighting when `set conceallevel=0`. If the unconcealed capture should not be highlighted (e.g., because an earlier pattern handles this), you can use `@conceal`. + +A conceal can be restricted to part of the capture via the [`#offset!` directive](https://neovim.io/doc/user/treesitter.html#treesitter-directive-offset%21). + #### Priority Captures can be assigned a priority to control precedence of highlights via the -- cgit v1.2.3-70-g09d2