1.1--- a/lisp/ffi/tree-sitter/ts-api.h Fri Oct 04 16:14:44 2024 -0400
1.2+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3@@ -1,1180 +0,0 @@
1.4-#ifndef TREE_SITTER_API_H_
1.5-#define TREE_SITTER_API_H_
1.6-
1.7-#if defined(__GNUC__) || defined(__clang__)
1.8-#pragma GCC visibility push(default)
1.9-#endif
1.10-
1.11-#ifdef __cplusplus
1.12-extern "C" {
1.13-#endif
1.14-
1.15-#include <stdlib.h>
1.16-#include <stdint.h>
1.17-#include <stdbool.h>
1.18-
1.19-/****************************/
1.20-/* Section - ABI Versioning */
1.21-/****************************/
1.22-
1.23-/**
1.24- * The latest ABI version that is supported by the current version of the
1.25- * library. When Languages are generated by the Tree-sitter CLI, they are
1.26- * assigned an ABI version number that corresponds to the current CLI version.
1.27- * The Tree-sitter library is generally backwards-compatible with languages
1.28- * generated using older CLI versions, but is not forwards-compatible.
1.29- */
1.30-#define TREE_SITTER_LANGUAGE_VERSION 14
1.31-
1.32-/**
1.33- * The earliest ABI version that is supported by the current version of the
1.34- * library.
1.35- */
1.36-#define TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION 13
1.37-
1.38-/*******************/
1.39-/* Section - Types */
1.40-/*******************/
1.41-
1.42-typedef uint16_t TSStateId;
1.43-typedef uint16_t TSSymbol;
1.44-typedef uint16_t TSFieldId;
1.45-typedef struct TSLanguage TSLanguage;
1.46-typedef struct TSParser TSParser;
1.47-typedef struct TSTree TSTree;
1.48-typedef struct TSQuery TSQuery;
1.49-typedef struct TSQueryCursor TSQueryCursor;
1.50-typedef struct TSLookaheadIterator TSLookaheadIterator;
1.51-
1.52-typedef enum {
1.53- TSInputEncodingUTF8,
1.54- TSInputEncodingUTF16,
1.55-} TSInputEncoding;
1.56-
1.57-typedef enum {
1.58- TSSymbolTypeRegular,
1.59- TSSymbolTypeAnonymous,
1.60- TSSymbolTypeAuxiliary,
1.61-} TSSymbolType;
1.62-
1.63-typedef struct {
1.64- uint32_t row;
1.65- uint32_t column;
1.66-} TSPoint;
1.67-
1.68-typedef struct {
1.69- TSPoint start_point;
1.70- TSPoint end_point;
1.71- uint32_t start_byte;
1.72- uint32_t end_byte;
1.73-} TSRange;
1.74-
1.75-typedef struct {
1.76- void *payload;
1.77- const char *(*read)(void *payload, uint32_t byte_index, TSPoint position, uint32_t *bytes_read);
1.78- TSInputEncoding encoding;
1.79-} TSInput;
1.80-
1.81-typedef enum {
1.82- TSLogTypeParse,
1.83- TSLogTypeLex,
1.84-} TSLogType;
1.85-
1.86-typedef struct {
1.87- void *payload;
1.88- void (*log)(void *payload, TSLogType log_type, const char *buffer);
1.89-} TSLogger;
1.90-
1.91-typedef struct {
1.92- uint32_t start_byte;
1.93- uint32_t old_end_byte;
1.94- uint32_t new_end_byte;
1.95- TSPoint start_point;
1.96- TSPoint old_end_point;
1.97- TSPoint new_end_point;
1.98-} TSInputEdit;
1.99-
1.100-typedef struct {
1.101- uint32_t context[4];
1.102- const void *id;
1.103- const TSTree *tree;
1.104-} TSNode;
1.105-
1.106-typedef struct {
1.107- const void *tree;
1.108- const void *id;
1.109- uint32_t context[2];
1.110-} TSTreeCursor;
1.111-
1.112-typedef struct {
1.113- TSNode node;
1.114- uint32_t index;
1.115-} TSQueryCapture;
1.116-
1.117-typedef enum {
1.118- TSQuantifierZero = 0, // must match the array initialization value
1.119- TSQuantifierZeroOrOne,
1.120- TSQuantifierZeroOrMore,
1.121- TSQuantifierOne,
1.122- TSQuantifierOneOrMore,
1.123-} TSQuantifier;
1.124-
1.125-typedef struct {
1.126- uint32_t id;
1.127- uint16_t pattern_index;
1.128- uint16_t capture_count;
1.129- const TSQueryCapture *captures;
1.130-} TSQueryMatch;
1.131-
1.132-typedef enum {
1.133- TSQueryPredicateStepTypeDone,
1.134- TSQueryPredicateStepTypeCapture,
1.135- TSQueryPredicateStepTypeString,
1.136-} TSQueryPredicateStepType;
1.137-
1.138-typedef struct {
1.139- TSQueryPredicateStepType type;
1.140- uint32_t value_id;
1.141-} TSQueryPredicateStep;
1.142-
1.143-typedef enum {
1.144- TSQueryErrorNone = 0,
1.145- TSQueryErrorSyntax,
1.146- TSQueryErrorNodeType,
1.147- TSQueryErrorField,
1.148- TSQueryErrorCapture,
1.149- TSQueryErrorStructure,
1.150- TSQueryErrorLanguage,
1.151-} TSQueryError;
1.152-
1.153-/********************/
1.154-/* Section - Parser */
1.155-/********************/
1.156-
1.157-/**
1.158- * Create a new parser.
1.159- */
1.160-TSParser *ts_parser_new(void);
1.161-
1.162-/**
1.163- * Delete the parser, freeing all of the memory that it used.
1.164- */
1.165-void ts_parser_delete(TSParser *self);
1.166-
1.167-/**
1.168- * Get the parser's current language.
1.169- */
1.170-const TSLanguage *ts_parser_language(const TSParser *self);
1.171-
1.172-/**
1.173- * Set the language that the parser should use for parsing.
1.174- *
1.175- * Returns a boolean indicating whether or not the language was successfully
1.176- * assigned. True means assignment succeeded. False means there was a version
1.177- * mismatch: the language was generated with an incompatible version of the
1.178- * Tree-sitter CLI. Check the language's version using [`ts_language_version`]
1.179- * and compare it to this library's [`TREE_SITTER_LANGUAGE_VERSION`] and
1.180- * [`TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION`] constants.
1.181- */
1.182-bool ts_parser_set_language(TSParser *self, const TSLanguage *language);
1.183-
1.184-/**
1.185- * Set the ranges of text that the parser should include when parsing.
1.186- *
1.187- * By default, the parser will always include entire documents. This function
1.188- * allows you to parse only a *portion* of a document but still return a syntax
1.189- * tree whose ranges match up with the document as a whole. You can also pass
1.190- * multiple disjoint ranges.
1.191- *
1.192- * The second and third parameters specify the location and length of an array
1.193- * of ranges. The parser does *not* take ownership of these ranges; it copies
1.194- * the data, so it doesn't matter how these ranges are allocated.
1.195- *
1.196- * If `count` is zero, then the entire document will be parsed. Otherwise,
1.197- * the given ranges must be ordered from earliest to latest in the document,
1.198- * and they must not overlap. That is, the following must hold for all:
1.199- *
1.200- * `i < count - 1`: `ranges[i].end_byte <= ranges[i + 1].start_byte`
1.201- *
1.202- * If this requirement is not satisfied, the operation will fail, the ranges
1.203- * will not be assigned, and this function will return `false`. On success,
1.204- * this function returns `true`
1.205- */
1.206-bool ts_parser_set_included_ranges(
1.207- TSParser *self,
1.208- const TSRange *ranges,
1.209- uint32_t count
1.210-);
1.211-
1.212-/**
1.213- * Get the ranges of text that the parser will include when parsing.
1.214- *
1.215- * The returned pointer is owned by the parser. The caller should not free it
1.216- * or write to it. The length of the array will be written to the given
1.217- * `count` pointer.
1.218- */
1.219-const TSRange *ts_parser_included_ranges(
1.220- const TSParser *self,
1.221- uint32_t *count
1.222-);
1.223-
1.224-/**
1.225- * Use the parser to parse some source code and create a syntax tree.
1.226- *
1.227- * If you are parsing this document for the first time, pass `NULL` for the
1.228- * `old_tree` parameter. Otherwise, if you have already parsed an earlier
1.229- * version of this document and the document has since been edited, pass the
1.230- * previous syntax tree so that the unchanged parts of it can be reused.
1.231- * This will save time and memory. For this to work correctly, you must have
1.232- * already edited the old syntax tree using the [`ts_tree_edit`] function in a
1.233- * way that exactly matches the source code changes.
1.234- *
1.235- * The [`TSInput`] parameter lets you specify how to read the text. It has the
1.236- * following three fields:
1.237- * 1. [`read`]: A function to retrieve a chunk of text at a given byte offset
1.238- * and (row, column) position. The function should return a pointer to the
1.239- * text and write its length to the [`bytes_read`] pointer. The parser does
1.240- * not take ownership of this buffer; it just borrows it until it has
1.241- * finished reading it. The function should write a zero value to the
1.242- * [`bytes_read`] pointer to indicate the end of the document.
1.243- * 2. [`payload`]: An arbitrary pointer that will be passed to each invocation
1.244- * of the [`read`] function.
1.245- * 3. [`encoding`]: An indication of how the text is encoded. Either
1.246- * `TSInputEncodingUTF8` or `TSInputEncodingUTF16`.
1.247- *
1.248- * This function returns a syntax tree on success, and `NULL` on failure. There
1.249- * are three possible reasons for failure:
1.250- * 1. The parser does not have a language assigned. Check for this using the
1.251- [`ts_parser_language`] function.
1.252- * 2. Parsing was cancelled due to a timeout that was set by an earlier call to
1.253- * the [`ts_parser_set_timeout_micros`] function. You can resume parsing from
1.254- * where the parser left out by calling [`ts_parser_parse`] again with the
1.255- * same arguments. Or you can start parsing from scratch by first calling
1.256- * [`ts_parser_reset`].
1.257- * 3. Parsing was cancelled using a cancellation flag that was set by an
1.258- * earlier call to [`ts_parser_set_cancellation_flag`]. You can resume parsing
1.259- * from where the parser left out by calling [`ts_parser_parse`] again with
1.260- * the same arguments.
1.261- *
1.262- * [`read`]: TSInput::read
1.263- * [`payload`]: TSInput::payload
1.264- * [`encoding`]: TSInput::encoding
1.265- * [`bytes_read`]: TSInput::read
1.266- */
1.267-TSTree *ts_parser_parse(
1.268- TSParser *self,
1.269- const TSTree *old_tree,
1.270- TSInput input
1.271-);
1.272-
1.273-/**
1.274- * Use the parser to parse some source code stored in one contiguous buffer.
1.275- * The first two parameters are the same as in the [`ts_parser_parse`] function
1.276- * above. The second two parameters indicate the location of the buffer and its
1.277- * length in bytes.
1.278- */
1.279-TSTree *ts_parser_parse_string(
1.280- TSParser *self,
1.281- const TSTree *old_tree,
1.282- const char *string,
1.283- uint32_t length
1.284-);
1.285-
1.286-/**
1.287- * Use the parser to parse some source code stored in one contiguous buffer with
1.288- * a given encoding. The first four parameters work the same as in the
1.289- * [`ts_parser_parse_string`] method above. The final parameter indicates whether
1.290- * the text is encoded as UTF8 or UTF16.
1.291- */
1.292-TSTree *ts_parser_parse_string_encoding(
1.293- TSParser *self,
1.294- const TSTree *old_tree,
1.295- const char *string,
1.296- uint32_t length,
1.297- TSInputEncoding encoding
1.298-);
1.299-
1.300-/**
1.301- * Instruct the parser to start the next parse from the beginning.
1.302- *
1.303- * If the parser previously failed because of a timeout or a cancellation, then
1.304- * by default, it will resume where it left off on the next call to
1.305- * [`ts_parser_parse`] or other parsing functions. If you don't want to resume,
1.306- * and instead intend to use this parser to parse some other document, you must
1.307- * call [`ts_parser_reset`] first.
1.308- */
1.309-void ts_parser_reset(TSParser *self);
1.310-
1.311-/**
1.312- * Set the maximum duration in microseconds that parsing should be allowed to
1.313- * take before halting.
1.314- *
1.315- * If parsing takes longer than this, it will halt early, returning NULL.
1.316- * See [`ts_parser_parse`] for more information.
1.317- */
1.318-void ts_parser_set_timeout_micros(TSParser *self, uint64_t timeout_micros);
1.319-
1.320-/**
1.321- * Get the duration in microseconds that parsing is allowed to take.
1.322- */
1.323-uint64_t ts_parser_timeout_micros(const TSParser *self);
1.324-
1.325-/**
1.326- * Set the parser's current cancellation flag pointer.
1.327- *
1.328- * If a non-null pointer is assigned, then the parser will periodically read
1.329- * from this pointer during parsing. If it reads a non-zero value, it will
1.330- * halt early, returning NULL. See [`ts_parser_parse`] for more information.
1.331- */
1.332-void ts_parser_set_cancellation_flag(TSParser *self, const size_t *flag);
1.333-
1.334-/**
1.335- * Get the parser's current cancellation flag pointer.
1.336- */
1.337-const size_t *ts_parser_cancellation_flag(const TSParser *self);
1.338-
1.339-/**
1.340- * Set the logger that a parser should use during parsing.
1.341- *
1.342- * The parser does not take ownership over the logger payload. If a logger was
1.343- * previously assigned, the caller is responsible for releasing any memory
1.344- * owned by the previous logger.
1.345- */
1.346-void ts_parser_set_logger(TSParser *self, TSLogger logger);
1.347-
1.348-/**
1.349- * Get the parser's current logger.
1.350- */
1.351-TSLogger ts_parser_logger(const TSParser *self);
1.352-
1.353-/**
1.354- * Set the file descriptor to which the parser should write debugging graphs
1.355- * during parsing. The graphs are formatted in the DOT language. You may want
1.356- * to pipe these graphs directly to a `dot(1)` process in order to generate
1.357- * SVG output. You can turn off this logging by passing a negative number.
1.358- */
1.359-void ts_parser_print_dot_graphs(TSParser *self, int fd);
1.360-
1.361-/******************/
1.362-/* Section - Tree */
1.363-/******************/
1.364-
1.365-/**
1.366- * Create a shallow copy of the syntax tree. This is very fast.
1.367- *
1.368- * You need to copy a syntax tree in order to use it on more than one thread at
1.369- * a time, as syntax trees are not thread safe.
1.370- */
1.371-TSTree *ts_tree_copy(const TSTree *self);
1.372-
1.373-/**
1.374- * Delete the syntax tree, freeing all of the memory that it used.
1.375- */
1.376-void ts_tree_delete(TSTree *self);
1.377-
1.378-/**
1.379- * Get the root node of the syntax tree.
1.380- */
1.381-TSNode ts_tree_root_node(const TSTree *self);
1.382-
1.383-/**
1.384- * Get the root node of the syntax tree, but with its position
1.385- * shifted forward by the given offset.
1.386- */
1.387-TSNode ts_tree_root_node_with_offset(
1.388- const TSTree *self,
1.389- uint32_t offset_bytes,
1.390- TSPoint offset_extent
1.391-);
1.392-
1.393-/**
1.394- * Get the language that was used to parse the syntax tree.
1.395- */
1.396-const TSLanguage *ts_tree_language(const TSTree *self);
1.397-
1.398-/**
1.399- * Get the array of included ranges that was used to parse the syntax tree.
1.400- *
1.401- * The returned pointer must be freed by the caller.
1.402- */
1.403-TSRange *ts_tree_included_ranges(const TSTree *self, uint32_t *length);
1.404-
1.405-/**
1.406- * Edit the syntax tree to keep it in sync with source code that has been
1.407- * edited.
1.408- *
1.409- * You must describe the edit both in terms of byte offsets and in terms of
1.410- * (row, column) coordinates.
1.411- */
1.412-void ts_tree_edit(TSTree *self, const TSInputEdit *edit);
1.413-
1.414-/**
1.415- * Compare an old edited syntax tree to a new syntax tree representing the same
1.416- * document, returning an array of ranges whose syntactic structure has changed.
1.417- *
1.418- * For this to work correctly, the old syntax tree must have been edited such
1.419- * that its ranges match up to the new tree. Generally, you'll want to call
1.420- * this function right after calling one of the [`ts_parser_parse`] functions.
1.421- * You need to pass the old tree that was passed to parse, as well as the new
1.422- * tree that was returned from that function.
1.423- *
1.424- * The returned array is allocated using `malloc` and the caller is responsible
1.425- * for freeing it using `free`. The length of the array will be written to the
1.426- * given `length` pointer.
1.427- */
1.428-TSRange *ts_tree_get_changed_ranges(
1.429- const TSTree *old_tree,
1.430- const TSTree *new_tree,
1.431- uint32_t *length
1.432-);
1.433-
1.434-/**
1.435- * Write a DOT graph describing the syntax tree to the given file.
1.436- */
1.437-void ts_tree_print_dot_graph(const TSTree *self, int file_descriptor);
1.438-
1.439-/******************/
1.440-/* Section - Node */
1.441-/******************/
1.442-
1.443-/**
1.444- * Get the node's type as a null-terminated string.
1.445- */
1.446-const char *ts_node_type(TSNode self);
1.447-
1.448-/**
1.449- * Get the node's type as a numerical id.
1.450- */
1.451-TSSymbol ts_node_symbol(TSNode self);
1.452-
1.453-/**
1.454- * Get the node's language.
1.455- */
1.456-const TSLanguage *ts_node_language(TSNode self);
1.457-
1.458-/**
1.459- * Get the node's type as it appears in the grammar ignoring aliases as a
1.460- * null-terminated string.
1.461- */
1.462-const char *ts_node_grammar_type(TSNode self);
1.463-
1.464-/**
1.465- * Get the node's type as a numerical id as it appears in the grammar ignoring
1.466- * aliases. This should be used in [`ts_language_next_state`] instead of
1.467- * [`ts_node_symbol`].
1.468- */
1.469-TSSymbol ts_node_grammar_symbol(TSNode self);
1.470-
1.471-/**
1.472- * Get the node's start byte.
1.473- */
1.474-uint32_t ts_node_start_byte(TSNode self);
1.475-
1.476-/**
1.477- * Get the node's start position in terms of rows and columns.
1.478- */
1.479-TSPoint ts_node_start_point(TSNode self);
1.480-
1.481-/**
1.482- * Get the node's end byte.
1.483- */
1.484-uint32_t ts_node_end_byte(TSNode self);
1.485-
1.486-/**
1.487- * Get the node's end position in terms of rows and columns.
1.488- */
1.489-TSPoint ts_node_end_point(TSNode self);
1.490-
1.491-/**
1.492- * Get an S-expression representing the node as a string.
1.493- *
1.494- * This string is allocated with `malloc` and the caller is responsible for
1.495- * freeing it using `free`.
1.496- */
1.497-char *ts_node_string(TSNode self);
1.498-
1.499-/**
1.500- * Check if the node is null. Functions like [`ts_node_child`] and
1.501- * [`ts_node_next_sibling`] will return a null node to indicate that no such node
1.502- * was found.
1.503- */
1.504-bool ts_node_is_null(TSNode self);
1.505-
1.506-/**
1.507- * Check if the node is *named*. Named nodes correspond to named rules in the
1.508- * grammar, whereas *anonymous* nodes correspond to string literals in the
1.509- * grammar.
1.510- */
1.511-bool ts_node_is_named(TSNode self);
1.512-
1.513-/**
1.514- * Check if the node is *missing*. Missing nodes are inserted by the parser in
1.515- * order to recover from certain kinds of syntax errors.
1.516- */
1.517-bool ts_node_is_missing(TSNode self);
1.518-
1.519-/**
1.520- * Check if the node is *extra*. Extra nodes represent things like comments,
1.521- * which are not required the grammar, but can appear anywhere.
1.522- */
1.523-bool ts_node_is_extra(TSNode self);
1.524-
1.525-/**
1.526- * Check if a syntax node has been edited.
1.527- */
1.528-bool ts_node_has_changes(TSNode self);
1.529-
1.530-/**
1.531- * Check if the node is a syntax error or contains any syntax errors.
1.532- */
1.533-bool ts_node_has_error(TSNode self);
1.534-
1.535-/**
1.536- * Check if the node is a syntax error.
1.537-*/
1.538-bool ts_node_is_error(TSNode self);
1.539-
1.540-/**
1.541- * Get this node's parse state.
1.542-*/
1.543-TSStateId ts_node_parse_state(TSNode self);
1.544-
1.545-/**
1.546- * Get the parse state after this node.
1.547-*/
1.548-TSStateId ts_node_next_parse_state(TSNode self);
1.549-
1.550-/**
1.551- * Get the node's immediate parent.
1.552- */
1.553-TSNode ts_node_parent(TSNode self);
1.554-
1.555-/**
1.556- * Get the node's child at the given index, where zero represents the first
1.557- * child.
1.558- */
1.559-TSNode ts_node_child(TSNode self, uint32_t child_index);
1.560-
1.561-/**
1.562- * Get the field name for node's child at the given index, where zero represents
1.563- * the first child. Returns NULL, if no field is found.
1.564- */
1.565-const char *ts_node_field_name_for_child(TSNode self, uint32_t child_index);
1.566-
1.567-/**
1.568- * Get the node's number of children.
1.569- */
1.570-uint32_t ts_node_child_count(TSNode self);
1.571-
1.572-/**
1.573- * Get the node's *named* child at the given index.
1.574- *
1.575- * See also [`ts_node_is_named`].
1.576- */
1.577-TSNode ts_node_named_child(TSNode self, uint32_t child_index);
1.578-
1.579-/**
1.580- * Get the node's number of *named* children.
1.581- *
1.582- * See also [`ts_node_is_named`].
1.583- */
1.584-uint32_t ts_node_named_child_count(TSNode self);
1.585-
1.586-/**
1.587- * Get the node's child with the given field name.
1.588- */
1.589-TSNode ts_node_child_by_field_name(
1.590- TSNode self,
1.591- const char *name,
1.592- uint32_t name_length
1.593-);
1.594-
1.595-/**
1.596- * Get the node's child with the given numerical field id.
1.597- *
1.598- * You can convert a field name to an id using the
1.599- * [`ts_language_field_id_for_name`] function.
1.600- */
1.601-TSNode ts_node_child_by_field_id(TSNode self, TSFieldId field_id);
1.602-
1.603-/**
1.604- * Get the node's next / previous sibling.
1.605- */
1.606-TSNode ts_node_next_sibling(TSNode self);
1.607-TSNode ts_node_prev_sibling(TSNode self);
1.608-
1.609-/**
1.610- * Get the node's next / previous *named* sibling.
1.611- */
1.612-TSNode ts_node_next_named_sibling(TSNode self);
1.613-TSNode ts_node_prev_named_sibling(TSNode self);
1.614-
1.615-/**
1.616- * Get the node's first child that extends beyond the given byte offset.
1.617- */
1.618-TSNode ts_node_first_child_for_byte(TSNode self, uint32_t byte);
1.619-
1.620-/**
1.621- * Get the node's first named child that extends beyond the given byte offset.
1.622- */
1.623-TSNode ts_node_first_named_child_for_byte(TSNode self, uint32_t byte);
1.624-
1.625-/**
1.626- * Get the node's number of descendants, including one for the node itself.
1.627- */
1.628-uint32_t ts_node_descendant_count(TSNode self);
1.629-
1.630-/**
1.631- * Get the smallest node within this node that spans the given range of bytes
1.632- * or (row, column) positions.
1.633- */
1.634-TSNode ts_node_descendant_for_byte_range(TSNode self, uint32_t start, uint32_t end);
1.635-TSNode ts_node_descendant_for_point_range(TSNode self, TSPoint start, TSPoint end);
1.636-
1.637-/**
1.638- * Get the smallest named node within this node that spans the given range of
1.639- * bytes or (row, column) positions.
1.640- */
1.641-TSNode ts_node_named_descendant_for_byte_range(TSNode self, uint32_t start, uint32_t end);
1.642-TSNode ts_node_named_descendant_for_point_range(TSNode self, TSPoint start, TSPoint end);
1.643-
1.644-/**
1.645- * Edit the node to keep it in-sync with source code that has been edited.
1.646- *
1.647- * This function is only rarely needed. When you edit a syntax tree with the
1.648- * [`ts_tree_edit`] function, all of the nodes that you retrieve from the tree
1.649- * afterward will already reflect the edit. You only need to use [`ts_node_edit`]
1.650- * when you have a [`TSNode`] instance that you want to keep and continue to use
1.651- * after an edit.
1.652- */
1.653-void ts_node_edit(TSNode *self, const TSInputEdit *edit);
1.654-
1.655-/**
1.656- * Check if two nodes are identical.
1.657- */
1.658-bool ts_node_eq(TSNode self, TSNode other);
1.659-
1.660-/************************/
1.661-/* Section - TreeCursor */
1.662-/************************/
1.663-
1.664-/**
1.665- * Create a new tree cursor starting from the given node.
1.666- *
1.667- * A tree cursor allows you to walk a syntax tree more efficiently than is
1.668- * possible using the [`TSNode`] functions. It is a mutable object that is always
1.669- * on a certain syntax node, and can be moved imperatively to different nodes.
1.670- */
1.671-TSTreeCursor ts_tree_cursor_new(TSNode node);
1.672-
1.673-/**
1.674- * Delete a tree cursor, freeing all of the memory that it used.
1.675- */
1.676-void ts_tree_cursor_delete(TSTreeCursor *self);
1.677-
1.678-/**
1.679- * Re-initialize a tree cursor to start at a different node.
1.680- */
1.681-void ts_tree_cursor_reset(TSTreeCursor *self, TSNode node);
1.682-
1.683-/**
1.684- * Re-initialize a tree cursor to the same position as another cursor.
1.685- *
1.686- * Unlike [`ts_tree_cursor_reset`], this will not lose parent information and
1.687- * allows reusing already created cursors.
1.688-*/
1.689-void ts_tree_cursor_reset_to(TSTreeCursor *dst, const TSTreeCursor *src);
1.690-
1.691-/**
1.692- * Get the tree cursor's current node.
1.693- */
1.694-TSNode ts_tree_cursor_current_node(const TSTreeCursor *self);
1.695-
1.696-/**
1.697- * Get the field name of the tree cursor's current node.
1.698- *
1.699- * This returns `NULL` if the current node doesn't have a field.
1.700- * See also [`ts_node_child_by_field_name`].
1.701- */
1.702-const char *ts_tree_cursor_current_field_name(const TSTreeCursor *self);
1.703-
1.704-/**
1.705- * Get the field id of the tree cursor's current node.
1.706- *
1.707- * This returns zero if the current node doesn't have a field.
1.708- * See also [`ts_node_child_by_field_id`], [`ts_language_field_id_for_name`].
1.709- */
1.710-TSFieldId ts_tree_cursor_current_field_id(const TSTreeCursor *self);
1.711-
1.712-/**
1.713- * Move the cursor to the parent of its current node.
1.714- *
1.715- * This returns `true` if the cursor successfully moved, and returns `false`
1.716- * if there was no parent node (the cursor was already on the root node).
1.717- */
1.718-bool ts_tree_cursor_goto_parent(TSTreeCursor *self);
1.719-
1.720-/**
1.721- * Move the cursor to the next sibling of its current node.
1.722- *
1.723- * This returns `true` if the cursor successfully moved, and returns `false`
1.724- * if there was no next sibling node.
1.725- */
1.726-bool ts_tree_cursor_goto_next_sibling(TSTreeCursor *self);
1.727-
1.728-/**
1.729- * Move the cursor to the previous sibling of its current node.
1.730- *
1.731- * This returns `true` if the cursor successfully moved, and returns `false` if
1.732- * there was no previous sibling node.
1.733- *
1.734- * Note, that this function may be slower than
1.735- * [`ts_tree_cursor_goto_next_sibling`] due to how node positions are stored. In
1.736- * the worst case, this will need to iterate through all the children upto the
1.737- * previous sibling node to recalculate its position.
1.738- */
1.739-bool ts_tree_cursor_goto_previous_sibling(TSTreeCursor *self);
1.740-
1.741-/**
1.742- * Move the cursor to the first child of its current node.
1.743- *
1.744- * This returns `true` if the cursor successfully moved, and returns `false`
1.745- * if there were no children.
1.746- */
1.747-bool ts_tree_cursor_goto_first_child(TSTreeCursor *self);
1.748-
1.749-/**
1.750- * Move the cursor to the last child of its current node.
1.751- *
1.752- * This returns `true` if the cursor successfully moved, and returns `false` if
1.753- * there were no children.
1.754- *
1.755- * Note that this function may be slower than [`ts_tree_cursor_goto_first_child`]
1.756- * because it needs to iterate through all the children to compute the child's
1.757- * position.
1.758- */
1.759-bool ts_tree_cursor_goto_last_child(TSTreeCursor *self);
1.760-
1.761-/**
1.762- * Move the cursor to the node that is the nth descendant of
1.763- * the original node that the cursor was constructed with, where
1.764- * zero represents the original node itself.
1.765- */
1.766-void ts_tree_cursor_goto_descendant(TSTreeCursor *self, uint32_t goal_descendant_index);
1.767-
1.768-/**
1.769- * Get the index of the cursor's current node out of all of the
1.770- * descendants of the original node that the cursor was constructed with.
1.771- */
1.772-uint32_t ts_tree_cursor_current_descendant_index(const TSTreeCursor *self);
1.773-
1.774-/**
1.775- * Get the depth of the cursor's current node relative to the original
1.776- * node that the cursor was constructed with.
1.777- */
1.778-uint32_t ts_tree_cursor_current_depth(const TSTreeCursor *self);
1.779-
1.780-/**
1.781- * Move the cursor to the first child of its current node that extends beyond
1.782- * the given byte offset or point.
1.783- *
1.784- * This returns the index of the child node if one was found, and returns -1
1.785- * if no such child was found.
1.786- */
1.787-int64_t ts_tree_cursor_goto_first_child_for_byte(TSTreeCursor *self, uint32_t goal_byte);
1.788-int64_t ts_tree_cursor_goto_first_child_for_point(TSTreeCursor *self, TSPoint goal_point);
1.789-
1.790-TSTreeCursor ts_tree_cursor_copy(const TSTreeCursor *cursor);
1.791-
1.792-/*******************/
1.793-/* Section - Query */
1.794-/*******************/
1.795-
1.796-/**
1.797- * Create a new query from a string containing one or more S-expression
1.798- * patterns. The query is associated with a particular language, and can
1.799- * only be run on syntax nodes parsed with that language.
1.800- *
1.801- * If all of the given patterns are valid, this returns a [`TSQuery`].
1.802- * If a pattern is invalid, this returns `NULL`, and provides two pieces
1.803- * of information about the problem:
1.804- * 1. The byte offset of the error is written to the `error_offset` parameter.
1.805- * 2. The type of error is written to the `error_type` parameter.
1.806- */
1.807-TSQuery *ts_query_new(
1.808- const TSLanguage *language,
1.809- const char *source,
1.810- uint32_t source_len,
1.811- uint32_t *error_offset,
1.812- TSQueryError *error_type
1.813-);
1.814-
1.815-/**
1.816- * Delete a query, freeing all of the memory that it used.
1.817- */
1.818-void ts_query_delete(TSQuery *self);
1.819-
1.820-/**
1.821- * Get the number of patterns, captures, or string literals in the query.
1.822- */
1.823-uint32_t ts_query_pattern_count(const TSQuery *self);
1.824-uint32_t ts_query_capture_count(const TSQuery *self);
1.825-uint32_t ts_query_string_count(const TSQuery *self);
1.826-
1.827-/**
1.828- * Get the byte offset where the given pattern starts in the query's source.
1.829- *
1.830- * This can be useful when combining queries by concatenating their source
1.831- * code strings.
1.832- */
1.833-uint32_t ts_query_start_byte_for_pattern(const TSQuery *self, uint32_t pattern_index);
1.834-
1.835-/**
1.836- * Get all of the predicates for the given pattern in the query.
1.837- *
1.838- * The predicates are represented as a single array of steps. There are three
1.839- * types of steps in this array, which correspond to the three legal values for
1.840- * the `type` field:
1.841- * - `TSQueryPredicateStepTypeCapture` - Steps with this type represent names
1.842- * of captures. Their `value_id` can be used with the
1.843- * [`ts_query_capture_name_for_id`] function to obtain the name of the capture.
1.844- * - `TSQueryPredicateStepTypeString` - Steps with this type represent literal
1.845- * strings. Their `value_id` can be used with the
1.846- * [`ts_query_string_value_for_id`] function to obtain their string value.
1.847- * - `TSQueryPredicateStepTypeDone` - Steps with this type are *sentinels*
1.848- * that represent the end of an individual predicate. If a pattern has two
1.849- * predicates, then there will be two steps with this `type` in the array.
1.850- */
1.851-const TSQueryPredicateStep *ts_query_predicates_for_pattern(
1.852- const TSQuery *self,
1.853- uint32_t pattern_index,
1.854- uint32_t *step_count
1.855-);
1.856-
1.857-/*
1.858- * Check if the given pattern in the query has a single root node.
1.859- */
1.860-bool ts_query_is_pattern_rooted(const TSQuery *self, uint32_t pattern_index);
1.861-
1.862-/*
1.863- * Check if the given pattern in the query is 'non local'.
1.864- *
1.865- * A non-local pattern has multiple root nodes and can match within a
1.866- * repeating sequence of nodes, as specified by the grammar. Non-local
1.867- * patterns disable certain optimizations that would otherwise be possible
1.868- * when executing a query on a specific range of a syntax tree.
1.869- */
1.870-bool ts_query_is_pattern_non_local(const TSQuery *self, uint32_t pattern_index);
1.871-
1.872-/*
1.873- * Check if a given pattern is guaranteed to match once a given step is reached.
1.874- * The step is specified by its byte offset in the query's source code.
1.875- */
1.876-bool ts_query_is_pattern_guaranteed_at_step(const TSQuery *self, uint32_t byte_offset);
1.877-
1.878-/**
1.879- * Get the name and length of one of the query's captures, or one of the
1.880- * query's string literals. Each capture and string is associated with a
1.881- * numeric id based on the order that it appeared in the query's source.
1.882- */
1.883-const char *ts_query_capture_name_for_id(
1.884- const TSQuery *self,
1.885- uint32_t index,
1.886- uint32_t *length
1.887-);
1.888-
1.889-/**
1.890- * Get the quantifier of the query's captures. Each capture is * associated
1.891- * with a numeric id based on the order that it appeared in the query's source.
1.892- */
1.893-TSQuantifier ts_query_capture_quantifier_for_id(
1.894- const TSQuery *self,
1.895- uint32_t pattern_index,
1.896- uint32_t capture_index
1.897-);
1.898-
1.899-const char *ts_query_string_value_for_id(
1.900- const TSQuery *self,
1.901- uint32_t index,
1.902- uint32_t *length
1.903-);
1.904-
1.905-/**
1.906- * Disable a certain capture within a query.
1.907- *
1.908- * This prevents the capture from being returned in matches, and also avoids
1.909- * any resource usage associated with recording the capture. Currently, there
1.910- * is no way to undo this.
1.911- */
1.912-void ts_query_disable_capture(TSQuery *self, const char *name, uint32_t length);
1.913-
1.914-/**
1.915- * Disable a certain pattern within a query.
1.916- *
1.917- * This prevents the pattern from matching and removes most of the overhead
1.918- * associated with the pattern. Currently, there is no way to undo this.
1.919- */
1.920-void ts_query_disable_pattern(TSQuery *self, uint32_t pattern_index);
1.921-
1.922-/**
1.923- * Create a new cursor for executing a given query.
1.924- *
1.925- * The cursor stores the state that is needed to iteratively search
1.926- * for matches. To use the query cursor, first call [`ts_query_cursor_exec`]
1.927- * to start running a given query on a given syntax node. Then, there are
1.928- * two options for consuming the results of the query:
1.929- * 1. Repeatedly call [`ts_query_cursor_next_match`] to iterate over all of the
1.930- * *matches* in the order that they were found. Each match contains the
1.931- * index of the pattern that matched, and an array of captures. Because
1.932- * multiple patterns can match the same set of nodes, one match may contain
1.933- * captures that appear *before* some of the captures from a previous match.
1.934- * 2. Repeatedly call [`ts_query_cursor_next_capture`] to iterate over all of the
1.935- * individual *captures* in the order that they appear. This is useful if
1.936- * don't care about which pattern matched, and just want a single ordered
1.937- * sequence of captures.
1.938- *
1.939- * If you don't care about consuming all of the results, you can stop calling
1.940- * [`ts_query_cursor_next_match`] or [`ts_query_cursor_next_capture`] at any point.
1.941- * You can then start executing another query on another node by calling
1.942- * [`ts_query_cursor_exec`] again.
1.943- */
1.944-TSQueryCursor *ts_query_cursor_new(void);
1.945-
1.946-/**
1.947- * Delete a query cursor, freeing all of the memory that it used.
1.948- */
1.949-void ts_query_cursor_delete(TSQueryCursor *self);
1.950-
1.951-/**
1.952- * Start running a given query on a given node.
1.953- */
1.954-void ts_query_cursor_exec(TSQueryCursor *self, const TSQuery *query, TSNode node);
1.955-
1.956-/**
1.957- * Manage the maximum number of in-progress matches allowed by this query
1.958- * cursor.
1.959- *
1.960- * Query cursors have an optional maximum capacity for storing lists of
1.961- * in-progress captures. If this capacity is exceeded, then the
1.962- * earliest-starting match will silently be dropped to make room for further
1.963- * matches. This maximum capacity is optional — by default, query cursors allow
1.964- * any number of pending matches, dynamically allocating new space for them as
1.965- * needed as the query is executed.
1.966- */
1.967-bool ts_query_cursor_did_exceed_match_limit(const TSQueryCursor *self);
1.968-uint32_t ts_query_cursor_match_limit(const TSQueryCursor *self);
1.969-void ts_query_cursor_set_match_limit(TSQueryCursor *self, uint32_t limit);
1.970-
1.971-/**
1.972- * Set the range of bytes or (row, column) positions in which the query
1.973- * will be executed.
1.974- */
1.975-void ts_query_cursor_set_byte_range(TSQueryCursor *self, uint32_t start_byte, uint32_t end_byte);
1.976-void ts_query_cursor_set_point_range(TSQueryCursor *self, TSPoint start_point, TSPoint end_point);
1.977-
1.978-/**
1.979- * Advance to the next match of the currently running query.
1.980- *
1.981- * If there is a match, write it to `*match` and return `true`.
1.982- * Otherwise, return `false`.
1.983- */
1.984-bool ts_query_cursor_next_match(TSQueryCursor *self, TSQueryMatch *match);
1.985-void ts_query_cursor_remove_match(TSQueryCursor *self, uint32_t match_id);
1.986-
1.987-/**
1.988- * Advance to the next capture of the currently running query.
1.989- *
1.990- * If there is a capture, write its match to `*match` and its index within
1.991- * the matche's capture list to `*capture_index`. Otherwise, return `false`.
1.992- */
1.993-bool ts_query_cursor_next_capture(
1.994- TSQueryCursor *self,
1.995- TSQueryMatch *match,
1.996- uint32_t *capture_index
1.997-);
1.998-
1.999-/**
1.1000- * Set the maximum start depth for a query cursor.
1.1001- *
1.1002- * This prevents cursors from exploring children nodes at a certain depth.
1.1003- * Note if a pattern includes many children, then they will still be checked.
1.1004- *
1.1005- * The zero max start depth value can be used as a special behavior and
1.1006- * it helps to destructure a subtree by staying on a node and using captures
1.1007- * for interested parts. Note that the zero max start depth only limit a search
1.1008- * depth for a pattern's root node but other nodes that are parts of the pattern
1.1009- * may be searched at any depth what defined by the pattern structure.
1.1010- *
1.1011- * Set to `UINT32_MAX` to remove the maximum start depth.
1.1012- */
1.1013-void ts_query_cursor_set_max_start_depth(TSQueryCursor *self, uint32_t max_start_depth);
1.1014-
1.1015-/**********************/
1.1016-/* Section - Language */
1.1017-/**********************/
1.1018-
1.1019-/**
1.1020- * Get the number of distinct node types in the language.
1.1021- */
1.1022-uint32_t ts_language_symbol_count(const TSLanguage *self);
1.1023-
1.1024-/**
1.1025- * Get the number of valid states in this language.
1.1026-*/
1.1027-uint32_t ts_language_state_count(const TSLanguage *self);
1.1028-
1.1029-/**
1.1030- * Get a node type string for the given numerical id.
1.1031- */
1.1032-const char *ts_language_symbol_name(const TSLanguage *self, TSSymbol symbol);
1.1033-
1.1034-/**
1.1035- * Get the numerical id for the given node type string.
1.1036- */
1.1037-TSSymbol ts_language_symbol_for_name(
1.1038- const TSLanguage *self,
1.1039- const char *string,
1.1040- uint32_t length,
1.1041- bool is_named
1.1042-);
1.1043-
1.1044-/**
1.1045- * Get the number of distinct field names in the language.
1.1046- */
1.1047-uint32_t ts_language_field_count(const TSLanguage *self);
1.1048-
1.1049-/**
1.1050- * Get the field name string for the given numerical id.
1.1051- */
1.1052-const char *ts_language_field_name_for_id(const TSLanguage *self, TSFieldId id);
1.1053-
1.1054-/**
1.1055- * Get the numerical id for the given field name string.
1.1056- */
1.1057-TSFieldId ts_language_field_id_for_name(const TSLanguage *self, const char *name, uint32_t name_length);
1.1058-
1.1059-/**
1.1060- * Check whether the given node type id belongs to named nodes, anonymous nodes,
1.1061- * or a hidden nodes.
1.1062- *
1.1063- * See also [`ts_node_is_named`]. Hidden nodes are never returned from the API.
1.1064- */
1.1065-TSSymbolType ts_language_symbol_type(const TSLanguage *self, TSSymbol symbol);
1.1066-
1.1067-/**
1.1068- * Get the ABI version number for this language. This version number is used
1.1069- * to ensure that languages were generated by a compatible version of
1.1070- * Tree-sitter.
1.1071- *
1.1072- * See also [`ts_parser_set_language`].
1.1073- */
1.1074-uint32_t ts_language_version(const TSLanguage *self);
1.1075-
1.1076-/**
1.1077- * Get the next parse state. Combine this with lookahead iterators to generate
1.1078- * completion suggestions or valid symbols in error nodes. Use
1.1079- * [`ts_node_grammar_symbol`] for valid symbols.
1.1080-*/
1.1081-TSStateId ts_language_next_state(const TSLanguage *self, TSStateId state, TSSymbol symbol);
1.1082-
1.1083-/********************************/
1.1084-/* Section - Lookahead Iterator */
1.1085-/********************************/
1.1086-
1.1087-/**
1.1088- * Create a new lookahead iterator for the given language and parse state.
1.1089- *
1.1090- * This returns `NULL` if state is invalid for the language.
1.1091- *
1.1092- * Repeatedly using [`ts_lookahead_iterator_next`] and
1.1093- * [`ts_lookahead_iterator_current_symbol`] will generate valid symbols in the
1.1094- * given parse state. Newly created lookahead iterators will contain the `ERROR`
1.1095- * symbol.
1.1096- *
1.1097- * Lookahead iterators can be useful to generate suggestions and improve syntax
1.1098- * error diagnostics. To get symbols valid in an ERROR node, use the lookahead
1.1099- * iterator on its first leaf node state. For `MISSING` nodes, a lookahead
1.1100- * iterator created on the previous non-extra leaf node may be appropriate.
1.1101-*/
1.1102-TSLookaheadIterator *ts_lookahead_iterator_new(const TSLanguage *self, TSStateId state);
1.1103-
1.1104-/**
1.1105- * Delete a lookahead iterator freeing all the memory used.
1.1106-*/
1.1107-void ts_lookahead_iterator_delete(TSLookaheadIterator *self);
1.1108-
1.1109-/**
1.1110- * Reset the lookahead iterator to another state.
1.1111- *
1.1112- * This returns `true` if the iterator was reset to the given state and `false`
1.1113- * otherwise.
1.1114-*/
1.1115-bool ts_lookahead_iterator_reset_state(TSLookaheadIterator *self, TSStateId state);
1.1116-
1.1117-/**
1.1118- * Reset the lookahead iterator.
1.1119- *
1.1120- * This returns `true` if the language was set successfully and `false`
1.1121- * otherwise.
1.1122-*/
1.1123-bool ts_lookahead_iterator_reset(TSLookaheadIterator *self, const TSLanguage *language, TSStateId state);
1.1124-
1.1125-/**
1.1126- * Get the current language of the lookahead iterator.
1.1127-*/
1.1128-const TSLanguage *ts_lookahead_iterator_language(const TSLookaheadIterator *self);
1.1129-
1.1130-/**
1.1131- * Advance the lookahead iterator to the next symbol.
1.1132- *
1.1133- * This returns `true` if there is a new symbol and `false` otherwise.
1.1134-*/
1.1135-bool ts_lookahead_iterator_next(TSLookaheadIterator *self);
1.1136-
1.1137-/**
1.1138- * Get the current symbol of the lookahead iterator;
1.1139-*/
1.1140-TSSymbol ts_lookahead_iterator_current_symbol(const TSLookaheadIterator *self);
1.1141-
1.1142-/**
1.1143- * Get the current symbol type of the lookahead iterator as a null terminated
1.1144- * string.
1.1145-*/
1.1146-const char *ts_lookahead_iterator_current_symbol_name(const TSLookaheadIterator *self);
1.1147-
1.1148-/**********************************/
1.1149-/* Section - Global Configuration */
1.1150-/**********************************/
1.1151-
1.1152-/**
1.1153- * Set the allocation functions used by the library.
1.1154- *
1.1155- * By default, Tree-sitter uses the standard libc allocation functions,
1.1156- * but aborts the process when an allocation fails. This function lets
1.1157- * you supply alternative allocation functions at runtime.
1.1158- *
1.1159- * If you pass `NULL` for any parameter, Tree-sitter will switch back to
1.1160- * its default implementation of that function.
1.1161- *
1.1162- * If you call this function after the library has already been used, then
1.1163- * you must ensure that either:
1.1164- * 1. All the existing objects have been freed.
1.1165- * 2. The new allocator shares its state with the old one, so it is capable
1.1166- * of freeing memory that was allocated by the old allocator.
1.1167- */
1.1168-void ts_set_allocator(
1.1169- void *(*new_malloc)(size_t),
1.1170- void *(*new_calloc)(size_t, size_t),
1.1171- void *(*new_realloc)(void *, size_t),
1.1172- void (*new_free)(void *)
1.1173-);
1.1174-
1.1175-#ifdef __cplusplus
1.1176-}
1.1177-#endif
1.1178-
1.1179-#if defined(__GNUC__) || defined(__clang__)
1.1180-#pragma GCC visibility pop
1.1181-#endif
1.1182-
1.1183-#endif // TREE_SITTER_API_H_
