tree_sitter/

lib.rs

#![cfg_attr(not(any(test, doctest)), doc = include_str!("./README.md"))]
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg_attr(docsrs, feature(doc_cfg))]

pub mod ffi;
mod util;

#[cfg(any(
    not(feature = "std"),
    all(target_arch = "wasm32", target_os = "unknown")
))]
extern crate alloc;
#[cfg(not(feature = "std"))]
use alloc::{boxed::Box, format, string::String, string::ToString, vec::Vec};
use core::{
    ffi::{CStr, c_char, c_void},
    fmt::{self, Write},
    hash, iter,
    marker::PhantomData,
    mem::MaybeUninit,
    num::NonZeroU16,
    ops::{self, ControlFlow, Deref},
    ptr::{self, NonNull},
    slice, str,
};
#[cfg(feature = "std")]
use std::error;
#[cfg(all(unix, feature = "std"))]
use std::os::fd::AsRawFd;
#[cfg(all(windows, feature = "std"))]
use std::os::windows::io::AsRawHandle;

pub use streaming_iterator::{StreamingIterator, StreamingIteratorMut};
use tree_sitter_language::LanguageFn;

#[cfg(feature = "wasm")]
mod wasm_language;
#[cfg(feature = "wasm")]
#[cfg_attr(docsrs, doc(cfg(feature = "wasm")))]
pub use wasm_language::*;

#[cfg(all(target_arch = "wasm32", target_os = "unknown"))]
mod wasm_allocator;

/// The latest ABI version that the current version of the library supports.
///
/// The CLI of this fork assigns it to each generated language. Its upper 16
/// bits (`0x5742`, "WB") tag the fork and its lower 16 bits count the fork's
/// ABI revisions, so that it never equals an ABI version of upstream
/// Tree-sitter: the library rejects languages generated by upstream's CLI, and
/// upstream's library rejects languages generated by this fork's CLI.
#[doc(alias = "TREE_SITTER_LANGUAGE_VERSION")]
pub const LANGUAGE_VERSION: usize = ffi::TREE_SITTER_LANGUAGE_VERSION as usize;

/// The earliest ABI version that is supported by the current version of the
/// library. Its parse tables are a subset of those of [`LANGUAGE_VERSION`], so
/// the library loads both.
#[doc(alias = "TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION")]
pub const MIN_COMPATIBLE_LANGUAGE_VERSION: usize =
    ffi::TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION as usize;

pub const PARSER_HEADER: &str = include_str!("../src/parser.h");

/// An opaque object that defines how to parse a particular language. The code
/// for each `Language` is generated by the Tree-sitter CLI.
#[doc(alias = "TSLanguage")]
#[derive(Debug, PartialEq, Eq, Hash)]
#[repr(transparent)]
pub struct Language(*const ffi::TSLanguage);

pub struct LanguageRef<'a>(*const ffi::TSLanguage, PhantomData<&'a ()>);

/// The metadata associated with a language.
///
/// Currently, this metadata can be used to check the [Semantic Version](https://semver.org/)
/// of the language. This version information should be used to signal if a given parser might
/// be incompatible with existing queries when upgrading between major versions, or minor versions
/// if it's in zerover.
#[doc(alias = "TSLanguageMetadata")]
pub struct LanguageMetadata {
    pub major_version: u8,
    pub minor_version: u8,
    pub patch_version: u8,
}

impl From<ffi::TSLanguageMetadata> for LanguageMetadata {
    fn from(val: ffi::TSLanguageMetadata) -> Self {
        Self {
            major_version: val.major_version,
            minor_version: val.minor_version,
            patch_version: val.patch_version,
        }
    }
}

/// A tree that represents the syntactic structure of a source code file.
#[doc(alias = "TSTree")]
pub struct Tree(NonNull<ffi::TSTree>);

/// A position in a multi-line text document, in terms of rows and columns.
///
/// Rows and columns are zero-based.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Point {
    pub row: usize,
    pub column: usize,
}

/// A range of positions in a multi-line text document, both in terms of bytes
/// and of rows and columns.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Range {
    pub start_byte: usize,
    pub end_byte: usize,
    pub start_point: Point,
    pub end_point: Point,
}

/// A summary of a change to a text document.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct InputEdit {
    pub start_byte: usize,
    pub old_end_byte: usize,
    pub new_end_byte: usize,
    pub start_position: Point,
    pub old_end_position: Point,
    pub new_end_position: Point,
}

impl InputEdit {
    /// Edit a point to keep it in-sync with source code that has been edited.
    ///
    /// This function updates a single point's byte offset and row/column position
    /// based on this edit operation. This is useful for editing points without
    /// requiring a tree or node instance.
    #[doc(alias = "ts_point_edit")]
    pub fn edit_point(&self, point: &mut Point, byte: &mut usize) {
        let edit = self.into();
        let mut ts_point = (*point).into();
        let mut ts_byte = *byte as u32;

        unsafe {
            ffi::ts_point_edit(
                core::ptr::addr_of_mut!(ts_point),
                core::ptr::addr_of_mut!(ts_byte),
                &raw const edit,
            );
        }

        *point = ts_point.into();
        *byte = ts_byte as usize;
    }

    /// Edit a range to keep it in-sync with source code that has been edited.
    ///
    /// This function updates a range's start and end positions based on this edit
    /// operation. This is useful for editing ranges without requiring a tree
    /// or node instance.
    #[doc(alias = "ts_range_edit")]
    pub fn edit_range(&self, range: &mut Range) {
        let edit = self.into();
        let mut ts_range = (*range).into();

        unsafe {
            ffi::ts_range_edit(core::ptr::addr_of_mut!(ts_range), &raw const edit);
        }

        *range = ts_range.into();
    }
}

/// A single node within a syntax [`Tree`].
#[doc(alias = "TSNode")]
#[derive(Clone, Copy)]
#[repr(transparent)]
pub struct Node<'tree>(ffi::TSNode, PhantomData<&'tree ()>);

/// A stateful object that this is used to produce a [`Tree`] based on some
/// source code.
#[doc(alias = "TSParser")]
pub struct Parser(NonNull<ffi::TSParser>);

/// A stateful object that is used to look up symbols valid in a specific parse
/// state
#[doc(alias = "TSLookaheadIterator")]
pub struct LookaheadIterator(NonNull<ffi::TSLookaheadIterator>);
struct LookaheadNamesIterator<'a>(&'a mut LookaheadIterator);

/// A stateful object that is passed into a [`ParseProgressCallback`]
/// to pass in the current state of the parser.
pub struct ParseState(NonNull<ffi::TSParseState>);

impl ParseState {
    #[must_use]
    pub const fn current_byte_offset(&self) -> usize {
        unsafe { self.0.as_ref() }.current_byte_offset as usize
    }

    #[must_use]
    pub const fn has_error(&self) -> bool {
        unsafe { self.0.as_ref() }.has_error
    }
}

/// A stateful object that is passed into a [`QueryProgressCallback`]
/// to pass in the current state of the query execution.
pub struct QueryCursorState(NonNull<ffi::TSQueryCursorState>);

impl QueryCursorState {
    #[must_use]
    pub const fn current_byte_offset(&self) -> usize {
        unsafe { self.0.as_ref() }.current_byte_offset as usize
    }
}

#[derive(Default)]
pub struct ParseOptions<'a> {
    pub progress_callback: Option<ParseProgressCallback<'a>>,
}

impl<'a> ParseOptions<'a> {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    #[must_use]
    pub fn progress_callback<F: FnMut(&ParseState) -> ControlFlow<()>>(
        mut self,
        callback: &'a mut F,
    ) -> Self {
        self.progress_callback = Some(callback);
        self
    }

    /// Create a new `ParseOptions` with a shorter lifetime, borrowing from this one.
    ///
    /// This is useful when you need to reuse parse options multiple times, e.g., calling
    /// [`Parser::parse_with_options`] multiple times with the same options.
    #[must_use]
    pub fn reborrow(&mut self) -> ParseOptions {
        ParseOptions {
            progress_callback: match &mut self.progress_callback {
                Some(cb) => Some(*cb),
                None => None,
            },
        }
    }
}

#[derive(Default)]
pub struct QueryCursorOptions<'a> {
    pub progress_callback: Option<QueryProgressCallback<'a>>,
}

impl<'a> QueryCursorOptions<'a> {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    #[must_use]
    pub fn progress_callback<F: FnMut(&QueryCursorState) -> ControlFlow<()>>(
        mut self,
        callback: &'a mut F,
    ) -> Self {
        self.progress_callback = Some(callback);
        self
    }

    /// Create a new `QueryCursorOptions` with a shorter lifetime, borrowing from this one.
    ///
    /// This is useful when you need to reuse query cursor options multiple times, e.g., calling
    /// [`QueryCursor::matches`] multiple times with the same options.
    #[must_use]
    pub fn reborrow(&mut self) -> QueryCursorOptions {
        QueryCursorOptions {
            progress_callback: match &mut self.progress_callback {
                Some(cb) => Some(*cb),
                None => None,
            },
        }
    }
}

struct QueryCursorOptionsDrop<'options>(
    *mut ffi::TSQueryCursorOptions,
    PhantomData<QueryProgressCallback<'options>>,
);

impl Drop for QueryCursorOptionsDrop<'_> {
    fn drop(&mut self) {
        unsafe {
            if !(*self.0).payload.is_null() {
                drop(Box::from_raw(
                    (*self.0).payload.cast::<QueryProgressCallback>(),
                ));
            }
            drop(Box::from_raw(self.0));
        }
    }
}

/// A type of log message.
#[derive(Debug, PartialEq, Eq)]
pub enum LogType {
    Parse,
    Lex,
}

type FieldId = NonZeroU16;

/// A callback that receives log messages during parsing.
type Logger = Box<dyn FnMut(LogType, &str) + Send + 'static>;

/// A callback that receives log messages during parsing, with relaxed constraints.
type UnsafeLogger<'a> = Box<dyn FnMut(LogType, &str) + Send + 'a>;

/// A callback that receives the parse state during parsing.
type ParseProgressCallback<'a> = &'a mut dyn FnMut(&ParseState) -> ControlFlow<()>;

/// A callback that receives the query state during query execution.
type QueryProgressCallback<'a> = &'a mut dyn FnMut(&QueryCursorState) -> ControlFlow<()>;

pub trait Decode {
    /// A callback that decodes the next code point from the input slice. It should return the code
    /// point, and how many bytes were decoded.
    fn decode(bytes: &[u8]) -> (i32, u32);
}

/// A stateful object for walking a syntax [`Tree`] efficiently.
#[doc(alias = "TSTreeCursor")]
pub struct TreeCursor<'tree>(ffi::TSTreeCursor, PhantomData<&'tree ()>);

/// A set of patterns that match nodes in a syntax tree.
#[doc(alias = "TSQuery")]
#[derive(Debug)]
#[expect(
    clippy::type_complexity,
    reason = "complex nested types are inherent to the query data model"
)]
pub struct Query {
    ptr: NonNull<ffi::TSQuery>,
    capture_names: Box<[&'static str]>,
    capture_quantifiers: Box<[Box<[CaptureQuantifier]>]>,
    text_predicates: Box<[Box<[TextPredicateCapture]>]>,
    property_settings: Box<[Box<[QueryProperty]>]>,
    property_predicates: Box<[Box<[(QueryProperty, bool)]>]>,
    general_predicates: Box<[Box<[QueryPredicate]>]>,
}

/// A quantifier for captures
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
pub enum CaptureQuantifier {
    Zero,
    ZeroOrOne,
    ZeroOrMore,
    One,
    OneOrMore,
}

impl From<ffi::TSQuantifier> for CaptureQuantifier {
    fn from(value: ffi::TSQuantifier) -> Self {
        match value {
            ffi::TSQuantifierZero => Self::Zero,
            ffi::TSQuantifierZeroOrOne => Self::ZeroOrOne,
            ffi::TSQuantifierZeroOrMore => Self::ZeroOrMore,
            ffi::TSQuantifierOne => Self::One,
            ffi::TSQuantifierOneOrMore => Self::OneOrMore,
            _ => unreachable!(),
        }
    }
}

/// A stateful object for executing a [`Query`] on a syntax [`Tree`].
#[doc(alias = "TSQueryCursor")]
pub struct QueryCursor {
    ptr: NonNull<ffi::TSQueryCursor>,
}

/// A key-value pair associated with a particular pattern in a [`Query`].
#[derive(Debug, PartialEq, Eq)]
pub struct QueryProperty {
    pub key: Box<str>,
    pub value: Option<Box<str>>,
    pub capture_id: Option<usize>,
}

#[derive(Debug, PartialEq, Eq)]
pub enum QueryPredicateArg {
    Capture(u32),
    String(Box<str>),
}

/// A key-value pair associated with a particular pattern in a [`Query`].
#[derive(Debug, PartialEq, Eq)]
pub struct QueryPredicate {
    pub operator: Box<str>,
    pub args: Box<[QueryPredicateArg]>,
}

/// A match of a [`Query`] to a particular set of [`Node`]s.
pub struct QueryMatch<'cursor, 'tree> {
    pub pattern_index: usize,
    captures: &'cursor [QueryCapture<'tree>],
    id: u32,
    cursor: *mut ffi::TSQueryCursor,
}

/// A sequence of [`QueryMatch`]es associated with a given [`QueryCursor`].
pub struct QueryMatches<'query, 'tree, 'options, T: TextProvider<I>, I: AsRef<[u8]>> {
    ptr: *mut ffi::TSQueryCursor,
    query: &'query Query,
    text_provider: T,
    buffer1: Vec<u8>,
    buffer2: Vec<u8>,
    current_match: Option<QueryMatch<'query, 'tree>>,
    _options: Option<QueryCursorOptionsDrop<'options>>,
    _phantom: PhantomData<(&'tree (), I)>,
}

/// A sequence of [`QueryCapture`]s associated with a given [`QueryCursor`].
///
/// During iteration, each element contains a [`QueryMatch`] and index. The index can
/// be used to access the new capture inside of the [`QueryMatch::captures`]'s [`captures`].
pub struct QueryCaptures<'query, 'tree, 'options, T: TextProvider<I>, I: AsRef<[u8]>> {
    ptr: *mut ffi::TSQueryCursor,
    query: &'query Query,
    text_provider: T,
    buffer1: Vec<u8>,
    buffer2: Vec<u8>,
    current_match: Option<(QueryMatch<'query, 'tree>, usize)>,
    _options: Option<QueryCursorOptionsDrop<'options>>,
    _phantom: PhantomData<(&'tree (), I)>,
}

pub trait TextProvider<I>
where
    I: AsRef<[u8]>,
{
    type I: Iterator<Item = I>;
    fn text(&mut self, node: Node) -> Self::I;
}

/// A particular [`Node`] that has been captured with a particular name within a
/// [`Query`].
#[derive(Clone, Copy, Debug)]
#[repr(C)]
pub struct QueryCapture<'tree> {
    pub node: Node<'tree>,
    pub index: u32,
}

/// An error that occurred when trying to assign a [`Language`] to a [`Parser`].
/// If the `wasm` feature is enabled, this can also indicate a failure to load
/// the Wasm store.
#[derive(Debug, PartialEq, Eq)]
pub enum LanguageError {
    Version(usize),
    NotParseable,
    #[cfg(feature = "wasm")]
    Wasm,
}

/// An error that occurred in [`Parser::set_included_ranges`].
#[derive(Debug, PartialEq, Eq)]
pub struct IncludedRangesError(pub usize);

/// An error that occurred when trying to create a [`Query`].
#[derive(Debug, PartialEq, Eq)]
pub struct QueryError {
    pub row: usize,
    pub column: usize,
    pub offset: usize,
    pub message: String,
    pub kind: QueryErrorKind,
}

#[derive(Debug, PartialEq, Eq)]
pub enum QueryErrorKind {
    Syntax,
    NodeType,
    Field,
    Capture,
    Predicate,
    Structure,
    Language,
}

#[derive(Debug)]
/// The first item is the capture index
/// The next is capture specific, depending on what item is expected
/// The first bool is if the capture is positive
/// The last item is a bool signifying whether or not it's meant to match
/// any or all captures
enum TextPredicateCapture {
    EqString(u32, Box<str>, bool, bool),
    EqCapture(u32, u32, bool, bool),
    MatchString(u32, regex::bytes::Regex, bool, bool),
    AnyString(u32, Box<[Box<str>]>, bool),
}

// TODO: Remove this struct at some point. If `core::str::lossy::Utf8Lossy`
// is ever stabilized.
pub struct LossyUtf8<'a> {
    bytes: &'a [u8],
    in_replacement: bool,
}

impl Language {
    #[must_use]
    pub fn new(builder: LanguageFn) -> Self {
        Self(unsafe { builder.into_raw()().cast() })
    }

    /// Check whether this language can be assigned to a parser.
    ///
    /// When Tree-sitter is compiled to WebAssembly, languages obtained from a
    /// syntax tree can be used for parsing only within the same WebAssembly
    /// instance that created the tree. In other instances, such languages can
    /// still be used to inspect syntax trees.
    #[doc(alias = "ts_language_is_parseable")]
    #[must_use]
    pub fn is_parseable(&self) -> bool {
        unsafe { ffi::ts_language_is_parseable(self.0) }
    }

    /// Get the name of this language. This returns `None` for a language with
    /// another ABI version.
    #[doc(alias = "ts_language_name")]
    #[must_use]
    pub fn name(&self) -> Option<&str> {
        let ptr = unsafe { ffi::ts_language_name(self.0) };
        (!ptr.is_null()).then(|| unsafe { CStr::from_ptr(ptr) }.to_str().unwrap())
    }

