Language API

Functions for accessing language metadata and information

The Language API provides functions for accessing information about Tree-sitter language definitions, including symbols, fields, and metadata.

Reference counting

ts_language_copy

Get another reference to the given language.

const TSLanguage *ts_language_copy(const TSLanguage *self);

self · const TSLanguage *

The language to reference

Returns: The same language pointer with incremented reference count.

ts_language_delete

Free any dynamically-allocated resources for this language, if this is the last reference.

void ts_language_delete(const TSLanguage *self);

self · const TSLanguage *

The language to dereference

Language properties

ts_language_name

Get the name of this language.

const char *ts_language_name(const TSLanguage *self);

self · const TSLanguage *

The language instance

Returns: The language name, or NULL in older parsers.

Example:

const TSLanguage *lang = tree_sitter_javascript();
printf("Language: %s\n", ts_language_name(lang));

ts_language_abi_version

Get the ABI version number for this language.

uint32_t ts_language_abi_version(const TSLanguage *self);

self · const TSLanguage *

The language instance

Returns: The ABI version number.

This version number is used to ensure that languages were generated by a compatible version of Tree-sitter. Compare this to TREE_SITTER_LANGUAGE_VERSION and TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION.

See also ts_parser_set_language.

ts_language_metadata

Get the metadata for this language.

const TSLanguageMetadata *ts_language_metadata(const TSLanguage *self);

self · const TSLanguage *

The language instance

Returns: Pointer to the language metadata.

The metadata is generated by the CLI and relies on the language author providing the correct metadata in the language’s tree-sitter.json file. The TSLanguageMetadata struct contains:

• major_version - Major version number
• minor_version - Minor version number
• patch_version - Patch version number

This metadata can be used to check the Semantic Version of the language. Use this version information to signal if a given parser might be incompatible with existing queries when upgrading between major versions, or minor versions if it’s in zerover.

ts_language_is_wasm

Check if the language came from a Wasm module.

bool ts_language_is_wasm(const TSLanguage *self);

self · const TSLanguage *

The language instance

Returns: true if the language is from Wasm.

If so, then in order to use this language with a parser, that parser must have a Wasm store assigned.

Symbols

ts_language_symbol_count

Get the number of distinct node types in the language.

uint32_t ts_language_symbol_count(const TSLanguage *self);

self · const TSLanguage *

The language instance

Returns: The number of symbols.

ts_language_state_count

Get the number of valid states in this language.

uint32_t ts_language_state_count(const TSLanguage *self);

self · const TSLanguage *

The language instance

Returns: The number of parse states.

ts_language_symbol_name

Get a node type string for the given numerical id.

const char *ts_language_symbol_name(const TSLanguage *self, TSSymbol symbol);

self · const TSLanguage *

The language instance

symbol · TSSymbol

The symbol ID

Returns: The symbol name (do not free).

ts_language_symbol_for_name

Get the numerical id for the given node type string.

TSSymbol ts_language_symbol_for_name(
  const TSLanguage *self,
  const char *string,
  uint32_t length,
  bool is_named
);

self · const TSLanguage *

The language instance

string · const char *

The symbol name

length · uint32_t

Length of the string

is_named · bool

Whether to look for a named symbol

Returns: The symbol ID, or 0 if not found.

ts_language_symbol_type

Check whether the given node type id belongs to named nodes, anonymous nodes, or hidden nodes.

TSSymbolType ts_language_symbol_type(const TSLanguage *self, TSSymbol symbol);

self · const TSLanguage *

The language instance

symbol · TSSymbol

The symbol ID

Returns: TSSymbolTypeRegular, TSSymbolTypeAnonymous, TSSymbolTypeSupertype, or TSSymbolTypeAuxiliary.

See also ts_node_is_named. Hidden nodes are never returned from the API.

Fields

ts_language_field_count

Get the number of distinct field names in the language.

uint32_t ts_language_field_count(const TSLanguage *self);

self · const TSLanguage *

The language instance

Returns: The number of fields.

ts_language_field_name_for_id

Get the field name string for the given numerical id.

const char *ts_language_field_name_for_id(const TSLanguage *self, TSFieldId id);

self · const TSLanguage *

The language instance

id · TSFieldId

The field ID

Returns: The field name (do not free).

ts_language_field_id_for_name

Get the numerical id for the given field name string.

TSFieldId ts_language_field_id_for_name(
  const TSLanguage *self,
  const char *name,
  uint32_t name_length
);

self · const TSLanguage *

The language instance

name · const char *

The field name

name_length · uint32_t

Length of the name

Returns: The field ID, or 0 if not found.

Example:

