Create npm-publish.yml

[zskbot]

#ifndef TREE_SITTER_API_H_
#define TREE_SITTER_API_H_

#ifndef TREE_SITTER_HIDE_SYMBOLS
#if defined(GNUC) || defined(clang)
#pragma GCC visibility push(default)
#endif
#endif

#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

//
/ Section - ABI Versioning /
//

/**

• The latest ABI version that is supported by the current version of the
• library. When Languages are generated by the Tree-sitter CLI, they are
• assigned an ABI version number that corresponds to the current CLI version.
• The Tree-sitter library is generally backwards-compatible with languages
• generated using older CLI versions, but is not forwards-compatible.
  */
  #define TREE_SITTER_LANGUAGE_VERSION 15

/**

• The earliest ABI version that is supported by the current version of the
• library.
  */
  #define TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION 13

//
/ Section - Types /
//

typedef uint16_t TSStateId;
typedef uint16_t TSSymbol;
typedef uint16_t TSFieldId;
typedef struct TSLanguage TSLanguage;
typedef struct TSParser TSParser;
typedef struct TSTree TSTree;
typedef struct TSQuery TSQuery;
typedef struct TSQueryCursor TSQueryCursor;
typedef struct TSLookaheadIterator TSLookaheadIterator;

// This function signature reads one code point from the given string,
// returning the number of bytes consumed. It should write the code point
// to the code_point pointer, or write -1 if the input is invalid.
typedef uint32_t (*TSDecodeFunction)(
const uint8_t *string,
uint32_t length,
int32_t *code_point
);

// Deprecated alias to be removed in ABI 16
typedef TSDecodeFunction DecodeFunction;

typedef enum TSInputEncoding {
TSInputEncodingUTF8,
TSInputEncodingUTF16LE,
TSInputEncodingUTF16BE,
TSInputEncodingCustom
} TSInputEncoding;

typedef enum TSSymbolType {
TSSymbolTypeRegular,
TSSymbolTypeAnonymous,
TSSymbolTypeSupertype,
TSSymbolTypeAuxiliary,
} TSSymbolType;

typedef struct TSPoint {
uint32_t row;
uint32_t column;
} TSPoint;

typedef struct TSRange {
TSPoint start_point;
TSPoint end_point;
uint32_t start_byte;
uint32_t end_byte;
} TSRange;

typedef struct TSInput {
void *payload;
const char *(*read)(void *payload, uint32_t byte_index, TSPoint position, uint32_t *bytes_read);
TSInputEncoding encoding;
TSDecodeFunction decode;
} TSInput;

typedef struct TSParseState {
void *payload;
uint32_t current_byte_offset;
bool has_error;
} TSParseState;

typedef struct TSParseOptions {
void *payload;
bool (*progress_callback)(TSParseState *state);
} TSParseOptions;

typedef enum TSLogType {
TSLogTypeParse,
TSLogTypeLex,
} TSLogType;

typedef struct TSLogger {
void *payload;
void (*log)(void *payload, TSLogType log_type, const char *buffer);
} TSLogger;

/**

• A summary of a change to a text document.
• The start_byte and start_point values must be less than or equal to the
• old_end_byte and old_end_point values, respectively. Passing an edit
• that violates these invariants may produce nonsensical results.
  */
  typedef struct TSInputEdit {
  uint32_t start_byte;
  uint32_t old_end_byte;
  uint32_t new_end_byte;
  TSPoint start_point;
  TSPoint old_end_point;
  TSPoint new_end_point;
  } TSInputEdit;

typedef struct TSNode {
uint32_t context[4];
const void *id;
const TSTree *tree;
} TSNode;

typedef struct TSTreeCursor {
const void *tree;
const void *id;
uint32_t context[3];
} TSTreeCursor;

typedef struct TSQueryCapture {
TSNode node;
uint32_t index;
} TSQueryCapture;

typedef enum TSQuantifier {
TSQuantifierZero = 0, // must match the array initialization value
TSQuantifierZeroOrOne,
TSQuantifierZeroOrMore,
TSQuantifierOne,
TSQuantifierOneOrMore,
} TSQuantifier;

typedef struct TSQueryMatch {
uint32_t id;
uint16_t pattern_index;
uint16_t capture_count;
const TSQueryCapture *captures;
} TSQueryMatch;

typedef enum TSQueryPredicateStepType {
TSQueryPredicateStepTypeDone,
TSQueryPredicateStepTypeCapture,
TSQueryPredicateStepTypeString,
} TSQueryPredicateStepType;

typedef struct TSQueryPredicateStep {
TSQueryPredicateStepType type;
uint32_t value_id;
} TSQueryPredicateStep;

typedef enum TSQueryError {
TSQueryErrorNone = 0,
TSQueryErrorSyntax,
TSQueryErrorNodeType,
TSQueryErrorField,
TSQueryErrorCapture,
TSQueryErrorStructure,
TSQueryErrorLanguage,
} TSQueryError;

typedef struct TSQueryCursorState {
void *payload;
uint32_t current_byte_offset;
} TSQueryCursorState;

typedef struct TSQueryCursorOptions {
void *payload;
bool (*progress_callback)(TSQueryCursorState *state);
} TSQueryCursorOptions;