    /// Get the ABI version number of this [`Language`].
    ///
    /// The library loads only languages whose number is from
    /// [`MIN_COMPATIBLE_LANGUAGE_VERSION`] to [`LANGUAGE_VERSION`], which the CLI
    /// of this fork assigns. Any other number comes from a parser
    /// that another CLI generated.
    #[doc(alias = "ts_language_abi_version")]
    #[must_use]
    pub fn abi_version(&self) -> usize {
        unsafe { ffi::ts_language_abi_version(self.0) as usize }
    }

    /// Get the metadata for this language. This information is generated by the
    /// CLI, and relies on the language author providing the correct metadata in
    /// the language's `tree-sitter.json` file. This returns `None` for a
    /// language with another ABI version.
    ///
    /// See also [`LanguageMetadata`].
    #[doc(alias = "ts_language_metadata")]
    #[must_use]
    pub fn metadata(&self) -> Option<LanguageMetadata> {
        unsafe {
            let ptr = ffi::ts_language_metadata(self.0);
            (!ptr.is_null()).then(|| (*ptr).into())
        }
    }

    /// Get the number of distinct node types in this language.
    #[doc(alias = "ts_language_symbol_count")]
    #[must_use]
    pub fn node_kind_count(&self) -> usize {
        unsafe { ffi::ts_language_symbol_count(self.0) as usize }
    }

    /// Get the number of valid states in this language.
    #[doc(alias = "ts_language_state_count")]
    #[must_use]
    pub fn parse_state_count(&self) -> usize {
        unsafe { ffi::ts_language_state_count(self.0) as usize }
    }

    /// Get a list of all supertype symbols for the language. The list is empty
    /// for a language with another ABI version.
    #[doc(alias = "ts_language_supertypes")]
    #[must_use]
    pub fn supertypes(&self) -> &[u16] {
        let mut length = 0u32;
        unsafe {
            let ptr = ffi::ts_language_supertypes(self.0, core::ptr::addr_of_mut!(length));
            if length == 0 {
                &[]
            } else {
                slice::from_raw_parts(ptr.cast_mut(), length as usize)
            }
        }
    }

    /// Get a list of all subtype symbols for a given supertype symbol. The list
    /// is empty for a language with another ABI version.
    #[doc(alias = "ts_language_supertype_map")]
    #[must_use]
    pub fn subtypes_for_supertype(&self, supertype: u16) -> &[u16] {
        unsafe {
            let mut length = 0u32;
            let ptr = ffi::ts_language_subtypes(self.0, supertype, core::ptr::addr_of_mut!(length));
            if length == 0 {
                &[]
            } else {
                slice::from_raw_parts(ptr.cast_mut(), length as usize)
            }
        }
    }

    /// Get the name of the node kind for the given numerical id.
    #[doc(alias = "ts_language_symbol_name")]
    #[must_use]
    pub fn node_kind_for_id(&self, id: u16) -> Option<&str> {
        let ptr = unsafe { ffi::ts_language_symbol_name(self.0, id) };
        (!ptr.is_null()).then(|| unsafe { CStr::from_ptr(ptr) }.to_str().unwrap())
    }

    /// Get the numeric id for the given node kind.
    #[doc(alias = "ts_language_symbol_for_name")]
    #[must_use]
    pub fn id_for_node_kind(&self, kind: &str, named: bool) -> u16 {
        unsafe {
            ffi::ts_language_symbol_for_name(
                self.0,
                kind.as_bytes().as_ptr().cast::<c_char>(),
                kind.len() as u32,
                named,
            )
        }
    }

    /// Check whether `id` can be used to index this language's symbol tables.
    ///
    /// `ts_symbol_metadata` holds one entry per grammar symbol plus one per alias,
    /// so [`Self::node_kind_count`] is an exact bound. `ERROR` and `_ERROR` sit
    /// at the top of the `u16` range and are handled by the C library before any
    /// table lookup.
    fn node_kind_id_is_valid(&self, id: u16) -> bool {
        (id as usize) < self.node_kind_count() || id >= u16::MAX - 1
    }

    /// Check if the node type for the given numerical id is named (as opposed
    /// to an anonymous node type).
    #[must_use]
    pub fn node_kind_is_named(&self, id: u16) -> bool {
        self.node_kind_id_is_valid(id)
            && unsafe { ffi::ts_language_symbol_type(self.0, id) == ffi::TSSymbolTypeRegular }
    }

    /// Check if the node type for the given numerical id is visible (as opposed
    /// to a hidden node type).
    #[must_use]
    pub fn node_kind_is_visible(&self, id: u16) -> bool {
        self.node_kind_id_is_valid(id)
            && unsafe { ffi::ts_language_symbol_type(self.0, id) <= ffi::TSSymbolTypeAnonymous }
    }

    /// Check if the node type for the given numerical id is a supertype.
    #[must_use]
    pub fn node_kind_is_supertype(&self, id: u16) -> bool {
        self.node_kind_id_is_valid(id)
            && unsafe { ffi::ts_language_symbol_type(self.0, id) == ffi::TSSymbolTypeSupertype }
    }

    /// Get the number of distinct field names in this language.
    #[doc(alias = "ts_language_field_count")]
    #[must_use]
    pub fn field_count(&self) -> usize {
        unsafe { ffi::ts_language_field_count(self.0) as usize }
    }

    /// Get the field name for the given numerical id.
    #[doc(alias = "ts_language_field_name_for_id")]
    #[must_use]
    pub fn field_name_for_id(&self, field_id: u16) -> Option<&str> {
        let ptr = unsafe { ffi::ts_language_field_name_for_id(self.0, field_id) };
        (!ptr.is_null()).then(|| unsafe { CStr::from_ptr(ptr) }.to_str().unwrap())
    }

    /// Get the numerical id for the given field name.
    #[doc(alias = "ts_language_field_id_for_name")]
    #[must_use]
    pub fn field_id_for_name(&self, field_name: impl AsRef<[u8]>) -> Option<FieldId> {
        let field_name = field_name.as_ref();
        let id = unsafe {
            ffi::ts_language_field_id_for_name(
                self.0,
                field_name.as_ptr().cast::<c_char>(),
                field_name.len() as u32,
            )
        };
        FieldId::new(id)
    }

    /// Get the next parse state. Combine this with
    /// [`lookahead_iterator`](Language::lookahead_iterator) to
    /// generate completion suggestions or valid symbols in error nodes.
    ///
    /// Example:
    /// ```ignore
    /// let state = language.next_state(node.parse_state(), node.grammar_id());
    /// ```
    #[doc(alias = "ts_language_next_state")]
    #[must_use]
    pub fn next_state(&self, state: u16, id: u16) -> u16 {
        unsafe { ffi::ts_language_next_state(self.0, state, id) }
    }

    /// Create a new lookahead iterator for this language and parse state.
    ///
    /// This returns `None` if state is invalid for this language.
    ///
    /// Iterating [`LookaheadIterator`] will yield valid symbols in the given
    /// parse state. A newly created iterator is not positioned on a symbol, so
    /// [`LookaheadIterator::current_symbol`] returns `None` until the first
    /// [`Iterator::next`] call.
    ///
    /// The iterator retains the language, so the language may be dropped while
    /// the iterator is still in use.
    ///
    /// Lookahead iterators can be useful to generate suggestions and improve
    /// syntax error diagnostics. To get symbols valid in an `ERROR` node, use the
    /// lookahead iterator on its first leaf node state. For a missing node, use
    /// the node's [`parse_state`](Node::parse_state). Keep in mind that lookahead
    /// symbols are valid in that parse state, but are not necessarily valid
    /// continuations in the context of the actual following token or guaranteed
    /// to be considered during error recovery.
    #[doc(alias = "ts_lookahead_iterator_new")]
    #[must_use]
    pub fn lookahead_iterator(&self, state: u16) -> Option<LookaheadIterator> {
        let ptr = unsafe { ffi::ts_lookahead_iterator_new(self.0, state) };
        (!ptr.is_null()).then(|| unsafe { LookaheadIterator::from_raw(ptr) })
    }
}

impl From<LanguageFn> for Language {
    fn from(value: LanguageFn) -> Self {
        Self::new(value)
    }
}

impl Clone for Language {
    fn clone(&self) -> Self {
        unsafe { Self(ffi::ts_language_copy(self.0)) }
    }
}

impl Drop for Language {
    fn drop(&mut self) {
        unsafe { ffi::ts_language_delete(self.0) }
    }
}

impl Deref for LanguageRef<'_> {
    type Target = Language;

    fn deref(&self) -> &Self::Target {
        unsafe { &*(core::ptr::addr_of!(self.0).cast::<Language>()) }
    }
}

impl Default for Parser {
    fn default() -> Self {
        Self::new()
    }
}

impl Parser {
    /// Create a new parser.
    #[doc(alias = "ts_parser_new")]
    #[must_use]
    pub fn new() -> Self {
        unsafe {
            let parser = ffi::ts_parser_new();
            Self(NonNull::new_unchecked(parser))
        }
    }

