Struct Syntax 

pub struct Syntax { /* private fields */ }

Implementations

impl Syntax

pub fn for_language(lang: Lang) -> Result<Option<Syntax>, SyntaxError>

Build a Syntax for the given language using a fresh standard registry. Convenient when the caller doesn’t already hold a shared registry; for the App’s hot path use Self::for_language_with_registry so all documents share one registry.

Lang::Plain returns None because there’s nothing to parse.

pub fn for_language_with_registry( lang: Lang, registry: Arc<LangRegistry>, ) -> Result<Option<Syntax>, SyntaxError>

Build a Syntax borrowing from a shared registry. Multiple documents (and the help-buffer system) all share one Arc<LangRegistry>; per-document state stays in the Highlighter + source.

pub fn snapshot(&self) -> &SyntaxSnapshot

Borrow the read-only snapshot of the latest parse state. Callers that want to share the snapshot cheaply (across threads, into ArcSwap) clone it; readers that just need one method call use the pass-through helpers below.

pub fn snapshot_owned(&self) -> SyntaxSnapshot

Owned clone of the snapshot. Cheap (Arc-shareable fields).

impl Syntax

pub fn lang(&self) -> Lang

Convenience getter for self.snapshot().lang(). Kept on Syntax so &Syntax callers (help-buffer markdown highlighting, tests) don’t have to thread .snapshot() through.

pub fn tree(&self) -> Option<&Tree>

Convenience getter for self.snapshot().tree().

pub fn source(&self) -> &[u8]

Convenience getter for self.snapshot().source().

pub fn registry(&self) -> &LangRegistry

Convenience getter for self.snapshot().registry().

pub fn cursor_in_string_scope(&self, cursor_byte: usize) -> bool

Convenience pass-through to SyntaxSnapshot::cursor_in_string_scope.

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

Convenience pass-through to SyntaxSnapshot::collect_symbols.

pub fn collect_symbol_locations(&self) -> Vec<(String, u32, u32)>

Convenience pass-through to SyntaxSnapshot::collect_symbol_locations.

pub fn scope_at_cursor( &self, line: u32, col_byte: u32, capture_suffix: &str, ) -> Option<Range>

Convenience pass-through to SyntaxSnapshot::scope_at_cursor.

pub fn highlight_lines( &self, start_line: u32, end_line: u32, ) -> Result<Vec<Vec<StyledSpan>>, SyntaxError>

Convenience pass-through to SyntaxSnapshot::highlight_lines. Note: takes &self (the read API never needed &mut).

pub fn highlight_lines_native( &self, start_line: u32, end_line: u32, ) -> Result<Vec<Vec<StyledSpan>>, SyntaxError>

Convenience pass-through to SyntaxSnapshot::highlight_lines_native.

pub fn parse(&mut self, source: &str)

Replace the cached source and drive a tree-sitter (re)parse. This is the only mutating call on Syntax; everything else is read-only against the snapshot. Production callers should route parse requests through crate::SyntaxHandle so the parse runs off the UI thread (paramount goal #1).

pub fn parse_at(&mut self, source: &str, text_version: u64)

parse variant that also stamps a caller-supplied text_version onto the resulting snapshot. The async handle uses this so consumers can deduplicate stale snapshots.

Full reparse (passes None as the prior tree). The incremental sibling Self::parse_at_with_edits is the keystroke-path entry point; this method is the file-load / cold-start / fallback path.

Parser::parse returning None means cancellation, which we don’t trigger on this synchronous path. Keep the old tree in that unlikely case rather than dropping it – the next parse round will retry.

pub fn parse_at_with_edits( &mut self, source: &str, text_version: u64, from_version: u64, edits: &[EditDelta], )

Incremental reparse: apply edits to the cached tree (sync pre-step on the worker, ~500ns per edit), then parse with the edited tree as the seed (~50µs floor on medium files per §8.2). Falls back to Self::parse_at (full reparse) if the guards on Self::try_apply_intermediate fail.

Slice C.2 split this into two halves so the worker can publish an intermediate snapshot between them – byte ranges shifted to track the edit but tree shape pre-parse, so renderers see byte-aligned spans during the entire parse window. This convenience runs both halves back-to- back without an intermediate publish; the worker calls the two halves directly with the publish in between.

pub fn try_apply_intermediate( &mut self, source: &str, text_version: u64, from_version: u64, edits: &[EditDelta], ) -> Result<(), ()>

Slice C.2: try to apply edits to the cached tree and update source + text_version, WITHOUT running Parser::parse. Returns Ok(()) if the resulting state is valid for the worker to publish as an intermediate snapshot (byte ranges shifted via tree.edit to track the edits; tree shape is pre-parse for the changed regions). Returns Err(()) if any of:

1. No cached tree – first reparse / worker recovered from prior cancellation; nothing to seed with.
2. from_version mismatch – worker’s tree isn’t at the version the edits expect to start from. Indicates a dropped reparse request, file load, or document replace; the cached tree’s byte ranges don’t match the edits.
3. edits empty – nothing to apply.
4. Byte-length mismatch – accumulated edit delta doesn’t match the source-length delta. Catches dropped or truncated edit lists.

On Err, the caller falls back to Self::parse_at (full reparse).

Tree-sitter’s failure mode for a malformed InputEdit is a silently wrong tree, not a panic. The layered guards here + the slice-B.4 parametrized parity matrix (incremental == full reparse across 27 edit shapes × Rust / Python / JavaScript / Markdown) keep the silent- corruption surface contained.

pub fn reparse_with_cached_tree(&mut self, reparsed_from: u64)

Slice C.2: re-parse using self.inner.source and the cached tree (assumed to already have tree.edit applied via Self::try_apply_intermediate) as seed. Updates self.inner.tree to the freshly-parsed shape.

Pairs with try_apply_intermediate: the worker calls try_apply_intermediate (fast), publishes the intermediate snapshot, then calls this to run the actual parse (slow).

Trait Implementations

impl Debug for Syntax

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.