Types Reference

Types Reference

All types defined by the library, grouped by category. Types are shown using Rust as the canonical representation.

Result Types

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.

Field	Type	Default	Description
language	String	—	The language name used to parse the source file.
metrics	FileMetrics	—	File-level metrics (line counts, byte size, error count).
structure	Vec<StructureItem>	vec!\[\]	Top-level structural items (functions, classes, etc.).
imports	Vec<ImportInfo>	vec!\[\]	Import statements extracted from the source.
exports	Vec<ExportInfo>	vec!\[\]	Export statements extracted from the source.
comments	Vec<CommentInfo>	vec!\[\]	Comments extracted from the source.
docstrings	Vec<DocstringInfo>	vec!\[\]	Docstrings extracted from the source.
symbols	Vec<SymbolInfo>	vec!\[\]	Symbol definitions (variables, types, functions) extracted from the source.
diagnostics	Vec<Diagnostic>	vec!\[\]	Parse diagnostics (syntax errors, missing nodes) from tree-sitter.
chunks	Vec<CodeChunk>	vec!\[\]	Syntax-aware code chunks produced when chunking is enabled.
data	Option<DataNode>	Default::default()	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). None 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.

---

Configuration Types

See Configuration Reference for detailed defaults and language-specific representations.

DataAttribute

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	String	—	Attribute name (e.g. "class", "href").
value	String	—	Attribute value as a raw string (quotes stripped).
span	Span	—	Source span covering the entire name="value" attribute token.

---

DataNode

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	DataNodeKind	DataNodeKind::KeyValue	Whether this node is a key/value pair, XML element, or sequence item.
key	Option<String>	Default::default()	Key, attribute name, tag name, or positional index ("0", "1", …). None at the document root.
value	Option<String>	Default::default()	Leaf scalar value, if any. None for containers (objects, arrays, XML elements with child elements).
attributes	Vec<DataAttribute>	vec!\[\]	Attributes on element-shape nodes (XML STag attributes). Empty for all other kinds.
children	Vec<DataNode>	vec!\[\]	Children for nested containers and XML element bodies.
span	Span	—	Source span covering this node in the original source file.

---

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

Field	Type	Default	Description
start_byte	usize	—	Inclusive start byte offset in the source.
end_byte	usize	—	Exclusive end byte offset in the source.
start_line	usize	—	Zero-indexed line number of the span’s start.
start_column	usize	—	Zero-indexed column number of the span’s start.
end_line	usize	—	Zero-indexed line number of the span’s end.
end_column	usize	—	Zero-indexed column number of the span’s end.

---

FileMetrics

Aggregate metrics for a source file.

Field	Type	Default	Description
total_lines	usize	—	Total number of lines (including blank and comment lines).
code_lines	usize	—	Number of lines containing non-blank, non-comment source code.
comment_lines	usize	—	Number of lines that are entirely comments.
blank_lines	usize	—	Number of blank (whitespace-only) lines.
total_bytes	usize	—	Total byte length of the source file.
node_count	usize	—	Total number of nodes in the syntax tree.
error_count	usize	—	Number of error nodes in the syntax tree (parse errors).
max_depth	usize	—	Maximum nesting depth reached in the syntax tree.

---

StructureItem

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

Field	Type	Default	Description
kind	StructureKind	StructureKind::Function	The kind of structural item.
name	Option<String>	Default::default()	The declared name of the item, if present.
visibility	Option<String>	Default::default()	Visibility modifier (e.g., "pub", "public", "private").
span	Span	—	Source span covering the entire item declaration.
children	Vec<StructureItem>	vec!\[\]	Nested structural items (e.g., methods within a class).
decorators	Vec<String>	vec!\[\]	Decorator or attribute names applied to the item.
doc_comment	Option<String>	Default::default()	Documentation comment attached to the item, if any.
signature	Option<String>	Default::default()	Full signature text of the item (e.g., function parameters and return type).
body_span	Option<Span>	Default::default()	Source span covering only the body of the item, if distinct from the declaration.

---

CommentInfo

A comment extracted from source code.