    /// Set the language that the parser should use for parsing.
    ///
    /// Returns a Result indicating whether or not the language was successfully
    /// assigned. Assignment fails if the language cannot be used for parsing,
    /// or if it was generated with an incompatible version of the Tree-sitter
    /// CLI. Check this using [`Language::is_parseable`] and
    /// [`Language::abi_version`].
    #[doc(alias = "ts_parser_set_language")]
    pub fn set_language(&mut self, language: &Language) -> Result<(), LanguageError> {
        let version = language.abi_version();
        if (MIN_COMPATIBLE_LANGUAGE_VERSION..=LANGUAGE_VERSION).contains(&version) {
            if !language.is_parseable() {
                return Err(LanguageError::NotParseable);
            }
            #[cfg_attr(
                not(feature = "wasm"),
                expect(unused_variables, reason = "only used when wasm feature is enabled")
            )]
            let success = unsafe { ffi::ts_parser_set_language(self.0.as_ptr(), language.0) };
            #[cfg(feature = "wasm")]
            if !success {
                return Err(LanguageError::Wasm);
            }
            Ok(())
        } else {
            Err(LanguageError::Version(version))
        }
    }

    /// Get the parser's current language.
    #[doc(alias = "ts_parser_language")]
    #[must_use]
    pub fn language(&self) -> Option<LanguageRef<'_>> {
        let ptr = unsafe { ffi::ts_parser_language(self.0.as_ptr()) };
        (!ptr.is_null()).then_some(LanguageRef(ptr, PhantomData))
    }

    /// Get the parser's current logger.
    #[doc(alias = "ts_parser_logger")]
    #[must_use]
    pub fn logger(&self) -> Option<&Logger> {
        let logger = unsafe { ffi::ts_parser_logger(self.0.as_ptr()) };
        unsafe { logger.payload.cast::<Logger>().as_ref() }
    }

    /// Set the logging callback that the parser should use during parsing.
    ///
    /// To log through a callback that borrows non-`'static` data, see
    /// [`set_logger_unchecked`](Parser::set_logger_unchecked).
    #[doc(alias = "ts_parser_set_logger")]
    pub fn set_logger(&mut self, logger: Option<Logger>) {
        // SAFETY: `Logger` is `Send + 'static`
        unsafe { self.set_logger_unchecked(logger) };
    }

    /// Set the logging callback, allowing the callback to borrow non-`'static`
    /// data. See [`set_logger`](Parser::set_logger).
    ///
    /// # Safety
    ///
    /// Any data borrowed by `logger` must remain valid until the logger is
    /// removed. Equivalently, the parser must not be used to parse once the
    /// borrowed data has gone out of scope.
    pub unsafe fn set_logger_unchecked(&mut self, logger: Option<UnsafeLogger<'_>>) {
        let prev_logger = unsafe { ffi::ts_parser_logger(self.0.as_ptr()) };
        if !prev_logger.payload.is_null() {
            drop(unsafe { Box::from_raw(prev_logger.payload.cast::<Logger>()) });
        }

        let c_logger = if let Some(logger) = logger {
            let container = Box::new(logger);

            unsafe extern "C" fn log(
                payload: *mut c_void,
                c_log_type: ffi::TSLogType,
                c_message: *const c_char,
            ) {
                unsafe {
                    let callback = payload.cast::<Logger>().as_mut().unwrap();
                    if let Ok(message) = CStr::from_ptr(c_message).to_str() {
                        let log_type = if c_log_type == ffi::TSLogTypeParse {
                            LogType::Parse
                        } else {
                            LogType::Lex
                        };
                        callback(log_type, message);
                    }
                }
            }

            let raw_container = Box::into_raw(container);

            ffi::TSLogger {
                payload: raw_container.cast::<c_void>(),
                log: Some(log),
            }
        } else {
            ffi::TSLogger {
                payload: ptr::null_mut(),
                log: None,
            }
        };

        unsafe { ffi::ts_parser_set_logger(self.0.as_ptr(), c_logger) };
    }

    /// 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.
    #[doc(alias = "ts_parser_print_dot_graphs")]
    #[cfg(not(target_os = "wasi"))]
    #[cfg(feature = "std")]
    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
    pub fn print_dot_graphs(
        &mut self,
        #[cfg(unix)] file: &impl AsRawFd,
        #[cfg(windows)] file: &impl AsRawHandle,
    ) {
        #[cfg(unix)]
        {
            let fd = file.as_raw_fd();
            unsafe {
                ffi::ts_parser_print_dot_graphs(self.0.as_ptr(), ffi::_ts_dup(fd));
            }
        }

        #[cfg(windows)]
        {
            let handle = file.as_raw_handle();
            unsafe {
                ffi::ts_parser_print_dot_graphs(self.0.as_ptr(), ffi::_ts_dup(handle));
            }
        }
    }

    /// Stop the parser from printing debugging graphs while parsing.
    #[doc(alias = "ts_parser_print_dot_graphs")]
    #[cfg(not(target_os = "wasi"))]
    #[cfg(feature = "std")]
    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
    pub fn stop_printing_dot_graphs(&mut self) {
        unsafe { ffi::ts_parser_print_dot_graphs(self.0.as_ptr(), -1) }
    }

    /// 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`]
    #[doc(alias = "ts_parser_parse")]
    pub fn parse(&mut self, text: impl AsRef<[u8]>, old_tree: Option<&Tree>) -> Option<Tree> {
        let bytes = text.as_ref();
        let len = bytes.len();
        self.parse_with_options(
            &mut |i, _| {
                if i < len {
                    &bytes[i..]
                } else {
                    Default::default()
                }
            },
            old_tree,
            None,
        )
    }

    /// Parse 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`].
    /// * `options` Options for parsing the text. This can be used to set a progress callback.
    pub fn parse_with_options<T: AsRef<[u8]>, F: FnMut(usize, Point) -> T>(
        &mut self,
        callback: &mut F,
        old_tree: Option<&Tree>,
        options: Option<ParseOptions>,
    ) -> Option<Tree> {
        type Payload<'a, F, T> = (&'a mut F, Option<T>);

        // This C function is passed to Tree-sitter as the progress callback.
        unsafe extern "C" fn progress(state: *mut ffi::TSParseState) -> bool {
            unsafe {
                let callback = (*state)
                    .payload
                    .cast::<ParseProgressCallback>()
                    .as_mut()
                    .unwrap();
                match callback(&ParseState::from_raw(state)) {
                    ControlFlow::Continue(()) => false,
                    ControlFlow::Break(()) => true,
                }
            }
        }

        // This C function is passed to Tree-sitter as the input callback.
        unsafe extern "C" fn read<T: AsRef<[u8]>, F: FnMut(usize, Point) -> T>(
            payload: *mut c_void,
            byte_offset: u32,
            position: ffi::TSPoint,
            bytes_read: *mut u32,
        ) -> *const c_char {
            unsafe {
                let (callback, text) = payload.cast::<Payload<F, T>>().as_mut().unwrap();
                *text = Some(callback(byte_offset as usize, position.into()));
                let slice = text.as_ref().unwrap().as_ref();
                *bytes_read = slice.len() as u32;
                slice.as_ptr().cast::<c_char>()
            }
        }

        let empty_options = ffi::TSParseOptions {
            payload: ptr::null_mut(),
            progress_callback: None,
        };

        let mut callback_ptr;
        let parse_options = if let Some(options) = options {
            if let Some(cb) = options.progress_callback {
                callback_ptr = cb;
                ffi::TSParseOptions {
                    payload: core::ptr::addr_of_mut!(callback_ptr).cast::<c_void>(),
                    progress_callback: Some(progress),
                }
            } else {
                empty_options
            }
        } else {
            empty_options
        };

        // A pointer to this payload is passed on every call to the `read` C function.
        // The payload contains two things:
        // 1. A reference to the rust `callback`.
        // 2. The text that was returned from the previous call to `callback`. This allows the
        //    callback to return owned values like vectors.
        let mut payload: Payload<F, T> = (callback, None);

        let c_input = ffi::TSInput {
            payload: ptr::addr_of_mut!(payload).cast::<c_void>(),
            read: Some(read::<T, F>),
            encoding: ffi::TSInputEncodingUTF8,
            decode: None,
        };

        let c_old_tree = old_tree.map_or(ptr::null_mut(), |t| t.0.as_ptr());
        unsafe {
            let c_new_tree = ffi::ts_parser_parse_with_options(
                self.0.as_ptr(),
                c_old_tree,
                c_input,
                parse_options,
            );

            NonNull::new(c_new_tree).map(Tree)
        }
    }

    /// Parse a slice of UTF16 little-endian 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_utf16_le(
        &mut self,
        input: impl AsRef<[u16]>,
        old_tree: Option<&Tree>,
    ) -> Option<Tree> {
        let code_points = input.as_ref();
        let len = code_points.len();
        self.parse_utf16_le_with_options(
            &mut |i, _| {
                if i < len {
                    &code_points[i..]
                } else {
                    Default::default()
                }
            },
            old_tree,
            None,
        )
    }

    /// Parse UTF16 little-endian 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`].
    /// * `options` Options for parsing the text. This can be used to set a progress callback.
    pub fn parse_utf16_le_with_options<T: AsRef<[u16]>, F: FnMut(usize, Point) -> T>(
        &mut self,
        callback: &mut F,
        old_tree: Option<&Tree>,
        options: Option<ParseOptions>,
    ) -> Option<Tree> {
        type Payload<'a, F, T> = (&'a mut F, Option<T>);

        unsafe extern "C" fn progress(state: *mut ffi::TSParseState) -> bool {
            unsafe {
                let callback = (*state)
                    .payload
                    .cast::<ParseProgressCallback>()
                    .as_mut()
                    .unwrap();
                match callback(&ParseState::from_raw(state)) {
                    ControlFlow::Continue(()) => false,
                    ControlFlow::Break(()) => true,
                }
            }
        }

        // This C function is passed to Tree-sitter as the input callback.
        unsafe extern "C" fn read<T: AsRef<[u16]>, F: FnMut(usize, Point) -> T>(
            payload: *mut c_void,
            byte_offset: u32,
            position: ffi::TSPoint,
            bytes_read: *mut u32,
        ) -> *const c_char {
            unsafe {
                let (callback, text) = payload.cast::<Payload<F, T>>().as_mut().unwrap();
                *text = Some(callback(
                    (byte_offset / 2) as usize,
                    Point {
                        row: position.row as usize,
                        column: position.column as usize / 2,
                    },
                ));
                let slice = text.as_ref().unwrap().as_ref();
                *bytes_read = slice.len() as u32 * 2;
                slice.as_ptr().cast::<c_char>()
            }
        }

        let empty_options = ffi::TSParseOptions {
            payload: ptr::null_mut(),
            progress_callback: None,
        };

        let mut callback_ptr;
        let parse_options = if let Some(options) = options {
            if let Some(cb) = options.progress_callback {
                callback_ptr = cb;
                ffi::TSParseOptions {
                    payload: core::ptr::addr_of_mut!(callback_ptr).cast::<c_void>(),
                    progress_callback: Some(progress),
                }
            } else {
                empty_options
            }
        } else {
            empty_options
        };

        // A pointer to this payload is passed on every call to the `read` C function.
        // The payload contains two things:
        // 1. A reference to the rust `callback`.
        // 2. The text that was returned from the previous call to `callback`. This allows the
        //    callback to return owned values like vectors.
        let mut payload: Payload<F, T> = (callback, None);

        let c_input = ffi::TSInput {
            payload: core::ptr::addr_of_mut!(payload).cast::<c_void>(),
            read: Some(read::<T, F>),
            encoding: ffi::TSInputEncodingUTF16LE,
            decode: None,
        };

        let c_old_tree = old_tree.map_or(ptr::null_mut(), |t| t.0.as_ptr());
        unsafe {
            let c_new_tree = ffi::ts_parser_parse_with_options(
                self.0.as_ptr(),
                c_old_tree,
                c_input,
                parse_options,
            );

            NonNull::new(c_new_tree).map(Tree)
        }
    }

    /// Parse a slice of UTF16 big-endian 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_utf16_be(
        &mut self,
        input: impl AsRef<[u16]>,
        old_tree: Option<&Tree>,
    ) -> Option<Tree> {
        let code_points = input.as_ref();
        let len = code_points.len();
        self.parse_utf16_be_with_options(
            &mut |i, _| if i < len { &code_points[i..] } else { &[] },
            old_tree,
            None,
        )
    }

    /// Parse UTF16 big-endian 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`].
    /// * `options` Options for parsing the text. This can be used to set a progress callback.
    pub fn parse_utf16_be_with_options<T: AsRef<[u16]>, F: FnMut(usize, Point) -> T>(
        &mut self,
        callback: &mut F,
        old_tree: Option<&Tree>,
        options: Option<ParseOptions>,
    ) -> Option<Tree> {
        type Payload<'a, F, T> = (&'a mut F, Option<T>);

        // This C function is passed to Tree-sitter as the progress callback.
        unsafe extern "C" fn progress(state: *mut ffi::TSParseState) -> bool {
            unsafe {
                let callback = (*state)
                    .payload
                    .cast::<ParseProgressCallback>()
                    .as_mut()
                    .unwrap();
                match callback(&ParseState::from_raw(state)) {
                    ControlFlow::Continue(()) => false,
                    ControlFlow::Break(()) => true,
                }
            }
        }

        // This C function is passed to Tree-sitter as the input callback.
        unsafe extern "C" fn read<T: AsRef<[u16]>, F: FnMut(usize, Point) -> T>(
            payload: *mut c_void,
            byte_offset: u32,
            position: ffi::TSPoint,
            bytes_read: *mut u32,
        ) -> *const c_char {
            unsafe {
                let (callback, text) = payload.cast::<Payload<F, T>>().as_mut().unwrap();
                *text = Some(callback(
                    (byte_offset / 2) as usize,
                    Point {
                        row: position.row as usize,
                        column: position.column as usize / 2,
                    },
                ));
                let slice = text.as_ref().unwrap().as_ref();
                *bytes_read = slice.len() as u32 * 2;
                slice.as_ptr().cast::<c_char>()
            }
        }

        let empty_options = ffi::TSParseOptions {
            payload: ptr::null_mut(),
            progress_callback: None,
        };

        let mut callback_ptr;
        let parse_options = if let Some(options) = options {
            if let Some(cb) = options.progress_callback {
                callback_ptr = cb;
                ffi::TSParseOptions {
                    payload: core::ptr::addr_of_mut!(callback_ptr).cast::<c_void>(),
                    progress_callback: Some(progress),
                }
            } else {
                empty_options
            }
        } else {
            empty_options
        };

        // A pointer to this payload is passed on every call to the `read` C function.
        // The payload contains two things:
        // 1. A reference to the rust `callback`.
        // 2. The text that was returned from the previous call to `callback`. This allows the
        //    callback to return owned values like vectors.
        let mut payload: Payload<F, T> = (callback, None);

        let c_input = ffi::TSInput {
            payload: core::ptr::addr_of_mut!(payload).cast::<c_void>(),
            read: Some(read::<T, F>),
            encoding: ffi::TSInputEncodingUTF16BE,
            decode: None,
        };

        let c_old_tree = old_tree.map_or(ptr::null_mut(), |t| t.0.as_ptr());
        unsafe {
            let c_new_tree = ffi::ts_parser_parse_with_options(
                self.0.as_ptr(),
                c_old_tree,
                c_input,
                parse_options,
            );

            NonNull::new(c_new_tree).map(Tree)
        }
    }

    /// Parse text provided in chunks by a callback using a custom encoding.
    /// This is useful for parsing text in encodings that are not UTF-8 or UTF-16.
    ///
    /// # Arguments:
    /// * `callback` A function that takes a byte offset and position and returns a slice of 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`].
    /// * `options` Options for parsing the text. This can be used to set a progress callback.
    ///
    /// Additionally, you must set the generic parameter [`D`] to a type that implements the
    /// [`Decode`] trait. This trait has a single method, [`decode`](Decode::decode), which takes a
    /// slice of bytes and returns a tuple of the code point and the number of bytes consumed.
    /// The `decode` method should return `-1` for the code point if decoding fails.
    pub fn parse_custom_encoding<D: Decode, T: AsRef<[u8]>, F: FnMut(usize, Point) -> T>(
        &mut self,
        callback: &mut F,
        old_tree: Option<&Tree>,
        options: Option<ParseOptions>,
    ) -> Option<Tree> {
        type Payload<'a, F, T> = (&'a mut F, Option<T>);

        unsafe extern "C" fn progress(state: *mut ffi::TSParseState) -> bool {
            unsafe {
                let callback = (*state)
                    .payload
                    .cast::<ParseProgressCallback>()
                    .as_mut()
                    .unwrap();
                match callback(&ParseState::from_raw(state)) {
                    ControlFlow::Continue(()) => false,
                    ControlFlow::Break(()) => true,
                }
            }
        }

        // At compile time, create a C-compatible callback that calls the custom `decode` method.
        unsafe extern "C" fn decode_fn<D: Decode>(
            data: *const u8,
            len: u32,
            code_point: *mut i32,
        ) -> u32 {
            unsafe {
                let (c, len) = D::decode(core::slice::from_raw_parts(data, len as usize));
                if let Some(code_point) = code_point.as_mut() {
                    *code_point = c;
                }
                len
            }
        }

        // This C function is passed to Tree-sitter as the input callback.
        unsafe extern "C" fn read<T: AsRef<[u8]>, F: FnMut(usize, Point) -> T>(
            payload: *mut c_void,
            byte_offset: u32,
            position: ffi::TSPoint,
            bytes_read: *mut u32,
        ) -> *const c_char {
            unsafe {
                let (callback, text) = payload.cast::<Payload<F, T>>().as_mut().unwrap();
                *text = Some(callback(byte_offset as usize, position.into()));
                let slice = text.as_ref().unwrap().as_ref();
                *bytes_read = slice.len() as u32;
                slice.as_ptr().cast::<c_char>()
            }
        }

        let empty_options = ffi::TSParseOptions {
            payload: ptr::null_mut(),
            progress_callback: None,
        };

        let mut callback_ptr;
        let parse_options = if let Some(options) = options {
            if let Some(cb) = options.progress_callback {
                callback_ptr = cb;
                ffi::TSParseOptions {
                    payload: core::ptr::addr_of_mut!(callback_ptr).cast::<c_void>(),
                    progress_callback: Some(progress),
                }
            } else {
                empty_options
            }
        } else {
            empty_options
        };

        // A pointer to this payload is passed on every call to the `read` C function.
        // The payload contains two things:
        // 1. A reference to the rust `callback`.
        // 2. The text that was returned from the previous call to `callback`. This allows the
        //    callback to return owned values like vectors.
        let mut payload: Payload<F, T> = (callback, None);

        let c_input = ffi::TSInput {
            payload: core::ptr::addr_of_mut!(payload).cast::<c_void>(),
            read: Some(read::<T, F>),
            encoding: ffi::TSInputEncodingCustom,
            // Use this custom decode callback
            decode: Some(decode_fn::<D>),
        };

        let c_old_tree = old_tree.map_or(ptr::null_mut(), |t| t.0.as_ptr());
        unsafe {
            let c_new_tree = ffi::ts_parser_parse_with_options(
                self.0.as_ptr(),
                c_old_tree,
                c_input,
                parse_options,
            );

            NonNull::new(c_new_tree).map(Tree)
        }
    }

    /// Instruct the parser to start the next parse from the beginning.
    ///
    /// If the parser previously failed because of a callback, then by default,
    /// it will resume where it left off on the next call to [`parse`](Parser::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.
    #[doc(alias = "ts_parser_reset")]
    pub fn reset(&mut self) {
        unsafe { ffi::ts_parser_reset(self.0.as_ptr()) }
    }

    /// 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`:
    /// ```text
    ///     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.
    #[doc(alias = "ts_parser_set_included_ranges")]
    pub fn set_included_ranges(&mut self, ranges: &[Range]) -> Result<(), IncludedRangesError> {
        let ts_ranges = ranges.iter().copied().map(Into::into).collect::<Vec<_>>();
        let result = unsafe {
            ffi::ts_parser_set_included_ranges(
                self.0.as_ptr(),
                ts_ranges.as_ptr(),
                ts_ranges.len() as u32,
            )
        };

        if result {
            Ok(())
        } else {
            let mut prev_end_byte = 0;
            for (i, range) in ranges.iter().enumerate() {
                if range.start_byte < prev_end_byte || range.end_byte < range.start_byte {
                    return Err(IncludedRangesError(i));
                }
                prev_end_byte = range.end_byte;
            }
            Err(IncludedRangesError(0))
        }
    }

    /// Get the ranges of text that the parser will include when parsing.
    #[doc(alias = "ts_parser_included_ranges")]
    #[must_use]
    pub fn included_ranges(&self) -> Vec<Range> {
        let mut count = 0u32;
        unsafe {
            let ptr =
                ffi::ts_parser_included_ranges(self.0.as_ptr(), core::ptr::addr_of_mut!(count));
            let ranges = slice::from_raw_parts(ptr, count as usize);
            ranges.iter().copied().map(Into::into).collect()
        }
    }
}

impl Drop for Parser {
    fn drop(&mut self) {
        #[cfg(feature = "std")]
        #[cfg(not(target_os = "wasi"))]
        {
            self.stop_printing_dot_graphs();
        }
        self.set_logger(None);
        unsafe { ffi::ts_parser_delete(self.0.as_ptr()) }
    }
}

#[cfg(windows)]
unsafe extern "C" {
    fn _open_osfhandle(osfhandle: isize, flags: core::ffi::c_int) -> core::ffi::c_int;
}

impl Tree {
    /// Get the root node of the syntax tree.
    #[doc(alias = "ts_tree_root_node")]
    #[must_use]
    pub fn root_node(&self) -> Node {
        Node::new(unsafe { ffi::ts_tree_root_node(self.0.as_ptr()) }).unwrap()
    }

    /// Get the root node of the syntax tree, but with its position shifted
    /// forward by the given offset.
    #[doc(alias = "ts_tree_root_node_with_offset")]
    #[must_use]
    pub fn root_node_with_offset(&self, offset_bytes: usize, offset_extent: Point) -> Node {
        Node::new(unsafe {
            ffi::ts_tree_root_node_with_offset(
                self.0.as_ptr(),
                offset_bytes as u32,
                offset_extent.into(),
            )
        })
        .unwrap()
    }

    /// Get the language that was used to parse the syntax tree.
    ///
    /// When Tree-sitter is compiled to WebAssembly, this returns the original
    /// language if the tree is being accessed from the same WebAssembly
    /// instance that created it. Otherwise, this returns a copy of the language
    /// that can be used to inspect the tree but cannot be assigned to a parser.
    #[doc(alias = "ts_tree_language")]
    #[must_use]
    pub fn language(&self) -> LanguageRef {
        LanguageRef(
            unsafe { ffi::ts_tree_language(self.0.as_ptr()) },
            PhantomData,
        )
    }

    /// Edit the syntax tree to keep it in sync with source code that has been
    /// edited.
    ///
    /// You must describe the edit both in terms of byte offsets and in terms of
    /// row/column coordinates.
    #[doc(alias = "ts_tree_edit")]
    pub fn edit(&mut self, edit: &InputEdit) {
        let edit = edit.into();
        unsafe { ffi::ts_tree_edit(self.0.as_ptr(), &raw const edit) };
    }

    /// Create a new [`TreeCursor`] starting from the root of the tree.
    #[must_use]
    pub fn walk(&self) -> TreeCursor {
        self.root_node().walk()
    }

    /// Compare this old edited syntax tree to a new syntax tree representing
    /// the same document, returning a sequence of ranges whose syntactic
    /// structure has changed.
    ///
    /// For this to work correctly, this syntax tree must have been edited such
    /// that its ranges match up to the new tree. Generally, you'll want to
    /// call this method right after calling one of the [`Parser::parse`]
    /// functions. Call it on the old tree that was passed to parse, and
    /// pass the new tree that was returned from `parse`.
    #[doc(alias = "ts_tree_get_changed_ranges")]
    pub fn changed_ranges(&self, other: &Self) -> impl ExactSizeIterator<Item = Range> {
        let mut count = 0u32;
        unsafe {
            let ptr = ffi::ts_tree_get_changed_ranges(
                self.0.as_ptr(),
                other.0.as_ptr(),
                core::ptr::addr_of_mut!(count),
            );
            util::CBufferIter::new(ptr, count as usize).map(Into::into)
        }
    }

    /// Get the included ranges that were used to parse the syntax tree.
    #[doc(alias = "ts_tree_included_ranges")]
    #[must_use]
    pub fn included_ranges(&self) -> Vec<Range> {
        let mut count = 0u32;
        unsafe {
            let ptr = ffi::ts_tree_included_ranges(self.0.as_ptr(), core::ptr::addr_of_mut!(count));
            let ranges = slice::from_raw_parts(ptr, count as usize);
            let result = ranges.iter().copied().map(Into::into).collect();
            ts_free(ptr.cast::<c_void>());
            result
        }
    }

    /// Print a graph of the tree to the given file descriptor.
    /// The graph is formatted in the DOT language. You may want to pipe this
    /// graph directly to a `dot(1)` process in order to generate SVG
    /// output.
    #[doc(alias = "ts_tree_print_dot_graph")]
    #[cfg(not(target_os = "wasi"))]
    #[cfg(feature = "std")]
    #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
    pub fn print_dot_graph(
        &self,
        #[cfg(unix)] file: &impl AsRawFd,
        #[cfg(windows)] file: &impl AsRawHandle,
    ) {
        #[cfg(unix)]
        {
            let fd = file.as_raw_fd();
            unsafe { ffi::ts_tree_print_dot_graph(self.0.as_ptr(), fd) }
        }

        #[cfg(windows)]
        {
            let handle = file.as_raw_handle();
            let fd = unsafe { _open_osfhandle(handle as isize, 0) };
            unsafe { ffi::ts_tree_print_dot_graph(self.0.as_ptr(), fd) }
        }
    }
}

