Rust API Reference

Rust API Reference v1.8.1¶

Functions¶

detect_language_from_extension()¶

Detect language name from a file extension (without leading dot).

Returns None for unrecognized extensions. The match is case-insensitive.

Signature:

pub fn detect_language_from_extension(ext: &str) -> Option<String>

Returns: Option<String>

detect_language_from_path()¶

Detect language name from a file path.

Extracts the file extension and looks it up. Returns None if the path has no extension or the extension is not recognized.

Signature:

pub fn detect_language_from_path(path: &str) -> Option<String>

Returns: Option<String>

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.

Returns None when content does not start with #!, the shebang is malformed, or the interpreter is not recognised.

Signature:

pub fn detect_language_from_content(content: &str) -> Option<String>

Returns: Option<String>

get_highlights_query()¶

Get the highlights query for a language, if bundled.

Returns the contents of highlights.scm as a static string, or None if no highlights query is bundled for this language.

Signature:

pub fn get_highlights_query(language: &str) -> Option<String>

Returns: Option<String>

get_injections_query()¶

Get the injections query for a language, if bundled.

Returns the contents of injections.scm as a static string, or None if no injections query is bundled for this language.

Signature:

pub fn get_injections_query(language: &str) -> Option<String>

Returns: Option<String>

get_locals_query()¶

Get the locals query for a language, if bundled.

Returns the contents of locals.scm as a static string, or None if no locals query is bundled for this language.

Signature:

pub fn get_locals_query(language: &str) -> Option<String>

Returns: Option<String>

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:

pub fn get_language(name: &str) -> Result<Language, Error>

Returns: Language Errors: Returns Err(Error).

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:

pub fn get_parser(name: &str) -> Result<Parser, Error>

Returns: Parser Errors: Returns Err(Error).

detect_language()¶

Detect language name from a file path or extension.

This compatibility alias matches the pre-Alef Python binding API.

Signature:

pub fn detect_language(path: &str) -> Option<String>

Returns: Option<String>

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:

pub fn available_languages() -> Vec<String>

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:

pub fn has_language(name: &str) -> bool

Returns: bool

language_count()¶

Return the number of available languages.

Includes statically compiled languages, dynamically loadable languages, and aliases.

Signature:

pub fn language_count() -> usize

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 an error if the language is not found or parsing fails.

Signature:

pub fn process(source: &str, config: ProcessConfig) -> Result<ProcessResult, Error>

Returns: ProcessResult Errors: Returns Err(Error).

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:

pub fn init(config: PackConfig) -> Result<(), Error>

Returns: () Errors: Returns Err(Error).

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.

Errors:

Returns an error if the lock cannot be acquired.

Signature:

pub fn configure(config: PackConfig) -> Result<(), Error>

Returns: () Errors: Returns Err(Error).

download()¶

Download specific languages to the local cache.

Returns the number of requested languages available after the call. Already compiled or cached languages are included in the count.

Errors:

Returns an error if any language is not available in the manifest or if the download fails.

Signature:

pub fn download(names: Vec<String>) -> Result<usize, Error>

Returns: usize Errors: Returns Err(Error).

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:

pub fn download_all() -> Result<usize, Error>

manifest_languages()¶

Return all language names available in the remote manifest (305).

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:

pub fn manifest_languages() -> Result<Vec<String>, Error>

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:

pub fn downloaded_languages() -> Vec<String>

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:

pub fn clean_cache() -> Result<(), Error>

cache_dir()¶

Return the effective cache directory path.

This is either the custom path set via configure / init or the default: ~/.cache/tree-sitter-language-pack/v{version}/libs/.

Errors:

Returns an error if the system cache directory cannot be determined.

Signature:

pub fn cache_dir() -> Result<String, Error>

Types¶

ByteRange¶

A byte range — start (inclusive) to end (exclusive).

ChunkContext¶

Metadata for a single chunk of source code.

CodeChunk¶

A chunk of source code with rich metadata.

CommentInfo¶

A comment extracted from source code.

Diagnostic¶

A diagnostic (syntax error, missing node, etc.) from parsing.

DocSection¶

A section within a docstring (e.g., Args, Returns, Raises).

DocstringInfo¶

A docstring extracted from source code.

DownloadManager¶

Manages downloading and caching of pre-built parser shared libraries.

Methods¶

new()¶

Create a new download manager for the given version.

Signature:

pub fn new(version: &str) -> DownloadManager

with_cache_dir()¶

Create a download manager with a custom cache directory.

Signature:

pub fn with_cache_dir(version: &str, cache_dir: PathBuf) -> DownloadManager

installed_languages()¶

List languages that are already downloaded and cached.

Signature:

pub fn installed_languages(&self) -> Vec<String>

download_all_best_effort()¶

Download the platform bundle and extract every library file it contains.

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

pub fn download_all_best_effort(&self) -> usize

clean_cache()¶

Remove all cached parser libraries.

Signature:

pub fn clean_cache(&self)

ExportInfo¶

An export statement extracted from source code.

FileMetrics¶

Aggregate metrics for a source file.

ImportInfo¶

An import statement extracted from source code.

Language¶

LanguageRegistry¶

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¶

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:

pub fn get_language(&self, name: &str) -> Language

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:

pub fn available_languages(&self) -> Vec<String>

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.

Signature:

pub fn has_language(&self, name: &str) -> bool

language_count()¶

Return the total number of available languages (including aliases).

Signature:

pub fn language_count(&self) -> usize

process()¶

Parse source code and extract file intelligence based on config in a single pass.

Signature:

pub fn process(&self, source: &str, config: ProcessConfig) -> ProcessResult

default()¶

Signature:

pub fn default() -> LanguageRegistry

