GrammarRegistry

Description

This class holds the grammars used for tokenizing.

An instance of this class is always available as the atom.grammars global.

API documentation

All methods

::maintainLanguageMode(buffer)

set a TextBuffer's language mode based on its path and content, and continue to update its language mode as grammars are added or updated, or the buffer's file path changes.

Argument Description
buffer

The TextBuffer whose language mode will be maintained.
Return values

  • Returns a Disposable that can be used to stop updating the buffer's language mode.

::assignLanguageMode(buffer, languageId)

Force a TextBuffer to use a different grammar than the one that would otherwise be selected for it.

Argument Description
buffer

The TextBuffer whose grammar will be set.
languageId

The String id of the desired language.
Return values

  • Returns a Boolean that indicates whether the language was successfully found.

::assignGrammar(buffer, grammar)

Force a TextBuffer to use a different grammar than the one that would otherwise be selected for it.

Argument Description
buffer

The TextBuffer whose grammar will be set.
grammar

The desired Grammar.
Return values

  • Returns a Boolean that indicates whether the assignment was successful

::getAssignedLanguageId()

Get the languageId that has been explicitly assigned to the given buffer, if any.

Return values

  • Returns a String id of the language

::autoAssignLanguageMode(buffer)

Remove any language mode override that has been set for the given TextBuffer. This will assign to the buffer the best language mode available.

Argument Description
buffer

The TextBuffer.

::selectGrammar(filePath, fileContents)

Select a grammar for the given file path and file contents.

This picks the best match by checking the file path and contents against each grammar.

Argument Description
filePath

A String file path.
fileContents

A String of text for the file path.
Return values

::getGrammarScore()

Return values

  • Returns a Number representing how well the grammar matches the filePath and contents.

::onDidAddGrammar(callback)

Invoke the given callback when a grammar is added to the registry.

Argument Description
callback

Function to call when a grammar is added.
grammar

Grammar that was added.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::onDidUpdateGrammar(callback)

Invoke the given callback when a grammar is updated due to a grammar it depends on being added or removed from the registry.

Argument Description
callback

Function to call when a grammar is updated.
grammar

Grammar that was updated.
Return values

  • Returns a Disposable on which .dispose() can be called to unsubscribe.

::addInjectionPoint(grammarId, injectionPoint)

Specify a type of syntax node that may embed other languages.

Argument Description
grammarId

The String id of the parent language
injectionPoint

An Object with the following keys:
type

The String type of syntax node that may embed other languages
language

A Function that is called with syntax nodes of the specified type and returns a String that will be tested against other grammars' injectionRegex in order to determine what language should be embedded.
content

A Function that is called with syntax nodes of the specified type and returns another syntax node or array of syntax nodes that contain the embedded source code. Depending on the settings below, the content node(s) will be converted into a series of buffer ranges; when this injection is parsed, anything not inside those ranges will be invisible to the parser.
includeChildren

A Boolean that indicates whether the children (and, in fact, all descendants) of the nodes returned by content should be included in the injection's buffer range(s). Defaults to false.
newlinesBetween

A Boolean that indicates whether each node returned from content should be separated by at least one newline character so that the parser understands them to be logically separated. Embedded languages like ERB and EJS need this. Defaults to false.
languageScope

A String or Function that returns the desired scope name to apply to each of the injection's buffer ranges. Defaults to the injected grammar's own language scope — e.g., source.js for the JavaScript grammar. Set to null if the language scope should be omitted. If a Function, will be called with the grammar instance as an argument, and should return either a String or null.
coverShallowerScopes

A Boolean that indicates whether this injection should prevent shallower layers (including the layer that created this injection) from adding scopes within any of this injection's buffer ranges. Useful for injecting languages into themselves — for instance, injecting Rust into Rust macro definitions.
includeAdjacentWhitespace

A Boolean that indicates whether the injection's buffer range(s) should include whitespace that occurs between two adjacent ranges. Defaults to false. When true, if two consecutive injection buffer ranges are separated only by whitespace, those ranges will be consolidated into one range along with that whitespace.

::loadGrammar(grammarPath, callback)

Read a grammar asynchronously and add it to the registry.

Argument Description
grammarPath

A String absolute file path to a grammar file.
callback

A Function to call when loaded with the following arguments:
error

An Error, may be null.
grammar

A Grammar or null if an error occurred.

::loadGrammarSync(grammarPath)

Read a grammar synchronously and add it to this registry.

Argument Description
grammarPath

A String absolute file path to a grammar file.
Return values

::readGrammar(grammarPath, callback)

Read a grammar asynchronously but don't add it to the registry.

Argument Description
grammarPath

A String absolute file path to a grammar file.
callback

A Function to call when read with the following arguments:
error

An Error, may be null.
grammar

A Grammar or null if an error occurred.
Return values

  • Returns undefined.

::readGrammarSync(grammarPath)

Read a grammar synchronously but don't add it to the registry.

Argument Description
grammarPath

A String absolute file path to a grammar file.
Return values

::getGrammars(options)

Get all the grammars in this registry.

Argument Description
options optional

Object
includeTreeSitter optional

Boolean Set to include Tree-sitter grammars
Return values