TSFieldId field_id = ts_language_field_id_for_name(lang, "name", 4);
if (field_id != 0) {
  TSNode child = ts_node_child_by_field_id(node, field_id);
}

Supertypes and subtypes

ts_language_supertypes

Get a list of all supertype symbols for the language.

const TSSymbol *ts_language_supertypes(const TSLanguage *self, uint32_t *length);

self · const TSLanguage *

The language instance

length · uint32_t *

Output parameter for the array length

Returns: Pointer to array of supertype symbols (do not free).

ts_language_subtypes

Get a list of all subtype symbol ids for a given supertype symbol.

const TSSymbol *ts_language_subtypes(
  const TSLanguage *self,
  TSSymbol supertype,
  uint32_t *length
);

self · const TSLanguage *

The language instance

supertype · TSSymbol

The supertype symbol

length · uint32_t *

Output parameter for the array length

Returns: Pointer to array of subtype symbols (do not free).

See ts_language_supertypes for fetching all supertype symbols.

Parse states

ts_language_next_state

Get the next parse state.

TSStateId ts_language_next_state(
  const TSLanguage *self,
  TSStateId state,
  TSSymbol symbol
);

self · const TSLanguage *

The language instance

state · TSStateId

The current parse state

symbol · TSSymbol

The grammar symbol to transition on

Returns: The next parse state.

Combine this with lookahead iterators to generate completion suggestions or valid symbols in error nodes. Use ts_node_grammar_symbol for valid symbols.

Lookahead iterators

ts_lookahead_iterator_new

Create a new lookahead iterator for the given language and parse state.

TSLookaheadIterator *ts_lookahead_iterator_new(const TSLanguage *self, TSStateId state);

self · const TSLanguage *

The language instance

state · TSStateId

The parse state

Returns: A new lookahead iterator, or NULL if the state is invalid.

Repeatedly using ts_lookahead_iterator_next and ts_lookahead_iterator_current_symbol will generate valid symbols in the given parse state. Newly created lookahead iterators will contain the ERROR symbol.

Lookahead iterators can be useful to generate suggestions and improve syntax error diagnostics. To get symbols valid in an ERROR node, use the lookahead iterator on its first leaf node state. For MISSING nodes, a lookahead iterator created on the previous non-extra leaf node may be appropriate.

Example:

TSLookaheadIterator *iter = ts_lookahead_iterator_new(lang, state);
if (iter != NULL) {
  while (ts_lookahead_iterator_next(iter)) {
    TSSymbol sym = ts_lookahead_iterator_current_symbol(iter);
    const char *name = ts_lookahead_iterator_current_symbol_name(iter);
    printf("Valid symbol: %s\n", name);
  }
  ts_lookahead_iterator_delete(iter);
}

ts_lookahead_iterator_delete

Delete a lookahead iterator, freeing all the memory used.

void ts_lookahead_iterator_delete(TSLookaheadIterator *self);

self · TSLookaheadIterator *

The iterator to delete

ts_lookahead_iterator_reset_state

Reset the lookahead iterator to another state.

bool ts_lookahead_iterator_reset_state(TSLookaheadIterator *self, TSStateId state);

self · TSLookaheadIterator *

The iterator instance

state · TSStateId

The new parse state

Returns: true if the iterator was reset, false if the state is invalid.

ts_lookahead_iterator_reset

Reset the lookahead iterator to a different language and state.

bool ts_lookahead_iterator_reset(
  TSLookaheadIterator *self,
  const TSLanguage *language,
  TSStateId state
);

self · TSLookaheadIterator *

The iterator instance

language · const TSLanguage *

The new language

state · TSStateId

The new parse state

Returns: true if the language was set successfully, false otherwise.

ts_lookahead_iterator_language

Get the current language of the lookahead iterator.

const TSLanguage *ts_lookahead_iterator_language(const TSLookaheadIterator *self);

self · const TSLookaheadIterator *

The iterator instance

Returns: The current language.

ts_lookahead_iterator_next

Advance the lookahead iterator to the next symbol.

bool ts_lookahead_iterator_next(TSLookaheadIterator *self);

self · TSLookaheadIterator *

The iterator instance

Returns: true if there is a new symbol, false otherwise.

ts_lookahead_iterator_current_symbol

Get the current symbol of the lookahead iterator.

TSSymbol ts_lookahead_iterator_current_symbol(const TSLookaheadIterator *self);

self · const TSLookaheadIterator *

The iterator instance

Returns: The current symbol ID.

ts_lookahead_iterator_current_symbol_name

Get the current symbol type of the lookahead iterator as a null-terminated string.

const char *ts_lookahead_iterator_current_symbol_name(const TSLookaheadIterator *self);

self · const TSLookaheadIterator *

The iterator instance

Returns: The current symbol name (do not free).