Struct Parser

pub struct Parser(/* private fields */);

A stateful object that this is used to produce a Tree based on some source code.

Implementations

impl Parser

pub const unsafe fn from_raw(ptr: *mut TSParser) -> Self

Reconstructs a Parser from a raw pointer.

Safety

ptr must be non-null.

pub fn into_raw(self) -> *mut TSParser

Consumes the Parser, returning a raw pointer to the underlying C structure.

Safety

It’s a caller responsibility to adjust parser’s state like disable logging or dot graphs printing if this may cause issues like use after free.

impl Parser

pub fn new() -> Self

Create a new parser.

pub fn set_language(&mut self, language: &Language) -> Result<(), LanguageError>

Set the language that the parser should use for parsing.

Returns a Result indicating whether or not the language was successfully assigned. True means assignment succeeded. False means there was a version mismatch: the language was generated with an incompatible version of the Tree-sitter CLI. Check the language’s version using Language::version and compare it to this library’s LANGUAGE_VERSION and MIN_COMPATIBLE_LANGUAGE_VERSION constants.

pub fn language(&self) -> Option<Language>

Get the parser’s current language.

pub fn logger(&self) -> Option<&Box<dyn FnMut(LogType, &str) + '_>>

Get the parser’s current logger.

pub fn set_logger(&mut self, logger: Option<Box<dyn FnMut(LogType, &str) + '_>>)

Set the logging callback that a parser should use during parsing.

pub fn print_dot_graphs(&mut self, file: &impl AsRawFd)

Set the destination to which the parser should write debugging graphs during parsing. The graphs are formatted in the DOT language. You may want to pipe these graphs directly to a dot(1) process in order to generate SVG output.

pub fn stop_printing_dot_graphs(&mut self)

Stop the parser from printing debugging graphs while parsing.

pub fn parse( &mut self, text: impl AsRef<[u8]>, old_tree: Option<&Tree>, ) -> Option<Tree>

Parse a slice of UTF8 text.

Arguments:

• text The UTF8-encoded text to parse.
• old_tree A previous syntax tree parsed from the same document. If the text of the document has changed since old_tree was created, then you must edit old_tree to match the new text using Tree::edit.

Returns a Tree if parsing succeeded, or None if:

• The parser has not yet had a language assigned with Parser::set_language
• The timeout set with Parser::set_timeout_micros expired
• The cancellation flag set with Parser::set_cancellation_flag was flipped

pub fn parse_utf16( &mut self, input: impl AsRef<[u16]>, old_tree: Option<&Tree>, ) -> Option<Tree>

Parse a slice of UTF16 text.

Arguments:

• text The UTF16-encoded text to parse.
• old_tree A previous syntax tree parsed from the same document. If the text of the document has changed since old_tree was created, then you must edit old_tree to match the new text using Tree::edit.

pub fn parse_with<T: AsRef<[u8]>, F: FnMut(usize, Point) -> T>( &mut self, callback: &mut F, old_tree: Option<&Tree>, ) -> Option<Tree>

Parse UTF8 text provided in chunks by a callback.

Arguments:

• callback A function that takes a byte offset and position and returns a slice of UTF8-encoded text starting at that byte offset and position. The slices can be of any length. If the given position is at the end of the text, the callback should return an empty slice.
• old_tree A previous syntax tree parsed from the same document. If the text of the document has changed since old_tree was created, then you must edit old_tree to match the new text using Tree::edit.

pub fn parse_utf16_with<T: AsRef<[u16]>, F: FnMut(usize, Point) -> T>( &mut self, callback: &mut F, old_tree: Option<&Tree>, ) -> Option<Tree>

Parse UTF16 text provided in chunks by a callback.

Arguments:

• callback A function that takes a code point offset and position and returns a slice of UTF16-encoded text starting at that byte offset and position. The slices can be of any length. If the given position is at the end of the text, the callback should return an empty slice.
• old_tree A previous syntax tree parsed from the same document. If the text of the document has changed since old_tree was created, then you must edit old_tree to match the new text using Tree::edit.

pub fn reset(&mut self)

Instruct the parser to start the next parse from the beginning.

If the parser previously failed because of a timeout or a cancellation, then by default, it will resume where it left off on the next call to parse or other parsing functions. If you don’t want to resume, and instead intend to use this parser to parse some other document, you must call reset first.

pub fn timeout_micros(&self) -> u64

Get the duration in microseconds that parsing is allowed to take.

This is set via set_timeout_micros.

pub fn set_timeout_micros(&mut self, timeout_micros: u64)

Set the maximum duration in microseconds that parsing should be allowed to take before halting.

If parsing takes longer than this, it will halt early, returning None. See parse for more information.

pub fn set_included_ranges( &mut self, ranges: &[Range], ) -> Result<(), IncludedRangesError>

Set the ranges of text that the parser should include when parsing.

By default, the parser will always include entire documents. This function allows you to parse only a portion of a document but still return a syntax tree whose ranges match up with the document as a whole. You can also pass multiple disjoint ranges.

If ranges is empty, then the entire document will be parsed. Otherwise, the given ranges must be ordered from earliest to latest in the document, and they must not overlap. That is, the following must hold for all i < length - 1:

    ranges[i].end_byte <= ranges[i + 1].start_byte

If this requirement is not satisfied, method will return IncludedRangesError error with an offset in the passed ranges slice pointing to a first incorrect range.

pub fn included_ranges(&self) -> Vec<Range>

Get the ranges of text that the parser will include when parsing.

pub unsafe fn cancellation_flag(&self) -> Option<&AtomicUsize>

Get the parser’s current cancellation flag pointer.

Safety

It uses FFI

pub unsafe fn set_cancellation_flag(&mut self, flag: Option<&AtomicUsize>)

Set the parser’s current cancellation flag pointer.

If a pointer is assigned, then the parser will periodically read from this pointer during parsing. If it reads a non-zero value, it will halt early, returning None. See parse for more information.

Safety

It uses FFI

Trait Implementations

impl Default for Parser

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Parser

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Parser

impl Sync for Parser