/**

• The metadata associated with a language.
• Currently, this metadata can be used to check the Semantic Version
• 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.
  */
  typedef struct TSLanguageMetadata {
  uint8_t major_version;
  uint8_t minor_version;
  uint8_t patch_version;
  } TSLanguageMetadata;

//
/* Section - Parser */
//

/**

• Create a new parser.
  */
  TSParser *ts_parser_new(void);

/**

• Delete the parser, freeing all of the memory that it used.
  */
  void ts_parser_delete(TSParser *self);

/**

• Get the parser's current language.
  */
  const TSLanguage *ts_parser_language(const TSParser *self);

/**

• Set the language that the parser should use for parsing.
• Returns a boolean indicating whether or not the language was successfully
• assigned. True means assignment succeeded. False means the language cannot
• be used for parsing, or it was generated with an incompatible version of the
• Tree-sitter CLI. Check whether the language can be used for parsing with
• [ts_language_is_parseable]. Check the language's ABI version using
• [ts_language_abi_version] and compare it to this library's
• [TREE_SITTER_LANGUAGE_VERSION] and
• [TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION] constants.
  */
  bool ts_parser_set_language(TSParser *self, const TSLanguage *language);

/**

• 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.
• The second and third parameters specify the location and length of an array
• of ranges. The parser does not take ownership of these ranges; it copies
• the data, so it doesn't matter how these ranges are allocated.
• If count is zero, 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 < count - 1: ranges[i].end_byte <= ranges[i + 1].start_byte
• If this requirement is not satisfied, the operation will fail, the ranges
• will not be assigned, and this function will return false. On success,
• this function returns true
  */
  bool ts_parser_set_included_ranges(
  TSParser *self,
  const TSRange *ranges,
  uint32_t count
  );

/**

• Get the ranges of text that the parser will include when parsing.
• The returned pointer is owned by the parser. The caller should not free it
• or write to it. The length of the array will be written to the given
• count pointer.
  */
  const TSRange *ts_parser_included_ranges(
  const TSParser *self,
  uint32_t *count
  );

/**

• Use the parser to parse some source code and create a syntax tree.
• If you are parsing this document for the first time, pass NULL for the
• old_tree parameter. Otherwise, if you have already parsed an earlier
• version of this document and the document has since been edited, pass the
• previous syntax tree so that the unchanged parts of it can be reused.
• This will save time and memory. For this to work correctly, you must have
• already edited the old syntax tree using the [ts_tree_edit] function in a
• way that exactly matches the source code changes.
• The [TSInput] parameter lets you specify how to read the text. It has the
• following three fields:
• 1. read: A function to retrieve a chunk of text at a given byte offset
• and (row, column) position. The function should return a pointer to the
• text and write its length to the bytes_read pointer. The parser does
• not take ownership of this buffer; it just borrows it until it has
• finished reading it. The function should write a zero value to the
• bytes_read pointer to indicate the end of the document.
• 2. payload: An arbitrary pointer that will be passed to each invocation
• of the read function.
• 3. encoding: An indication of how the text is encoded. Either
• TSInputEncodingUTF8, TSInputEncodingUTF16LE, TSInputEncoding16BE,
• or TSInputEncodingCustom.
• 4. decode: A function to read one code point from the given input. This
• function should return the number of bytes consumed and write the code point
• to the code_point pointer, or write -1 if the input is invalid.
• This function returns a syntax tree on success, and NULL on failure. There
• are two possible reasons for failure:
• 1. The parser does not have a language assigned. Check for this using the
• [ts_parser_language] function.
• 2. Parsing was cancelled due to the progress callback returning true. This callback
• is passed in [ts_parser_parse_with_options] inside the [TSParseOptions] struct.
• */
  TSTree *ts_parser_parse(
  TSParser *self,
  const TSTree *old_tree,
  TSInput input
  );

/**

• Use the parser to parse some source code and create a syntax tree, with some options.
• See [ts_parser_parse] for more details.
• See [TSParseOptions] for more details on the options.
  /
  TSTree ts_parser_parse_with_options(
  TSParser *self,
  const TSTree *old_tree,
  TSInput input,
  TSParseOptions parse_options
  );

/**

• Use the parser to parse some source code stored in one contiguous buffer.
• The first two parameters are the same as in the [ts_parser_parse] function
• above. The second two parameters indicate the location of the buffer and its
• length in bytes.
  */
  TSTree *ts_parser_parse_string(
  TSParser *self,
  const TSTree *old_tree,
  const char *string,
  uint32_t length
  );

/**

• Use the parser to parse some source code stored in one contiguous buffer with
• a given encoding. The first four parameters work the same as in the
• [ts_parser_parse_string] method above. The final parameter indicates whether
• the text is encoded as UTF8 or UTF16.
  */
  TSTree *ts_parser_parse_string_encoding(
  TSParser *self,
  const TSTree *old_tree,
  const char *string,
  uint32_t length,
  TSInputEncoding encoding
  );

/**

• Instruct the parser to start the next parse from the beginning.
• If the parser previously failed because of the progress callback, then
• by default, it will resume where it left off on the next call to
• [ts_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 [ts_parser_reset] first.
  */
  void ts_parser_reset(TSParser *self);