Node¶

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¶

clone()¶

Signature:

pub fn clone(&self) -> Node

kind()¶

Return the node's kind name (e.g. "function_definition").

Signature:

pub fn kind(&self) -> String

start_byte()¶

Return the inclusive start byte offset of this node.

Signature:

pub fn start_byte(&self) -> usize

end_byte()¶

Return the exclusive end byte offset of this node.

Signature:

pub fn end_byte(&self) -> usize

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:

pub fn byte_range(&self) -> ByteRange

start_position()¶

Return the start Point (row, column).

Signature:

pub fn start_position(&self) -> Point

end_position()¶

Return the end Point (row, column).

Signature:

pub fn end_position(&self) -> Point

is_named()¶

True when this node is named (not punctuation/whitespace).

Signature:

pub fn is_named(&self) -> bool

is_error()¶

True when this is an error node.

Signature:

pub fn is_error(&self) -> bool

is_missing()¶

True when this is a missing-token node.

Signature:

pub fn is_missing(&self) -> bool

is_extra()¶

True when this is an "extra" node (e.g. a comment).

Signature:

pub fn is_extra(&self) -> bool

has_error()¶

True when this node or any descendant is an error.

Signature:

pub fn has_error(&self) -> bool

parent()¶

Return this node's parent, if any.

Signature:

pub fn parent(&self) -> Option<Node>

child()¶

Return the i-th child of this node, if any.

Signature:

pub fn child(&self, index: u32) -> Option<Node>

child_count()¶

Total number of children (including unnamed).

Signature:

pub fn child_count(&self) -> usize

named_child()¶

Return the i-th named child of this node, if any.

Signature:

pub fn named_child(&self, index: u32) -> Option<Node>

named_child_count()¶

Number of named children of this node.

Signature:

pub fn named_child_count(&self) -> usize

child_by_field_name()¶

Look up a child by its grammar-defined field name.

Signature:

pub fn child_by_field_name(&self, name: &str) -> Option<Node>

to_sexp()¶

Return the S-expression form of this node's subtree.

Signature:

pub fn to_sexp(&self) -> String

walk()¶

Return a TreeCursor positioned at this node.

Signature:

pub fn walk(&self) -> TreeCursor

PackConfig¶

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.

Parser¶

A tree-sitter parser configured for one language at a time.

Methods¶

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:

pub fn set_language(&self, name: &str)

parse()¶

Parse a UTF-8 source string. Returns None if parsing was cancelled or no language is set.

Signature:

pub fn parse(&self, source: &str) -> Option<Tree>

parse_bytes()¶

Parse a raw byte slice. Returns None if parsing was cancelled or no language is set.

Signature:

pub fn parse_bytes(&self, source: &[u8]) -> Option<Tree>

reset()¶

Reset internal state. The next call to parse will not be incremental.

Signature:

pub fn reset(&self)

default()¶

Signature:

pub fn default() -> Parser

Point¶

A source position — row + column, zero-indexed.

Methods¶

from()¶

Signature:

pub fn from(p: Point) -> Point

ProcessConfig¶

Configuration for the process() function.

Controls which analysis features are enabled and whether chunking is performed.

Methods¶

default()¶

Signature:

pub fn default() -> ProcessConfig

with_chunking()¶

Enable chunking with the given maximum chunk size in bytes.

Signature:

pub fn with_chunking(&self, max_size: usize) -> ProcessConfig

all()¶

Enable all analysis features.

Signature:

pub fn all(&self) -> ProcessConfig

minimal()¶

Disable all analysis features (only metrics computed).

Signature:

pub fn minimal(&self) -> ProcessConfig

ProcessResult¶

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.

Span¶

Byte and line/column range in source code.

Represents both byte offsets (for slicing) and human-readable line/column positions (for display and diagnostics).

StructureItem¶

A structural item (function, class, struct, etc.) in source code.

SymbolInfo¶

A symbol (variable, function, type, etc.) extracted from source code.

Tree¶

A parsed syntax tree. Cheap to clone (refcount bump).

Methods¶

root_node()¶

Return the root Node of this tree.

Signature:

pub fn root_node(&self) -> Node

walk()¶

Return a TreeCursor positioned at the root.

Signature:

pub fn walk(&self) -> TreeCursor

TreeCursor¶

A cursor for traversing a Tree.

Methods¶

node()¶

Return the Node at the cursor's current position.

Signature:

pub fn node(&self) -> Node

goto_first_child()¶

Move the cursor to the first child of the current node. Returns true if a child existed.

Signature:

pub fn goto_first_child(&self) -> bool

goto_parent()¶

Move the cursor to the parent of the current node. Returns true if a parent existed.

Signature:

pub fn goto_parent(&self) -> bool

goto_next_sibling()¶

Move the cursor to the next sibling of the current node. Returns true if a sibling existed.

Signature:

pub fn goto_next_sibling(&self) -> bool

field_name()¶

Return the field name for the current node, if any.

Signature:

pub fn field_name(&self) -> Option<String>

Enums¶

StructureKind¶

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.

CommentKind¶

The kind of a comment found in source code.

Distinguishes between single-line comments, block (multi-line) comments, and documentation comments.

DocstringFormat¶

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

ExportKind¶

The kind of an export statement found in source code.

Covers named exports, default exports, and re-exports from other modules.

SymbolKind¶

The kind of a symbol definition found in source code.

Categorizes symbol definitions such as variables, constants, functions, classes, types, interfaces, enums, and modules.

DiagnosticSeverity¶

Severity level of a diagnostic produced during parsing.

Used to classify parse errors, warnings, and informational messages found in the syntax tree.

Errors¶

Error¶

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.

Edit this page on GitHub