impl fmt::Debug for Tree {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "{{Tree {:?}}}", self.root_node())
    }
}

impl Drop for Tree {
    fn drop(&mut self) {
        unsafe { ffi::ts_tree_delete(self.0.as_ptr()) }
    }
}

impl Clone for Tree {
    fn clone(&self) -> Self {
        unsafe { Self(NonNull::new_unchecked(ffi::ts_tree_copy(self.0.as_ptr()))) }
    }
}

impl<'tree> Node<'tree> {
    fn new(node: ffi::TSNode) -> Option<Self> {
        (!node.id.is_null()).then_some(Node(node, PhantomData))
    }

    /// Get a numeric id for this node that is unique.
    ///
    /// Within a given syntax tree, no two nodes have the same id. However:
    ///
    /// - If a new tree is created based on an older tree, and a node from the old tree is reused in
    ///   the process, then that node will have the same id in both trees.
    ///
    /// - A node not marked as having changes does not guarantee it was reused.
    ///
    /// - If a node is marked as having changed in the old tree, it will not be reused.
    #[must_use]
    pub fn id(&self) -> usize {
        self.0.id as usize
    }

    /// Get this node's type as a numerical id.
    #[doc(alias = "ts_node_symbol")]
    #[must_use]
    pub fn kind_id(&self) -> u16 {
        unsafe { ffi::ts_node_symbol(self.0) }
    }

    /// Get the node's type as a numerical id as it appears in the grammar
    /// ignoring aliases.
    #[doc(alias = "ts_node_grammar_symbol")]
    #[must_use]
    pub fn grammar_id(&self) -> u16 {
        unsafe { ffi::ts_node_grammar_symbol(self.0) }
    }

    /// Get this node's type as a string.
    #[doc(alias = "ts_node_type")]
    #[must_use]
    pub fn kind(&self) -> &'tree str {
        let ptr = unsafe { ffi::ts_node_type(self.0) };
        assert!(!ptr.is_null());
        unsafe { CStr::from_ptr(ptr) }.to_str().unwrap()
    }

    /// Get this node's symbol name as it appears in the grammar ignoring
    /// aliases as a string.
    #[doc(alias = "ts_node_grammar_type")]
    #[must_use]
    pub fn grammar_name(&self) -> &'tree str {
        let ptr = unsafe { ffi::ts_node_grammar_type(self.0) };
        assert!(!ptr.is_null());
        unsafe { CStr::from_ptr(ptr) }.to_str().unwrap()
    }

    /// Get the [`Language`] that was used to parse this node's syntax tree.
    ///
    /// When Tree-sitter is compiled to WebAssembly, this returns the original
    /// language if the node is being accessed from the same WebAssembly
    /// instance that created its tree. Otherwise, this returns a copy of the
    /// language that can be used to inspect the tree but cannot be assigned to
    /// a parser.
    #[doc(alias = "ts_node_language")]
    #[must_use]
    pub fn language(&self) -> LanguageRef<'tree> {
        LanguageRef(unsafe { ffi::ts_node_language(self.0) }, PhantomData)
    }

    /// Check if this node is *named*.
    ///
    /// Named nodes correspond to named rules in the grammar, whereas
    /// *anonymous* nodes correspond to string literals in the grammar.
    #[doc(alias = "ts_node_is_named")]
    #[must_use]
    pub fn is_named(&self) -> bool {
        unsafe { ffi::ts_node_is_named(self.0) }
    }

    /// Check if this node is *extra*.
    ///
    /// Extra nodes represent things like comments, which are not required by the
    /// grammar, but can appear anywhere.
    #[doc(alias = "ts_node_is_extra")]
    #[must_use]
    pub fn is_extra(&self) -> bool {
        unsafe { ffi::ts_node_is_extra(self.0) }
    }

    /// Check if this node has been edited.
    #[doc(alias = "ts_node_has_changes")]
    #[must_use]
    pub fn has_changes(&self) -> bool {
        unsafe { ffi::ts_node_has_changes(self.0) }
    }

    /// Check if this node represents a syntax error or contains any syntax
    /// errors anywhere within it.
    #[doc(alias = "ts_node_has_error")]
    #[must_use]
    pub fn has_error(&self) -> bool {
        unsafe { ffi::ts_node_has_error(self.0) }
    }

    /// Check if this node represents a syntax error.
    ///
    /// Syntax errors represent parts of the code that could not be incorporated
    /// into a valid syntax tree.
    #[doc(alias = "ts_node_is_error")]
    #[must_use]
    pub fn is_error(&self) -> bool {
        unsafe { ffi::ts_node_is_error(self.0) }
    }

    /// Get the parse state immediately before this node.
    ///
    /// For a missing node, this is the state from the recovery path that was
    /// selected by the parser. It can be used with
    /// [`Language::lookahead_iterator`] to inspect the symbols that are valid in
    /// that state. This does not necessarily include every symbol that could be
    /// recovered by inserting a missing node, because the recovery process can
    /// consider multiple stack versions.
    #[doc(alias = "ts_node_parse_state")]
    #[must_use]
    pub fn parse_state(&self) -> u16 {
        unsafe { ffi::ts_node_parse_state(self.0) }
    }

    /// Get the parse state after this node.
    #[doc(alias = "ts_node_next_parse_state")]
    #[must_use]
    pub fn next_parse_state(&self) -> u16 {
        unsafe { ffi::ts_node_next_parse_state(self.0) }
    }

    /// Check if this node is *missing*.
    ///
    /// Missing nodes are inserted by the parser in order to recover from
    /// certain kinds of syntax errors.
    #[doc(alias = "ts_node_is_missing")]
    #[must_use]
    pub fn is_missing(&self) -> bool {
        unsafe { ffi::ts_node_is_missing(self.0) }
    }

    /// Get the byte offset where this node starts.
    #[doc(alias = "ts_node_start_byte")]
    #[must_use]
    pub fn start_byte(&self) -> usize {
        unsafe { ffi::ts_node_start_byte(self.0) as usize }
    }

    /// Get the byte offset where this node ends.
    #[doc(alias = "ts_node_end_byte")]
    #[must_use]
    pub fn end_byte(&self) -> usize {
        unsafe { ffi::ts_node_end_byte(self.0) as usize }
    }

    /// Get the byte range of source code that this node represents.
    #[must_use]
    pub fn byte_range(&self) -> core::ops::Range<usize> {
        self.start_byte()..self.end_byte()
    }

    /// Get the range of source code that this node represents, both in terms of
    /// raw bytes and of row/column coordinates.
    #[must_use]
    pub fn range(&self) -> Range {
        Range {
            start_byte: self.start_byte(),
            end_byte: self.end_byte(),
            start_point: self.start_position(),
            end_point: self.end_position(),
        }
    }

    /// Get this node's start position in terms of rows and columns.
    #[doc(alias = "ts_node_start_point")]
    #[must_use]
    pub fn start_position(&self) -> Point {
        let result = unsafe { ffi::ts_node_start_point(self.0) };
        result.into()
    }

    /// Get this node's end position in terms of rows and columns.
    #[doc(alias = "ts_node_end_point")]
    #[must_use]
    pub fn end_position(&self) -> Point {
        let result = unsafe { ffi::ts_node_end_point(self.0) };
        result.into()
    }

    /// Get the node's child at the given index, where zero represents the first
    /// child.
    ///
    /// This method is fairly fast, but its cost is technically log(i), so if
    /// you might be iterating over a long list of children, you should use
    /// [`Node::children`] instead.
    #[doc(alias = "ts_node_child")]
    #[must_use]
    pub fn child(&self, i: u32) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_child(self.0, i) })
    }

    /// Get this node's number of children.
    #[doc(alias = "ts_node_child_count")]
    #[must_use]
    pub fn child_count(&self) -> u32 {
        unsafe { ffi::ts_node_child_count(self.0) }
    }

    /// Get this node's *named* child at the given index.
    ///
    /// See also [`Node::is_named`].
    /// This method is fairly fast, but its cost is technically log(i), so if
    /// you might be iterating over a long list of children, you should use
    /// [`Node::named_children`] instead.
    #[doc(alias = "ts_node_named_child")]
    #[must_use]
    pub fn named_child(&self, i: u32) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_named_child(self.0, i) })
    }

    /// Get this node's number of *named* children.
    ///
    /// See also [`Node::is_named`].
    #[doc(alias = "ts_node_named_child_count")]
    #[must_use]
    pub fn named_child_count(&self) -> usize {
        unsafe { ffi::ts_node_named_child_count(self.0) as usize }
    }

    /// Get the first child with the given field name.
    ///
    /// If multiple children may have the same field name, access them using
    /// [`children_by_field_name`](Node::children_by_field_name)
    #[doc(alias = "ts_node_child_by_field_name")]
    #[must_use]
    pub fn child_by_field_name(&self, field_name: impl AsRef<[u8]>) -> Option<Self> {
        let field_name = field_name.as_ref();
        Self::new(unsafe {
            ffi::ts_node_child_by_field_name(
                self.0,
                field_name.as_ptr().cast::<c_char>(),
                field_name.len() as u32,
            )
        })
    }

    /// Get this node's child with the given numerical field id.
    ///
    /// See also [`child_by_field_name`](Node::child_by_field_name). You can
    /// convert a field name to an id using [`Language::field_id_for_name`].
    #[doc(alias = "ts_node_child_by_field_id")]
    #[must_use]
    pub fn child_by_field_id(&self, field_id: u16) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_child_by_field_id(self.0, field_id) })
    }

    /// Get the field name of this node's child at the given index.
    #[doc(alias = "ts_node_field_name_for_child")]
    #[must_use]
    pub fn field_name_for_child(&self, child_index: u32) -> Option<&'tree str> {
        unsafe {
            let ptr = ffi::ts_node_field_name_for_child(self.0, child_index);
            (!ptr.is_null()).then(|| CStr::from_ptr(ptr).to_str().unwrap())
        }
    }

    /// Get the field name of this node's named child at the given index.
    #[must_use]
    pub fn field_name_for_named_child(&self, named_child_index: u32) -> Option<&'tree str> {
        unsafe {
            let ptr = ffi::ts_node_field_name_for_named_child(self.0, named_child_index);
            (!ptr.is_null()).then(|| CStr::from_ptr(ptr).to_str().unwrap())
        }
    }

    /// Iterate over this node's children.
    ///
    /// A [`TreeCursor`] is used to retrieve the children efficiently. Obtain
    /// a [`TreeCursor`] by calling [`Tree::walk`] or [`Node::walk`]. To avoid
    /// unnecessary allocations, you should reuse the same cursor for
    /// subsequent calls to this method.
    ///
    /// If you're walking the tree recursively, you may want to use the
    /// [`TreeCursor`] APIs directly instead.
    pub fn children<'cursor>(
        &self,
        cursor: &'cursor mut TreeCursor<'tree>,
    ) -> impl ExactSizeIterator<Item = Node<'tree>> + 'cursor {
        cursor.reset(*self);
        cursor.goto_first_child();
        (0..self.child_count()).map(move |_| {
            let result = cursor.node();
            cursor.goto_next_sibling();
            result
        })
    }

    /// Iterate over this node's named children.
    ///
    /// See also [`Node::children`].
    pub fn named_children<'cursor>(
        &self,
        cursor: &'cursor mut TreeCursor<'tree>,
    ) -> impl ExactSizeIterator<Item = Node<'tree>> + 'cursor {
        cursor.reset(*self);
        cursor.goto_first_child();
        (0..self.named_child_count()).map(move |_| {
            while !cursor.node().is_named() {
                if !cursor.goto_next_sibling() {
                    break;
                }
            }
            let result = cursor.node();
            cursor.goto_next_sibling();
            result
        })
    }

    /// Iterate over this node's children with a given field name.
    ///
    /// See also [`Node::children`].
    pub fn children_by_field_name<'cursor>(
        &self,
        field_name: &str,
        cursor: &'cursor mut TreeCursor<'tree>,
    ) -> impl Iterator<Item = Node<'tree>> + 'cursor {
        let field_id = self.language().field_id_for_name(field_name);
        let mut done = field_id.is_none();
        if !done {
            cursor.reset(*self);
            cursor.goto_first_child();
        }
        iter::from_fn(move || {
            if !done {
                while cursor.field_id() != field_id {
                    if !cursor.goto_next_sibling() {
                        return None;
                    }
                }
                let result = cursor.node();
                if !cursor.goto_next_sibling() {
                    done = true;
                }
                return Some(result);
            }
            None
        })
    }

    /// Iterate over this node's children with a given field id.
    ///
    /// See also [`Node::children_by_field_name`].
    pub fn children_by_field_id<'cursor>(
        &self,
        field_id: FieldId,
        cursor: &'cursor mut TreeCursor<'tree>,
    ) -> impl Iterator<Item = Node<'tree>> + 'cursor {
        cursor.reset(*self);
        cursor.goto_first_child();
        let mut done = false;
        iter::from_fn(move || {
            if !done {
                while cursor.field_id() != Some(field_id) {
                    if !cursor.goto_next_sibling() {
                        return None;
                    }
                }
                let result = cursor.node();
                if !cursor.goto_next_sibling() {
                    done = true;
                }
                return Some(result);
            }
            None
        })
    }

    /// Get this node's immediate parent.
    /// Prefer [`child_with_descendant`](Node::child_with_descendant)
    /// for iterating over this node's ancestors.
    #[doc(alias = "ts_node_parent")]
    #[must_use]
    pub fn parent(&self) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_parent(self.0) })
    }

    /// Get the node that contains `descendant`.
    ///
    /// Note that this can return `descendant` itself.
    #[doc(alias = "ts_node_child_with_descendant")]
    #[must_use]
    pub fn child_with_descendant(&self, descendant: Self) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_child_with_descendant(self.0, descendant.0) })
    }

    /// Get this node's next sibling.
    #[doc(alias = "ts_node_next_sibling")]
    #[must_use]
    pub fn next_sibling(&self) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_next_sibling(self.0) })
    }

    /// Get this node's previous sibling.
    #[doc(alias = "ts_node_prev_sibling")]
    #[must_use]
    pub fn prev_sibling(&self) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_prev_sibling(self.0) })
    }

    /// Get this node's next named sibling.
    #[doc(alias = "ts_node_next_named_sibling")]
    #[must_use]
    pub fn next_named_sibling(&self) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_next_named_sibling(self.0) })
    }

    /// Get this node's previous named sibling.
    #[doc(alias = "ts_node_prev_named_sibling")]
    #[must_use]
    pub fn prev_named_sibling(&self) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_prev_named_sibling(self.0) })
    }

    /// Get this node's first child that contains or starts after the given byte offset.
    #[doc(alias = "ts_node_first_child_for_byte")]
    #[must_use]
    pub fn first_child_for_byte(&self, byte: usize) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_first_child_for_byte(self.0, byte as u32) })
    }

    /// Get this node's first named child that contains or starts after the given byte offset.
    #[doc(alias = "ts_node_first_named_child_for_point")]
    #[must_use]
    pub fn first_named_child_for_byte(&self, byte: usize) -> Option<Self> {
        Self::new(unsafe { ffi::ts_node_first_named_child_for_byte(self.0, byte as u32) })
    }

    /// Get the node's number of descendants, including one for the node itself.
    #[doc(alias = "ts_node_descendant_count")]
    #[must_use]
    pub fn descendant_count(&self) -> usize {
        unsafe { ffi::ts_node_descendant_count(self.0) as usize }
    }

    /// Get the smallest node within this node that spans the given byte range.
    #[doc(alias = "ts_node_descendant_for_byte_range")]
    #[must_use]
    pub fn descendant_for_byte_range(&self, start: usize, end: usize) -> Option<Self> {
        Self::new(unsafe {
            ffi::ts_node_descendant_for_byte_range(self.0, start as u32, end as u32)
        })
    }

    /// Get the smallest named node within this node that spans the given byte range.
    #[doc(alias = "ts_node_named_descendant_for_byte_range")]
    #[must_use]
    pub fn named_descendant_for_byte_range(&self, start: usize, end: usize) -> Option<Self> {
        Self::new(unsafe {
            ffi::ts_node_named_descendant_for_byte_range(self.0, start as u32, end as u32)
        })
    }

    /// Get the smallest node within this node that spans the given point range.
    #[doc(alias = "ts_node_descendant_for_point_range")]
    #[must_use]
    pub fn descendant_for_point_range(&self, start: Point, end: Point) -> Option<Self> {
        Self::new(unsafe {
            ffi::ts_node_descendant_for_point_range(self.0, start.into(), end.into())
        })
    }

    /// Get the smallest named node within this node that spans the given point range.
    #[doc(alias = "ts_node_named_descendant_for_point_range")]
    #[must_use]
    pub fn named_descendant_for_point_range(&self, start: Point, end: Point) -> Option<Self> {
        Self::new(unsafe {
            ffi::ts_node_named_descendant_for_point_range(self.0, start.into(), end.into())
        })
    }

    /// Get an S-expression representing the node.
    #[doc(alias = "ts_node_string")]
    #[must_use]
    pub fn to_sexp(&self) -> String {
        let c_string = unsafe { ffi::ts_node_string(self.0) };
        let result = unsafe { CStr::from_ptr(c_string) }
            .to_str()
            .unwrap()
            .to_string();
        unsafe { ts_free(c_string.cast::<c_void>()) };
        result
    }

    pub fn utf8_text<'a>(&self, source: &'a [u8]) -> Result<&'a str, str::Utf8Error> {
        str::from_utf8(&source[self.start_byte()..self.end_byte()])
    }

    #[must_use]
    pub fn utf16_text<'a>(&self, source: &'a [u16]) -> &'a [u16] {
        &source[self.start_byte() / 2..self.end_byte() / 2]
    }

    /// Create a new [`TreeCursor`] starting from this node.
    ///
    /// Note that the given node is considered the root of the cursor,
    /// and the cursor cannot walk outside this node.
    #[doc(alias = "ts_tree_cursor_new")]
    #[must_use]
    pub fn walk(&self) -> TreeCursor<'tree> {
        TreeCursor(unsafe { ffi::ts_tree_cursor_new(self.0) }, PhantomData)
    }

    /// Edit this node to keep it in-sync with source code that has been edited.
    ///
    /// This function is only rarely needed. When you edit a syntax tree with
    /// the [`Tree::edit`] method, all of the nodes that you retrieve from
    /// the tree afterward will already reflect the edit. You only need to
    /// use [`Node::edit`] when you have a specific [`Node`] instance that
    /// you want to keep and continue to use after an edit.
    #[doc(alias = "ts_node_edit")]
    pub fn edit(&mut self, edit: &InputEdit) {
        let edit = edit.into();
        unsafe { ffi::ts_node_edit(core::ptr::addr_of_mut!(self.0), &raw const edit) }
    }
}