/**

• Set the logger that a parser should use during parsing.
• The parser does not take ownership over the logger payload. If a logger was
• previously assigned, the caller is responsible for releasing any memory
• owned by the previous logger.
  */
  void ts_parser_set_logger(TSParser *self, TSLogger logger);

/**

• Get the parser's current logger.
  */
  TSLogger ts_parser_logger(const TSParser *self);

/**

• Set the file descriptor 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. You can turn off this logging by passing a negative number.
  */
  void ts_parser_print_dot_graphs(TSParser *self, int fd);

//
/ Section - Tree /
//

/**

• Create a shallow copy of the syntax tree. This is very fast.
• You need to copy a syntax tree in order to use it on more than one thread at
• a time, as syntax trees are not thread safe.
  */
  TSTree *ts_tree_copy(const TSTree *self);

/**

• Delete the syntax tree, freeing all of the memory that it used.
  */
  void ts_tree_delete(TSTree *self);

/**

• Get the root node of the syntax tree.
  */
  TSNode ts_tree_root_node(const TSTree *self);

/**

• Get the root node of the syntax tree, but with its position
• shifted forward by the given offset.
  */
  TSNode ts_tree_root_node_with_offset(
  const TSTree *self,
  uint32_t offset_bytes,
  TSPoint offset_extent
  );

/**

• 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.
  */
  const TSLanguage *ts_tree_language(const TSTree *self);

/**

• Get the array of included ranges that was used to parse the syntax tree.
• The returned pointer must be freed by the caller.
  */
  TSRange *ts_tree_included_ranges(const TSTree *self, uint32_t *length);

/**

• 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.
• The edit's start_byte must be less than or equal to its old_end_byte,
• and its start_point must be less than or equal to its old_end_point.
  */
  void ts_tree_edit(TSTree *self, const TSInputEdit *edit);

/**

• Compare an old edited syntax tree to a new syntax tree representing the same
• document, returning an array of ranges whose syntactic structure has changed.
• For this to work correctly, the old syntax tree must have been edited such
• that its ranges match up to the new tree. Generally, you'll want to call
• this function right after calling one of the [ts_parser_parse] functions.
• You need to pass the old tree that was passed to parse, as well as the new
• tree that was returned from that function.
• The returned ranges indicate areas where the hierarchical structure of syntax
• nodes (from root to leaf) has changed between the old and new trees. Characters
• outside these ranges have identical ancestor nodes in both trees.
• Note that the returned ranges may be slightly larger than the exact changed areas,
• but Tree-sitter attempts to make them as small as possible.
• The returned array is allocated using malloc and the caller is responsible
• for freeing it using free. The length of the array will be written to the
• given length pointer.
  */
  TSRange *ts_tree_get_changed_ranges(
  const TSTree *old_tree,
  const TSTree *new_tree,
  uint32_t *length
  );

/**

• Write a DOT graph describing the syntax tree to the given file.
  */
  void ts_tree_print_dot_graph(const TSTree *self, int file_descriptor);

//
/ Section - Node /
//

/**

• Get the node's type as a null-terminated string.
  */
  const char *ts_node_type(TSNode self);

/**

• Get the node's type as a numerical id.
  */
  TSSymbol ts_node_symbol(TSNode self);

/**

• Get the node's language.
• 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.
  */
  const TSLanguage *ts_node_language(TSNode self);

/**

• Get the node's type as it appears in the grammar ignoring aliases as a
• null-terminated string.
  */
  const char *ts_node_grammar_type(TSNode self);

/**

• Get the node's type as a numerical id as it appears in the grammar ignoring
• aliases. This should be used in [ts_language_next_state] instead of
• [ts_node_symbol].
  */
  TSSymbol ts_node_grammar_symbol(TSNode self);

/**

• Get the node's start byte.
  */
  uint32_t ts_node_start_byte(TSNode self);

/**

• Get the node's start position in terms of rows and columns.
  */
  TSPoint ts_node_start_point(TSNode self);

/**

• Get the node's end byte.
  */
  uint32_t ts_node_end_byte(TSNode self);

/**

• Get the node's end position in terms of rows and columns.
  */
  TSPoint ts_node_end_point(TSNode self);

/**

• Get an S-expression representing the node as a string.
• This string is allocated with malloc and the caller is responsible for
• freeing it using free.
  */
  char *ts_node_string(TSNode self);

/**

• Check if the node is null. Functions like [ts_node_child] and
• [ts_node_next_sibling] will return a null node to indicate that no such node
• was found.
  */
  bool ts_node_is_null(TSNode self);

/**

• Check if the node is named. Named nodes correspond to named rules in the
• grammar, whereas anonymous nodes correspond to string literals in the
• grammar.
  */
  bool ts_node_is_named(TSNode self);

/**

• Check if the node is missing. Missing nodes are inserted by the parser in
• order to recover from certain kinds of syntax errors.
  */
  bool ts_node_is_missing(TSNode self);

/**

• Check if the node is extra. Extra nodes represent things like comments,
• which are not required by the grammar, but can appear anywhere.
  */
  bool ts_node_is_extra(TSNode self);

/**

• Check if a syntax node has been edited.
  */
  bool ts_node_has_changes(TSNode self);