Field	Type	Default	Description
text	String	—	The raw text content of the comment.
kind	CommentKind	CommentKind::Line	The kind of comment (line, block, or doc).
span	Span	—	Source span covering the comment.
associated_node	Option<String>	Default::default()	Name of the syntax node this comment is directly associated with.

---

DocstringInfo

A docstring extracted from source code.

Field	Type	Default	Description
text	String	—	The raw text of the docstring.
format	DocstringFormat	DocstringFormat::PythonTripleQuote	The docstring format (Python, JSDoc, Rustdoc, etc.).
span	Span	—	Source span covering the docstring.
associated_item	Option<String>	Default::default()	Name of the item this docstring documents.
parsed_sections	Vec<DocSection>	vec!\[\]	Parsed sections of the docstring (Args, Returns, Raises, etc.).

---

DocSection

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

Field	Type	Default	Description
kind	String	—	Section kind (e.g., "args", "returns", "raises").
name	Option<String>	Default::default()	Parameter or return value name, if applicable.
description	String	—	Description text for this section.

---

ImportInfo

An import statement extracted from source code.

Field	Type	Default	Description
source	String	—	The module or path being imported from.
items	Vec<String>	vec!\[\]	Specific names imported from the source module.
alias	Option<String>	Default::default()	Alias assigned to the import (e.g., import numpy as np).
is_wildcard	bool	—	Whether this is a wildcard import (e.g., import * or use foo::*).
span	Span	—	Source span covering the import statement.

---

ExportInfo

An export statement extracted from source code.

Field	Type	Default	Description
name	String	—	The exported name.
kind	ExportKind	ExportKind::Named	The kind of export (named, default, or re-export).
span	Span	—	Source span covering the export statement.

---

SymbolInfo

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

Field	Type	Default	Description
name	String	—	The name of the symbol.
kind	SymbolKind	SymbolKind::Variable	The kind of symbol (variable, function, class, etc.).
span	Span	—	Source span covering the symbol definition.
type_annotation	Option<String>	Default::default()	Explicit type annotation, if present in the source.
doc	Option<String>	Default::default()	Documentation comment associated with this symbol.

---

Diagnostic

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

Field	Type	Default	Description
message	String	—	Human-readable description of the diagnostic.
severity	DiagnosticSeverity	DiagnosticSeverity::Error	Severity of the diagnostic.
span	Span	—	Source span where the diagnostic was detected.

---

CodeChunk

A chunk of source code with rich metadata.

Field	Type	Default	Description
content	String	—	The raw source text of this chunk.
start_byte	usize	—	Inclusive start byte offset of this chunk in the original source.
end_byte	usize	—	Exclusive end byte offset of this chunk in the original source.
start_line	usize	—	Zero-indexed start line of this chunk.
end_line	usize	—	Zero-indexed end line of this chunk.
metadata	ChunkContext	—	Contextual metadata about this chunk.

---

ChunkContext

Metadata for a single chunk of source code.

Field	Type	Default	Description
language	String	—	Language name used to parse this chunk.
chunk_index	usize	—	Zero-indexed position of this chunk within the file’s chunk list.
total_chunks	usize	—	Total number of chunks the file was split into.
node_types	Vec<String>	vec!\[\]	Tree-sitter node kinds that appear at the top level of this chunk.
context_path	Vec<String>	vec!\[\]	Hierarchical path of enclosing structural items (e.g., \["MyClass", "my_method"\]).
symbols_defined	Vec<String>	vec!\[\]	Names of symbols defined within this chunk.
comments	Vec<CommentInfo>	vec!\[\]	Comments contained within this chunk.
docstrings	Vec<DocstringInfo>	vec!\[\]	Docstrings contained within this chunk.
has_error_nodes	bool	—	Whether this chunk contains any tree-sitter error nodes.

---

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.

Field	Type	Default	Description
cache_dir	Option<PathBuf>	Default::default()	Override default cache directory. Default: ~/.cache/tree-sitter-language-pack/v{version}/libs/
languages	Vec<String>	vec!\[\]	Languages to pre-download on init. Each entry is a language name (e.g. "python", "rust").
groups	Vec<String>	vec!\[\]	Language groups to pre-download (e.g. "web", "systems", "scripting").

