> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tree-sitter/tree-sitter/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```c theme={null}
const TSLanguage *ts_language_copy(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language to reference
</ParamField>

**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.

```c theme={null}
void ts_language_delete(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language to dereference
</ParamField>

## Language properties

### ts\_language\_name

Get the name of this language.

```c theme={null}
const char *ts_language_name(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

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

**Example:**

```c theme={null}
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.

```c theme={null}
uint32_t ts_language_abi_version(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

**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.

```c theme={null}
const TSLanguageMetadata *ts_language_metadata(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

**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](https://semver.org/) 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.

```c theme={null}
bool ts_language_is_wasm(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

**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.

```c theme={null}
uint32_t ts_language_symbol_count(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

**Returns:** The number of symbols.

### ts\_language\_state\_count

Get the number of valid states in this language.

```c theme={null}
uint32_t ts_language_state_count(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

**Returns:** The number of parse states.

### ts\_language\_symbol\_name

Get a node type string for the given numerical id.

```c theme={null}
const char *ts_language_symbol_name(const TSLanguage *self, TSSymbol symbol);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="symbol" type="TSSymbol">
  The symbol ID
</ParamField>

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

### ts\_language\_symbol\_for\_name

Get the numerical id for the given node type string.

```c theme={null}
TSSymbol ts_language_symbol_for_name(
  const TSLanguage *self,
  const char *string,
  uint32_t length,
  bool is_named
);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="string" type="const char *">
  The symbol name
</ParamField>

<ParamField path="length" type="uint32_t">
  Length of the string
</ParamField>

<ParamField path="is_named" type="bool">
  Whether to look for a named symbol
</ParamField>

**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.

```c theme={null}
TSSymbolType ts_language_symbol_type(const TSLanguage *self, TSSymbol symbol);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="symbol" type="TSSymbol">
  The symbol ID
</ParamField>

**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.

```c theme={null}
uint32_t ts_language_field_count(const TSLanguage *self);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

**Returns:** The number of fields.

### ts\_language\_field\_name\_for\_id

Get the field name string for the given numerical id.

```c theme={null}
const char *ts_language_field_name_for_id(const TSLanguage *self, TSFieldId id);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="id" type="TSFieldId">
  The field ID
</ParamField>

**Returns:** The field name (do not free).

### ts\_language\_field\_id\_for\_name

Get the numerical id for the given field name string.

```c theme={null}
TSFieldId ts_language_field_id_for_name(
  const TSLanguage *self,
  const char *name,
  uint32_t name_length
);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="name" type="const char *">
  The field name
</ParamField>

<ParamField path="name_length" type="uint32_t">
  Length of the name
</ParamField>

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

**Example:**

```c theme={null}
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.

```c theme={null}
const TSSymbol *ts_language_supertypes(const TSLanguage *self, uint32_t *length);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="length" type="uint32_t *">
  Output parameter for the array length
</ParamField>

**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.

```c theme={null}
const TSSymbol *ts_language_subtypes(
  const TSLanguage *self,
  TSSymbol supertype,
  uint32_t *length
);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="supertype" type="TSSymbol">
  The supertype symbol
</ParamField>

<ParamField path="length" type="uint32_t *">
  Output parameter for the array length
</ParamField>

**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.

```c theme={null}
TSStateId ts_language_next_state(
  const TSLanguage *self,
  TSStateId state,
  TSSymbol symbol
);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="state" type="TSStateId">
  The current parse state
</ParamField>

<ParamField path="symbol" type="TSSymbol">
  The grammar symbol to transition on
</ParamField>

**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.

```c theme={null}
TSLookaheadIterator *ts_lookahead_iterator_new(const TSLanguage *self, TSStateId state);
```

<ParamField path="self" type="const TSLanguage *">
  The language instance
</ParamField>

<ParamField path="state" type="TSStateId">
  The parse state
</ParamField>

**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:**

```c theme={null}
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.

```c theme={null}
void ts_lookahead_iterator_delete(TSLookaheadIterator *self);
```

<ParamField path="self" type="TSLookaheadIterator *">
  The iterator to delete
</ParamField>

### ts\_lookahead\_iterator\_reset\_state

Reset the lookahead iterator to another state.

```c theme={null}
bool ts_lookahead_iterator_reset_state(TSLookaheadIterator *self, TSStateId state);
```

<ParamField path="self" type="TSLookaheadIterator *">
  The iterator instance
</ParamField>

<ParamField path="state" type="TSStateId">
  The new parse state
</ParamField>

**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.

```c theme={null}
bool ts_lookahead_iterator_reset(
  TSLookaheadIterator *self,
  const TSLanguage *language,
  TSStateId state
);
```

<ParamField path="self" type="TSLookaheadIterator *">
  The iterator instance
</ParamField>

<ParamField path="language" type="const TSLanguage *">
  The new language
</ParamField>

<ParamField path="state" type="TSStateId">
  The new parse state
</ParamField>

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

### ts\_lookahead\_iterator\_language

Get the current language of the lookahead iterator.

```c theme={null}
const TSLanguage *ts_lookahead_iterator_language(const TSLookaheadIterator *self);
```

<ParamField path="self" type="const TSLookaheadIterator *">
  The iterator instance
</ParamField>

**Returns:** The current language.

### ts\_lookahead\_iterator\_next

Advance the lookahead iterator to the next symbol.

```c theme={null}
bool ts_lookahead_iterator_next(TSLookaheadIterator *self);
```

<ParamField path="self" type="TSLookaheadIterator *">
  The iterator instance
</ParamField>

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

### ts\_lookahead\_iterator\_current\_symbol

Get the current symbol of the lookahead iterator.

```c theme={null}
TSSymbol ts_lookahead_iterator_current_symbol(const TSLookaheadIterator *self);
```

<ParamField path="self" type="const TSLookaheadIterator *">
  The iterator instance
</ParamField>

**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.

```c theme={null}
const char *ts_lookahead_iterator_current_symbol_name(const TSLookaheadIterator *self);
```

<ParamField path="self" type="const TSLookaheadIterator *">
  The iterator instance
</ParamField>

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