/**

• Check if the node is a syntax error or contains any syntax errors.
  */
  bool ts_node_has_error(TSNode self);

/**

• Check if the node is a syntax error.
  */
  bool ts_node_is_error(TSNode self);

/**

• Get this node's parse state.
• For a missing node, this is the state from the recovery path that was
• selected by the parser. It can be used with [ts_lookahead_iterator_new] 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.
  */
  TSStateId ts_node_parse_state(TSNode self);

/**

• Get the parse state after this node.
  */
  TSStateId ts_node_next_parse_state(TSNode self);

/**

• Get the node's immediate parent.
• Prefer [ts_node_child_with_descendant] for
• iterating over the node's ancestors.
  */
  TSNode ts_node_parent(TSNode self);

/**

• Get the node that contains descendant.
• Note that this can return descendant itself.
  */
  TSNode ts_node_child_with_descendant(TSNode self, TSNode descendant);

/**

• Get the node's child at the given index, where zero represents the first
• child.
  */
  TSNode ts_node_child(TSNode self, uint32_t child_index);

/**

• Get the field name for node's child at the given index, where zero represents
• the first child. Returns NULL, if no field is found.
  */
  const char *ts_node_field_name_for_child(TSNode self, uint32_t child_index);

/**

• Get the field name for node's named child at the given index, where zero
• represents the first named child. Returns NULL, if no field is found.
  */
  const char *ts_node_field_name_for_named_child(TSNode self, uint32_t named_child_index);

/**

• Get the node's number of children.
  */
  uint32_t ts_node_child_count(TSNode self);

/**

• Get the node's named child at the given index.
• See also [ts_node_is_named].
  */
  TSNode ts_node_named_child(TSNode self, uint32_t child_index);

/**

• Get the node's number of named children.
• See also [ts_node_is_named].
  */
  uint32_t ts_node_named_child_count(TSNode self);

/**

• Get the node's child with the given field name.
  */
  TSNode ts_node_child_by_field_name(
  TSNode self,
  const char *name,
  uint32_t name_length
  );

/**

• Get the node's child with the given numerical field id.
• You can convert a field name to an id using the
• [ts_language_field_id_for_name] function.
  */
  TSNode ts_node_child_by_field_id(TSNode self, TSFieldId field_id);

/**

• Get the node's next / previous sibling.
  */
  TSNode ts_node_next_sibling(TSNode self);
  TSNode ts_node_prev_sibling(TSNode self);

/**

• Get the node's next / previous named sibling.
  */
  TSNode ts_node_next_named_sibling(TSNode self);
  TSNode ts_node_prev_named_sibling(TSNode self);

/**

• Get the node's first child that contains or starts after the given byte offset.
  */
  TSNode ts_node_first_child_for_byte(TSNode self, uint32_t byte);

/**

• Get the node's first named child that contains or starts after the given byte offset.
  */
  TSNode ts_node_first_named_child_for_byte(TSNode self, uint32_t byte);

/**

• Get the node's number of descendants, including one for the node itself.
  */
  uint32_t ts_node_descendant_count(TSNode self);

/**

• Get the smallest node within this node that spans the given range of bytes
• or (row, column) positions.
  */
  TSNode ts_node_descendant_for_byte_range(TSNode self, uint32_t start, uint32_t end);
  TSNode ts_node_descendant_for_point_range(TSNode self, TSPoint start, TSPoint end);

/**

• Get the smallest named node within this node that spans the given range of
• bytes or (row, column) positions.
  */
  TSNode ts_node_named_descendant_for_byte_range(TSNode self, uint32_t start, uint32_t end);
  TSNode ts_node_named_descendant_for_point_range(TSNode self, TSPoint start, TSPoint end);

/**

• Edit the 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
• [ts_tree_edit] function, all of the nodes that you retrieve from the tree
• afterward will already reflect the edit. You only need to use [ts_node_edit]
• when you have a [TSNode] instance that you want to keep and continue to use
• after an edit.
• The edit's start_byte must be less than or equal to its old_end_byte,
• and its start_point must be less than or equal to its old_end_point.
  */
  void ts_node_edit(TSNode *self, const TSInputEdit *edit);

/**

• Check if two nodes are identical.
  */
  bool ts_node_eq(TSNode self, TSNode other);

/**

• 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 an edit operation. This is useful for editing points without
• requiring a tree or node instance.
• The edit's start_byte must be less than or equal to its old_end_byte,
• and its start_point must be less than or equal to its old_end_point.
  */
  void ts_point_edit(TSPoint *point, uint32_t *point_byte, const TSInputEdit *edit);

/**

• 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 an edit
• operation. This is useful for editing ranges without requiring a tree
• or node instance.
• The edit's start_byte must be less than or equal to its old_end_byte,
• and its start_point must be less than or equal to its old_end_point.
  */
  void ts_range_edit(TSRange *range, const TSInputEdit *edit);

//
/ Section - TreeCursor /
//

/**

• Create a new tree cursor starting from the given node.
• A tree cursor allows you to walk a syntax tree more efficiently than is
• possible using the [TSNode] functions. It is a mutable object that is always
• on a certain syntax node, and can be moved imperatively to different nodes.
• Note that the given node is considered the root of the cursor,
• and the cursor cannot walk outside this node.
  */
  TSTreeCursor ts_tree_cursor_new(TSNode node);

