C API Reference
C API Reference v1.15.7
Section titled “C API Reference v1.15.7”Functions
Section titled “Functions”ts_pack_detect_language_from_extension()
Section titled “ts_pack_detect_language_from_extension()”Detect language name from a file extension (without leading dot).
Returns NULL for unrecognized extensions. The match is case-insensitive.
Signature:
const char* ts_pack_detect_language_from_extension(const char* ext);Example:
const char* result = ts_pack_detect_language_from_extension("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
ext |
const char* |
Yes | The ext |
Returns: const char*
ts_pack_detect_language_from_path()
Section titled “ts_pack_detect_language_from_path()”Detect language name from a file path.
Extracts the file extension and looks it up. Returns NULL if the
path has no extension or the extension is not recognized.
Signature:
const char* ts_pack_detect_language_from_path(const char* path);Example:
const char* result = ts_pack_detect_language_from_path("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
path |
const char* |
Yes | Path to the file |
Returns: const char*
ts_pack_detect_language_from_content()
Section titled “ts_pack_detect_language_from_content()”Detect language name from file content using the shebang line (#!).
Inspects only the first line of content. If it begins with #!, the
interpreter name is extracted and mapped to a language name.
Handles common patterns:
#!/usr/bin/env python3→"python"#!/bin/bash→"bash"#!/usr/bin/env node→"javascript"
The -S flag accepted by some env implementations is skipped automatically.
Version suffixes (e.g. python3.11, ruby3.2) are stripped before matching.
A leading UTF-8 BOM (U+FEFF) is skipped before the #! check, so a
BOM-prefixed script is still detected by its shebang.
Returns NULL when content does not start with #! (after stripping a
leading BOM), the shebang is malformed, or the interpreter is not recognised.
Signature:
const char* ts_pack_detect_language_from_content(const char* content);Example:
const char* result = ts_pack_detect_language_from_content("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
content |
const char* |
Yes | The content to process |
Returns: const char*
ts_pack_get_highlights_query()
Section titled “ts_pack_get_highlights_query()”Get the highlights query for a language, if bundled.
Returns the contents of highlights.scm as a static string, or NULL
if no highlights query is bundled for this language.
Signature:
const char* ts_pack_get_highlights_query(const char* language);Example:
const char* result = ts_pack_get_highlights_query("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
language |
const char* |
Yes | The language |
Returns: const char*
ts_pack_get_injections_query()
Section titled “ts_pack_get_injections_query()”Get the injections query for a language, if bundled.
Returns the contents of injections.scm as a static string, or NULL
if no injections query is bundled for this language.
Signature:
const char* ts_pack_get_injections_query(const char* language);Example:
const char* result = ts_pack_get_injections_query("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
language |
const char* |
Yes | The language |
Returns: const char*
ts_pack_get_locals_query()
Section titled “ts_pack_get_locals_query()”Get the locals query for a language, if bundled.
Returns the contents of locals.scm as a static string, or NULL
if no locals query is bundled for this language.
Signature:
const char* ts_pack_get_locals_query(const char* language);Example:
const char* result = ts_pack_get_locals_query("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
language |
const char* |
Yes | The language |
Returns: const char*
ts_pack_get_tags_query()
Section titled “ts_pack_get_tags_query()”Get the tags query for a language, if bundled.
Returns the contents of tags.scm as a static string, or NULL
if no tags query is bundled for this language.
Signature:
const char* ts_pack_get_tags_query(const char* language);Example:
const char* result = ts_pack_get_tags_query("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
language |
const char* |
Yes | The language |
Returns: const char*
ts_pack_get_indents_query()
Section titled “ts_pack_get_indents_query()”Get the indents query for a language, if bundled.
Returns the contents of indents.scm (used for auto-indentation) as a static
string, or NULL if no indents query is bundled for this language.
Signature:
const char* ts_pack_get_indents_query(const char* language);Example:
const char* result = ts_pack_get_indents_query("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
language |
const char* |
Yes | The language |
Returns: const char*
ts_pack_get_folds_query()
Section titled “ts_pack_get_folds_query()”Get the folds query for a language, if bundled.
Returns the contents of folds.scm (used for code folding) as a static string,
or NULL if no folds query is bundled for this language.
Signature:
const char* ts_pack_get_folds_query(const char* language);Example:
const char* result = ts_pack_get_folds_query("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
language |
const char* |
Yes | The language |
Returns: const char*
ts_pack_get_language()
Section titled “ts_pack_get_language()”Get a tree-sitter Language by name using the global registry.
Resolves language aliases (e.g., "shell" maps to "bash").
When the download feature is enabled (default), automatically downloads
the parser from GitHub releases if not found locally.
Errors:
Returns Error.LanguageNotFound if the language is not recognized,
or Error.Download if auto-download fails.
Signature:
TS_PACKAlefHandle ts_pack_get_language(const char* name);Example:
TS_PACKAlefHandle result = ts_pack_get_language("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: TS_PACKAlefHandle
Errors: Returns the sentinel handle 0 on error.
ts_pack_get_parser()
Section titled “ts_pack_get_parser()”Get a Parser pre-configured for the given language.
This is a convenience function that calls get_language and configures
a new parser in one step.
Errors:
Returns Error.LanguageNotFound if the language is not recognized, or
Error.ParserSetup if the language cannot be applied to the parser.
Signature:
TS_PACKAlefHandle ts_pack_get_parser(const char* name);Example:
TS_PACKAlefHandle result = ts_pack_get_parser("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: TS_PACKAlefHandle
Errors: Returns the sentinel handle 0 on error.
ts_pack_detect_language()
Section titled “ts_pack_detect_language()”Detect language name from a file path or extension.
This compatibility alias matches the pre-Alef Python binding API.
Signature:
const char* ts_pack_detect_language(const char* path);Example:
const char* result = ts_pack_detect_language("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
path |
const char* |
Yes | Path to the file |
Returns: const char*
ts_pack_available_languages()
Section titled “ts_pack_available_languages()”List all available language names (sorted, deduplicated, includes aliases).
Returns names of both statically compiled and dynamically loadable languages, plus any configured aliases.
Signature:
const char** ts_pack_available_languages();Example:
const char** result = ts_pack_available_languages();Returns: const char**
ts_pack_has_language()
Section titled “ts_pack_has_language()”Check if a language is available by name or alias.
Returns true if the language can be loaded (statically compiled,
dynamically available, or a known alias for one of these).
Signature:
int32_t ts_pack_has_language(const char* name);Example:
int32_t result = ts_pack_has_language("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: int32_t
ts_pack_language_count()
Section titled “ts_pack_language_count()”Return the number of available languages.
Includes statically compiled languages, dynamically loadable languages, and aliases.
Signature:
uintptr_t ts_pack_language_count();Example:
uintptr_t result = ts_pack_language_count();Returns: uintptr_t
ts_pack_process()
Section titled “ts_pack_process()”Process source code and extract file intelligence using the global registry.
Parses the source with tree-sitter and extracts metrics, structure, imports,
exports, comments, docstrings, symbols, diagnostics, and/or chunks based on
the flags set in ProcessConfig.
Errors:
Returns Error.InvalidRange if the config carries a zero-valued limit or
the source exceeds ProcessConfig.max_source_bytes,
Error.ParseTimeout if the parse exceeds
ProcessConfig.parse_timeout_ms, Error.LanguageNotFound if the
language is unknown, or Error.ParseFailed if parsing yields no tree.
Signature:
TS_PACKAlefHandle ts_pack_process(const char* source, TS_PACKAlefHandle config);Example:
TS_PACKAlefHandle result = ts_pack_process("value", 0);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
source |
const char* |
Yes | The source |
config |
TS_PACKAlefHandle |
Yes | The configuration options |
Returns: TS_PACKAlefHandle
Errors: Returns the sentinel handle 0 on error.
ts_pack_init()
Section titled “ts_pack_init()”Initialize the language pack with the given configuration.
Applies any custom cache directory, then downloads all languages and groups specified in the config. This is the recommended entry point when you want to pre-warm the cache before use.
Errors:
Returns an error if configuration cannot be applied or if downloads fail.
Signature:
int32_t ts_pack_init(TS_PACKAlefHandle config);Example:
ts_pack_init(0);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
config |
TS_PACKAlefHandle |
Yes | The configuration options |
Returns: int32_t status code – 0 on success, -1 on error.
Errors: Returns -1 on error.
ts_pack_configure()
Section titled “ts_pack_configure()”Apply download configuration without downloading anything.
Use this to set a custom cache directory before the first call to
get_language or any download function. Changing the cache dir
after languages have been registered has no effect on already-loaded
languages.
PackConfig.cache_dir is a BASE directory, not the final libs path: this
crate appends tree-sitter-language-pack/v{version}/libs to it, the same
suffix applied to the platform default cache directory. In the example below,
files actually land under /tmp/my-parsers/tree-sitter-language-pack/v{version}/libs/,
never directly in /tmp/my-parsers/. Call cache_dir to read back the
resolved, fully-suffixed path.
Errors:
Returns an error if the lock cannot be acquired.
Signature:
int32_t ts_pack_configure(TS_PACKAlefHandle config);Example:
ts_pack_configure(0);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
config |
TS_PACKAlefHandle |
Yes | The configuration options |
Returns: int32_t status code – 0 on success, -1 on error.
Errors: Returns -1 on error.
ts_pack_download()
Section titled “ts_pack_download()”Download specific languages to the local cache.
Returns the number of distinct languages available after the call. Already compiled or cached languages are included in the count.
Aliases are resolved before counting, so ["shell", "bash"] names one
language and returns 1.
Errors:
Returns an error if any language is not available in the manifest or if the download fails.
Signature:
uintptr_t ts_pack_download(const char** names);Example:
uintptr_t result = ts_pack_download(NULL);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
names |
const char** |
Yes | The names |
Returns: uintptr_t
Errors: Returns 0 on error.
ts_pack_prefetch()
Section titled “ts_pack_prefetch()”Prefetch grammars: download any not already loadable from disk, then load every requested language into the process registry so a subsequent hot loop only parses.
Unlike download(), this does not trust in-memory availability — it downloads
whenever a grammar is not actually loadable from disk (fixing the case where a
known-but-not-downloaded grammar is reported present), then resolves and caches
every requested language. Call it once, up front, before a parallel workload.
Errors:
Returns Error.Download if a required grammar cannot be fetched, or
Error.LanguageNotFound if a requested name is unknown.
Signature:
int32_t ts_pack_prefetch(const char** languages);Example:
ts_pack_prefetch(NULL);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
languages |
const char** |
Yes | The languages |
Returns: int32_t status code – 0 on success, -1 on error.
Errors: Returns -1 on error.
ts_pack_download_all()
Section titled “ts_pack_download_all()”Download all available languages from the remote manifest.
Downloads the platform bundle and extracts every library it contains. Languages that appear in the manifest but are absent from the bundle (e.g. grammars that failed to compile at release time) are silently skipped — they are not treated as an error.
Returns the total number of languages now available (statically compiled plus downloaded and cached).
Errors:
Returns an error if the manifest cannot be fetched or the bundle download fails.
Signature:
uintptr_t ts_pack_download_all();Example:
uintptr_t result = ts_pack_download_all();Returns: uintptr_t
Errors: Returns 0 on error.
ts_pack_download_group()
Section titled “ts_pack_download_group()”Download every language in a named group.
Groups are defined by the remote manifest, not by this library, and let you
ensure a curated set of related grammars in one call instead of listing each
name to download(). Already-cached languages are skipped.
Call manifest_groups to discover the group names the manifest actually
defines. The published manifest currently defines a single group, "all";
earlier revisions of this documentation advertised "web", "data", and
"systems", which the manifest has never contained, so every call following
that example failed. Do not hardcode a group name without checking.
Returns the total number of languages now available (statically compiled plus downloaded and cached).
Errors:
Returns Error.Download if the manifest cannot be fetched, if the group
is unknown — the message lists the groups the manifest defines — or if any
constituent language fails to download.
Signature:
uintptr_t ts_pack_download_group(const char* name);Example:
uintptr_t result = ts_pack_download_group("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: uintptr_t
Errors: Returns 0 on error.
ts_pack_manifest_languages()
Section titled “ts_pack_manifest_languages()”Return all language names available in the remote manifest (371).
Fetches (and caches) the remote manifest to discover the full list of
downloadable languages. Use downloaded_languages to list what is
already cached locally.
Errors:
Returns an error if the manifest cannot be fetched.
Signature:
const char** ts_pack_manifest_languages();Example:
const char** result = ts_pack_manifest_languages();Returns: const char**
Errors: Returns NULL on error.
ts_pack_manifest_groups()
Section titled “ts_pack_manifest_groups()”Return the names of every language group the remote manifest defines, sorted.
Group names are manifest data, not a compile-time constant of this library, so
this is the only reliable way to learn what download_group and
PackConfig.groups accept. The published manifest currently defines just
"all".
Errors:
Returns Error.Download if the manifest cannot be fetched.
Signature:
const char** ts_pack_manifest_groups();Example:
const char** result = ts_pack_manifest_groups();Returns: const char**
Errors: Returns NULL on error.
ts_pack_downloaded_languages()
Section titled “ts_pack_downloaded_languages()”Return languages that are already downloaded and cached locally.
Does not perform any network requests. Returns an empty list if the cache directory does not exist or cannot be read.
Signature:
const char** ts_pack_downloaded_languages();Example:
const char** result = ts_pack_downloaded_languages();Returns: const char**
ts_pack_clean_cache()
Section titled “ts_pack_clean_cache()”Delete all cached parser shared libraries.
Resets the cache registration so the next call to get_language or
a download function will re-register the (now empty) cache directory.
Errors:
Returns an error if the cache directory cannot be removed.
Signature:
int32_t ts_pack_clean_cache();Example:
ts_pack_clean_cache();Returns: int32_t status code – 0 on success, -1 on error.
Errors: Returns -1 on error.
ts_pack_cache_dir()
Section titled “ts_pack_cache_dir()”Return the effective cache directory path.
This is {base}/tree-sitter-language-pack/v{version}/libs/, where {base} is
either the custom BASE directory set via configure / init
(PackConfig.cache_dir) or the platform default cache directory — both are
suffixed identically, so a custom cache_dir is never used as the final libs
path. The default resolves to ~/.cache/tree-sitter-language-pack/v{version}/libs/
on a typical Unix system.
Errors:
Returns an error if no cache directory can be resolved: version is somehow
invalid, or (with no custom cache_dir configured) the platform reports none
and TREE_SITTER_LANGUAGE_PACK_CACHE_DIR is unset. This crate no longer falls
back to the temporary directory for the latter case — see #101 H2.
Signature:
const char* ts_pack_cache_dir();Example:
const char *result = ts_pack_cache_dir();Returns: const char*
Errors: Returns NULL on error.
TS_PACKByteRange
Section titled “TS_PACKByteRange”C representation: TS_PACKByteRange is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKByteRange does not appear anywhere in the generated header.
A byte range — start (inclusive) to end (exclusive).
| Field | Type | Default | Description |
|---|---|---|---|
start |
uintptr_t |
— | Inclusive start byte offset. |
end |
uintptr_t |
— | Exclusive end byte offset. |
TS_PACKChunkContext
Section titled “TS_PACKChunkContext”C representation: TS_PACKChunkContext is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKChunkContext does not appear anywhere in the generated header.
Metadata for a single chunk of source code.
| Field | Type | Default | Description |
|---|---|---|---|
language |
const char* |
— | Language name used to parse this chunk. |
chunk_index |
uintptr_t |
— | Zero-indexed position of this chunk within the file’s chunk list. |
total_chunks |
uintptr_t |
— | Total number of chunks the file was split into. |
node_types |
const char** |
NULL |
Tree-sitter node kinds that appear at the top level of this chunk. |
context_path |
const char** |
NULL |
Hierarchical path of enclosing structural items (e.g., ["MyClass", "my_method"]). |
symbols_defined |
const char** |
NULL |
Names of symbols defined within this chunk. |
comments |
TS_PACKAlefHandle* |
NULL |
Comments contained within this chunk. |
docstrings |
TS_PACKAlefHandle* |
NULL |
Docstrings contained within this chunk. Populated only for Python — the same language for which ProcessResult.docstrings is populated, and by the same classifier. Always empty for every other language. |
has_error_nodes |
int32_t |
— | Whether this chunk contains any tree-sitter error nodes. |
TS_PACKCodeChunk
Section titled “TS_PACKCodeChunk”C representation: TS_PACKCodeChunk is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKCodeChunk does not appear anywhere in the generated header.
A chunk of source code with rich metadata.
| Field | Type | Default | Description |
|---|---|---|---|
content |
const char* |
— | The raw source text of this chunk. |
start_byte |
uintptr_t |
— | Inclusive start byte offset of this chunk in the original source. |
end_byte |
uintptr_t |
— | Exclusive end byte offset of this chunk in the original source. |
start_line |
uintptr_t |
— | Zero-indexed start line of this chunk. |
end_line |
uintptr_t |
— | Zero-indexed row of the last byte actually included in this chunk (inclusive — the same row a Span.end_line would report for a node ending on that byte). Computed the same way regardless of whether the source has a trailing newline: it is always the row of end_byte - 1, never a phantom row past the file’s real content. |
metadata |
TS_PACKAlefHandle |
— | Contextual metadata about this chunk. |
TS_PACKCommentInfo
Section titled “TS_PACKCommentInfo”C representation: TS_PACKCommentInfo is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKCommentInfo does not appear anywhere in the generated header.
A comment extracted from source code.
| Field | Type | Default | Description |
|---|---|---|---|
text |
const char* |
— | The raw text content of the comment. |
kind |
TS_PACKAlefHandle |
TS_PACK_TS_PACK_LINE |
The kind of comment (line, block, or doc). |
span |
TS_PACKAlefHandle |
— | Source span covering the comment. |
associated_node |
const char* |
NULL |
Name of the syntax node this comment is directly associated with. |
TS_PACKDataAttribute
Section titled “TS_PACKDataAttribute”C representation: TS_PACKDataAttribute is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKDataAttribute does not appear anywhere in the generated header.
An XML-style attribute attached to an Element node.
Populated only for DataNodeKind.Element; always empty for KeyValue and
Sequence nodes.
| Field | Type | Default | Description |
|---|---|---|---|
name |
const char* |
— | Attribute name (e.g. "class", "href"). |
value |
const char* |
— | Attribute value as a raw string (quotes stripped). |
span |
TS_PACKAlefHandle |
— | Source span covering the entire name="value" attribute token. |
TS_PACKDataNode
Section titled “TS_PACKDataNode”C representation: TS_PACKDataNode is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKDataNode does not appear anywhere in the generated header.
A node in the hierarchical data tree produced by data-format extraction.
When ProcessConfig.data_extraction is
true, ProcessResult.data is populated with a root DataNode whose
children mirror the structure of the parsed file.
The kind field determines which other fields are meaningful:
kind |
key |
value |
attributes |
children |
|---|---|---|---|---|
KeyValue |
key / mapping key / index | leaf value | empty | nested map |
Element |
XML tag name | text content | XML attrs | child elements |
Sequence |
positional index ("0") |
leaf value | empty | sub-items |
| Field | Type | Default | Description |
|---|---|---|---|
kind |
TS_PACKAlefHandle |
TS_PACK_TS_PACK_KEY_VALUE |
Whether this node is a key/value pair, XML element, or sequence item. |
key |
const char* |
NULL |
Key, attribute name, tag name, or positional index ("0", "1", …). NULL at the document root. |
value |
const char* |
NULL |
Leaf scalar value, if any. NULL for containers (objects, arrays, XML elements with child elements). |
attributes |
TS_PACKAlefHandle* |
NULL |
Attributes on element-shape nodes (XML STag attributes). Empty for all other kinds. |
children |
TS_PACKAlefHandle* |
NULL |
Children for nested containers and XML element bodies. |
span |
TS_PACKAlefHandle |
— | Source span covering this node in the original source file. |
TS_PACKDiagnostic
Section titled “TS_PACKDiagnostic”C representation: TS_PACKDiagnostic is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKDiagnostic does not appear anywhere in the generated header.
A diagnostic (syntax error, missing node, etc.) from parsing.
| Field | Type | Default | Description |
|---|---|---|---|
message |
const char* |
— | Human-readable description of the diagnostic. |
severity |
TS_PACKAlefHandle |
TS_PACK_TS_PACK_ERROR |
Severity of the diagnostic. |
span |
TS_PACKAlefHandle |
— | Source span where the diagnostic was detected. |
TS_PACKDocSection
Section titled “TS_PACKDocSection”C representation: TS_PACKDocSection is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKDocSection does not appear anywhere in the generated header.
A section within a docstring (e.g., Args, Returns, Raises).
| Field | Type | Default | Description |
|---|---|---|---|
kind |
const char* |
— | Section kind (e.g., "args", "returns", "raises"). |
name |
const char* |
NULL |
Parameter or return value name, if applicable. |
description |
const char* |
— | Description text for this section. |
TS_PACKDocstringInfo
Section titled “TS_PACKDocstringInfo”C representation: TS_PACKDocstringInfo is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKDocstringInfo does not appear anywhere in the generated header.
A docstring extracted from source code.
| Field | Type | Default | Description |
|---|---|---|---|
text |
const char* |
— | The raw text of the docstring. |
format |
TS_PACKAlefHandle |
TS_PACK_TS_PACK_PYTHON_TRIPLE_QUOTE |
The docstring format (Python, JSDoc, Rustdoc, etc.). |
span |
TS_PACKAlefHandle |
— | Source span covering the docstring. |
associated_item |
const char* |
NULL |
Name of the item this docstring documents. |
parsed_sections |
TS_PACKAlefHandle* |
NULL |
Parsed sections of the docstring (Args, Returns, Raises, etc.). Reserved: not yet populated. Always empty, for every DocstringFormat. Parsing a docstring body into sections requires implementing each convention’s own layout (Google/NumPy/reST style for Python, @param/@returns for JSDoc/Javadoc, and so on), which no extractor here does yet. The field is kept rather than removed so a consumer’s deserializer does not need updating once it is. |
TS_PACKDownloadManager
Section titled “TS_PACKDownloadManager”C representation: TS_PACKDownloadManager is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKDownloadManager does not appear anywhere in the generated header.
Manages downloading and caching of pre-built parser shared libraries.
Methods
Section titled “Methods”ts_pack_download_manager_new()
Section titled “ts_pack_download_manager_new()”Create a new download manager for the given version.
Errors:
Returns Error.Download if version is empty, contains a path
separator or .., or contains a character outside [A-Za-z0-9.+-] — see
validate_version — or if no cache directory can be resolved (see
Self.default_cache_dir).
Signature:
TS_PACKAlefHandle ts_pack_download_manager_new(const char* version);Example:
TS_PACKAlefHandle result = ts_pack_download_manager_new("value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
version |
const char* |
Yes | The version |
Returns: TS_PACKAlefHandle
Errors: Returns the sentinel handle 0 on error.
ts_pack_download_manager_installed_languages()
Section titled “ts_pack_download_manager_installed_languages()”List languages that are already downloaded and cached.
Derived from the on-disk cache filenames, one canonical name per file, plus
every alias that resolves to it (via aliases_for) — so
this list agrees with the user-facing
LanguageRegistry.available_languages
about which names are “available”; both report "shell" once bash is
cached, for example. A previous version reported canonical names only,
which could never agree with available_languages(). See #107.
Returns an empty list if the cache directory does not exist. If it exists
but cannot be read (e.g. a permission error), also returns an empty list —
changing this to a Result would be a breaking change across every
language binding — but logs a tracing.warn! so the failure is not
silently indistinguishable from “nothing installed”.
Signature:
const char** ts_pack_download_manager_installed_languages(TS_PACKAlefHandle this);Example:
const char** result = ts_pack_download_manager_installed_languages(instance);Returns: const char**
ts_pack_download_manager_download_all_best_effort()
Section titled “ts_pack_download_manager_download_all_best_effort()”Download the platform bundle and extract every library file it contains.
Unlike Self.ensure_languages, this does not check the manifest language list
against archive contents — it simply extracts all .so/.dylib/.dll files
from the bundle. Languages in the manifest that are missing from the archive
are silently ignored rather than returning an error.
Returns the number of library files extracted (including those already cached).
Signature:
uintptr_t ts_pack_download_manager_download_all_best_effort(TS_PACKAlefHandle this);Example:
uintptr_t result = ts_pack_download_manager_download_all_best_effort(instance);Returns: uintptr_t
Errors: Returns 0 on error.
ts_pack_download_manager_clean_cache()
Section titled “ts_pack_download_manager_clean_cache()”Remove all cached parser libraries.
Acquires the cross-process lock so clean_cache cannot race a concurrent
downloader (avoids Windows sharing-violation errors against an in-flight
bundle write). The .download.lock file itself is not removed — it is
permanent infrastructure; deleting it could allow a concurrent process that
already opened the file to continue holding a stale lock handle while a new
process opens a fresh inode, breaking the mutual-exclusion guarantee.
Signature:
int32_t ts_pack_download_manager_clean_cache(TS_PACKAlefHandle this);Example:
ts_pack_download_manager_clean_cache(instance);Returns: int32_t status code – 0 on success, -1 on error.
Errors: Returns -1 on error.
TS_PACKExportInfo
Section titled “TS_PACKExportInfo”C representation: TS_PACKExportInfo is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKExportInfo does not appear anywhere in the generated header.
An export statement extracted from source code.
| Field | Type | Default | Description |
|---|---|---|---|
name |
const char* |
— | The exported name. |
kind |
TS_PACKAlefHandle |
TS_PACK_TS_PACK_NAMED |
The kind of export (named, default, or re-export). |
span |
TS_PACKAlefHandle |
— | Source span covering the export statement. |
TS_PACKFileMetrics
Section titled “TS_PACKFileMetrics”C representation: TS_PACKFileMetrics is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKFileMetrics does not appear anywhere in the generated header.
Aggregate metrics for a source file.
| Field | Type | Default | Description |
|---|---|---|---|
total_lines |
uintptr_t |
— | Total number of lines (including blank and comment lines). |
code_lines |
uintptr_t |
— | Number of lines containing non-blank, non-comment source code. |
comment_lines |
uintptr_t |
— | Number of lines that are entirely comments. |
blank_lines |
uintptr_t |
— | Number of blank (whitespace-only) lines. |
total_bytes |
uintptr_t |
— | Total byte length of the source file. |
node_count |
uintptr_t |
— | Total number of nodes in the syntax tree. |
error_count |
uintptr_t |
— | Number of error nodes in the syntax tree (parse errors). |
max_depth |
uintptr_t |
— | Maximum nesting depth reached in the syntax tree. |
TS_PACKImportInfo
Section titled “TS_PACKImportInfo”C representation: TS_PACKImportInfo is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKImportInfo does not appear anywhere in the generated header.
An import statement extracted from source code.
| Field | Type | Default | Description |
|---|---|---|---|
source |
const char* |
— | The module or path being imported from. |
items |
const char** |
NULL |
Specific names imported from the source module. For import a, b / from m import a, b, every entry’s base name (never the alias). For a JavaScript/TypeScript named-imports clause (import { a, b as c } from 'm'), every specifier’s original name. Populated for Python and JavaScript/TypeScript only. Always empty for every other language this library recognises import statements for — Rust, Go, Java, Kotlin, and Elixir (import/alias/require/use) — and for a JS/TS namespace import (import * as ns) or default import (import x from 'm'), neither of which names individual items. |
alias |
const char* |
NULL |
Alias assigned to the import (e.g., import numpy as np). Populated for Python’s single-name form (import numpy as np, from m import a as b) and JavaScript/TypeScript’s namespace form (import * as ns from 'm') or a named-imports clause naming exactly one specifier (import { a as b } from 'm'). NULL for Rust, Go, Java, Kotlin, and Elixir (which has its own as: alias option on alias directives, not yet extracted here) — and for a Python statement that aliases several names at once (import os, sys as s), where there is no single alias to report for the statement as a whole, so only items is populated for it. |
is_wildcard |
int32_t |
— | Whether this is a wildcard import (e.g., import * or use foo.*). Detected from the syntax tree — a dedicated wildcard node (wildcard_import in Python, use_wildcard in Rust) or a bare * token outside of string-literal content — not by searching the import’s source text for a * character, so a glob in an import path string (import a from './glob*.js') is not mistaken for one. |
span |
TS_PACKAlefHandle |
— | Source span covering the import statement. |
TS_PACKLanguage
Section titled “TS_PACKLanguage”C representation: TS_PACKLanguage is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKLanguage does not appear anywhere in the generated header.
TS_PACKLanguageRegistry
Section titled “TS_PACKLanguageRegistry”C representation: TS_PACKLanguageRegistry is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKLanguageRegistry does not appear anywhere in the generated header.
Thread-safe registry of tree-sitter language parsers.
Manages both statically compiled and dynamically loaded language grammars.
Use LanguageRegistry.new() for the default registry, or access the
global instance via the module-level convenience functions
(get_language, available_languages, etc.).
Methods
Section titled “Methods”ts_pack_language_registry_new()
Section titled “ts_pack_language_registry_new()”Create a new registry populated with all statically compiled languages.
When the dynamic-loading feature is enabled, the registry also knows
about dynamically loadable grammars and will load them on demand.
Signature:
TS_PACKAlefHandle ts_pack_language_registry_new();Example:
TS_PACKAlefHandle result = ts_pack_language_registry_new();Returns: TS_PACKAlefHandle
ts_pack_language_registry_get_language()
Section titled “ts_pack_language_registry_get_language()”Get a tree-sitter Language by name.
Resolves aliases (e.g., "shell" -> "bash", "makefile" -> "make"),
then looks up the language in the static table. When the dynamic-loading
feature is enabled, falls back to loading a shared library on demand.
Errors:
Returns Error.LanguageNotFound if the name (after alias resolution)
does not match any known grammar.
Signature:
TS_PACKAlefHandle ts_pack_language_registry_get_language(TS_PACKAlefHandle this, const char* name);Example:
TS_PACKAlefHandle result = ts_pack_language_registry_get_language(instance, "value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: TS_PACKAlefHandle
Errors: Returns the sentinel handle 0 on error.
ts_pack_language_registry_available_languages()
Section titled “ts_pack_language_registry_available_languages()”List all available language names, sorted and deduplicated.
Includes statically compiled languages, dynamically loadable languages
(if the dynamic-loading feature is enabled), and all configured aliases.
Signature:
const char** ts_pack_language_registry_available_languages(TS_PACKAlefHandle this);Example:
const char** result = ts_pack_language_registry_available_languages(instance);Returns: const char**
ts_pack_language_registry_has_parser()
Section titled “ts_pack_language_registry_has_parser()”Check whether this language can be parsed right now, without downloading.
Resolves aliases, then answers from exactly the lookup
get_language performs: the statically compiled
table, the already-loaded dynamic grammars, and the parser shared
libraries present in the primary and extra (download-cache) library
directories. It never performs network I/O.
A previous implementation consulted only the statically compiled table.
That table is empty in every build that does not set TSLP_LANGUAGES,
so the function answered false for languages this registry parses
perfectly well.
Contrast has_language, which is also true for a
grammar that is merely known to the manifest and would have to be
downloaded first. The pair distinguishes “we can parse it offline, now”
from “we recognise the name”.
The first true answer for a dynamic grammar loads its shared library:
loading is the only way to know the grammar is usable, since a truncated
or wrong-architecture library exists on disk but cannot parse. Loads are
cached process-wide, so repeat calls are cheap.
use tree_sitter_language_pack::{detect_language_from_extension, LanguageRegistry};
let registry = LanguageRegistry::new();// Extension detection uses the static ext table for all 371 grammars.let lang = detect_language_from_extension("feature"); // always returns Some("gherkin")// Parser availability depends on what is compiled in or cached on disk.let can_parse = lang.map(|name| registry.has_parser(name)).unwrap_or(false);Signature:
int32_t ts_pack_language_registry_has_parser(TS_PACKAlefHandle this, const char* name);Example:
int32_t result = ts_pack_language_registry_has_parser(instance, "value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: int32_t
ts_pack_language_registry_has_language()
Section titled “ts_pack_language_registry_has_language()”Check whether a language is available by name or alias.
Returns true if the language can be loaded, either from the static
table or from a dynamic library on disk.
Every branch is one more way to answer true, so they are ordered
cheapest-first and the filesystem is only consulted once every in-memory
source has said no. Probing the loaded-grammar map and the manifest ahead
of the stat calls is what keeps this off the syscall path for the
languages a process actually uses.
Signature:
int32_t ts_pack_language_registry_has_language(TS_PACKAlefHandle this, const char* name);Example:
int32_t result = ts_pack_language_registry_has_language(instance, "value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: int32_t
ts_pack_language_registry_language_count()
Section titled “ts_pack_language_registry_language_count()”Return the total number of available languages (including aliases).
Counts the same set available_languages
lists, without materialising or sorting it.
Signature:
uintptr_t ts_pack_language_registry_language_count(TS_PACKAlefHandle this);Example:
uintptr_t result = ts_pack_language_registry_language_count(instance);Returns: uintptr_t
ts_pack_language_registry_process()
Section titled “ts_pack_language_registry_process()”Parse source code and extract file intelligence based on config in a single pass.
Errors:
Returns Error.InvalidRange if the config is invalid (see
ProcessConfig.validate) or if the source
exceeds the configured
max_source_bytes;
Error.LanguageNotFound if the language is unknown; or
Error.ParseFailed if parsing produces no tree.
Signature:
TS_PACKAlefHandle ts_pack_language_registry_process(TS_PACKAlefHandle this, const char* source, TS_PACKAlefHandle config);Example:
TS_PACKAlefHandle result = ts_pack_language_registry_process(instance, "value", 0);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
source |
const char* |
Yes | The source |
config |
TS_PACKAlefHandle |
Yes | The configuration options |
Returns: TS_PACKAlefHandle
Errors: Returns the sentinel handle 0 on error.
TS_PACKNode
Section titled “TS_PACKNode”C representation: TS_PACKNode is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKNode does not appear anywhere in the generated header.
A single syntax node within a Tree.
Nodes hold a strong reference to their parent tree so they remain valid regardless of how the tree is moved or stored at the FFI boundary.
Methods
Section titled “Methods”ts_pack_node_kind()
Section titled “ts_pack_node_kind()”Return the node’s kind name (e.g. "function_definition").
Signature:
const char* ts_pack_node_kind(TS_PACKAlefHandle this);Example:
const char *result = ts_pack_node_kind(instance);Returns: const char*
ts_pack_node_kind_id()
Section titled “ts_pack_node_kind_id()”Return the node’s numeric kind ID.
Tree-sitter assigns a stable u16 ID to every node kind in a grammar
(e.g. "function_definition" → 42). Comparing kind_id() is cheaper
than comparing the string kind() in tight AST loops.
Signature:
uint16_t ts_pack_node_kind_id(TS_PACKAlefHandle this);Example:
uint16_t result = ts_pack_node_kind_id(instance);Returns: uint16_t
ts_pack_node_start_byte()
Section titled “ts_pack_node_start_byte()”Return the inclusive start byte offset of this node.
Signature:
uintptr_t ts_pack_node_start_byte(TS_PACKAlefHandle this);Example:
uintptr_t result = ts_pack_node_start_byte(instance);Returns: uintptr_t
ts_pack_node_end_byte()
Section titled “ts_pack_node_end_byte()”Return the exclusive end byte offset of this node.
Signature:
uintptr_t ts_pack_node_end_byte(TS_PACKAlefHandle this);Example:
uintptr_t result = ts_pack_node_end_byte(instance);Returns: uintptr_t
ts_pack_node_byte_range()
Section titled “ts_pack_node_byte_range()”Return the node’s byte range as a ByteRange.
Callers should slice their own source bytes — this is a zero-copy text accessor.
Signature:
TS_PACKAlefHandle ts_pack_node_byte_range(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_node_byte_range(instance);Returns: TS_PACKAlefHandle
ts_pack_node_start_position()
Section titled “ts_pack_node_start_position()”Return the start Point (row, column).
Signature:
TS_PACKAlefHandle ts_pack_node_start_position(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_node_start_position(instance);Returns: TS_PACKAlefHandle
ts_pack_node_end_position()
Section titled “ts_pack_node_end_position()”Return the end Point (row, column).
Signature:
TS_PACKAlefHandle ts_pack_node_end_position(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_node_end_position(instance);Returns: TS_PACKAlefHandle
ts_pack_node_is_named()
Section titled “ts_pack_node_is_named()”True when this node is named (not punctuation/whitespace).
Signature:
int32_t ts_pack_node_is_named(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_node_is_named(instance);Returns: int32_t
ts_pack_node_is_error()
Section titled “ts_pack_node_is_error()”True when this is an error node.
Signature:
int32_t ts_pack_node_is_error(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_node_is_error(instance);Returns: int32_t
ts_pack_node_is_missing()
Section titled “ts_pack_node_is_missing()”True when this is a missing-token node.
Signature:
int32_t ts_pack_node_is_missing(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_node_is_missing(instance);Returns: int32_t
ts_pack_node_is_extra()
Section titled “ts_pack_node_is_extra()”True when this is an “extra” node (e.g. a comment).
Signature:
int32_t ts_pack_node_is_extra(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_node_is_extra(instance);Returns: int32_t
ts_pack_node_has_error()
Section titled “ts_pack_node_has_error()”True when this node or any descendant is an error.
Signature:
int32_t ts_pack_node_has_error(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_node_has_error(instance);Returns: int32_t
ts_pack_node_parent()
Section titled “ts_pack_node_parent()”Return this node’s parent, if any.
Signature:
TS_PACKAlefHandle ts_pack_node_parent(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_node_parent(instance);Returns: TS_PACKAlefHandle
ts_pack_node_child()
Section titled “ts_pack_node_child()”Return the i-th child of this node, if any.
Signature:
TS_PACKAlefHandle ts_pack_node_child(TS_PACKAlefHandle this, uint32_t index);Example:
TS_PACKAlefHandle result = ts_pack_node_child(instance, 42);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
index |
uint32_t |
Yes | The index |
Returns: TS_PACKAlefHandle
ts_pack_node_child_count()
Section titled “ts_pack_node_child_count()”Total number of children (including unnamed).
Signature:
uintptr_t ts_pack_node_child_count(TS_PACKAlefHandle this);Example:
uintptr_t result = ts_pack_node_child_count(instance);Returns: uintptr_t
ts_pack_node_named_child()
Section titled “ts_pack_node_named_child()”Return the i-th named child of this node, if any.
Signature:
TS_PACKAlefHandle ts_pack_node_named_child(TS_PACKAlefHandle this, uint32_t index);Example:
TS_PACKAlefHandle result = ts_pack_node_named_child(instance, 42);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
index |
uint32_t |
Yes | The index |
Returns: TS_PACKAlefHandle
ts_pack_node_named_child_count()
Section titled “ts_pack_node_named_child_count()”Number of named children of this node.
Signature:
uintptr_t ts_pack_node_named_child_count(TS_PACKAlefHandle this);Example:
uintptr_t result = ts_pack_node_named_child_count(instance);Returns: uintptr_t
ts_pack_node_child_by_field_name()
Section titled “ts_pack_node_child_by_field_name()”Look up a child by its grammar-defined field name.
Signature:
TS_PACKAlefHandle ts_pack_node_child_by_field_name(TS_PACKAlefHandle this, const char* name);Example:
TS_PACKAlefHandle result = ts_pack_node_child_by_field_name(instance, "value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: TS_PACKAlefHandle
ts_pack_node_to_sexp()
Section titled “ts_pack_node_to_sexp()”Return the S-expression form of this node’s subtree.
Signature:
const char* ts_pack_node_to_sexp(TS_PACKAlefHandle this);Example:
const char *result = ts_pack_node_to_sexp(instance);Returns: const char*
ts_pack_node_walk()
Section titled “ts_pack_node_walk()”Return a TreeCursor positioned at this node.
Signature:
TS_PACKAlefHandle ts_pack_node_walk(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_node_walk(instance);Returns: TS_PACKAlefHandle
TS_PACKPackConfig
Section titled “TS_PACKPackConfig”C representation: TS_PACKPackConfig is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKPackConfig does not appear anywhere in the generated header.
Configuration for the tree-sitter language pack.
Controls cache directory and which languages to pre-download. Can be loaded from a TOML file, constructed programmatically, or passed as a dict/object from language bindings.
| Field | Type | Default | Description |
|---|---|---|---|
cache_dir |
const char* |
NULL |
Override the BASE directory the parser cache lives under. This is a base, not the final library path: the crate appends tree-sitter-language-pack/v{version}/libs to it, exactly as it does to the platform default. So cache_dir = "/tmp/my-parsers" resolves to /tmp/my-parsers/tree-sitter-language-pack/v{version}/libs/. The suffix is not cosmetic. It keeps the whole cache tree — manifest, bundles and lock file included — inside a directory this library owns and versions. Earlier releases used this path verbatim, which put those files in the configured directory’s PARENT and let a cache built by one crate version be reused by another. Default base: the platform cache dir, e.g. ~/.cache on Linux. |
languages |
const char** |
NULL |
Languages to pre-download on init. Each entry is a language name (e.g. "python", "rust"). |
groups |
const char** |
NULL |
Language groups to pre-download. Group names come from the remote manifest, so the valid set is not fixed by this library; the published manifest currently defines only "all". Call manifest_groups to enumerate them. An unknown name makes init fail. |
TS_PACKParser
Section titled “TS_PACKParser”C representation: TS_PACKParser is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKParser does not appear anywhere in the generated header.
A tree-sitter parser configured for one language at a time.
Methods
Section titled “Methods”ts_pack_parser_new()
Section titled “ts_pack_parser_new()”Construct a new parser with no language set and no parse limits.
Call Parser.set_language before parsing. Limits are opt-in via
set_max_source_bytes and
set_parse_timeout_ms; both default to
unbounded so that existing callers are unaffected.
Signature:
TS_PACKAlefHandle ts_pack_parser_new();Example:
TS_PACKAlefHandle result = ts_pack_parser_new();Returns: TS_PACKAlefHandle
ts_pack_parser_set_max_source_bytes()
Section titled “ts_pack_parser_set_max_source_bytes()”Refuse to parse sources longer than max_bytes.
NULL (the default) means no limit. Over-limit input makes
parse and parse_bytes return
NULL after emitting a WARN; input is never silently truncated.
See RECOMMENDED_MAX_SOURCE_BYTES.
Signature:
void ts_pack_parser_set_max_source_bytes(TS_PACKAlefHandle this, uintptr_t max_bytes);Example:
ts_pack_parser_set_max_source_bytes(instance, 42);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
max_bytes |
uintptr_t* |
No | The max bytes |
Returns: No return value.
ts_pack_parser_set_parse_timeout_ms()
Section titled “ts_pack_parser_set_parse_timeout_ms()”Cancel a parse that exceeds timeout_ms milliseconds of wall clock.
NULL (the default) means no budget. Cancellation runs through
tree-sitter’s parse progress callback, so it is granular to that
callback’s interval rather than exact.
See RECOMMENDED_PARSE_TIMEOUT_MS.
Signature:
void ts_pack_parser_set_parse_timeout_ms(TS_PACKAlefHandle this, uint64_t timeout_ms);Example:
ts_pack_parser_set_parse_timeout_ms(instance, 42);Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
timeout_ms |
uint64_t* |
No | The timeout ms |
Returns: No return value.
ts_pack_parser_set_language()
Section titled “ts_pack_parser_set_language()”Configure the parser to use the language identified by name (e.g. "python").
Resolves the language through the global registry — auto-downloading
if necessary, when the download feature is enabled.
Errors:
Returns Error.LanguageNotFound if the language is not recognized,
or Error.ParserSetup if the language ABI is incompatible.
Signature:
int32_t ts_pack_parser_set_language(TS_PACKAlefHandle this, const char* name);Example:
ts_pack_parser_set_language(instance, "value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name |
const char* |
Yes | The name |
Returns: int32_t status code – 0 on success, -1 on error.
Errors: Returns -1 on error.
ts_pack_parser_parse()
Section titled “ts_pack_parser_parse()”Parse a UTF-8 source string.
Returns NULL if no language is set, if the parse was cancelled by the
configured timeout, or if the source
exceeds the configured size limit. Each
non-parse outcome is logged, so an empty result is never silent.
Concurrency
Section titled “Concurrency”Parsing runs fully in parallel across threads for almost every language — no lock is
taken. The exception is the small set of grammars whose external scanner keeps mutable
process-global state (currently just properties): parses of that language are
serialized against each other through an internal per-language lock, so that concurrent
threads can’t corrupt shared scanner state. Every other language is unaffected by that
lock and never waits on it.
Signature:
TS_PACKAlefHandle ts_pack_parser_parse(TS_PACKAlefHandle this, const char* source);Example:
TS_PACKAlefHandle result = ts_pack_parser_parse(instance, "value");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
source |
const char* |
Yes | The source |
Returns: TS_PACKAlefHandle
ts_pack_parser_parse_bytes()
Section titled “ts_pack_parser_parse_bytes()”Parse a raw byte slice.
Same outcomes as parse, including the concurrency behaviour documented
there.
Signature:
TS_PACKAlefHandle ts_pack_parser_parse_bytes(TS_PACKAlefHandle this, const uint8_t* source);Example:
TS_PACKAlefHandle result = ts_pack_parser_parse_bytes(instance, (const uint8_t *)"data");Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
source |
const uint8_t* |
Yes | The source |
Returns: TS_PACKAlefHandle
ts_pack_parser_reset()
Section titled “ts_pack_parser_reset()”Reset internal state. The next call to parse will
not be incremental.
Signature:
void ts_pack_parser_reset(TS_PACKAlefHandle this);Example:
ts_pack_parser_reset(instance);Returns: No return value.
TS_PACKPoint
Section titled “TS_PACKPoint”C representation: TS_PACKPoint is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKPoint does not appear anywhere in the generated header.
A source position — row + column, zero-indexed.
| Field | Type | Default | Description |
|---|---|---|---|
row |
uintptr_t |
— | Zero-indexed row number. |
column |
uintptr_t |
— | Zero-indexed column, counted in bytes from the start of the row. This is tree_sitter.Point.column verbatim, and tree-sitter defines it as a byte offset — not characters, and not UTF-16 code units. Measured on a row of the form x = '<c>' where <c> is a single 4-byte character (an emoji), the string node reports columns 4..10, identical to its byte range; the character columns would be 4..7 and the UTF-16 columns 4..8. Anything that builds LSP positions (UTF-16) or editor caret columns (characters) from this field is silently wrong on every row containing a non-ASCII byte, and must re-measure the row against the source text instead. Earlier releases documented this field as UTF-16 code units; that was never what the value contained. |
TS_PACKProcessConfig
Section titled “TS_PACKProcessConfig”C representation: TS_PACKProcessConfig is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKProcessConfig does not appear anywhere in the generated header.
Configuration for the process() function.
Controls which analysis features are enabled and whether chunking is performed.
| Field | Type | Default | Description |
|---|---|---|---|
language |
const char* |
"" |
Language name (required). |
structure |
int32_t |
true |
Extract structural items (functions, classes, etc.). Default: true. |
imports |
int32_t |
true |
Extract import statements. Default: true. |
exports |
int32_t |
true |
Extract export statements. Default: true. |
comments |
int32_t |
false |
Extract comments. Default: false. |
docstrings |
int32_t |
false |
Extract docstrings. Default: false. |
symbols |
int32_t |
false |
Extract symbol definitions. Default: false. |
diagnostics |
int32_t |
false |
Include parse diagnostics. Default: false. |
chunk_max_size |
uintptr_t* |
NULL |
Maximum chunk size in bytes. NULL disables chunking. Some(0) is rejected by ProcessConfig.validate with Error.InvalidRange. A zero-sized chunk limit previously produced an empty chunk list and silently discarded the whole source; use NULL to mean “do not chunk”. |
data_extraction |
int32_t |
false |
Extract hierarchical key/value data tree from data-format files. Default: false. When true, ProcessResult.data is populated with a DataNode tree for supported languages: JSON, YAML, TOML, .properties, HCL/HOCON, INI, editorconfig, KDL, CUE, CSV, PSV, PO, nginx config, Caddy config, XML, and DTD. For languages outside this set the field is left as NULL. |
max_source_bytes |
uintptr_t* |
NULL |
Reject source longer than this many bytes instead of parsing it. Default: NULL (unbounded). Tree-sitter allocates and walks proportionally to input size, so an unbounded parse of attacker-supplied input is a denial-of-service vector. The default stays unbounded for backward compatibility; services handling untrusted input should opt in, e.g. with RECOMMENDED_MAX_SOURCE_BYTES. Exceeding the limit fails the call with Error.InvalidRange — the source is never silently truncated. |
parse_timeout_ms |
uint64_t* |
NULL |
Wall-clock budget for the parse step, in milliseconds. Default: NULL (no timeout). Enforced through tree-sitter’s parse progress callback, which the parser invokes periodically; cancellation is therefore granular to that callback interval rather than exact. A parse that exceeds the budget fails with Error.ParseTimeout. |
TS_PACKProcessResult
Section titled “TS_PACKProcessResult”C representation: TS_PACKProcessResult is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKProcessResult does not appear anywhere in the generated header.
Complete analysis result from processing a source file.
Contains metrics, structural analysis, imports/exports, comments,
docstrings, symbols, diagnostics, and optionally chunked code segments.
Fields are populated based on the ProcessConfig flags.
| Field | Type | Default | Description |
|---|---|---|---|
language |
const char* |
— | The language name used to parse the source file. |
metrics |
TS_PACKAlefHandle |
— | File-level metrics (line counts, byte size, error count). |
structure |
TS_PACKAlefHandle* |
NULL |
Top-level structural items (functions, classes, etc.). |
imports |
TS_PACKAlefHandle* |
NULL |
Import statements extracted from the source. |
exports |
TS_PACKAlefHandle* |
NULL |
Export statements extracted from the source. |
comments |
TS_PACKAlefHandle* |
NULL |
Comments extracted from the source. |
docstrings |
TS_PACKAlefHandle* |
NULL |
Docstrings extracted from the source. |
symbols |
TS_PACKAlefHandle* |
NULL |
Symbol definitions (variables, types, functions) extracted from the source. |
diagnostics |
TS_PACKAlefHandle* |
NULL |
Parse diagnostics (syntax errors, missing nodes) from tree-sitter. |
chunks |
TS_PACKAlefHandle* |
NULL |
Syntax-aware code chunks produced when chunking is enabled. |
data |
TS_PACKAlefHandle |
NULL |
Hierarchical data tree extracted when config.data_extraction is true. Populated for supported data-format languages (JSON, YAML, TOML, properties, HCL, INI, XML, CSV, and more). NULL when data_extraction is false (the default) or when the language is not a recognised data format. See DataNode for the shape of the returned tree. |
TS_PACKSpan
Section titled “TS_PACKSpan”C representation: TS_PACKSpan is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKSpan does not appear anywhere in the generated header.
Byte and line/column range in source code.
Represents both byte offsets (for slicing) and human-readable line/column positions (for display and diagnostics).
| Field | Type | Default | Description |
|---|---|---|---|
start_byte |
uintptr_t |
— | Inclusive start byte offset in the source. |
end_byte |
uintptr_t |
— | Exclusive end byte offset in the source. |
start_line |
uintptr_t |
— | Zero-indexed line number of the span’s start. |
start_column |
uintptr_t |
— | Zero-indexed column of the span’s start, counted in bytes from the start of the line — not characters, not UTF-16 code units. |
end_line |
uintptr_t |
— | Zero-indexed line number of the span’s end. |
end_column |
uintptr_t |
— | Zero-indexed column of the span’s end, counted in bytes from the start of the line — not characters, not UTF-16 code units. |
TS_PACKStructureItem
Section titled “TS_PACKStructureItem”C representation: TS_PACKStructureItem is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKStructureItem does not appear anywhere in the generated header.
A structural item (function, class, struct, etc.) in source code.
| Field | Type | Default | Description |
|---|---|---|---|
kind |
TS_PACKAlefHandle |
TS_PACK_TS_PACK_FUNCTION |
The kind of structural item. |
name |
const char* |
NULL |
The declared name of the item, if present. |
visibility |
const char* |
NULL |
Visibility modifier (e.g., "pub", "public", "private"). |
span |
TS_PACKAlefHandle |
— | Source span covering the entire item declaration. |
children |
TS_PACKAlefHandle* |
NULL |
Nested structural items (e.g., methods within a class). |
decorators |
const char** |
NULL |
Decorator or attribute names applied to the item. Reserved: not yet populated. Always empty, for every language. Recognising a decorator requires per-language grammar knowledge (a Python decorated_definition wrapper, Java/C# annotations, Rust attributes each have a different shape), which no extractor here implements yet. The field is kept rather than removed so a consumer’s deserializer does not need updating once it is. |
doc_comment |
const char* |
NULL |
Documentation comment attached to the item, if any. The text of the comment (or run of comments) immediately preceding the item, with no blank line in between, when that comment is classified as a doc comment. Multiple adjacent single-line doc comments (Rust ///) are joined with \n in source order. Populated for Rust (//////!), Java (/** */), and JavaScript/ TypeScript (/** */). NULL for every other language, and for a preceding comment that is not in doc-comment form (a plain # comment in Python, Ruby, or Elixir) — Python’s docstring convention is captured separately, as DocstringInfo, not through this field. |
signature |
const char* |
NULL |
Full signature text of the item (e.g., function parameters and return type). The item’s own source text from its start up to the start of its body (see StructureItem.body_span), trimmed of trailing whitespace — for example fn add(a: i32, b: i32) -> i32 for a Rust function whose body is { a + b }. NULL only when that text is empty, which does not happen for any item StructureKind currently reports. Populated for every language and kind this library extracts structure for, since it is derived from body_span’s boundary rather than per-language syntax. |
body_span |
TS_PACKAlefHandle |
NULL |
Source span covering only the body of the item, if distinct from the declaration. |
TS_PACKSymbolInfo
Section titled “TS_PACKSymbolInfo”C representation: TS_PACKSymbolInfo is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKSymbolInfo does not appear anywhere in the generated header.
A symbol (variable, function, type, etc.) extracted from source code.
| Field | Type | Default | Description |
|---|---|---|---|
name |
const char* |
— | The name of the symbol. |
kind |
TS_PACKAlefHandle |
TS_PACK_TS_PACK_VARIABLE |
The kind of symbol (variable, function, class, etc.). |
span |
TS_PACKAlefHandle |
— | Source span covering the symbol definition. |
type_annotation |
const char* |
NULL |
Explicit type annotation, if present in the source. |
doc |
const char* |
NULL |
Documentation comment immediately preceding this symbol, resolved by the same walk StructureItem.doc_comment uses (see doc_comment_at) — never hard-coded NULL. Populated for Rust (//////!), Java (/** */), and JavaScript/ TypeScript (/** */) — the languages whose comment classification recognizes a doc-kind comment. NULL for every other language (e.g. Python, Go, Ruby, which have no doc-kind comment classification), and also NULL when a symbol in a supported language simply has no doc comment immediately above it. |
TS_PACKTree
Section titled “TS_PACKTree”C representation: TS_PACKTree is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKTree does not appear anywhere in the generated header.
A parsed syntax tree. Cheap to clone (refcount bump).
Methods
Section titled “Methods”ts_pack_tree_root_node()
Section titled “ts_pack_tree_root_node()”Return the root Node of this tree.
Signature:
TS_PACKAlefHandle ts_pack_tree_root_node(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_tree_root_node(instance);Returns: TS_PACKAlefHandle
ts_pack_tree_walk()
Section titled “ts_pack_tree_walk()”Return a TreeCursor positioned at the root.
Signature:
TS_PACKAlefHandle ts_pack_tree_walk(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_tree_walk(instance);Returns: TS_PACKAlefHandle
TS_PACKTreeCursor
Section titled “TS_PACKTreeCursor”C representation: TS_PACKTreeCursor is a documentation-only name for this type. The C ABI hands you a scalar TS_PACKAlefHandle handle – the literal string TS_PACKTreeCursor does not appear anywhere in the generated header.
A cursor for traversing a Tree.
Methods
Section titled “Methods”ts_pack_tree_cursor_node()
Section titled “ts_pack_tree_cursor_node()”Return the Node at the cursor’s current position.
Signature:
TS_PACKAlefHandle ts_pack_tree_cursor_node(TS_PACKAlefHandle this);Example:
TS_PACKAlefHandle result = ts_pack_tree_cursor_node(instance);Returns: TS_PACKAlefHandle
ts_pack_tree_cursor_goto_first_child()
Section titled “ts_pack_tree_cursor_goto_first_child()”Move the cursor to the first child of the current node.
Returns true if a child existed.
Signature:
int32_t ts_pack_tree_cursor_goto_first_child(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_tree_cursor_goto_first_child(instance);Returns: int32_t
ts_pack_tree_cursor_goto_parent()
Section titled “ts_pack_tree_cursor_goto_parent()”Move the cursor to the parent of the current node.
Returns true if a parent existed.
Signature:
int32_t ts_pack_tree_cursor_goto_parent(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_tree_cursor_goto_parent(instance);Returns: int32_t
ts_pack_tree_cursor_goto_next_sibling()
Section titled “ts_pack_tree_cursor_goto_next_sibling()”Move the cursor to the next sibling of the current node.
Returns true if a sibling existed.
Signature:
int32_t ts_pack_tree_cursor_goto_next_sibling(TS_PACKAlefHandle this);Example:
int32_t result = ts_pack_tree_cursor_goto_next_sibling(instance);Returns: int32_t
ts_pack_tree_cursor_field_name()
Section titled “ts_pack_tree_cursor_field_name()”Return the field name for the current node, if any.
Signature:
const char* ts_pack_tree_cursor_field_name(TS_PACKAlefHandle this);Example:
const char* result = ts_pack_tree_cursor_field_name(instance);Returns: const char*
TS_PACKDataNodeKind
Section titled “TS_PACKDataNodeKind”The kind of a data node extracted from a data-format file.
Classifies each node in the hierarchical DataNode tree returned when
data_extraction is enabled on ProcessConfig.
Wire format (public JSON contract)
Section titled “Wire format (public JSON contract)”Unit variants serialize as a bare string ("KeyValue"). DO NOT add
#[serde(tag = "...")] or rename variants — every language binding has a
hand-written deserializer matching this exact shape, and any change breaks
all bindings’ process() tests simultaneously.
Covered by tests/wire_format.rs.
| Value | Description |
|---|---|
TS_PACK_KEY_VALUE |
A key/value pair or mapping (json/toml/properties/yaml/hcl/cue/kdl pair, or a wrapper “object”/“mapping” container). |
TS_PACK_ELEMENT |
An XML element with a tag name in key and attributes in attributes. |
TS_PACK_SEQUENCE |
A positional sequence item (JSON array element, YAML block sequence item, CSV/PSV row or cell). |
TS_PACKStructureKind
Section titled “TS_PACKStructureKind”The kind of structural item found in source code.
Categorizes top-level and nested declarations such as functions, classes,
structs, enums, traits, and more. Use Other for
language-specific constructs that do not fit a standard category.
Wire format (public JSON contract)
Section titled “Wire format (public JSON contract)”Unit variants serialize as a bare string ("Function"); the Other
variant serializes as a single-keyed object ({"Other": "macro"}). DO
NOT add #[serde(tag = "...")] or rename variants — every language
binding has a hand-written deserializer matching this exact shape, and
any change breaks all bindings’ process() tests simultaneously.
Covered by tests/wire_format.rs.
| Value | Description |
|---|---|
TS_PACK_FUNCTION |
A free-standing or associated function. |
TS_PACK_METHOD |
A method defined inside a class, struct, trait, or impl block. |
TS_PACK_CLASS |
A class definition. |
TS_PACK_STRUCT |
A struct definition. |
TS_PACK_INTERFACE |
An interface or protocol definition. |
TS_PACK_ENUM |
An enum definition. |
TS_PACK_MODULE |
A module or package declaration. |
TS_PACK_TRAIT |
A trait definition. |
TS_PACK_IMPL |
An impl block (Rust) or similar implementation block. |
TS_PACK_NAMESPACE |
A namespace declaration. |
TS_PACK_OTHER |
A language-specific construct that does not fit any standard category. — Fields: 0: const char* |
TS_PACKCommentKind
Section titled “TS_PACKCommentKind”The kind of a comment found in source code.
Distinguishes between single-line comments, block (multi-line) comments, and documentation comments.
| Value | Description |
|---|---|
TS_PACK_LINE |
A single-line comment (e.g., // ... or # ...). |
TS_PACK_BLOCK |
A block or multi-line comment using slash-star delimiters. |
TS_PACK_DOC |
A documentation comment such as /// ... or slash-double-star block. |
TS_PACKDocstringFormat
Section titled “TS_PACKDocstringFormat”The format of a docstring extracted from source code.
Identifies the docstring convention used, which varies by language
(e.g., Python triple-quoted strings, JSDoc, Rustdoc /// comments).
Wire format (public JSON contract)
Section titled “Wire format (public JSON contract)”Unit variants serialize as a bare string ("JSDoc"); the Other
variant serializes as a single-keyed object ({"Other": "rst"}). DO
NOT add #[serde(tag = "...")]. Covered by tests/wire_format.rs.
| Value | Description |
|---|---|
TS_PACK_PYTHON_TRIPLE_QUOTE |
Python triple-quoted string docstring ("""..."""). |
TS_PACK_JS_DOC |
JavaScript/TypeScript JSDoc block comment (opens with two stars, closes with star-slash). |
TS_PACK_RUSTDOC |
Rust /// or //! doc comment. |
TS_PACK_GO_DOC |
Go doc comment (a comment block immediately preceding a declaration). |
TS_PACK_JAVA_DOC |
Java Javadoc block comment (opens with two stars, closes with star-slash). |
TS_PACK_OTHER |
A language-specific docstring format not covered by the standard variants. — Fields: 0: const char* |
TS_PACKExportKind
Section titled “TS_PACKExportKind”The kind of an export statement found in source code.
Covers named exports, default exports, and re-exports from other modules.
| Value | Description |
|---|---|
TS_PACK_NAMED |
A named export (e.g., export { foo }). |
TS_PACK_DEFAULT |
A default export (e.g., export default foo). |
TS_PACK_RE_EXPORT |
A re-export from another module (e.g., export { foo } from 'bar'). |
TS_PACKSymbolKind
Section titled “TS_PACKSymbolKind”The kind of a symbol definition found in source code.
Categorizes symbol definitions such as variables, constants, functions, classes, types, interfaces, enums, and modules.
Wire format (public JSON contract)
Section titled “Wire format (public JSON contract)”Unit variants serialize as a bare string ("Function"); the Other
variant serializes as a single-keyed object ({"Other": "macro"}). DO
NOT add #[serde(tag = "...")]. Covered by tests/wire_format.rs.
| Value | Description |
|---|---|
TS_PACK_VARIABLE |
A variable binding. |
TS_PACK_CONSTANT |
A constant (immutable binding). |
TS_PACK_FUNCTION |
A function definition. |
TS_PACK_CLASS |
A class definition. |
TS_PACK_TYPE |
A type alias or typedef. |
TS_PACK_INTERFACE |
An interface definition. |
TS_PACK_ENUM |
An enum definition. |
TS_PACK_MODULE |
A module declaration. |
TS_PACK_OTHER |
A symbol kind not covered by the standard variants. — Fields: 0: const char* |
TS_PACKDiagnosticSeverity
Section titled “TS_PACKDiagnosticSeverity”Severity level of a diagnostic produced during parsing.
Used to classify parse errors, warnings, and informational messages found in the syntax tree.
| Value | Description |
|---|---|
TS_PACK_ERROR |
A parse error (e.g., an ERROR or MISSING node in the tree). |
TS_PACK_WARNING |
A warning-level diagnostic. |
TS_PACK_INFO |
An informational diagnostic. |
Errors
Section titled “Errors”TS_PACKError
Section titled “TS_PACKError”Errors that can occur when using the tree-sitter language pack.
Covers language lookup failures, parse errors, query errors, and I/O issues.
Feature-gated variants are included when config, download, or related
features are enabled.
Matching on Error
Section titled “Matching on Error”The set of variants is not stable: new failure modes are added in minor
releases, and Io, Json, and Toml exist only under certain feature
combinations, so the variant set a downstream crate sees depends on which
features it enables. Downstream matches must therefore carry a _ arm;
#[non_exhaustive] makes the compiler enforce that instead of letting a
feature change silently break a build.
C ABI error codes
Section titled “C ABI error codes”Each variant alef can see carries an explicit alef(error_code = N)
allocation that becomes a member of the generated AlefFfiErrorCode C enum.
These numbers are a public ABI contract: an allocated number is never
reused after its variant is removed, and a variant’s number never changes,
because C callers compare against the value, not the name. New variants take
the next free number. 0-4 are reserved by alef, so allocation starts at 100.
An unannotated variant is emitted as the unknown code rather than as itself,
which silently flattens the taxonomy — annotate every new variant.
| Variant | Description |
|---|---|
TS_PACK_LANGUAGE_NOT_FOUND |
The requested language name (or alias) was not found in the registry. |
TS_PACK_DYNAMIC_LOAD |
A dynamic shared library could not be loaded at runtime. |
TS_PACK_NULL_LANGUAGE_POINTER |
The tree-sitter language function returned a null pointer for the given language name. |
TS_PACK_PARSER_SETUP |
The language could not be applied to the parser (e.g., ABI version mismatch). |
TS_PACK_LOCK_POISONED |
An internal RwLock or Mutex was poisoned by a previous panic. |
TS_PACK_CONFIG |
A configuration file or value was invalid or could not be applied. |
TS_PACK_PARSE_FAILED |
The tree-sitter parser returned no tree for the given source input. |
TS_PACK_PARSE_TIMEOUT |
The parse was cancelled because it exceeded its configured wall-clock budget. Raised only when a budget is configured — see ProcessConfig.parse_timeout_ms, which defaults to NULL. |
TS_PACK_QUERY_ERROR |
A tree-sitter query could not be compiled or executed. |
TS_PACK_INVALID_RANGE |
A byte range was invalid (e.g., end before start, or out of bounds). |
TS_PACK_DOWNLOAD |
A parser download from GitHub releases failed. |
TS_PACK_CHECKSUM_MISMATCH |
The downloaded file’s SHA-256 digest did not match the manifest’s expected value. |
TS_PACK_CACHE_LOCK |
The cross-process download cache lock file could not be acquired or created. |