impl PartialEq for Node<'_> {
    fn eq(&self, other: &Self) -> bool {
        core::ptr::eq(self.0.id, other.0.id)
    }
}

impl Eq for Node<'_> {}

impl hash::Hash for Node<'_> {
    fn hash<H: hash::Hasher>(&self, state: &mut H) {
        self.0.id.hash(state);
        self.0.context[0].hash(state);
        self.0.context[1].hash(state);
        self.0.context[2].hash(state);
        self.0.context[3].hash(state);
    }
}

impl fmt::Debug for Node<'_> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(
            f,
            "{{Node {} {} - {}}}",
            self.kind(),
            self.start_position(),
            self.end_position()
        )
    }
}

impl fmt::Display for Node<'_> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        if !f.alternate() {
            return f.write_str(&self.to_sexp());
        }
        let c_string = unsafe { ts_node_string_pretty(self.0, f.width().unwrap_or(0)) };
        let result = unsafe { CStr::from_ptr(c_string) }
            .to_str()
            .unwrap()
            .to_string();
        unsafe { ts_free(c_string.cast::<c_void>()) };
        f.write_str(&result)
    }
}

impl<'tree> TreeCursor<'tree> {
    /// Get the tree cursor's current [`Node`].
    #[doc(alias = "ts_tree_cursor_current_node")]
    #[must_use]
    pub fn node(&self) -> Node<'tree> {
        Node(
            unsafe { ffi::ts_tree_cursor_current_node(&raw const self.0) },
            PhantomData,
        )
    }

    /// Get the numerical field id of this tree cursor's current node.
    ///
    /// See also [`field_name`](TreeCursor::field_name).
    #[doc(alias = "ts_tree_cursor_current_field_id")]
    #[must_use]
    pub fn field_id(&self) -> Option<FieldId> {
        let id = unsafe { ffi::ts_tree_cursor_current_field_id(&raw const self.0) };
        FieldId::new(id)
    }

    /// Get the field name of this tree cursor's current node.
    #[doc(alias = "ts_tree_cursor_current_field_name")]
    #[must_use]
    pub fn field_name(&self) -> Option<&'tree str> {
        unsafe {
            let ptr = ffi::ts_tree_cursor_current_field_name(&raw const self.0);
            (!ptr.is_null()).then(|| CStr::from_ptr(ptr).to_str().unwrap())
        }
    }

    /// Get the depth of the cursor's current node relative to the original
    /// node that the cursor was constructed with.
    #[doc(alias = "ts_tree_cursor_current_depth")]
    #[must_use]
    pub fn depth(&self) -> u32 {
        unsafe { ffi::ts_tree_cursor_current_depth(&raw const self.0) }
    }

    /// Get the index of the cursor's current node out of all of the
    /// descendants of the original node that the cursor was constructed with
    #[doc(alias = "ts_tree_cursor_current_descendant_index")]
    #[must_use]
    pub fn descendant_index(&self) -> usize {
        unsafe { ffi::ts_tree_cursor_current_descendant_index(&raw const self.0) as usize }
    }

    /// Move this cursor to the first child of its current node.
    ///
    /// This returns `true` if the cursor successfully moved, and returns
    /// `false` if there were no children.
    #[doc(alias = "ts_tree_cursor_goto_first_child")]
    pub fn goto_first_child(&mut self) -> bool {
        unsafe { ffi::ts_tree_cursor_goto_first_child(&raw mut self.0) }
    }

    /// Move this cursor to the last child of its current node.
    ///
    /// This returns `true` if the cursor successfully moved, and returns
    /// `false` if there were no children.
    ///
    /// Note that this function may be slower than
    /// [`goto_first_child`](TreeCursor::goto_first_child) because it needs to
    /// iterate through all the children to compute the child's position.
    #[doc(alias = "ts_tree_cursor_goto_last_child")]
    pub fn goto_last_child(&mut self) -> bool {
        unsafe { ffi::ts_tree_cursor_goto_last_child(&raw mut self.0) }
    }

    /// Move this cursor to the parent of its current node.
    ///
    /// This returns `true` if the cursor successfully moved, and returns
    /// `false` if there was no parent node (the cursor was already on the
    /// root node).
    ///
    /// Note that the node the cursor was constructed with is considered the root
    /// of the cursor, and the cursor cannot walk outside this node.
    #[doc(alias = "ts_tree_cursor_goto_parent")]
    pub fn goto_parent(&mut self) -> bool {
        unsafe { ffi::ts_tree_cursor_goto_parent(&raw mut self.0) }
    }

    /// Move this cursor to the next sibling of its current node.
    ///
    /// This returns `true` if the cursor successfully moved, and returns
    /// `false` if there was no next sibling node.
    ///
    /// Note that the node the cursor was constructed with is considered the root
    /// of the cursor, and the cursor cannot walk outside this node.
    #[doc(alias = "ts_tree_cursor_goto_next_sibling")]
    pub fn goto_next_sibling(&mut self) -> bool {
        unsafe { ffi::ts_tree_cursor_goto_next_sibling(&raw mut self.0) }
    }

    /// Move the cursor to the node that is the nth descendant of
    /// the original node that the cursor was constructed with, where
    /// zero represents the original node itself.
    #[doc(alias = "ts_tree_cursor_goto_descendant")]
    pub fn goto_descendant(&mut self, descendant_index: usize) {
        unsafe { ffi::ts_tree_cursor_goto_descendant(&raw mut self.0, descendant_index as u32) }
    }

    /// Move this cursor to the previous sibling of its current node.
    ///
    /// This returns `true` if the cursor successfully moved, and returns
    /// `false` if there was no previous sibling node.
    ///
    /// Note, that this function may be slower than
    /// [`goto_next_sibling`](TreeCursor::goto_next_sibling) due to how node
    /// positions are stored. In the worst case, this will need to iterate
    /// through all the children up to the previous sibling node to recalculate
    /// its position. Also note that the node the cursor was constructed with is
    /// considered the root of the cursor, and the cursor cannot walk outside this node.
    #[doc(alias = "ts_tree_cursor_goto_previous_sibling")]
    pub fn goto_previous_sibling(&mut self) -> bool {
        unsafe { ffi::ts_tree_cursor_goto_previous_sibling(&raw mut self.0) }
    }

    /// Move this cursor to the first child of its current node that contains or
    /// starts after the given byte offset.
    ///
    /// This returns the index of the child node if one was found, and returns
    /// `None` if no such child was found.
    #[doc(alias = "ts_tree_cursor_goto_first_child_for_byte")]
    pub fn goto_first_child_for_byte(&mut self, index: usize) -> Option<usize> {
        let result =
            unsafe { ffi::ts_tree_cursor_goto_first_child_for_byte(&raw mut self.0, index as u32) };
        result.try_into().ok()
    }

    /// Move this cursor to the first child of its current node that contains or
    /// starts after the given byte offset.
    ///
    /// This returns the index of the child node if one was found, and returns
    /// `None` if no such child was found.
    #[doc(alias = "ts_tree_cursor_goto_first_child_for_point")]
    pub fn goto_first_child_for_point(&mut self, point: Point) -> Option<usize> {
        let result = unsafe {
            ffi::ts_tree_cursor_goto_first_child_for_point(&raw mut self.0, point.into())
        };
        result.try_into().ok()
    }

    /// Re-initialize this tree cursor to start at the original node that the
    /// cursor was constructed with.
    #[doc(alias = "ts_tree_cursor_reset")]
    pub fn reset(&mut self, node: Node<'tree>) {
        unsafe { ffi::ts_tree_cursor_reset(&raw mut self.0, node.0) };
    }

    /// Re-initialize a tree cursor to the same position as another cursor.
    ///
    /// Unlike [`reset`](TreeCursor::reset), this will not lose parent
    /// information and allows reusing already created cursors.
    #[doc(alias = "ts_tree_cursor_reset_to")]
    pub fn reset_to(&mut self, cursor: &Self) {
        unsafe { ffi::ts_tree_cursor_reset_to(&raw mut self.0, &raw const cursor.0) };
    }
}

impl Clone for TreeCursor<'_> {
    fn clone(&self) -> Self {
        TreeCursor(
            unsafe { ffi::ts_tree_cursor_copy(&raw const self.0) },
            PhantomData,
        )
    }
}

impl Drop for TreeCursor<'_> {
    fn drop(&mut self) {
        unsafe { ffi::ts_tree_cursor_delete(&raw mut self.0) }
    }
}

impl LookaheadIterator {
    /// Get the current language of the lookahead iterator.
    #[doc(alias = "ts_lookahead_iterator_language")]
    #[must_use]
    pub fn language(&self) -> LanguageRef<'_> {
        LanguageRef(
            unsafe { ffi::ts_lookahead_iterator_language(self.0.as_ptr()) },
            PhantomData,
        )
    }

    /// Get the current symbol of the lookahead iterator.
    ///
    /// Returns `None` if the iterator is not positioned on a symbol:
    ///
    /// - Before the first [`Iterator::next`] call
    /// - After the iterator is exhausted
    /// - After a [`Self::reset`] or [`Self::reset_state`] call
    #[doc(alias = "ts_lookahead_iterator_current_symbol")]
    #[must_use]
    pub fn current_symbol(&self) -> Option<u16> {
        // C signals "not positioned" through a null symbol name.
        let name = unsafe { ffi::ts_lookahead_iterator_current_symbol_name(self.0.as_ptr()) };
        (!name.is_null())
            .then(|| unsafe { ffi::ts_lookahead_iterator_current_symbol(self.0.as_ptr()) })
    }

    /// Get the current symbol name of the lookahead iterator.
    ///
    /// Returns `None` if the iterator is not positioned on a symbol.
    #[doc(alias = "ts_lookahead_iterator_current_symbol_name")]
    #[must_use]
    pub fn current_symbol_name(&self) -> Option<&str> {
        unsafe {
            let name = ffi::ts_lookahead_iterator_current_symbol_name(self.0.as_ptr());
            if name.is_null() {
                None
            } else {
                Some(CStr::from_ptr(name).to_str().unwrap())
            }
        }
    }

    /// Reset the lookahead iterator.
    ///
    /// This returns `true` if the language was set successfully and `false`
    /// otherwise.
    #[doc(alias = "ts_lookahead_iterator_reset")]
    pub fn reset(&mut self, language: &Language, state: u16) -> bool {
        unsafe { ffi::ts_lookahead_iterator_reset(self.0.as_ptr(), language.0, state) }
    }

    /// Reset the lookahead iterator to another state.
    ///
    /// This returns `true` if the iterator was reset to the given state and
    /// `false` otherwise.
    #[doc(alias = "ts_lookahead_iterator_reset_state")]
    pub fn reset_state(&mut self, state: u16) -> bool {
        unsafe { ffi::ts_lookahead_iterator_reset_state(self.0.as_ptr(), state) }
    }

    /// Iterate symbol names.
    pub fn iter_names(&mut self) -> impl iter::FusedIterator<Item = &str> + '_ {
        LookaheadNamesIterator(self)
    }
}

impl<'a> Iterator for LookaheadNamesIterator<'a> {
    type Item = &'a str;

    #[doc(alias = "ts_lookahead_iterator_next")]
    fn next(&mut self) -> Option<Self::Item> {
        let ptr = self.0.0.as_ptr();
        // SAFETY: The borrow keeps the iterator (and the language refcount it holds)
        // alive for `'a`. The name is non-null because the iterator is positioned
        // whenever `next` returns `true`.
        unsafe {
            ffi::ts_lookahead_iterator_next(ptr).then(|| {
                let name = ffi::ts_lookahead_iterator_current_symbol_name(ptr);
                debug_assert!(!name.is_null());
                CStr::from_ptr(name).to_str().unwrap()
            })
        }
    }
}

impl iter::FusedIterator for LookaheadNamesIterator<'_> {}

impl Iterator for LookaheadIterator {
    type Item = u16;

    #[doc(alias = "ts_lookahead_iterator_next")]
    fn next(&mut self) -> Option<Self::Item> {
        unsafe { ffi::ts_lookahead_iterator_next(self.0.as_ptr()) }
            .then(|| unsafe { ffi::ts_lookahead_iterator_current_symbol(self.0.as_ptr()) })
    }
}

impl iter::FusedIterator for LookaheadIterator {}

impl Drop for LookaheadIterator {
    #[doc(alias = "ts_lookahead_iterator_delete")]
    fn drop(&mut self) {
        unsafe { ffi::ts_lookahead_iterator_delete(self.0.as_ptr()) }
    }
}

impl Query {
    /// Create a new query from a string containing one or more S-expression
    /// patterns.
    ///
    /// The query is associated with a particular language, and can only be run
    /// on syntax nodes parsed with that language. References to Queries can be
    /// shared between multiple threads.
    pub fn new(language: &Language, source: &str) -> Result<Self, QueryError> {
        let ptr = Self::new_raw(language, source)?;
        unsafe { Self::from_raw_parts(ptr, source) }
    }

    /// Constructs a raw [`TSQuery`](ffi::TSQuery) pointer without performing extra checks specific to the rust
    /// bindings, such as predicate validation. A [`Query`] object can be constructed from the
    /// returned pointer using [`from_raw_parts`](Query::from_raw_parts). The caller is
    /// responsible for ensuring that the returned pointer is eventually freed by calling
    /// [`ts_query_delete`](ffi::ts_query_delete).
    pub fn new_raw(language: &Language, source: &str) -> Result<*mut ffi::TSQuery, QueryError> {
        let mut error_offset = 0u32;
        let mut error_type: ffi::TSQueryError = 0;
        let bytes = source.as_bytes();

        // Compile the query.
        let ptr = unsafe {
            ffi::ts_query_new(
                language.0,
                bytes.as_ptr().cast::<c_char>(),
                bytes.len() as u32,
                core::ptr::addr_of_mut!(error_offset),
                core::ptr::addr_of_mut!(error_type),
            )
        };

        if !ptr.is_null() {
            return Ok(ptr);
        }

        // On failure, build an error based on the error code and offset.
        if error_type == ffi::TSQueryErrorLanguage {
            return Err(QueryError {
                row: 0,
                column: 0,
                offset: 0,
                message: LanguageError::Version(language.abi_version()).to_string(),
                kind: QueryErrorKind::Language,
            });
        }

        let offset = error_offset as usize;
        let mut line_start = 0;
        let mut row = 0;
        let mut line_containing_error = None;
        for line in source.lines() {
            let line_end = line_start + line.len() + 1;
            if line_end > offset {
                line_containing_error = Some(line);
                break;
            }
            line_start = line_end;
            row += 1;
        }
        let column = offset - line_start;

        let (message, kind) = match error_type {
            // Error types that report names
            ffi::TSQueryErrorNodeType | ffi::TSQueryErrorField | ffi::TSQueryErrorCapture => {
                let suffix = source.split_at(offset).1;
                let in_quotes = offset > 0 && source.as_bytes()[offset - 1] == b'"';
                let mut backslashes = 0;
                let end_offset = suffix
                    .find(|c| {
                        if in_quotes {
                            if c == '"' && backslashes % 2 == 0 {
                                true
                            } else if c == '\\' {
                                backslashes += 1;
                                false
                            } else {
                                backslashes = 0;
                                false
                            }
                        } else {
                            !char::is_alphanumeric(c) && c != '_' && c != '-'
                        }
                    })
                    .unwrap_or(suffix.len());
                (
                    format!("\"{}\"", suffix.split_at(end_offset).0),
                    match error_type {
                        ffi::TSQueryErrorNodeType => QueryErrorKind::NodeType,
                        ffi::TSQueryErrorField => QueryErrorKind::Field,
                        ffi::TSQueryErrorCapture => QueryErrorKind::Capture,
                        _ => unreachable!(),
                    },
                )
            }

            // Error types that report positions
            _ => (
                line_containing_error.map_or_else(
                    || "Unexpected EOF".to_string(),
                    |line| line.to_string() + "\n" + &" ".repeat(offset - line_start) + "^",
                ),
                match error_type {
                    ffi::TSQueryErrorStructure => QueryErrorKind::Structure,
                    _ => QueryErrorKind::Syntax,
                },
            ),
        };

        Err(QueryError {
            row,
            column,
            offset,
            message,
            kind,
        })
    }