/**

• Delete a tree cursor, freeing all of the memory that it used.
  */
  void ts_tree_cursor_delete(TSTreeCursor *self);

/**

• Re-initialize a tree cursor to start at the original node that the cursor was
• constructed with.
  */
  void ts_tree_cursor_reset(TSTreeCursor *self, TSNode node);

/**

• Re-initialize a tree cursor to the same position as another cursor.
• Unlike [ts_tree_cursor_reset], this will not lose parent information and
• allows reusing already created cursors.
  */
  void ts_tree_cursor_reset_to(TSTreeCursor *dst, const TSTreeCursor *src);

/**

• Get the tree cursor's current node.
  */
  TSNode ts_tree_cursor_current_node(const TSTreeCursor *self);

/**

• Get the field name of the tree cursor's current node.
• This returns NULL if the current node doesn't have a field.
• See also [ts_node_child_by_field_name].
  */
  const char *ts_tree_cursor_current_field_name(const TSTreeCursor *self);

/**

• Get the field id of the tree cursor's current node.
• This returns zero if the current node doesn't have a field.
• See also [ts_node_child_by_field_id], [ts_language_field_id_for_name].
  */
  TSFieldId ts_tree_cursor_current_field_id(const TSTreeCursor *self);

/**

• Move the 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.
  */
  bool ts_tree_cursor_goto_parent(TSTreeCursor *self);

/**

• Move the 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.
  */
  bool ts_tree_cursor_goto_next_sibling(TSTreeCursor *self);

/**

• Move the 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
• [ts_tree_cursor_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.
  */
  bool ts_tree_cursor_goto_previous_sibling(TSTreeCursor *self);

/**

• Move the 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.
  */
  bool ts_tree_cursor_goto_first_child(TSTreeCursor *self);

/**

• Move the 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 [ts_tree_cursor_goto_first_child]
• because it needs to iterate through all the children to compute the child's
• position.
  */
  bool ts_tree_cursor_goto_last_child(TSTreeCursor *self);

/**

• 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.
  */
  void ts_tree_cursor_goto_descendant(TSTreeCursor *self, uint32_t goal_descendant_index);

/**

• 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.
  */
  uint32_t ts_tree_cursor_current_descendant_index(const TSTreeCursor *self);

/**

• Get the depth of the cursor's current node relative to the original
• node that the cursor was constructed with.
  */
  uint32_t ts_tree_cursor_current_depth(const TSTreeCursor *self);

/**

• Move the cursor to the first child of its current node that contains or starts after
• the given byte offset or point.
• This returns the index of the child node if one was found, and returns -1
• if no such child was found.
  */
  int64_t ts_tree_cursor_goto_first_child_for_byte(TSTreeCursor *self, uint32_t goal_byte);
  int64_t ts_tree_cursor_goto_first_child_for_point(TSTreeCursor *self, TSPoint goal_point);

TSTreeCursor ts_tree_cursor_copy(const TSTreeCursor *cursor);

//
/ Section - 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.
• If all of the given patterns are valid, this returns a [TSQuery].
• If a pattern is invalid, this returns NULL, and provides two pieces
• of information about the problem:
• 1. The byte offset of the error is written to the error_offset parameter.
• 2. The type of error is written to the error_type parameter.
     */
     TSQuery *ts_query_new(
     const TSLanguage *language,
     const char *source,
     uint32_t source_len,
     uint32_t *error_offset,
     TSQueryError *error_type
     );

/**

• Delete a query, freeing all of the memory that it used.
  */
  void ts_query_delete(TSQuery *self);

/**

• Create a copy of a query.
  */
  TSQuery *ts_query_copy(const TSQuery *self);

/**

• Get the number of patterns, captures, or string literals in the query.
  */
  uint32_t ts_query_pattern_count(const TSQuery *self);
  uint32_t ts_query_capture_count(const TSQuery *self);
  uint32_t ts_query_string_count(const TSQuery *self);

/**

• Get the byte offset where the given pattern starts in the query's source.
• This can be useful when combining queries by concatenating their source
• code strings.
  */
  uint32_t ts_query_start_byte_for_pattern(const TSQuery *self, uint32_t pattern_index);

/**

• Get the byte offset where the given pattern ends in the query's source.
• This can be useful when combining queries by concatenating their source
• code strings.
  */
  uint32_t ts_query_end_byte_for_pattern(const TSQuery *self, uint32_t pattern_index);

/**

• Get all of the predicates for the given pattern in the query.
• The predicates are represented as a single array of steps. There are three
• types of steps in this array, which correspond to the three legal values for
• the type field:
• • TSQueryPredicateStepTypeCapture - Steps with this type represent names
• of captures. Their value_id can be used with the
• [ts_query_capture_name_for_id] function to obtain the name of the capture.
• • TSQueryPredicateStepTypeString - Steps with this type represent literal
• strings. Their value_id can be used with the
• [ts_query_string_value_for_id] function to obtain their string value.
• • TSQueryPredicateStepTypeDone - Steps with this type are sentinels
• that represent the end of an individual predicate. If a pattern has two
• predicates, then there will be two steps with this type in the array.
  */
  const TSQueryPredicateStep *ts_query_predicates_for_pattern(
  const TSQuery *self,
  uint32_t pattern_index,
  uint32_t *step_count
  );

