WASMTreeSitterGrammar

Description

This class holds an instance of a Tree-sitter grammar.

API documentation

All methods

::getCommentDelimiters()

Retrieve all known comment delimiters for this grammar.

Some grammars may have different delimiters for different parts of a file (such as JSX within JavaScript). In these cases, you might want to call TextEditor::getCommentDelimitersForBufferPosition with a {Point} in the buffer.

Return values

  • Returns an Object with the following properties:

    • line: If present, a String representing a line comment delimiter. (If undefined, there is no known line comment delimiter for the given buffer position.)
    • block: If present, a two-item Array containing Strings representing the starting and ending block comment delimiters. (If undefined, there are no known block comment delimiters for the given buffer position.)

::getLanguageSync()

Retrieves the Tree-sitter Language instance associated with this grammar if it has already been loaded.

Language instances cannot be retrieved synchrously, so this will return undefined if the instance has not yet been loaded. In that case, going async will be unavoidable, and you’ll need to call WASMTreeSitterGrammar::getLanguage.

::getLanguage()

Retrieves the Tree-sitter language instance associated with this grammar.

Return values

  • Returns a Promise that will resolve with a Tree-sitter Language instance. Once it resolves, the grammar is ready to perform parsing and to execute query captures.

::getQuery(queryType)

Given a kind of query, retrieves a Tree-sitter Query object in async fashion.

Argument Description
queryType

A String describing the query type: typically one of highlightsQuery, foldsQuery, tagsQuery, or indentsQuery, but could be any other custom type.
Return values

  • Returns a Promise that resolves to a Tree-sitter Query object.

::createQuery(queryContents)

Creates an arbitrary query from this grammar. Package authors and end users can use queries for whatever purposes they like.

Argument Description
queryContents

A String representing the entire contents of a query file. Can contain any number of queries.
Return values

  • Returns a Promise that will resolve to a Tree-sitter Query object.

::createQuerySync(queryContents)

Creates an arbitrary query from this grammar. Package authors and end users can use queries for whatever purposes they like.

Synchronous; use only when you can be certain that the tree-sitter language has already loaded.

Argument Description
queryContents

A String representing the entire contents of a query file. Can contain any number of queries.
Return values

  • Returns a Tree-sitter Query object.

::onDidChangeQuery()

Calls callback when any of this grammar's queries change.

A grammar's queries typically will not change after initial load. When they do, it may mean:

  • The user is editing query files in dev mode; Pulsar will automatically reload queries in dev mode after changes.
  • A community package is altering a query file via an API like WASMTreeSitterGrammar::setQueryForTest.
  • callback Function
    • data Object
      • filePath String The path to the query file on disk.
      • queryType String The type of query file, as denoted by its configuration key in the grammar file. Usually one of highlightsQuery, indentsQuery, foldsQuery, or tagsQuery.

::onDidChangeQueryFile()

Calls callback when any of this grammar's queries change.

Alias of WASMTreeSitterGrammar::onDidChangeQuery.

::onDidLoadQueryFiles()

Calls callback when this grammar first loads its query files.

Since a grammar may not load immedately on startup, this method makes it easier to hook into the query life cycle in order to modify or augment a grammar's default queries.

  • callback A function with the following argument:

::onDidAddInjectionPoint()

Calls callback when an injection point is added to this grammar.

::onDidRemoveInjectionPoint()

Calls callback when an injection point is removed from this grammar.

::addInjectionPoint(options)

Define a set of rules for when this grammar should delegate to a different grammar for certain regions of a buffer. Examples:

  • embedding one language inside another (e.g., JavaScript in HTML)
  • tokenizing certain structures with greater detail (e.g., regular expressions in most languages)
  • highlighting non-standard augmentations to a language (e.g., JSDoc comments in JavaScript)

This differs from TextMate-style injections, which operate at the scope level and are currently incompatible with Tree-sitter grammars.

You should typically not call this method directly; instead, call GrammarRegistry::addInjectionPoint and pass a given grammar’s root language scope as the first argument.

NOTE: Packages will call WASMTreeSitterGrammar::addInjectionPoint with a given scope name, and that call will be delegated to any Tree-sitter grammars that match that scope name, whether they're legacy Tree-sitter or modern Tree-sitter. But modern Tree-sitter grammars cannot be injected into legacy Tree-sitter grammars, and vice versa.

Argument Description
options

The options for the injection point:
type

A String describing type of node to inject into.
language

A Function that should return a string describing the language that should inject into this area. The string should be a short, unambiguous description of the language; it will be tested against other grammars’ injectionRegex properties. Receives one parameter:
node

A Tree-sitter node.
content

A Function that should return the node (or nodes) that will actually be injected into. Usually this will be the same node that was given, but could also be a specific child or descendant of that node.
includeChildren optional

Boolean controlling whether the injection range should include the ranges of the content node’s children. Defaults to false, meaning that the range of each of this node's children will be "subtracted" from the injection range, and the remainder will be parsed as if those ranges of the buffer do not exist.
includeAdjacentWhitespace optional

Boolean controlling whether the injection range should include whitespace that occurs between content nodes. Defaults to false. When true, if two injection ranges are separated from one another by only whitespace, that whitespace will be added to the injection range, and the ranges will be consolidated.
newlinesBetween optional

Boolean controlling whether the injection range should include any newline characters that may exist in between injection ranges. Defaults to false. Grammars like ERB and EJS need this so that they do not interpret two different embedded code sections on different lines as occurring on the same line.
coverShallowerScopes optional

Boolean controlling whether the injection should prevent the parent grammar (and any of its ancestors) from applying scope boundaries within its injection range(s). Defalts to false.
languageScope optional

A value that determines what scope, if any, is added to the injection as its “base” scope name. Can be a String, null, or a Function that returns either of these values. The base language scope that should be used by this injection. Defaults to the grammar's own scopeName property. Set this to a string to override the default scope name, or null to omit a base scope name altogether. Set this to a function if the scope name to be applied varies based on the grammar; the function will be called with a grammar instance as its only argument.