Trait SyntaxDriver 

pub trait SyntaxDriver: Send + Sync {
    // Required methods
    fn language(&self) -> &str;
    fn parse(&mut self, content: &str);
    fn update(&mut self, content: &str, edit: &SyntaxEdit);
    fn highlights(&self, byte_range: Range<usize>) -> Vec<Annotation>;
    fn is_parsed(&self) -> bool;

    // Provided methods
    fn injections(&self) -> Vec<Injection> { ... }
    fn decorations(&self, _byte_range: Range<usize>) -> Vec<Annotation> { ... }
    fn folds(&self) -> Vec<FoldRange> { ... }
    fn indent_for(&self, _line: usize) -> Option<usize> { ... }
    fn set_injection_factory(&mut self, _factory: Arc<dyn SyntaxDriverFactory>) { ... }
    fn set_injection_depth(&mut self, _depth: u8) { ... }
    fn set_default_injection_language(&mut self, _language: &str) { ... }
    fn scopes(&self, _line: u32, _col: u32) -> ContextHierarchy { ... }
    fn context_at_byte(&self, _byte_offset: usize) -> SyntaxContext { ... }
    fn textobject_range(
        &self,
        _kind: TextObjectKind,
        _scope: TextObjectScope,
        _line: u32,
        _col: u32,
    ) -> Option<TextObjectRange> { ... }
}

Main parsing interface for syntax highlighting.

Implementors provide language-specific parsing and highlighting. This trait is designed to be parser-agnostic - tree-sitter is just one possible implementation.

Lifecycle

1. Create driver via SyntaxDriverFactory
2. Call parse() with initial content
3. Call update() for incremental edits
4. Call highlights() to get highlights for rendering

Thread Safety

Implementations must be Send + Sync to allow use across threads. The driver may be shared between multiple views of the same buffer.

Example

// Get driver from factory
let mut driver = factory.create("rust")?;

// Initial parse
driver.parse("fn main() {}");
assert!(driver.is_parsed());

// Get highlights for visible range
let highlights = driver.highlights(0..100);

// After edit, update incrementally
driver.update("fn main() { println!(); }", &edit);

Required Methods

fn language(&self) -> &str

Get the language identifier.

Returns a unique identifier like “rust”, “python”, “javascript”. This should match the language ID used to create the driver.

fn parse(&mut self, content: &str)

Perform a full parse of the content.

Called on initial file open or when incremental update isn’t possible. After calling this, is_parsed() should return true.

fn update(&mut self, content: &str, edit: &SyntaxEdit)

Apply an incremental edit.

For efficient re-parsing after buffer modifications. The edit describes what changed; the driver updates its internal state.

Arguments

• content - The new full content after the edit
• edit - Description of what changed

fn highlights(&self, byte_range: Range<usize>) -> Vec<Annotation>

Get annotations for a byte range.

Returns all annotations that overlap with the given range. Results should be sorted by start position.

Arguments

• byte_range - The byte range to get annotations for

Returns

A vector of annotations overlapping the requested range.

fn is_parsed(&self) -> bool

Check if the driver has valid parse state.

Returns true if the driver has successfully parsed content. This should return false before parse() is called, and true after a successful parse.

Provided Methods

fn injections(&self) -> Vec<Injection>

Get language injection points.

Returns regions where a different language should be highlighted. Used for embedded languages (markdown code blocks, HTML scripts, etc.).

Default

Returns an empty vector. Override for languages that support injections.

fn decorations(&self, _byte_range: Range<usize>) -> Vec<Annotation>

Get decoration annotations for a byte range.

Returns annotations from decoration queries (e.g., markdown heading markers, list bullets, code blocks). These carry semantic categories like markup.heading.1 that clients map to render behaviors. Use-sites call this separately from highlights() to opt in to decoration rendering.

Default

Returns an empty vector. Override for languages with decoration support.

fn folds(&self) -> Vec<FoldRange>

Get foldable ranges.

Returns all foldable regions in the document.

Default

Returns an empty vector. Override to provide folding support.

fn indent_for(&self, _line: usize) -> Option<usize>

Get suggested indentation for a line.

Returns the suggested indent level (in spaces) for a given line, or None if indentation cannot be determined.

Arguments

• line - The 0-indexed line number

Default

Returns None. Override to provide indentation hints.

fn set_injection_factory(&mut self, _factory: Arc<dyn SyntaxDriverFactory>)

Configure injection support with the given factory.

Called by the runtime after driver creation to enable recursive injection highlighting. Implementations that support injections use this factory to create child drivers for embedded languages.

Default

No-op. Override for drivers that support injection highlighting.

fn set_injection_depth(&mut self, _depth: u8)

Set the injection nesting depth for this driver.

Used to propagate depth through the injection hierarchy so that MAX_INJECTION_DEPTH is correctly enforced. Depth 0 = root driver, depth 1 = direct child, etc.

Default

No-op. Override for drivers that support injection highlighting.

fn set_default_injection_language(&mut self, _language: &str)

Set the default injection language for bare code blocks.

When a child driver encounters an injection region with no explicit language tag (e.g., bare ``` in Markdown), it falls back to this value. The injection pipeline sets this to the parent driver’s language ID, so bare fences in Rust doc comments default to Rust, bare fences in Python docstrings default to Python, etc.

Default

No-op. Override for drivers that support injection highlighting.

fn scopes(&self, _line: u32, _col: u32) -> ContextHierarchy

Get the enclosing scope hierarchy at a position.

Returns the scope boundaries (function, class, module, etc.) that contain the given line and column. Items are ordered outermost-first.

Arguments

• line - 0-indexed line number
• col - 0-indexed column number

Default

Returns an empty hierarchy. Override for scope-aware behavior.

fn context_at_byte(&self, _byte_offset: usize) -> SyntaxContext

Get the syntax context at a byte position.

Returns the syntactic context (code, string, comment) at the given byte offset. Used by features like auto-pair to skip insertion inside strings or comments.

Default

Returns SyntaxContext::Code. Override for context-aware behavior.

fn textobject_range( &self, _kind: TextObjectKind, _scope: TextObjectScope, _line: u32, _col: u32, ) -> Option<TextObjectRange>

Get the range of a semantic text object at a position.

Resolves language-aware text objects like functions, classes, arguments, etc. at the given cursor position. Returns the byte and position range of the matching construct, or None if no match exists.

Arguments

• kind - The type of text object (function, class, etc.)
• scope - Inner (body only) or outer (full construct)
• line - 0-indexed cursor line
• col - 0-indexed cursor column

Default

Returns None. Override for drivers with treesitter query support.

Implementors