/*

• Check if the given pattern in the query has a single root node.
  */
  bool ts_query_is_pattern_rooted(const TSQuery *self, uint32_t pattern_index);

/*

• Check if the given pattern in the query is 'non local'.
• A non-local pattern has multiple root nodes and can match within a
• repeating sequence of nodes, as specified by the grammar. Non-local
• patterns disable certain optimizations that would otherwise be possible
• when executing a query on a specific range of a syntax tree.
  */
  bool ts_query_is_pattern_non_local(const TSQuery *self, uint32_t pattern_index);

/*

• Check if a given pattern is guaranteed to match once a given step is reached.
• The step is specified by its byte offset in the query's source code.
  */
  bool ts_query_is_pattern_guaranteed_at_step(const TSQuery *self, uint32_t byte_offset);

/**

• Get the name and length of one of the query's captures, or one of the
• query's string literals. Each capture and string is associated with a
• numeric id based on the order that it appeared in the query's source.
  */
  const char *ts_query_capture_name_for_id(
  const TSQuery *self,
  uint32_t index,
  uint32_t *length
  );

/**

• Get the quantifier of the query's captures. Each capture is associated
• with a numeric id based on the order that it appeared in the query's source.
  */
  TSQuantifier ts_query_capture_quantifier_for_id(
  const TSQuery *self,
  uint32_t pattern_index,
  uint32_t capture_index
  );

const char *ts_query_string_value_for_id(
const TSQuery *self,
uint32_t index,
uint32_t *length
);

/**

• 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. Currently, there
• is no way to undo this.
  */
  void ts_query_disable_capture(TSQuery *self, const char *name, uint32_t length);

/**

• Disable a certain pattern within a query.
• This prevents the pattern from matching and removes most of the overhead
• associated with the pattern. Currently, there is no way to undo this.
  */
  void ts_query_disable_pattern(TSQuery *self, uint32_t pattern_index);

/**

• Create a new cursor for executing a given query.
• The cursor stores the state that is needed to iteratively search
• for matches. To use the query cursor, first call [ts_query_cursor_exec]
• to start running a given query on a given syntax node. Then, there are
• two options for consuming the results of the query:
• 1. Repeatedly call [ts_query_cursor_next_match] to iterate over all of the
• matches in the order that they were found. Each match contains the
• index of the pattern that matched, and an array 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.
• 2. Repeatedly call [ts_query_cursor_next_capture] to 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.
• If you don't care about consuming all of the results, you can stop calling
• [ts_query_cursor_next_match] or [ts_query_cursor_next_capture] at any point.
• You can then start executing another query on another node by calling
• [ts_query_cursor_exec] again.
  */
  TSQueryCursor *ts_query_cursor_new(void);

/**

• Delete a query cursor, freeing all of the memory that it used.
  */
  void ts_query_cursor_delete(TSQueryCursor *self);

/**

• Start running a given query on a given node.
  */
  void ts_query_cursor_exec(TSQueryCursor *self, const TSQuery *query, TSNode node);

/**

• Start running a given query on a given node, with some options.
• If a progress callback is given, it is called periodically while the query
• runs. If it returns true, query execution halts. Matches that were still in
• progress are discarded, matches that had already finished can still be
• returned, and after that the cursor returns nothing more until it is started
• again with [ts_query_cursor_exec] or [ts_query_cursor_exec_with_options].
  */
  void ts_query_cursor_exec_with_options(
  TSQueryCursor *self,
  const TSQuery *query,
  TSNode node,
  const TSQueryCursorOptions *query_options
  );

/**

• Manage the maximum number of in-progress matches allowed by this query
• cursor.
• Query cursors have an optional maximum capacity for storing lists of
• in-progress captures. If this capacity is exceeded, then the
• earliest-starting match will silently be dropped to make room for further
• matches. This maximum capacity is optional — by default, query cursors allow
• any number of pending matches, dynamically allocating new space for them as
• needed as the query is executed.
  */
  bool ts_query_cursor_did_exceed_match_limit(const TSQueryCursor *self);
  uint32_t ts_query_cursor_match_limit(const TSQueryCursor *self);
  void ts_query_cursor_set_match_limit(TSQueryCursor *self, uint32_t limit);

/**

• Set the range of bytes in which the query will be executed.
• The query cursor will return matches that intersect with the given byte range.
• This means that a match may be returned even if some of its captures fall
• outside the specified range, as long as at least part of the match
• overlaps with the range.
• For example, if a query pattern matches a node that spans a larger area
• than the specified range, but part of that node intersects with the range,
• the entire match will be returned.
• NOTE: An end_byte of zero is interpreted as UINT32_MAX, making the range
• unbounded.
• This will return false if the start byte is greater than the end byte, otherwise
• it will return true.
  */
  bool ts_query_cursor_set_byte_range(TSQueryCursor *self, uint32_t start_byte, uint32_t end_byte);