---

Parser

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

Opaque type — fields are not directly accessible.

---

ProcessConfig

Configuration for the process() function.

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

Field	Type	Default	Description
language	String	—	Language name (required).
structure	bool	true	Extract structural items (functions, classes, etc.). Default: true.
imports	bool	true	Extract import statements. Default: true.
exports	bool	true	Extract export statements. Default: true.
comments	bool	false	Extract comments. Default: false.
docstrings	bool	false	Extract docstrings. Default: false.
symbols	bool	false	Extract symbol definitions. Default: false.
diagnostics	bool	false	Include parse diagnostics. Default: false.
chunk_max_size	Option<usize>	None	Maximum chunk size in bytes. None disables chunking.
data_extraction	bool	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 None.

---

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

Opaque type — fields are not directly accessible.

---

Structured Data Types

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.

Opaque type — fields are not directly accessible.

---

Other Types

Point

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

Field	Type	Default	Description
row	usize	—	Zero-indexed row number.
column	usize	—	Zero-indexed column number, in UTF-16 code units.

---

ByteRange

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

Field	Type	Default	Description
start	usize	—	Inclusive start byte offset.
end	usize	—	Exclusive end byte offset.

---

Tree

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

Opaque type — fields are not directly accessible.

---

TreeCursor

A cursor for traversing a Tree.

Opaque type — fields are not directly accessible.

---

DownloadManager

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

Opaque type — fields are not directly accessible.

---

Language

Opaque type — fields are not directly accessible.

---

Enums

CommentKind

The kind of a comment found in source code.

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

Variant	Description
Line	A single-line comment (e.g., // ... or # ...).
Block	A block or multi-line comment using slash-star delimiters.
Doc	A documentation comment such as /// ... or slash-double-star block.

---

DataNodeKind

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)

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.

Variant	Description
KeyValue	A key/value pair or mapping (json/toml/properties/yaml/hcl/cue/kdl pair, or a wrapper “object”/“mapping” container).
Element	An XML element with a tag name in key and attributes in attributes.
Sequence	A positional sequence item (JSON array element, YAML block sequence item, CSV/PSV row or cell).

---

DiagnosticSeverity

Severity level of a diagnostic produced during parsing.

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

Variant	Description
Error	A parse error (e.g., an ERROR or MISSING node in the tree).
Warning	A warning-level diagnostic.
Info	An informational diagnostic.

---

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

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.

Variant	Description
PythonTripleQuote	Python triple-quoted string docstring ("""...""").
JSDoc	JavaScript/TypeScript JSDoc block comment (opens with two stars, closes with star-slash).
Rustdoc	Rust /// or //! doc comment.
GoDoc	Go doc comment (a comment block immediately preceding a declaration).
JavaDoc	Java Javadoc block comment (opens with two stars, closes with star-slash).
Other	A language-specific docstring format not covered by the standard variants. — Fields: _0: String

---

ExportKind

The kind of an export statement found in source code.

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

Variant	Description
Named	A named export (e.g., export { foo }).
Default	A default export (e.g., export default foo).
ReExport	A re-export from another module (e.g., export { foo } from 'bar').

---

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.

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.

Variant	Description
Function	A free-standing or associated function.
Method	A method defined inside a class, struct, trait, or impl block.
Class	A class definition.
Struct	A struct definition.
Interface	An interface or protocol definition.
Enum	An enum definition.
Module	A module or package declaration.
Trait	A trait definition.
Impl	An impl block (Rust) or similar implementation block.
Namespace	A namespace declaration.
Other	A language-specific construct that does not fit any standard category. — Fields: _0: String

---

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.

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.

Variant	Description
Variable	A variable binding.
Constant	A constant (immutable binding).
Function	A function definition.
Class	A class definition.
Type	A type alias or typedef.
Interface	An interface definition.
Enum	An enum definition.
Module	A module declaration.
Other	A symbol kind not covered by the standard variants. — Fields: _0: String

---