    #[doc(hidden)]
    unsafe fn from_raw_parts(ptr: *mut ffi::TSQuery, source: &str) -> Result<Self, QueryError> {
        let ptr = {
            struct TSQueryDrop(*mut ffi::TSQuery);
            impl Drop for TSQueryDrop {
                fn drop(&mut self) {
                    unsafe { ffi::ts_query_delete(self.0) }
                }
            }
            TSQueryDrop(ptr)
        };

        let string_count = unsafe { ffi::ts_query_string_count(ptr.0) };
        let capture_count = unsafe { ffi::ts_query_capture_count(ptr.0) };
        let pattern_count = unsafe { ffi::ts_query_pattern_count(ptr.0) as usize };

        let mut capture_names = Vec::with_capacity(capture_count as usize);
        let mut capture_quantifiers_vec = Vec::with_capacity(pattern_count);
        let mut text_predicates_vec = Vec::with_capacity(pattern_count);
        let mut property_predicates_vec = Vec::with_capacity(pattern_count);
        let mut property_settings_vec = Vec::with_capacity(pattern_count);
        let mut general_predicates_vec = Vec::with_capacity(pattern_count);

        // Build a vector of strings to store the capture names.
        for i in 0..capture_count {
            unsafe {
                let mut length = 0u32;
                let name =
                    ffi::ts_query_capture_name_for_id(ptr.0, i, core::ptr::addr_of_mut!(length))
                        .cast::<u8>();
                let name = slice::from_raw_parts(name, length as usize);
                let name = str::from_utf8_unchecked(name);
                capture_names.push(name);
            }
        }

        // Build a vector to store capture quantifiers.
        for i in 0..pattern_count {
            let mut capture_quantifiers = Vec::with_capacity(capture_count as usize);
            for j in 0..capture_count {
                unsafe {
                    let quantifier = ffi::ts_query_capture_quantifier_for_id(ptr.0, i as u32, j);
                    capture_quantifiers.push(quantifier.into());
                }
            }
            capture_quantifiers_vec.push(capture_quantifiers.into());
        }

        // Build a vector of strings to represent literal values used in predicates.
        let string_values = (0..string_count)
            .map(|i| unsafe {
                let mut length = 0u32;
                let value =
                    ffi::ts_query_string_value_for_id(ptr.0, i, core::ptr::addr_of_mut!(length))
                        .cast::<u8>();
                let value = slice::from_raw_parts(value, length as usize);
                str::from_utf8_unchecked(value)
            })
            .collect::<Vec<_>>();

        // Build a vector of predicates for each pattern.
        for i in 0..pattern_count {
            let predicate_steps = unsafe {
                let mut length = 0u32;
                let raw_predicates = ffi::ts_query_predicates_for_pattern(
                    ptr.0,
                    i as u32,
                    core::ptr::addr_of_mut!(length),
                );
                if length > 0 {
                    slice::from_raw_parts(raw_predicates, length as usize)
                } else {
                    Default::default()
                }
            };

            let byte_offset = unsafe { ffi::ts_query_start_byte_for_pattern(ptr.0, i as u32) };
            let row = source
                .char_indices()
                .take_while(|(i, _)| *i < byte_offset as usize)
                .filter(|(_, c)| *c == '\n')
                .count();

            use ffi::TSQueryPredicateStepType as T;
            const TYPE_DONE: T = ffi::TSQueryPredicateStepTypeDone;
            const TYPE_CAPTURE: T = ffi::TSQueryPredicateStepTypeCapture;
            const TYPE_STRING: T = ffi::TSQueryPredicateStepTypeString;

            let mut text_predicates = Vec::new();
            let mut property_predicates = Vec::new();
            let mut property_settings = Vec::new();
            let mut general_predicates = Vec::new();
            for p in predicate_steps.split(|s| s.type_ == TYPE_DONE) {
                if p.is_empty() {
                    continue;
                }

                if p[0].type_ != TYPE_STRING {
                    return Err(predicate_error(
                        row,
                        format!(
                            "Expected predicate to start with a function name. Got @{}.",
                            capture_names[p[0].value_id as usize],
                        ),
                    ));
                }

                // Build a predicate for each of the known predicate function names.
                let operator_name = string_values[p[0].value_id as usize];
                match operator_name {
                    "eq?" | "not-eq?" | "any-eq?" | "any-not-eq?" => {
                        if p.len() != 3 {
                            return Err(predicate_error(
                                row,
                                format!(
                                    "Wrong number of arguments to #eq? predicate. Expected 2, got {}.",
                                    p.len() - 1
                                ),
                            ));
                        }
                        if p[1].type_ != TYPE_CAPTURE {
                            return Err(predicate_error(
                                row,
                                format!(
                                    "First argument to #eq? predicate must be a capture name. Got literal \"{}\".",
                                    string_values[p[1].value_id as usize],
                                ),
                            ));
                        }

                        let is_positive = operator_name == "eq?" || operator_name == "any-eq?";
                        let match_all = match operator_name {
                            "eq?" | "not-eq?" => true,
                            "any-eq?" | "any-not-eq?" => false,
                            _ => unreachable!(),
                        };
                        text_predicates.push(if p[2].type_ == TYPE_CAPTURE {
                            TextPredicateCapture::EqCapture(
                                p[1].value_id,
                                p[2].value_id,
                                is_positive,
                                match_all,
                            )
                        } else {
                            TextPredicateCapture::EqString(
                                p[1].value_id,
                                string_values[p[2].value_id as usize].to_string().into(),
                                is_positive,
                                match_all,
                            )
                        });
                    }

                    "match?" | "not-match?" | "any-match?" | "any-not-match?" => {
                        if p.len() != 3 {
                            return Err(predicate_error(
                                row,
                                format!(
                                    "Wrong number of arguments to #match? predicate. Expected 2, got {}.",
                                    p.len() - 1
                                ),
                            ));
                        }
                        if p[1].type_ != TYPE_CAPTURE {
                            return Err(predicate_error(
                                row,
                                format!(
                                    "First argument to #match? predicate must be a capture name. Got literal \"{}\".",
                                    string_values[p[1].value_id as usize],
                                ),
                            ));
                        }
                        if p[2].type_ == TYPE_CAPTURE {
                            return Err(predicate_error(
                                row,
                                format!(
                                    "Second argument to #match? predicate must be a literal. Got capture @{}.",
                                    capture_names[p[2].value_id as usize],
                                ),
                            ));
                        }

                        let is_positive =
                            operator_name == "match?" || operator_name == "any-match?";
                        let match_all = match operator_name {
                            "match?" | "not-match?" => true,
                            "any-match?" | "any-not-match?" => false,
                            _ => unreachable!(),
                        };
                        let regex = &string_values[p[2].value_id as usize];
                        text_predicates.push(TextPredicateCapture::MatchString(
                            p[1].value_id,
                            regex::bytes::Regex::new(regex).map_err(|_| {
                                predicate_error(row, format!("Invalid regex '{regex}'"))
                            })?,
                            is_positive,
                            match_all,
                        ));
                    }

                    "set!" => property_settings.push(Self::parse_property(
                        row,
                        operator_name,
                        &capture_names,
                        &string_values,
                        &p[1..],
                    )?),

                    "is?" | "is-not?" => property_predicates.push((
                        Self::parse_property(
                            row,
                            operator_name,
                            &capture_names,
                            &string_values,
                            &p[1..],
                        )?,
                        operator_name == "is?",
                    )),

                    "any-of?" | "not-any-of?" => {
                        if p.len() < 2 {
                            return Err(predicate_error(
                                row,
                                format!(
                                    "Wrong number of arguments to #any-of? predicate. Expected at least 1, got {}.",
                                    p.len() - 1
                                ),
                            ));
                        }
                        if p[1].type_ != TYPE_CAPTURE {
                            return Err(predicate_error(
                                row,
                                format!(
                                    "First argument to #any-of? predicate must be a capture name. Got literal \"{}\".",
                                    string_values[p[1].value_id as usize],
                                ),
                            ));
                        }

                        let is_positive = operator_name == "any-of?";
                        let mut values = Vec::new();
                        for arg in &p[2..] {
                            if arg.type_ == TYPE_CAPTURE {
                                return Err(predicate_error(
                                    row,
                                    format!(
                                        "Arguments to #any-of? predicate must be literals. Got capture @{}.",
                                        capture_names[arg.value_id as usize],
                                    ),
                                ));
                            }
                            values.push(string_values[arg.value_id as usize]);
                        }
                        text_predicates.push(TextPredicateCapture::AnyString(
                            p[1].value_id,
                            values
                                .iter()
                                .map(|x| (*x).to_string().into())
                                .collect::<Vec<_>>()
                                .into(),
                            is_positive,
                        ));
                    }

                    _ => general_predicates.push(QueryPredicate {
                        operator: operator_name.to_string().into(),
                        args: p[1..]
                            .iter()
                            .map(|a| {
                                if a.type_ == TYPE_CAPTURE {
                                    QueryPredicateArg::Capture(a.value_id)
                                } else {
                                    QueryPredicateArg::String(
                                        string_values[a.value_id as usize].to_string().into(),
                                    )
                                }
                            })
                            .collect(),
                    }),
                }
            }

            text_predicates_vec.push(text_predicates.into());
            property_predicates_vec.push(property_predicates.into());
            property_settings_vec.push(property_settings.into());
            general_predicates_vec.push(general_predicates.into());
        }

        let result = Self {
            ptr: unsafe { NonNull::new_unchecked(ptr.0) },
            capture_names: capture_names.into(),
            capture_quantifiers: capture_quantifiers_vec.into(),
            text_predicates: text_predicates_vec.into(),
            property_predicates: property_predicates_vec.into(),
            property_settings: property_settings_vec.into(),
            general_predicates: general_predicates_vec.into(),
        };

        core::mem::forget(ptr);

        Ok(result)
    }

    /// Get the byte offset where the given pattern starts in the query's
    /// source.
    #[doc(alias = "ts_query_start_byte_for_pattern")]
    #[must_use]
    pub fn start_byte_for_pattern(&self, pattern_index: usize) -> usize {
        assert!(
            pattern_index < self.text_predicates.len(),
            "Pattern index is {pattern_index} but the pattern count is {}",
            self.text_predicates.len(),
        );
        unsafe {
            ffi::ts_query_start_byte_for_pattern(self.ptr.as_ptr(), pattern_index as u32) as usize
        }
    }

    /// Get the byte offset where the given pattern ends in the query's
    /// source.
    #[doc(alias = "ts_query_end_byte_for_pattern")]
    #[must_use]
    pub fn end_byte_for_pattern(&self, pattern_index: usize) -> usize {
        assert!(
            pattern_index < self.text_predicates.len(),
            "Pattern index is {pattern_index} but the pattern count is {}",
            self.text_predicates.len(),
        );
        unsafe {
            ffi::ts_query_end_byte_for_pattern(self.ptr.as_ptr(), pattern_index as u32) as usize
        }
    }

    /// Get the number of patterns in the query.
    #[doc(alias = "ts_query_pattern_count")]
    #[must_use]
    pub fn pattern_count(&self) -> usize {
        unsafe { ffi::ts_query_pattern_count(self.ptr.as_ptr()) as usize }
    }

    /// Get the names of the captures used in the query.
    #[must_use]
    pub const fn capture_names(&self) -> &[&str] {
        &self.capture_names
    }

    /// Get the quantifiers of the captures used in the query.
    #[must_use]
    pub const fn capture_quantifiers(&self, index: usize) -> &[CaptureQuantifier] {
        &self.capture_quantifiers[index]
    }

    /// Get the index for a given capture name.
    #[must_use]
    pub fn capture_index_for_name(&self, name: &str) -> Option<u32> {
        self.capture_names
            .iter()
            .position(|n| *n == name)
            .map(|ix| ix as u32)
    }

    /// Get the properties that are checked for the given pattern index.
    ///
    /// This includes predicates with the operators `is?` and `is-not?`.
    #[must_use]
    pub const fn property_predicates(&self, index: usize) -> &[(QueryProperty, bool)] {
        &self.property_predicates[index]
    }

    /// Get the properties that are set for the given pattern index.
    ///
    /// This includes predicates with the operator `set!`.
    #[must_use]
    pub const fn property_settings(&self, index: usize) -> &[QueryProperty] {
        &self.property_settings[index]
    }

    /// Get the other user-defined predicates associated with the given index.
    ///
    /// This includes predicate with operators other than:
    /// * `match?`
    /// * `eq?` and `not-eq?`
    /// * `is?` and `is-not?`
    /// * `set!`
    #[must_use]
    pub const fn general_predicates(&self, index: usize) -> &[QueryPredicate] {
        &self.general_predicates[index]
    }

    /// Disable a certain capture within a query.
    ///
    /// This prevents the capture from being returned in matches, and also
    /// avoids any resource usage associated with recording the capture.
    #[doc(alias = "ts_query_disable_capture")]
    pub fn disable_capture(&mut self, name: &str) {
        unsafe {
            ffi::ts_query_disable_capture(
                self.ptr.as_ptr(),
                name.as_bytes().as_ptr().cast::<c_char>(),
                name.len() as u32,
            );
        }
    }

    /// Disable a certain pattern within a query.
    ///
    /// This prevents the pattern from matching, and also avoids any resource
    /// usage associated with the pattern.
    #[doc(alias = "ts_query_disable_pattern")]
    pub fn disable_pattern(&mut self, index: usize) {
        unsafe { ffi::ts_query_disable_pattern(self.ptr.as_ptr(), index as u32) }
    }

    /// Create a deep copy of this query.
    ///
    /// Queries are shareable across threads and cursors without cloning. You
    /// should only need this when you want an independent copy to mutate (e.g.
    /// via [`disable_capture`][Query::disable_capture] or
    /// [`disable_pattern`][Query::disable_pattern]).
    #[doc(alias = "ts_query_copy")]
    #[must_use]
    pub fn deep_clone(&self) -> Self {
        let ptr = unsafe { ffi::ts_query_copy(self.ptr.as_ptr()) };
        // SAFETY: from_raw_parts re-derives all Rust-side fields from the C
        // object. The source string is only used for predicate error row
        // numbers. Since this is a copy of an already-valid query, it cannot
        // return an error.
        unsafe { Self::from_raw_parts(ptr, "").unwrap_unchecked() }
    }

    /// Check if a given pattern within a query has a single root node.
    #[doc(alias = "ts_query_is_pattern_rooted")]
    #[must_use]
    pub fn is_pattern_rooted(&self, index: usize) -> bool {
        unsafe { ffi::ts_query_is_pattern_rooted(self.ptr.as_ptr(), index as u32) }
    }

    /// Check if a given pattern within a query has a single root node.
    #[doc(alias = "ts_query_is_pattern_non_local")]
    #[must_use]
    pub fn is_pattern_non_local(&self, index: usize) -> bool {
        unsafe { ffi::ts_query_is_pattern_non_local(self.ptr.as_ptr(), index as u32) }
    }

    /// Check if a given step in a query is 'definite'.
    ///
    /// A query step is 'definite' if its parent pattern will be guaranteed to
    /// match successfully once it reaches the step.
    #[doc(alias = "ts_query_is_pattern_guaranteed_at_step")]
    #[must_use]
    pub fn is_pattern_guaranteed_at_step(&self, byte_offset: usize) -> bool {
        unsafe {
            ffi::ts_query_is_pattern_guaranteed_at_step(self.ptr.as_ptr(), byte_offset as u32)
        }
    }

    fn parse_property(
        row: usize,
        function_name: &str,
        capture_names: &[&str],
        string_values: &[&str],
        args: &[ffi::TSQueryPredicateStep],
    ) -> Result<QueryProperty, QueryError> {
        if args.is_empty() || args.len() > 3 {
            return Err(predicate_error(
                row,
                format!(
                    "Wrong number of arguments to {function_name} predicate. Expected 1 to 3, got {}.",
                    args.len(),
                ),
            ));
        }

        let mut capture_id = None;
        let mut key = None;
        let mut value = None;

        for arg in args {
            if arg.type_ == ffi::TSQueryPredicateStepTypeCapture {
                if capture_id.is_some() {
                    return Err(predicate_error(
                        row,
                        format!(
                            "Invalid arguments to {function_name} predicate. Unexpected second capture name @{}",
                            capture_names[arg.value_id as usize]
                        ),
                    ));
                }
                capture_id = Some(arg.value_id as usize);
            } else if key.is_none() {
                key = Some(&string_values[arg.value_id as usize]);
            } else if value.is_none() {
                value = Some(string_values[arg.value_id as usize]);
            } else {
                return Err(predicate_error(
                    row,
                    format!(
                        "Invalid arguments to {function_name} predicate. Unexpected third argument @{}",
                        string_values[arg.value_id as usize]
                    ),
                ));
            }
        }

        if let Some(key) = key {
            Ok(QueryProperty::new(key, value, capture_id))
        } else {
            Err(predicate_error(
                row,
                format!("Invalid arguments to {function_name} predicate. Missing key argument"),
            ))
        }
    }
}

impl Default for QueryCursor {
    fn default() -> Self {
        Self::new()
    }
}