/**

• Set the range of (row, column) positions in which the query will be executed.
• The query cursor will return matches that intersect with the given point range.
• This means that a match may be returned even if some of its captures fall
• outside the specified range, as long as at least part of the match
• overlaps with the range.
• For example, if a query pattern matches a node that spans a larger area
• than the specified range, but part of that node intersects with the range,
• the entire match will be returned.
• NOTE: An end_point of (0, 0) is interpreted as POINT_MAX, making the
• range unbounded.
• This will return false if the start point is greater than the end point, otherwise
• it will return true.
  */
  bool ts_query_cursor_set_point_range(TSQueryCursor *self, TSPoint start_point, TSPoint end_point);

/**

• 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
• NOTE: An end_byte of zero is interpreted as UINT32_MAX, making the range
• unbounded.
  */
  bool ts_query_cursor_set_containing_byte_range(TSQueryCursor *self, uint32_t start_byte, uint32_t end_byte);

/**

• 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
• NOTE: An end_point of (0, 0) is interpreted as POINT_MAX, making the
• range unbounded.
  */
  bool ts_query_cursor_set_containing_point_range(TSQueryCursor *self, TSPoint start_point, TSPoint end_point);

/**

• Advance to the next match of the currently running query.
• If there is a match, write it to *match and return true.
• Otherwise, return false.
  */
  bool ts_query_cursor_next_match(TSQueryCursor *self, TSQueryMatch *match);
  void ts_query_cursor_remove_match(TSQueryCursor *self, uint32_t match_id);

/**

• Advance to the next capture of the currently running query.
• If there is a capture, write its match to *match and its index within
• the match's capture list to *capture_index. Otherwise, return false.
  */
  bool ts_query_cursor_next_capture(
  TSQueryCursor *self,
  TSQueryMatch *match,
  uint32_t *capture_index
  );

/**

• 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 as defined by the pattern structure.
• Set to UINT32_MAX to remove the maximum start depth.
  */
  void ts_query_cursor_set_max_start_depth(TSQueryCursor *self, uint32_t max_start_depth);

//
/ Section - Language /
//

/**

• Get another reference to the given language.
  */
  const TSLanguage *ts_language_copy(const TSLanguage *self);

/**

• Free any dynamically-allocated resources for this language, if
• this is the last reference.
  */
  void ts_language_delete(const TSLanguage *self);

/**

• Check whether this language can be assigned to a parser.
• Languages obtained from a syntax tree may be used to inspect that tree, but
• are not necessarily usable for parsing. When Tree-sitter is compiled to
• WebAssembly, a language obtained from a tree can be used for parsing only
• within the same WebAssembly instance that created the tree, because lexer
• function pointers are local to a WebAssembly instance.
  */
  bool ts_language_is_parseable(const TSLanguage *self);

/**

• Get the number of distinct node types in the language.
  */
  uint32_t ts_language_symbol_count(const TSLanguage *self);

/**

• Get the number of valid states in this language.
  */
  uint32_t ts_language_state_count(const TSLanguage *self);

/**

• Get the numerical id for the given node type string.
  */
  TSSymbol ts_language_symbol_for_name(
  const TSLanguage *self,
  const char *string,
  uint32_t length,
  bool is_named
  );

/**

• Get the number of distinct field names in the language.
  */
  uint32_t ts_language_field_count(const TSLanguage *self);

/**

• Get the field name string for the given numerical id.
  */
  const char *ts_language_field_name_for_id(const TSLanguage *self, TSFieldId id);

/**

• Get the numerical id for the given field name string.
  */
  TSFieldId ts_language_field_id_for_name(const TSLanguage *self, const char *name, uint32_t name_length);

/**

• Get a list of all supertype symbols for the language.
  */
  const TSSymbol *ts_language_supertypes(const TSLanguage *self, uint32_t *length);

/**

• Get a list of all subtype symbol ids for a given supertype symbol.
• See [ts_language_supertypes] for fetching all supertype symbols.
  */
  const TSSymbol *ts_language_subtypes(
  const TSLanguage *self,
  TSSymbol supertype,
  uint32_t *length
  );

/**

• Get a node type string for the given numerical id.
  */
  const char *ts_language_symbol_name(const TSLanguage *self, TSSymbol symbol);

/**

• Check whether the given node type id belongs to named nodes, anonymous nodes,
• or hidden nodes.
• See also [ts_node_is_named]. Hidden nodes are never returned from the API.
  */
  TSSymbolType ts_language_symbol_type(const TSLanguage *self, TSSymbol symbol);

/**

• Get the ABI version number for this language. This version number is used
• to ensure that languages were generated by a compatible version of
• Tree-sitter.
• See also [ts_parser_set_language].
  */
  uint32_t ts_language_abi_version(const TSLanguage *self);

/**

• 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.
• See also [TSMetadata].
  */
  const TSLanguageMetadata *ts_language_metadata(const TSLanguage *self);

/**

• Get the next parse state. Combine this with lookahead iterators to generate
• completion suggestions or valid symbols in error nodes. Use
• [ts_node_grammar_symbol] for valid symbols.
  */
  TSStateId ts_language_next_state(const TSLanguage *self, TSStateId state, TSSymbol symbol);

/**

• Get the name of this language. This returns NULL in older parsers.
  */
  const char *ts_language_name(const TSLanguage *self);

//
/* Section - Lookahead Iterator */
//

/**

• Create a new lookahead iterator for the given language and parse state.
• This returns NULL if state is invalid for the language.
• Repeatedly using [ts_lookahead_iterator_next] and
• [ts_lookahead_iterator_current_symbol] will generate valid symbols in the
• given parse state. A newly created iterator is not positioned on a symbol
• until [ts_lookahead_iterator_next] is called.
• The iterator retains the language, so the language may be deleted 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 MISSING nodes, a lookahead
• iterator created on the previous non-extra leaf node, or using the node's
• parse state may be appropriate.
  */
  TSLookaheadIterator *ts_lookahead_iterator_new(const TSLanguage *self, TSStateId state);

/**

• Delete a lookahead iterator freeing all the memory used.
  */
  void ts_lookahead_iterator_delete(TSLookaheadIterator *self);

/**

• Reset the lookahead iterator to another state.
• This returns true if the iterator was reset to the given state and false
• otherwise. A reset iterator is not positioned on a symbol.
  */
  bool ts_lookahead_iterator_reset_state(TSLookaheadIterator *self, TSStateId state);

/**

• Reset the lookahead iterator.
• This returns true if the language was set successfully and false
• otherwise. A reset iterator is not positioned on a symbol.
  */
  bool ts_lookahead_iterator_reset(TSLookaheadIterator *self, const TSLanguage *language, TSStateId state);

/**

• Get the current language of the lookahead iterator.
  */
  const TSLanguage *ts_lookahead_iterator_language(const TSLookaheadIterator *self);

/**

• Advance the lookahead iterator to the next symbol.
• This returns true if there is a new symbol and false otherwise.
  */
  bool ts_lookahead_iterator_next(TSLookaheadIterator *self);

/**

• Get the current symbol of the lookahead iterator.
• This is only meaningful when the most recent call to
• [ts_lookahead_iterator_next] on self returned true.
  */
  TSSymbol ts_lookahead_iterator_current_symbol(const TSLookaheadIterator *self);

/**

• Get the current symbol type of the lookahead iterator as a null terminated
• string.
• This returns NULL unless the most recent call to
• [ts_lookahead_iterator_next] on self returned true.
  */
  const char *ts_lookahead_iterator_current_symbol_name(const TSLookaheadIterator *self);

/*/
/ Section - WebAssembly Integration /
//

typedef struct wasm_engine_t TSWasmEngine;
typedef struct TSWasmStore TSWasmStore;

typedef enum {
TSWasmErrorKindNone = 0,
TSWasmErrorKindParse,
TSWasmErrorKindCompile,
TSWasmErrorKindInstantiate,
TSWasmErrorKindAllocate,
} TSWasmErrorKind;

typedef struct {
TSWasmErrorKind kind;
char *message;
} TSWasmError;

/**

• Create a Wasm store.
  */
  TSWasmStore *ts_wasm_store_new(
  TSWasmEngine *engine,
  TSWasmError *error
  );

/**

• Free the memory associated with the given Wasm store.
  */
  void ts_wasm_store_delete(TSWasmStore *);

/**

• Create a language from a buffer of Wasm. The resulting language behaves
• like any other Tree-sitter language, except that in order to use it with
• a parser, that parser must have a Wasm store. Note that the language
• can be used with any Wasm store, it doesn't need to be the same store that
• was used to originally load it.
  */
  const TSLanguage *ts_wasm_store_load_language(
  TSWasmStore *,
  const char *name,
  const char *wasm,
  uint32_t wasm_len,
  TSWasmError *error
  );

/**

• Get the number of languages instantiated in the given Wasm store.
  */
  size_t ts_wasm_store_language_count(const TSWasmStore *);

/**

• Check if the language came from a Wasm module. If so, then in order to use
• this language with a Parser, that parser must have a Wasm store assigned.
  */
  bool ts_language_is_wasm(const TSLanguage *);

/**

• Assign the given Wasm store to the parser. A parser must have a Wasm store
• in order to use Wasm languages.
  */
  void ts_parser_set_wasm_store(TSParser *, TSWasmStore *);

/**

• Remove the parser's current Wasm store and return it. This returns NULL if
• the parser doesn't have a Wasm store.
  */
  TSWasmStore *ts_parser_take_wasm_store(TSParser *);

//
/ Section - Global Configuration /
//

/**

• Set the allocation functions used by the library.
• By default, Tree-sitter uses the standard libc allocation functions,
• but aborts the process when an allocation fails. This function lets
• you supply alternative allocation functions at runtime.
• If you pass NULL for any parameter, Tree-sitter will switch back to
• its default implementation of that function.
• If you call this function after the library has already been used, then
• you must ensure that either:
• 1. All the existing objects have been freed.
• 2. The new allocator shares its state with the old one, so it is capable

• of freeing memory that was allocated by the old allocator.
  

*/
void ts_set_allocator(
void *(*new_malloc)(size_t),
void *(*new_calloc)(size_t, size_t),
void *(*new_realloc)(void *, size_t),
void (*new_free)(void *)
);

#ifdef __cplusplus
}
#endif

#ifndef TREE_SITTER_HIDE_SYMBOLS
#if defined(GNUC) || defined(clang)
#pragma GCC visibility pop
#endif
#endif

#endif // TREE_SITTER_API_H_