impl QueryCursor {
    /// Create a new cursor for executing a given query.
    ///
    /// The cursor stores the state that is needed to iteratively search for
    /// matches.
    #[doc(alias = "ts_query_cursor_new")]
    #[must_use]
    pub fn new() -> Self {
        Self {
            ptr: unsafe { NonNull::new_unchecked(ffi::ts_query_cursor_new()) },
        }
    }

    /// Return the maximum number of in-progress matches for this cursor.
    #[doc(alias = "ts_query_cursor_match_limit")]
    #[must_use]
    pub fn match_limit(&self) -> u32 {
        unsafe { ffi::ts_query_cursor_match_limit(self.ptr.as_ptr()) }
    }

    /// Set the maximum number of in-progress matches for this cursor.  The
    /// limit must be > 0 and <= 65536.
    #[doc(alias = "ts_query_cursor_set_match_limit")]
    pub fn set_match_limit(&mut self, limit: u32) {
        unsafe {
            ffi::ts_query_cursor_set_match_limit(self.ptr.as_ptr(), limit);
        }
    }

    /// Check if, on its last execution, this cursor exceeded its maximum number
    /// of in-progress matches.
    #[doc(alias = "ts_query_cursor_did_exceed_match_limit")]
    #[must_use]
    pub fn did_exceed_match_limit(&self) -> bool {
        unsafe { ffi::ts_query_cursor_did_exceed_match_limit(self.ptr.as_ptr()) }
    }

    /// Iterate over all of the matches in the order that they were found.
    ///
    /// Each match contains the index of the pattern that matched, and a list of
    /// captures. Because multiple patterns can match the same set of nodes,
    /// one match may contain captures that appear *before* some of the
    /// captures from a previous match.
    ///
    /// Iterating over a `QueryMatches` object requires the `StreamingIterator`
    /// or `StreamingIteratorMut` trait to be in scope. This can be done via
    /// `use tree_sitter::StreamingIterator` or `use tree_sitter::StreamingIteratorMut`
    #[doc(alias = "ts_query_cursor_exec")]
    pub fn matches<'query, 'cursor: 'query, 'tree, T: TextProvider<I>, I: AsRef<[u8]>>(
        &'cursor mut self,
        query: &'query Query,
        node: Node<'tree>,
        text_provider: T,
    ) -> QueryMatches<'query, 'tree, 'static, T, I> {
        let ptr = self.ptr.as_ptr();
        unsafe { ffi::ts_query_cursor_exec(ptr, query.ptr.as_ptr(), node.0) };
        QueryMatches {
            ptr,
            query,
            text_provider,
            buffer1: Vec::default(),
            buffer2: Vec::default(),
            current_match: None,
            _options: None,
            _phantom: PhantomData,
        }
    }

    /// Iterate over all of the matches in the order that they were found, with options.
    ///
    /// Each match contains the index of the pattern that matched, and a list of
    /// captures. Because multiple patterns can match the same set of nodes,
    /// one match may contain captures that appear *before* some of the
    /// captures from a previous match.
    #[doc(alias = "ts_query_cursor_exec_with_options")]
    pub fn matches_with_options<
        'query,
        'cursor: 'query,
        'tree,
        'options,
        T: TextProvider<I>,
        I: AsRef<[u8]>,
    >(
        &'cursor mut self,
        query: &'query Query,
        node: Node<'tree>,
        text_provider: T,
        options: QueryCursorOptions<'options>,
    ) -> QueryMatches<'query, 'tree, 'options, T, I> {
        unsafe extern "C" fn progress(state: *mut ffi::TSQueryCursorState) -> bool {
            unsafe {
                let callback = (*state)
                    .payload
                    .cast::<QueryProgressCallback>()
                    .as_mut()
                    .unwrap();
                match callback(&QueryCursorState::from_raw(state)) {
                    ControlFlow::Continue(()) => false,
                    ControlFlow::Break(()) => true,
                }
            }
        }

        let query_options = options.progress_callback.map(|cb| {
            QueryCursorOptionsDrop(
                Box::into_raw(Box::new(ffi::TSQueryCursorOptions {
                    payload: Box::into_raw(Box::new(cb)).cast::<c_void>(),
                    progress_callback: Some(progress),
                })),
                PhantomData,
            )
        });

        let ptr = self.ptr.as_ptr();
        unsafe {
            ffi::ts_query_cursor_exec_with_options(
                ptr,
                query.ptr.as_ptr(),
                node.0,
                query_options.as_ref().map_or(ptr::null_mut(), |q| q.0),
            );
        }
        QueryMatches {
            ptr,
            query,
            text_provider,
            buffer1: Vec::default(),
            buffer2: Vec::default(),
            current_match: None,
            _options: query_options,
            _phantom: PhantomData,
        }
    }

    /// Iterate over all of the individual captures in the order that they
    /// appear.
    ///
    /// This is useful if you don't care about which pattern matched, and just
    /// want a single, ordered sequence of captures.
    ///
    /// Iterating over a `QueryCaptures` object requires the `StreamingIterator`
    /// or `StreamingIteratorMut` trait to be in scope. This can be done via
    /// `use tree_sitter::StreamingIterator` or `use tree_sitter::StreamingIteratorMut`
    #[doc(alias = "ts_query_cursor_exec")]
    pub fn captures<'query, 'cursor: 'query, 'tree, T: TextProvider<I>, I: AsRef<[u8]>>(
        &'cursor mut self,
        query: &'query Query,
        node: Node<'tree>,
        text_provider: T,
    ) -> QueryCaptures<'query, 'tree, 'static, T, I> {
        let ptr = self.ptr.as_ptr();
        unsafe { ffi::ts_query_cursor_exec(ptr, query.ptr.as_ptr(), node.0) };
        QueryCaptures {
            ptr,
            query,
            text_provider,
            buffer1: Vec::default(),
            buffer2: Vec::default(),
            current_match: None,
            _options: None,
            _phantom: PhantomData,
        }
    }

    /// Iterate over all of the individual captures in the order that they
    /// appear, with options.
    ///
    /// This is useful if you don't care about which pattern matched, and just
    /// want a single, ordered sequence of captures.
    #[doc(alias = "ts_query_cursor_exec")]
    pub fn captures_with_options<
        'query,
        'cursor: 'query,
        'tree,
        'options,
        T: TextProvider<I>,
        I: AsRef<[u8]>,
    >(
        &'cursor mut self,
        query: &'query Query,
        node: Node<'tree>,
        text_provider: T,
        options: QueryCursorOptions<'options>,
    ) -> QueryCaptures<'query, 'tree, 'options, T, I> {
        unsafe extern "C" fn progress(state: *mut ffi::TSQueryCursorState) -> bool {
            unsafe {
                let callback = (*state)
                    .payload
                    .cast::<QueryProgressCallback>()
                    .as_mut()
                    .unwrap();
                match callback(&QueryCursorState::from_raw(state)) {
                    ControlFlow::Continue(()) => false,
                    ControlFlow::Break(()) => true,
                }
            }
        }

        let query_options = options.progress_callback.map(|cb| {
            QueryCursorOptionsDrop(
                Box::into_raw(Box::new(ffi::TSQueryCursorOptions {
                    payload: Box::into_raw(Box::new(cb)).cast::<c_void>(),
                    progress_callback: Some(progress),
                })),
                PhantomData,
            )
        });

        let ptr = self.ptr.as_ptr();
        unsafe {
            ffi::ts_query_cursor_exec_with_options(
                ptr,
                query.ptr.as_ptr(),
                node.0,
                query_options.as_ref().map_or(ptr::null_mut(), |q| q.0),
            );
        }
        QueryCaptures {
            ptr,
            query,
            text_provider,
            buffer1: Vec::default(),
            buffer2: Vec::default(),
            current_match: None,
            _options: query_options,
            _phantom: PhantomData,
        }
    }

    /// Set the range in which the query will be executed, in terms of byte
    /// offsets.
    #[doc(alias = "ts_query_cursor_set_byte_range")]
    pub fn set_byte_range(&mut self, range: ops::Range<usize>) -> &mut Self {
        unsafe {
            ffi::ts_query_cursor_set_byte_range(
                self.ptr.as_ptr(),
                range.start as u32,
                range.end as u32,
            );
        }
        self
    }

    /// Set the range in which the query will be executed, in terms of rows and
    /// columns.
    #[doc(alias = "ts_query_cursor_set_point_range")]
    pub fn set_point_range(&mut self, range: ops::Range<Point>) -> &mut Self {
        unsafe {
            ffi::ts_query_cursor_set_point_range(
                self.ptr.as_ptr(),
                range.start.into(),
                range.end.into(),
            );
        }
        self
    }

    /// Set the byte range within which all matches must be fully contained.
    ///
    /// Set the range of bytes in which matches will be searched for. In contrast to
    /// `ts_query_cursor_set_byte_range`, this will restrict the query cursor to only return
    /// matches where _all_ nodes are _fully_ contained within the given range. Both functions
    /// can be used together, e.g. to search for any matches that intersect line 5000, as
    /// long as they are fully contained within lines 4500-5500
    #[doc(alias = "ts_query_cursor_set_containing_byte_range")]
    pub fn set_containing_byte_range(&mut self, range: ops::Range<usize>) -> &mut Self {
        unsafe {
            ffi::ts_query_cursor_set_containing_byte_range(
                self.ptr.as_ptr(),
                range.start as u32,
                range.end as u32,
            );
        }
        self
    }

    /// Set the point range within which all matches must be fully contained.
    ///
    /// Set the range of bytes in which matches will be searched for. In contrast to
    /// `ts_query_cursor_set_point_range`, this will restrict the query cursor to only return
    /// matches where _all_ nodes are _fully_ contained within the given range. Both functions
    /// can be used together, e.g. to search for any matches that intersect line 5000, as
    /// long as they are fully contained within lines 4500-5500
    #[doc(alias = "ts_query_cursor_set_containing_point_range")]
    pub fn set_containing_point_range(&mut self, range: ops::Range<Point>) -> &mut Self {
        unsafe {
            ffi::ts_query_cursor_set_containing_point_range(
                self.ptr.as_ptr(),
                range.start.into(),
                range.end.into(),
            );
        }
        self
    }

    /// Set the maximum start depth for a query cursor.
    ///
    /// This prevents cursors from exploring children nodes at a certain depth.
    /// Note if a pattern includes many children, then they will still be
    /// checked.
    ///
    /// The zero max start depth value can be used as a special behavior and
    /// it helps to destructure a subtree by staying on a node and using
    /// captures for interested parts. Note that the zero max start depth
    /// only limits a search depth for a pattern's root node but other nodes
    /// that are parts of the pattern may be searched at any depth depending on
    /// what is defined by the pattern structure.
    ///
    /// Set to `None` to remove the maximum start depth.
    #[doc(alias = "ts_query_cursor_set_max_start_depth")]
    pub fn set_max_start_depth(&mut self, max_start_depth: Option<u32>) -> &mut Self {
        unsafe {
            ffi::ts_query_cursor_set_max_start_depth(
                self.ptr.as_ptr(),
                max_start_depth.unwrap_or(u32::MAX),
            );
        }
        self
    }
}

impl<'tree> QueryMatch<'_, 'tree> {
    #[must_use]
    pub const fn id(&self) -> u32 {
        self.id
    }

    #[must_use]
    pub const fn captures(&self) -> &[QueryCapture<'tree>] {
        self.captures
    }

    #[doc(alias = "ts_query_cursor_remove_match")]
    pub fn remove(&self) {
        unsafe { ffi::ts_query_cursor_remove_match(self.cursor, self.id) }
    }

    pub fn nodes_for_capture_index(
        &self,
        capture_ix: u32,
    ) -> impl Iterator<Item = Node<'tree>> + '_ {
        self.captures
            .iter()
            .filter_map(move |capture| (capture.index == capture_ix).then_some(capture.node))
    }

    fn new(m: &ffi::TSQueryMatch, cursor: *mut ffi::TSQueryCursor) -> Self {
        QueryMatch {
            cursor,
            id: m.id,
            pattern_index: m.pattern_index as usize,
            captures: if m.capture_count > 0 {
                unsafe {
                    slice::from_raw_parts(
                        m.captures.cast::<QueryCapture<'tree>>(),
                        m.capture_count as usize,
                    )
                }
            } else {
                Default::default()
            },
        }
    }

    pub fn satisfies_text_predicates<I: AsRef<[u8]>>(
        &self,
        query: &Query,
        buffer1: &mut Vec<u8>,
        buffer2: &mut Vec<u8>,
        text_provider: &mut impl TextProvider<I>,
    ) -> bool {
        struct NodeText<'a, T> {
            buffer: &'a mut Vec<u8>,
            first_chunk: Option<T>,
        }
        impl<'a, T: AsRef<[u8]>> NodeText<'a, T> {
            const fn new(buffer: &'a mut Vec<u8>) -> Self {
                Self {
                    buffer,
                    first_chunk: None,
                }
            }

            fn get_text(&mut self, chunks: &mut impl Iterator<Item = T>) -> &[u8] {
                self.first_chunk = chunks.next();
                if let Some(next_chunk) = chunks.next() {
                    self.buffer.clear();
                    self.buffer
                        .extend_from_slice(self.first_chunk.as_ref().unwrap().as_ref());
                    self.buffer.extend_from_slice(next_chunk.as_ref());
                    for chunk in chunks {
                        self.buffer.extend_from_slice(chunk.as_ref());
                    }
                    self.buffer.as_slice()
                } else if let Some(ref first_chunk) = self.first_chunk {
                    first_chunk.as_ref()
                } else {
                    &[]
                }
            }
        }

        let mut node_text1 = NodeText::new(buffer1);
        let mut node_text2 = NodeText::new(buffer2);

        query.text_predicates[self.pattern_index]
            .iter()
            .all(|predicate| match predicate {
                TextPredicateCapture::EqCapture(i, j, is_positive, match_all_nodes) => {
                    let mut nodes_1 = self.nodes_for_capture_index(*i).peekable();
                    let mut nodes_2 = self.nodes_for_capture_index(*j).peekable();
                    while nodes_1.peek().is_some() && nodes_2.peek().is_some() {
                        let node1 = nodes_1.next().unwrap();
                        let node2 = nodes_2.next().unwrap();
                        let mut text1 = text_provider.text(node1);
                        let mut text2 = text_provider.text(node2);
                        let text1 = node_text1.get_text(&mut text1);
                        let text2 = node_text2.get_text(&mut text2);
                        let is_positive_match = text1 == text2;
                        if is_positive_match != *is_positive && *match_all_nodes {
                            return false;
                        }
                        if is_positive_match == *is_positive && !*match_all_nodes {
                            return true;
                        }
                    }
                    nodes_1.next().is_none() && nodes_2.next().is_none()
                }
                TextPredicateCapture::EqString(i, s, is_positive, match_all_nodes) => {
                    let nodes = self.nodes_for_capture_index(*i);
                    for node in nodes {
                        let mut text = text_provider.text(node);
                        let text = node_text1.get_text(&mut text);
                        let is_positive_match = text == s.as_bytes();
                        if is_positive_match != *is_positive && *match_all_nodes {
                            return false;
                        }
                        if is_positive_match == *is_positive && !*match_all_nodes {
                            return true;
                        }
                    }
                    true
                }
                TextPredicateCapture::MatchString(i, r, is_positive, match_all_nodes) => {
                    let nodes = self.nodes_for_capture_index(*i);
                    for node in nodes {
                        let mut text = text_provider.text(node);
                        let text = node_text1.get_text(&mut text);
                        let is_positive_match = r.is_match(text);
                        if is_positive_match != *is_positive && *match_all_nodes {
                            return false;
                        }
                        if is_positive_match == *is_positive && !*match_all_nodes {
                            return true;
                        }
                    }
                    true
                }
                TextPredicateCapture::AnyString(i, v, is_positive) => {
                    let nodes = self.nodes_for_capture_index(*i);
                    for node in nodes {
                        let mut text = text_provider.text(node);
                        let text = node_text1.get_text(&mut text);
                        if (v.iter().any(|s| text == s.as_bytes())) != *is_positive {
                            return false;
                        }
                    }
                    true
                }
            })
    }
}

impl QueryProperty {
    #[must_use]
    pub fn new(key: &str, value: Option<&str>, capture_id: Option<usize>) -> Self {
        Self {
            capture_id,
            key: key.to_string().into(),
            value: value.map(|s| s.to_string().into()),
        }
    }
}

/// Provide a `StreamingIterator` instead of the traditional `Iterator`, as the
/// underlying object in the C library gets updated on each iteration. Copies would
/// have their internal state overwritten, leading to Undefined Behavior
impl<'query, 'tree, T: TextProvider<I>, I: AsRef<[u8]>> StreamingIterator
    for QueryMatches<'query, 'tree, '_, T, I>
{
    type Item = QueryMatch<'query, 'tree>;

    fn advance(&mut self) {
        self.current_match = unsafe {
            loop {
                let mut m = MaybeUninit::<ffi::TSQueryMatch>::uninit();
                if ffi::ts_query_cursor_next_match(self.ptr, m.as_mut_ptr()) {
                    let result = QueryMatch::new(&m.assume_init(), self.ptr);
                    if result.satisfies_text_predicates(
                        self.query,
                        &mut self.buffer1,
                        &mut self.buffer2,
                        &mut self.text_provider,
                    ) {
                        break Some(result);
                    }
                } else {
                    break None;
                }
            }
        };
    }

    fn get(&self) -> Option<&Self::Item> {
        self.current_match.as_ref()
    }
}

impl<T: TextProvider<I>, I: AsRef<[u8]>> StreamingIteratorMut for QueryMatches<'_, '_, '_, T, I> {
    fn get_mut(&mut self) -> Option<&mut Self::Item> {
        self.current_match.as_mut()
    }
}

impl<'query, 'tree, T: TextProvider<I>, I: AsRef<[u8]>> StreamingIterator
    for QueryCaptures<'query, 'tree, '_, T, I>
{
    type Item = (QueryMatch<'query, 'tree>, usize);

    fn advance(&mut self) {
        self.current_match = unsafe {
            loop {
                let mut capture_index = 0u32;
                let mut m = MaybeUninit::<ffi::TSQueryMatch>::uninit();
                if ffi::ts_query_cursor_next_capture(
                    self.ptr,
                    m.as_mut_ptr(),
                    core::ptr::addr_of_mut!(capture_index),
                ) {
                    let result = QueryMatch::new(&m.assume_init(), self.ptr);
                    if result.satisfies_text_predicates(
                        self.query,
                        &mut self.buffer1,
                        &mut self.buffer2,
                        &mut self.text_provider,
                    ) {
                        break Some((result, capture_index as usize));
                    }
                    result.remove();
                } else {
                    break None;
                }
            }
        }
    }

    fn get(&self) -> Option<&Self::Item> {
        self.current_match.as_ref()
    }
}

impl<T: TextProvider<I>, I: AsRef<[u8]>> StreamingIteratorMut for QueryCaptures<'_, '_, '_, T, I> {
    fn get_mut(&mut self) -> Option<&mut Self::Item> {
        self.current_match.as_mut()
    }
}

impl<T: TextProvider<I>, I: AsRef<[u8]>> QueryMatches<'_, '_, '_, T, I> {
    #[doc(alias = "ts_query_cursor_set_byte_range")]
    pub fn set_byte_range(&mut self, range: ops::Range<usize>) {
        unsafe {
            ffi::ts_query_cursor_set_byte_range(self.ptr, range.start as u32, range.end as u32);
        }
    }

    #[doc(alias = "ts_query_cursor_set_point_range")]
    pub fn set_point_range(&mut self, range: ops::Range<Point>) {
        unsafe {
            ffi::ts_query_cursor_set_point_range(self.ptr, range.start.into(), range.end.into());
        }
    }
}

impl<T: TextProvider<I>, I: AsRef<[u8]>> QueryCaptures<'_, '_, '_, T, I> {
    #[doc(alias = "ts_query_cursor_set_byte_range")]
    pub fn set_byte_range(&mut self, range: ops::Range<usize>) {
        unsafe {
            ffi::ts_query_cursor_set_byte_range(self.ptr, range.start as u32, range.end as u32);
        }
    }

    #[doc(alias = "ts_query_cursor_set_point_range")]
    pub fn set_point_range(&mut self, range: ops::Range<Point>) {
        unsafe {
            ffi::ts_query_cursor_set_point_range(self.ptr, range.start.into(), range.end.into());
        }
    }
}

impl fmt::Debug for QueryMatch<'_, '_> {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(
            f,
            "QueryMatch {{ id: {}, pattern_index: {}, captures: {:?} }}",
            self.id, self.pattern_index, self.captures
        )
    }
}

impl<F, R, I> TextProvider<I> for F
where
    F: FnMut(Node) -> R,
    R: Iterator<Item = I>,
    I: AsRef<[u8]>,
{
    type I = R;

    fn text(&mut self, node: Node) -> Self::I {
        (self)(node)
    }
}

impl<'a> TextProvider<&'a [u8]> for &'a [u8] {
    type I = iter::Once<&'a [u8]>;

    fn text(&mut self, node: Node) -> Self::I {
        iter::once(&self[node.byte_range()])
    }
}

impl PartialEq for Query {
    fn eq(&self, other: &Self) -> bool {
        self.ptr == other.ptr
    }
}

impl Drop for Query {
    fn drop(&mut self) {
        unsafe { ffi::ts_query_delete(self.ptr.as_ptr()) }
    }
}

impl Drop for QueryCursor {
    fn drop(&mut self) {
        unsafe { ffi::ts_query_cursor_delete(self.ptr.as_ptr()) }
    }
}

impl Point {
    #[must_use]
    pub const fn new(row: usize, column: usize) -> Self {
        Self { row, column }
    }
}

impl fmt::Display for Point {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "({}, {})", self.row, self.column)
    }
}

impl From<Point> for ffi::TSPoint {
    fn from(val: Point) -> Self {
        Self {
            row: val.row as u32,
            column: val.column as u32,
        }
    }
}

impl From<ffi::TSPoint> for Point {
    fn from(point: ffi::TSPoint) -> Self {
        Self {
            row: point.row as usize,
            column: point.column as usize,
        }
    }
}

impl From<Range> for ffi::TSRange {
    fn from(val: Range) -> Self {
        Self {
            start_byte: val.start_byte as u32,
            end_byte: val.end_byte as u32,
            start_point: val.start_point.into(),
            end_point: val.end_point.into(),
        }
    }
}

impl From<ffi::TSRange> for Range {
    fn from(range: ffi::TSRange) -> Self {
        Self {
            start_byte: range.start_byte as usize,
            end_byte: range.end_byte as usize,
            start_point: range.start_point.into(),
            end_point: range.end_point.into(),
        }
    }
}

impl From<&InputEdit> for ffi::TSInputEdit {
    fn from(val: &InputEdit) -> Self {
        Self {
            start_byte: val.start_byte as u32,
            old_end_byte: val.old_end_byte as u32,
            new_end_byte: val.new_end_byte as u32,
            start_point: val.start_position.into(),
            old_end_point: val.old_end_position.into(),
            new_end_point: val.new_end_position.into(),
        }
    }
}

impl<'a> LossyUtf8<'a> {
    #[must_use]
    pub const fn new(bytes: &'a [u8]) -> Self {
        LossyUtf8 {
            bytes,
            in_replacement: false,
        }
    }
}

impl<'a> Iterator for LossyUtf8<'a> {
    type Item = &'a str;

    fn next(&mut self) -> Option<&'a str> {
        if self.bytes.is_empty() {
            return None;
        }
        if self.in_replacement {
            self.in_replacement = false;
            return Some("\u{fffd}");
        }
        match core::str::from_utf8(self.bytes) {
            Ok(valid) => {
                self.bytes = &[];
                Some(valid)
            }
            Err(error) => {
                if let Some(error_len) = error.error_len() {
                    let error_start = error.valid_up_to();
                    if error_start > 0 {
                        let result =
                            unsafe { core::str::from_utf8_unchecked(&self.bytes[..error_start]) };
                        self.bytes = &self.bytes[(error_start + error_len)..];
                        self.in_replacement = true;
                        Some(result)
                    } else {
                        self.bytes = &self.bytes[error_len..];
                        Some("\u{fffd}")
                    }
                } else {
                    None
                }
            }
        }
    }
}

#[must_use]
const fn predicate_error(row: usize, message: String) -> QueryError {
    QueryError {
        kind: QueryErrorKind::Predicate,
        row,
        column: 0,
        offset: 0,
        message,
    }
}

impl fmt::Display for IncludedRangesError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Incorrect range by index: {}", self.0)
    }
}

impl fmt::Display for LanguageError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self {
            Self::Version(version) => {
                write!(
                    f,
                    "Incompatible language version {version:#x}. Expected {LANGUAGE_VERSION:#x}",
                )
            }
            Self::NotParseable => {
                write!(f, "Language cannot be used for parsing.")
            }
            #[cfg(feature = "wasm")]
            Self::Wasm => {
                write!(f, "Failed to load the Wasm store.")
            }
        }
    }
}

impl fmt::Display for QueryError {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let msg = match self.kind {
            QueryErrorKind::Field => "Invalid field name ",
            QueryErrorKind::NodeType => "Invalid node type ",
            QueryErrorKind::Capture => "Invalid capture name ",
            QueryErrorKind::Predicate => "Invalid predicate: ",
            QueryErrorKind::Structure => "Impossible pattern:\n",
            QueryErrorKind::Syntax => "Invalid syntax:\n",
            QueryErrorKind::Language => "",
        };
        if msg.is_empty() {
            write!(f, "{}", self.message)
        } else {
            write!(
                f,
                "Query error at {}:{}. {}{}",
                self.row + 1,
                self.column + 1,
                msg,
                self.message
            )
        }
    }
}

#[doc(hidden)]
#[must_use]
pub fn format_sexp(sexp: &str, initial_indent_level: usize) -> String {
    let sexp = sexp.trim();
    let mut indent_level = initial_indent_level;
    let mut formatted = String::with_capacity(sexp.len());
    let mut has_field = false;

    let mut c_iter = sexp.chars().peekable();
    let mut scratch = String::with_capacity(sexp.len());
    let mut quote = '\0';
    let mut saw_paren = false;
    let mut did_last = false;
    let mut first_token = true;
    let mut quote_suffixes = quote_suffix_minimum_depths(sexp);
    let mut byte_offset = 0;

    let mut fetch_next_str = |next: &mut String, payload_quote: char, open_nodes: usize| {
        let root_token = first_token;
        first_token = false;
        let open_nodes = if root_token { 1 } else { open_nodes };
        next.clear();
        let mut separated = false;
        while let Some(c) = c_iter.next() {
            byte_offset += c.len_utf8();
            if quote != '\0' {
                // `to_sexp` does not escape quotes in anonymous MISSING names or
                // quoted UNEXPECTED characters, so their node boundary disambiguates
                // the delimiter. Named MISSING payloads are emitted without delimiters.
                if c == quote
                    && quote_closing_depth(c_iter.clone()).is_some_and(|depth| depth <= open_nodes)
                {
                    quote = '\0';
                }
            } else if next.is_empty() && c == payload_quote {
                let suffixes = &mut quote_suffixes[usize::from(c == '"')];
                while suffixes
                    .last()
                    .is_some_and(|&(offset, _)| offset < byte_offset)
                {
                    suffixes.pop();
                }
                if suffixes
                    .last()
                    .is_some_and(|&(_, depth)| depth <= open_nodes)
                {
                    quote = c;
                }
            } else if root_token
                && next == "("
                && c == '"'
                && sexp.len() > 3
                && sexp.ends_with("\")")
            {
                quote = c;
            } else if c == ' ' {
                separated = true;
                break;
            } else if c == ')' {
                saw_paren = true;
                break;
            }
            next.push(c);
        }

        if c_iter.peek().is_none() && next.is_empty() {
            if saw_paren {
                saw_paren = false;
                return Some(false);
            }
            if !did_last {
                did_last = true;
                return Some(false);
            }
            return None;
        }
        let has_payload = separated
            && (next == "(MISSING" || next == "(UNEXPECTED")
            && c_iter.peek().is_some_and(|&c| c != '(' && c != ')')
            && !sexp_field_follows(c_iter.clone());
        Some(has_payload)
    };

    while let Some(has_payload) = fetch_next_str(
        &mut scratch,
        '\0',
        indent_level.saturating_sub(initial_indent_level),
    ) {
        if scratch.is_empty() && indent_level > initial_indent_level {
            indent_level -= 1;
            write!(formatted, ")").unwrap();
        } else if scratch.starts_with('(') {
            if has_field {
                has_field = false;
            } else {
                if indent_level > 0 {
                    writeln!(formatted).unwrap();
                    for _ in 0..indent_level {
                        write!(formatted, "  ").unwrap();
                    }
                }
                indent_level += 1;
            }

            write!(formatted, "{scratch}").unwrap();

            if has_payload {
                let payload_quote = if scratch == "(UNEXPECTED" { '\'' } else { '"' };
                fetch_next_str(
                    &mut scratch,
                    payload_quote,
                    indent_level.saturating_sub(initial_indent_level),
                )
                .unwrap();
                if scratch.is_empty() {
                    while indent_level > initial_indent_level {
                        indent_level -= 1;
                        write!(formatted, ")").unwrap();
                    }
                } else {
                    write!(formatted, " {scratch}").unwrap();
                }
            }
        } else if scratch.ends_with(':') {
            writeln!(formatted).unwrap();
            for _ in 0..indent_level {
                write!(formatted, "  ").unwrap();
            }
            write!(formatted, "{scratch} ").unwrap();
            has_field = true;
            indent_level += 1;
        }
    }

    formatted
}

fn sexp_field_follows(mut chars: impl Iterator<Item = char>) -> bool {
    let mut last = None;
    for c in chars.by_ref() {
        match c {
            '(' | ')' | '\'' | '"' => return false,
            ' ' => break,
            _ => last = Some(c),
        }
    }
    last == Some(':') && chars.next() == Some('(')
}

fn quote_suffix_minimum_depths(sexp: &str) -> [Vec<(usize, usize)>; 2] {
    let mut suffixes: [Vec<(usize, usize)>; 2] = [Vec::new(), Vec::new()];
    for (offset, c) in sexp.char_indices().rev() {
        if c != '\'' && c != '"' {
            continue;
        }
        if let Some(depth) = quote_closing_depth(sexp[offset + 1..].chars()) {
            let quotes = &mut suffixes[usize::from(c == '"')];
            // A later, shallower candidate answers the same existence query for longer.
            if quotes.last().is_none_or(|&(_, minimum)| depth < minimum) {
                quotes.push((offset, depth));
            }
        }
    }
    suffixes
}

fn quote_closing_depth(mut chars: impl Iterator<Item = char>) -> Option<usize> {
    match chars.next() {
        None => Some(0),
        Some(')') => {
            let mut depth = 1;
            for c in chars {
                match c {
                    ')' => depth += 1,
                    c if c.is_whitespace() => return Some(depth),
                    _ => return None,
                }
            }
            Some(depth)
        }
        _ => None,
    }
}

pub fn wasm_stdlib_symbols() -> impl Iterator<Item = &'static str> {
    const WASM_STDLIB_SYMBOLS: &str = include_str!(concat!(env!("OUT_DIR"), "/stdlib-symbols.txt"));

    WASM_STDLIB_SYMBOLS
        .lines()
        .map(|s| s.trim_matches(|c| c == '"' || c == ','))
}

unsafe extern "C" {
    fn ts_node_string_pretty(node: ffi::TSNode, initial_indent_level: usize) -> *mut c_char;
    static mut ts_current_free: unsafe extern "C" fn(ptr: *mut c_void);
}

/// Frees a pointer that was returned by a tree-sitter C API using whichever `free`
/// function is currently installed via [`set_allocator`] or [`ffi::ts_set_allocator`].
#[inline]
unsafe fn ts_free(ptr: *mut c_void) {
    let f = unsafe { core::ptr::addr_of!(ts_current_free).read() };
    unsafe { f(ptr) };
}

/// A complete set of memory allocation functions for the core C library.
#[derive(Copy, Clone)]
pub struct Allocator {
    pub malloc: unsafe extern "C" fn(size: usize) -> *mut c_void,
    pub calloc: unsafe extern "C" fn(nmemb: usize, size: usize) -> *mut c_void,
    pub realloc: unsafe extern "C" fn(ptr: *mut c_void, size: usize) -> *mut c_void,
    pub free: unsafe extern "C" fn(ptr: *mut c_void),
}

/// Replaces the memory allocation functions used by the core C library.
///
/// Pass `Some` to install an allocator, or `None` to restore libc defaults.
///
/// # Safety
///
/// All of the following must hold:
///
/// - The four functions must belong to a single allocator family.
///
/// - The functions must not return null for non-zero allocs.
///
/// - Returned pointers must satisfy the alignment that libc `malloc` provides.
///
/// - Call this before any other tree-sitter API call, and do not call it again
///   while live tree-sitter objects exist.
///
/// - This function is not thread-safe.
#[doc(alias = "ts_set_allocator")]
pub unsafe fn set_allocator(allocator: Option<Allocator>) {
    let (m, c, r, f) = match allocator {
        Some(a) => (
            Some(a.malloc),
            Some(a.calloc),
            Some(a.realloc),
            Some(a.free),
        ),
        None => (None, None, None, None),
    };
    unsafe { ffi::ts_set_allocator(m, c, r, f) };
}

#[cfg(feature = "std")]
#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
impl error::Error for IncludedRangesError {}
#[cfg(feature = "std")]
#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
impl error::Error for LanguageError {}
#[cfg(feature = "std")]
#[cfg_attr(docsrs, doc(cfg(feature = "std")))]
impl error::Error for QueryError {}

#[cfg(not(target_family = "wasm"))]
unsafe impl Send for Language {}
#[cfg(not(target_family = "wasm"))]
unsafe impl Sync for Language {}

unsafe impl Send for Node<'_> {}
unsafe impl Sync for Node<'_> {}

#[cfg(not(target_family = "wasm"))]
unsafe impl Send for LookaheadIterator {}
#[cfg(not(target_family = "wasm"))]
unsafe impl Sync for LookaheadIterator {}

#[cfg(not(target_family = "wasm"))]
unsafe impl Send for LookaheadNamesIterator<'_> {}
#[cfg(not(target_family = "wasm"))]
unsafe impl Sync for LookaheadNamesIterator<'_> {}

#[cfg(not(target_family = "wasm"))]
unsafe impl Send for Parser {}
#[cfg(not(target_family = "wasm"))]
unsafe impl Sync for Parser {}

unsafe impl Send for Query {}
unsafe impl Sync for Query {}

unsafe impl Send for QueryCursor {}
unsafe impl Sync for QueryCursor {}

unsafe impl Send for Tree {}
unsafe impl Sync for Tree {}

unsafe impl Send for TreeCursor<'_> {}
unsafe impl Sync for TreeCursor<'_> {}