1#ifndef TREE_SITTER_API_H_
2#define TREE_SITTER_API_H_
3
4#ifndef TREE_SITTER_HIDE_SYMBOLS
5#if defined(__GNUC__) || defined(__clang__)
6#pragma GCC visibility push(default)
7#endif
8#endif
9
10#ifdef __cplusplus
11extern "C" {
12#endif
13
14#include <stdlib.h>
15#include <stdint.h>
16#include <stdbool.h>
17
18/****************************/
19/* Section - ABI Versioning */
20/****************************/
21
22/**
23 * The latest ABI version that is supported by the current version of the
24 * library. When Languages are generated by the Tree-sitter CLI, they are
25 * assigned an ABI version number that corresponds to the current CLI version.
26 * The Tree-sitter library is generally backwards-compatible with languages
27 * generated using older CLI versions, but is not forwards-compatible.
28 */
29#define TREE_SITTER_LANGUAGE_VERSION 14
30
31/**
32 * The earliest ABI version that is supported by the current version of the
33 * library.
34 */
35#define TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION 13
36
37/*******************/
38/* Section - Types */
39/*******************/
40
41typedef uint16_t TSStateId;
42typedef uint16_t TSSymbol;
43typedef uint16_t TSFieldId;
44typedef struct TSLanguage TSLanguage;
45typedef struct TSParser TSParser;
46typedef struct TSTree TSTree;
47typedef struct TSQuery TSQuery;
48typedef struct TSQueryCursor TSQueryCursor;
49typedef struct TSLookaheadIterator TSLookaheadIterator;
50
51typedef enum TSInputEncoding {
52 TSInputEncodingUTF8,
53 TSInputEncodingUTF16,
54} TSInputEncoding;
55
56typedef enum TSSymbolType {
57 TSSymbolTypeRegular,
58 TSSymbolTypeAnonymous,
59 TSSymbolTypeAuxiliary,
60} TSSymbolType;
61
62typedef struct TSPoint {
63 uint32_t row;
64 uint32_t column;
65} TSPoint;
66
67typedef struct TSRange {
68 TSPoint start_point;
69 TSPoint end_point;
70 uint32_t start_byte;
71 uint32_t end_byte;
72} TSRange;
73
74typedef struct TSInput {
75 void *payload;
76 const char *(*read)(void *payload, uint32_t byte_index, TSPoint position, uint32_t *bytes_read);
77 TSInputEncoding encoding;
78} TSInput;
79
80typedef enum TSLogType {
81 TSLogTypeParse,
82 TSLogTypeLex,
83} TSLogType;
84
85typedef struct TSLogger {
86 void *payload;
87 void (*log)(void *payload, TSLogType log_type, const char *buffer);
88} TSLogger;
89
90typedef struct TSInputEdit {
91 uint32_t start_byte;
92 uint32_t old_end_byte;
93 uint32_t new_end_byte;
94 TSPoint start_point;
95 TSPoint old_end_point;
96 TSPoint new_end_point;
97} TSInputEdit;
98
99typedef struct TSNode {
100 uint32_t context[4];
101 const void *id;
102 const TSTree *tree;
103} TSNode;
104
105typedef struct TSTreeCursor {
106 const void *tree;
107 const void *id;
108 uint32_t context[3];
109} TSTreeCursor;
110
111typedef struct TSQueryCapture {
112 TSNode node;
113 uint32_t index;
114} TSQueryCapture;
115
116typedef enum TSQuantifier {
117 TSQuantifierZero = 0, // must match the array initialization value
118 TSQuantifierZeroOrOne,
119 TSQuantifierZeroOrMore,
120 TSQuantifierOne,
121 TSQuantifierOneOrMore,
122} TSQuantifier;
123
124typedef struct TSQueryMatch {
125 uint32_t id;
126 uint16_t pattern_index;
127 uint16_t capture_count;
128 const TSQueryCapture *captures;
129} TSQueryMatch;
130
131typedef enum TSQueryPredicateStepType {
132 TSQueryPredicateStepTypeDone,
133 TSQueryPredicateStepTypeCapture,
134 TSQueryPredicateStepTypeString,
135} TSQueryPredicateStepType;
136
137typedef struct TSQueryPredicateStep {
138 TSQueryPredicateStepType type;
139 uint32_t value_id;
140} TSQueryPredicateStep;
141
142typedef enum TSQueryError {
143 TSQueryErrorNone = 0,
144 TSQueryErrorSyntax,
145 TSQueryErrorNodeType,
146 TSQueryErrorField,
147 TSQueryErrorCapture,
148 TSQueryErrorStructure,
149 TSQueryErrorLanguage,
150} TSQueryError;
151
152/********************/
153/* Section - Parser */
154/********************/
155
156/**
157 * Create a new parser.
158 */
159TSParser *ts_parser_new(void);
160
161/**
162 * Delete the parser, freeing all of the memory that it used.
163 */
164void ts_parser_delete(TSParser *self);
165
166/**
167 * Get the parser's current language.
168 */
169const TSLanguage *ts_parser_language(const TSParser *self);
170
171/**
172 * Set the language that the parser should use for parsing.
173 *
174 * Returns a boolean indicating whether or not the language was successfully
175 * assigned. True means assignment succeeded. False means there was a version
176 * mismatch: the language was generated with an incompatible version of the
177 * Tree-sitter CLI. Check the language's version using [`ts_language_version`]
178 * and compare it to this library's [`TREE_SITTER_LANGUAGE_VERSION`] and
179 * [`TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION`] constants.
180 */
181bool ts_parser_set_language(TSParser *self, const TSLanguage *language);
182
183/**
184 * Set the ranges of text that the parser should include when parsing.
185 *
186 * By default, the parser will always include entire documents. This function
187 * allows you to parse only a *portion* of a document but still return a syntax
188 * tree whose ranges match up with the document as a whole. You can also pass
189 * multiple disjoint ranges.
190 *
191 * The second and third parameters specify the location and length of an array
192 * of ranges. The parser does *not* take ownership of these ranges; it copies
193 * the data, so it doesn't matter how these ranges are allocated.
194 *
195 * If `count` is zero, then the entire document will be parsed. Otherwise,
196 * the given ranges must be ordered from earliest to latest in the document,
197 * and they must not overlap. That is, the following must hold for all:
198 *
199 * `i < count - 1`: `ranges[i].end_byte <= ranges[i + 1].start_byte`
200 *
201 * If this requirement is not satisfied, the operation will fail, the ranges
202 * will not be assigned, and this function will return `false`. On success,
203 * this function returns `true`
204 */
205bool ts_parser_set_included_ranges(
206 TSParser *self,
207 const TSRange *ranges,
208 uint32_t count
209);
210
211/**
212 * Get the ranges of text that the parser will include when parsing.
213 *
214 * The returned pointer is owned by the parser. The caller should not free it
215 * or write to it. The length of the array will be written to the given
216 * `count` pointer.
217 */
218const TSRange *ts_parser_included_ranges(
219 const TSParser *self,
220 uint32_t *count
221);
222
223/**
224 * Use the parser to parse some source code and create a syntax tree.
225 *
226 * If you are parsing this document for the first time, pass `NULL` for the
227 * `old_tree` parameter. Otherwise, if you have already parsed an earlier
228 * version of this document and the document has since been edited, pass the
229 * previous syntax tree so that the unchanged parts of it can be reused.
230 * This will save time and memory. For this to work correctly, you must have
231 * already edited the old syntax tree using the [`ts_tree_edit`] function in a
232 * way that exactly matches the source code changes.
233 *
234 * The [`TSInput`] parameter lets you specify how to read the text. It has the
235 * following three fields:
236 * 1. [`read`]: A function to retrieve a chunk of text at a given byte offset
237 * and (row, column) position. The function should return a pointer to the
238 * text and write its length to the [`bytes_read`] pointer. The parser does
239 * not take ownership of this buffer; it just borrows it until it has
240 * finished reading it. The function should write a zero value to the
241 * [`bytes_read`] pointer to indicate the end of the document.
242 * 2. [`payload`]: An arbitrary pointer that will be passed to each invocation
243 * of the [`read`] function.
244 * 3. [`encoding`]: An indication of how the text is encoded. Either
245 * `TSInputEncodingUTF8` or `TSInputEncodingUTF16`.
246 *
247 * This function returns a syntax tree on success, and `NULL` on failure. There
248 * are three possible reasons for failure:
249 * 1. The parser does not have a language assigned. Check for this using the
250 [`ts_parser_language`] function.
251 * 2. Parsing was cancelled due to a timeout that was set by an earlier call to
252 * the [`ts_parser_set_timeout_micros`] function. You can resume parsing from
253 * where the parser left out by calling [`ts_parser_parse`] again with the
254 * same arguments. Or you can start parsing from scratch by first calling
255 * [`ts_parser_reset`].
256 * 3. Parsing was cancelled using a cancellation flag that was set by an
257 * earlier call to [`ts_parser_set_cancellation_flag`]. You can resume parsing
258 * from where the parser left out by calling [`ts_parser_parse`] again with
259 * the same arguments.
260 *
261 * [`read`]: TSInput::read
262 * [`payload`]: TSInput::payload
263 * [`encoding`]: TSInput::encoding
264 * [`bytes_read`]: TSInput::read
265 */
266TSTree *ts_parser_parse(
267 TSParser *self,
268 const TSTree *old_tree,
269 TSInput input
270);
271
272/**
273 * Use the parser to parse some source code stored in one contiguous buffer.
274 * The first two parameters are the same as in the [`ts_parser_parse`] function
275 * above. The second two parameters indicate the location of the buffer and its
276 * length in bytes.
277 */
278TSTree *ts_parser_parse_string(
279 TSParser *self,
280 const TSTree *old_tree,
281 const char *string,
282 uint32_t length
283);
284
285/**
286 * Use the parser to parse some source code stored in one contiguous buffer with
287 * a given encoding. The first four parameters work the same as in the
288 * [`ts_parser_parse_string`] method above. The final parameter indicates whether
289 * the text is encoded as UTF8 or UTF16.
290 */
291TSTree *ts_parser_parse_string_encoding(
292 TSParser *self,
293 const TSTree *old_tree,
294 const char *string,
295 uint32_t length,
296 TSInputEncoding encoding
297);
298
299/**
300 * Instruct the parser to start the next parse from the beginning.
301 *
302 * If the parser previously failed because of a timeout or a cancellation, then
303 * by default, it will resume where it left off on the next call to
304 * [`ts_parser_parse`] or other parsing functions. If you don't want to resume,
305 * and instead intend to use this parser to parse some other document, you must
306 * call [`ts_parser_reset`] first.
307 */
308void ts_parser_reset(TSParser *self);
309
310/**
311 * Set the maximum duration in microseconds that parsing should be allowed to
312 * take before halting.
313 *
314 * If parsing takes longer than this, it will halt early, returning NULL.
315 * See [`ts_parser_parse`] for more information.
316 */
317void ts_parser_set_timeout_micros(TSParser *self, uint64_t timeout_micros);
318
319/**
320 * Get the duration in microseconds that parsing is allowed to take.
321 */
322uint64_t ts_parser_timeout_micros(const TSParser *self);
323
324/**
325 * Set the parser's current cancellation flag pointer.
326 *
327 * If a non-null pointer is assigned, then the parser will periodically read
328 * from this pointer during parsing. If it reads a non-zero value, it will
329 * halt early, returning NULL. See [`ts_parser_parse`] for more information.
330 */
331void ts_parser_set_cancellation_flag(TSParser *self, const size_t *flag);
332
333/**
334 * Get the parser's current cancellation flag pointer.
335 */
336const size_t *ts_parser_cancellation_flag(const TSParser *self);
337
338/**
339 * Set the logger that a parser should use during parsing.
340 *
341 * The parser does not take ownership over the logger payload. If a logger was
342 * previously assigned, the caller is responsible for releasing any memory
343 * owned by the previous logger.
344 */
345void ts_parser_set_logger(TSParser *self, TSLogger logger);
346
347/**
348 * Get the parser's current logger.
349 */
350TSLogger ts_parser_logger(const TSParser *self);
351
352/**
353 * Set the file descriptor to which the parser should write debugging graphs
354 * during parsing. The graphs are formatted in the DOT language. You may want
355 * to pipe these graphs directly to a `dot(1)` process in order to generate
356 * SVG output. You can turn off this logging by passing a negative number.
357 */
358void ts_parser_print_dot_graphs(TSParser *self, int fd);
359
360/******************/
361/* Section - Tree */
362/******************/
363
364/**
365 * Create a shallow copy of the syntax tree. This is very fast.
366 *
367 * You need to copy a syntax tree in order to use it on more than one thread at
368 * a time, as syntax trees are not thread safe.
369 */
370TSTree *ts_tree_copy(const TSTree *self);
371
372/**
373 * Delete the syntax tree, freeing all of the memory that it used.
374 */
375void ts_tree_delete(TSTree *self);
376
377/**
378 * Get the root node of the syntax tree.
379 */
380TSNode ts_tree_root_node(const TSTree *self);
381
382/**
383 * Get the root node of the syntax tree, but with its position
384 * shifted forward by the given offset.
385 */
386TSNode ts_tree_root_node_with_offset(
387 const TSTree *self,
388 uint32_t offset_bytes,
389 TSPoint offset_extent
390);
391
392/**
393 * Get the language that was used to parse the syntax tree.
394 */
395const TSLanguage *ts_tree_language(const TSTree *self);
396
397/**
398 * Get the array of included ranges that was used to parse the syntax tree.
399 *
400 * The returned pointer must be freed by the caller.
401 */
402TSRange *ts_tree_included_ranges(const TSTree *self, uint32_t *length);
403
404/**
405 * Edit the syntax tree to keep it in sync with source code that has been
406 * edited.
407 *
408 * You must describe the edit both in terms of byte offsets and in terms of
409 * (row, column) coordinates.
410 */
411void ts_tree_edit(TSTree *self, const TSInputEdit *edit);
412
413/**
414 * Compare an old edited syntax tree to a new syntax tree representing the same
415 * document, returning an array of ranges whose syntactic structure has changed.
416 *
417 * For this to work correctly, the old syntax tree must have been edited such
418 * that its ranges match up to the new tree. Generally, you'll want to call
419 * this function right after calling one of the [`ts_parser_parse`] functions.
420 * You need to pass the old tree that was passed to parse, as well as the new
421 * tree that was returned from that function.
422 *
423 * The returned array is allocated using `malloc` and the caller is responsible
424 * for freeing it using `free`. The length of the array will be written to the
425 * given `length` pointer.
426 */
427TSRange *ts_tree_get_changed_ranges(
428 const TSTree *old_tree,
429 const TSTree *new_tree,
430 uint32_t *length
431);
432
433/**
434 * Write a DOT graph describing the syntax tree to the given file.
435 */
436void ts_tree_print_dot_graph(const TSTree *self, int file_descriptor);
437
438/******************/
439/* Section - Node */
440/******************/
441
442/**
443 * Get the node's type as a null-terminated string.
444 */
445const char *ts_node_type(TSNode self);
446
447/**
448 * Get the node's type as a numerical id.
449 */
450TSSymbol ts_node_symbol(TSNode self);
451
452/**
453 * Get the node's language.
454 */
455const TSLanguage *ts_node_language(TSNode self);
456
457/**
458 * Get the node's type as it appears in the grammar ignoring aliases as a
459 * null-terminated string.
460 */
461const char *ts_node_grammar_type(TSNode self);
462
463/**
464 * Get the node's type as a numerical id as it appears in the grammar ignoring
465 * aliases. This should be used in [`ts_language_next_state`] instead of
466 * [`ts_node_symbol`].
467 */
468TSSymbol ts_node_grammar_symbol(TSNode self);
469
470/**
471 * Get the node's start byte.
472 */
473uint32_t ts_node_start_byte(TSNode self);
474
475/**
476 * Get the node's start position in terms of rows and columns.
477 */
478TSPoint ts_node_start_point(TSNode self);
479
480/**
481 * Get the node's end byte.
482 */
483uint32_t ts_node_end_byte(TSNode self);
484
485/**
486 * Get the node's end position in terms of rows and columns.
487 */
488TSPoint ts_node_end_point(TSNode self);
489
490/**
491 * Get an S-expression representing the node as a string.
492 *
493 * This string is allocated with `malloc` and the caller is responsible for
494 * freeing it using `free`.
495 */
496char *ts_node_string(TSNode self);
497
498/**
499 * Check if the node is null. Functions like [`ts_node_child`] and
500 * [`ts_node_next_sibling`] will return a null node to indicate that no such node
501 * was found.
502 */
503bool ts_node_is_null(TSNode self);
504
505/**
506 * Check if the node is *named*. Named nodes correspond to named rules in the
507 * grammar, whereas *anonymous* nodes correspond to string literals in the
508 * grammar.
509 */
510bool ts_node_is_named(TSNode self);
511
512/**
513 * Check if the node is *missing*. Missing nodes are inserted by the parser in
514 * order to recover from certain kinds of syntax errors.
515 */
516bool ts_node_is_missing(TSNode self);
517
518/**
519 * Check if the node is *extra*. Extra nodes represent things like comments,
520 * which are not required the grammar, but can appear anywhere.
521 */
522bool ts_node_is_extra(TSNode self);
523
524/**
525 * Check if a syntax node has been edited.
526 */
527bool ts_node_has_changes(TSNode self);
528
529/**
530 * Check if the node is a syntax error or contains any syntax errors.
531 */
532bool ts_node_has_error(TSNode self);
533
534/**
535 * Check if the node is a syntax error.
536*/
537bool ts_node_is_error(TSNode self);
538
539/**
540 * Get this node's parse state.
541*/
542TSStateId ts_node_parse_state(TSNode self);
543
544/**
545 * Get the parse state after this node.
546*/
547TSStateId ts_node_next_parse_state(TSNode self);
548
549/**
550 * Get the node's immediate parent.
551 */
552TSNode ts_node_parent(TSNode self);
553
554/**
555 * Get the node's child at the given index, where zero represents the first
556 * child.
557 */
558TSNode ts_node_child(TSNode self, uint32_t child_index);
559
560/**
561 * Get the field name for node's child at the given index, where zero represents
562 * the first child. Returns NULL, if no field is found.
563 */
564const char *ts_node_field_name_for_child(TSNode self, uint32_t child_index);
565
566/**
567 * Get the node's number of children.
568 */
569uint32_t ts_node_child_count(TSNode self);
570
571/**
572 * Get the node's *named* child at the given index.
573 *
574 * See also [`ts_node_is_named`].
575 */
576TSNode ts_node_named_child(TSNode self, uint32_t child_index);
577
578/**
579 * Get the node's number of *named* children.
580 *
581 * See also [`ts_node_is_named`].
582 */
583uint32_t ts_node_named_child_count(TSNode self);
584
585/**
586 * Get the node's child with the given field name.
587 */
588TSNode ts_node_child_by_field_name(
589 TSNode self,
590 const char *name,
591 uint32_t name_length
592);
593
594/**
595 * Get the node's child with the given numerical field id.
596 *
597 * You can convert a field name to an id using the
598 * [`ts_language_field_id_for_name`] function.
599 */
600TSNode ts_node_child_by_field_id(TSNode self, TSFieldId field_id);
601
602/**
603 * Get the node's next / previous sibling.
604 */
605TSNode ts_node_next_sibling(TSNode self);
606TSNode ts_node_prev_sibling(TSNode self);
607
608/**
609 * Get the node's next / previous *named* sibling.
610 */
611TSNode ts_node_next_named_sibling(TSNode self);
612TSNode ts_node_prev_named_sibling(TSNode self);
613
614/**
615 * Get the node's first child that extends beyond the given byte offset.
616 */
617TSNode ts_node_first_child_for_byte(TSNode self, uint32_t byte);
618
619/**
620 * Get the node's first named child that extends beyond the given byte offset.
621 */
622TSNode ts_node_first_named_child_for_byte(TSNode self, uint32_t byte);
623
624/**
625 * Get the node's number of descendants, including one for the node itself.
626 */
627uint32_t ts_node_descendant_count(TSNode self);
628
629/**
630 * Get the smallest node within this node that spans the given range of bytes
631 * or (row, column) positions.
632 */
633TSNode ts_node_descendant_for_byte_range(TSNode self, uint32_t start, uint32_t end);
634TSNode ts_node_descendant_for_point_range(TSNode self, TSPoint start, TSPoint end);
635
636/**
637 * Get the smallest named node within this node that spans the given range of
638 * bytes or (row, column) positions.
639 */
640TSNode ts_node_named_descendant_for_byte_range(TSNode self, uint32_t start, uint32_t end);
641TSNode ts_node_named_descendant_for_point_range(TSNode self, TSPoint start, TSPoint end);
642
643/**
644 * Edit the node to keep it in-sync with source code that has been edited.
645 *
646 * This function is only rarely needed. When you edit a syntax tree with the
647 * [`ts_tree_edit`] function, all of the nodes that you retrieve from the tree
648 * afterward will already reflect the edit. You only need to use [`ts_node_edit`]
649 * when you have a [`TSNode`] instance that you want to keep and continue to use
650 * after an edit.
651 */
652void ts_node_edit(TSNode *self, const TSInputEdit *edit);
653
654/**
655 * Check if two nodes are identical.
656 */
657bool ts_node_eq(TSNode self, TSNode other);
658
659/************************/
660/* Section - TreeCursor */
661/************************/
662
663/**
664 * Create a new tree cursor starting from the given node.
665 *
666 * A tree cursor allows you to walk a syntax tree more efficiently than is
667 * possible using the [`TSNode`] functions. It is a mutable object that is always
668 * on a certain syntax node, and can be moved imperatively to different nodes.
669 */
670TSTreeCursor ts_tree_cursor_new(TSNode node);
671
672/**
673 * Delete a tree cursor, freeing all of the memory that it used.
674 */
675void ts_tree_cursor_delete(TSTreeCursor *self);
676
677/**
678 * Re-initialize a tree cursor to start at a different node.
679 */
680void ts_tree_cursor_reset(TSTreeCursor *self, TSNode node);
681
682/**
683 * Re-initialize a tree cursor to the same position as another cursor.
684 *
685 * Unlike [`ts_tree_cursor_reset`], this will not lose parent information and
686 * allows reusing already created cursors.
687*/
688void ts_tree_cursor_reset_to(TSTreeCursor *dst, const TSTreeCursor *src);
689
690/**
691 * Get the tree cursor's current node.
692 */
693TSNode ts_tree_cursor_current_node(const TSTreeCursor *self);
694
695/**
696 * Get the field name of the tree cursor's current node.
697 *
698 * This returns `NULL` if the current node doesn't have a field.
699 * See also [`ts_node_child_by_field_name`].
700 */
701const char *ts_tree_cursor_current_field_name(const TSTreeCursor *self);
702
703/**
704 * Get the field id of the tree cursor's current node.
705 *
706 * This returns zero if the current node doesn't have a field.
707 * See also [`ts_node_child_by_field_id`], [`ts_language_field_id_for_name`].
708 */
709TSFieldId ts_tree_cursor_current_field_id(const TSTreeCursor *self);
710
711/**
712 * Move the cursor to the parent of its current node.
713 *
714 * This returns `true` if the cursor successfully moved, and returns `false`
715 * if there was no parent node (the cursor was already on the root node).
716 */
717bool ts_tree_cursor_goto_parent(TSTreeCursor *self);
718
719/**
720 * Move the cursor to the next sibling of its current node.
721 *
722 * This returns `true` if the cursor successfully moved, and returns `false`
723 * if there was no next sibling node.
724 */
725bool ts_tree_cursor_goto_next_sibling(TSTreeCursor *self);
726
727/**
728 * Move the cursor to the previous sibling of its current node.
729 *
730 * This returns `true` if the cursor successfully moved, and returns `false` if
731 * there was no previous sibling node.
732 *
733 * Note, that this function may be slower than
734 * [`ts_tree_cursor_goto_next_sibling`] due to how node positions are stored. In
735 * the worst case, this will need to iterate through all the children upto the
736 * previous sibling node to recalculate its position.
737 */
738bool ts_tree_cursor_goto_previous_sibling(TSTreeCursor *self);
739
740/**
741 * Move the cursor to the first child of its current node.
742 *
743 * This returns `true` if the cursor successfully moved, and returns `false`
744 * if there were no children.
745 */
746bool ts_tree_cursor_goto_first_child(TSTreeCursor *self);
747
748/**
749 * Move the cursor to the last child of its current node.
750 *
751 * This returns `true` if the cursor successfully moved, and returns `false` if
752 * there were no children.
753 *
754 * Note that this function may be slower than [`ts_tree_cursor_goto_first_child`]
755 * because it needs to iterate through all the children to compute the child's
756 * position.
757 */
758bool ts_tree_cursor_goto_last_child(TSTreeCursor *self);
759
760/**
761 * Move the cursor to the node that is the nth descendant of
762 * the original node that the cursor was constructed with, where
763 * zero represents the original node itself.
764 */
765void ts_tree_cursor_goto_descendant(TSTreeCursor *self, uint32_t goal_descendant_index);
766
767/**
768 * Get the index of the cursor's current node out of all of the
769 * descendants of the original node that the cursor was constructed with.
770 */
771uint32_t ts_tree_cursor_current_descendant_index(const TSTreeCursor *self);
772
773/**
774 * Get the depth of the cursor's current node relative to the original
775 * node that the cursor was constructed with.
776 */
777uint32_t ts_tree_cursor_current_depth(const TSTreeCursor *self);
778
779/**
780 * Move the cursor to the first child of its current node that extends beyond
781 * the given byte offset or point.
782 *
783 * This returns the index of the child node if one was found, and returns -1
784 * if no such child was found.
785 */
786int64_t ts_tree_cursor_goto_first_child_for_byte(TSTreeCursor *self, uint32_t goal_byte);
787int64_t ts_tree_cursor_goto_first_child_for_point(TSTreeCursor *self, TSPoint goal_point);
788
789TSTreeCursor ts_tree_cursor_copy(const TSTreeCursor *cursor);
790
791/*******************/
792/* Section - Query */
793/*******************/
794
795/**
796 * Create a new query from a string containing one or more S-expression
797 * patterns. The query is associated with a particular language, and can
798 * only be run on syntax nodes parsed with that language.
799 *
800 * If all of the given patterns are valid, this returns a [`TSQuery`].
801 * If a pattern is invalid, this returns `NULL`, and provides two pieces
802 * of information about the problem:
803 * 1. The byte offset of the error is written to the `error_offset` parameter.
804 * 2. The type of error is written to the `error_type` parameter.
805 */
806TSQuery *ts_query_new(
807 const TSLanguage *language,
808 const char *source,
809 uint32_t source_len,
810 uint32_t *error_offset,
811 TSQueryError *error_type
812);
813
814/**
815 * Delete a query, freeing all of the memory that it used.
816 */
817void ts_query_delete(TSQuery *self);
818
819/**
820 * Get the number of patterns, captures, or string literals in the query.
821 */
822uint32_t ts_query_pattern_count(const TSQuery *self);
823uint32_t ts_query_capture_count(const TSQuery *self);
824uint32_t ts_query_string_count(const TSQuery *self);
825
826/**
827 * Get the byte offset where the given pattern starts in the query's source.
828 *
829 * This can be useful when combining queries by concatenating their source
830 * code strings.
831 */
832uint32_t ts_query_start_byte_for_pattern(const TSQuery *self, uint32_t pattern_index);
833
834/**
835 * Get all of the predicates for the given pattern in the query.
836 *
837 * The predicates are represented as a single array of steps. There are three
838 * types of steps in this array, which correspond to the three legal values for
839 * the `type` field:
840 * - `TSQueryPredicateStepTypeCapture` - Steps with this type represent names
841 * of captures. Their `value_id` can be used with the
842 * [`ts_query_capture_name_for_id`] function to obtain the name of the capture.
843 * - `TSQueryPredicateStepTypeString` - Steps with this type represent literal
844 * strings. Their `value_id` can be used with the
845 * [`ts_query_string_value_for_id`] function to obtain their string value.
846 * - `TSQueryPredicateStepTypeDone` - Steps with this type are *sentinels*
847 * that represent the end of an individual predicate. If a pattern has two
848 * predicates, then there will be two steps with this `type` in the array.
849 */
850const TSQueryPredicateStep *ts_query_predicates_for_pattern(
851 const TSQuery *self,
852 uint32_t pattern_index,
853 uint32_t *step_count
854);
855
856/*
857 * Check if the given pattern in the query has a single root node.
858 */
859bool ts_query_is_pattern_rooted(const TSQuery *self, uint32_t pattern_index);
860
861/*
862 * Check if the given pattern in the query is 'non local'.
863 *
864 * A non-local pattern has multiple root nodes and can match within a
865 * repeating sequence of nodes, as specified by the grammar. Non-local
866 * patterns disable certain optimizations that would otherwise be possible
867 * when executing a query on a specific range of a syntax tree.
868 */
869bool ts_query_is_pattern_non_local(const TSQuery *self, uint32_t pattern_index);
870
871/*
872 * Check if a given pattern is guaranteed to match once a given step is reached.
873 * The step is specified by its byte offset in the query's source code.
874 */
875bool ts_query_is_pattern_guaranteed_at_step(const TSQuery *self, uint32_t byte_offset);
876
877/**
878 * Get the name and length of one of the query's captures, or one of the
879 * query's string literals. Each capture and string is associated with a
880 * numeric id based on the order that it appeared in the query's source.
881 */
882const char *ts_query_capture_name_for_id(
883 const TSQuery *self,
884 uint32_t index,
885 uint32_t *length
886);
887
888/**
889 * Get the quantifier of the query's captures. Each capture is * associated
890 * with a numeric id based on the order that it appeared in the query's source.
891 */
892TSQuantifier ts_query_capture_quantifier_for_id(
893 const TSQuery *self,
894 uint32_t pattern_index,
895 uint32_t capture_index
896);
897
898const char *ts_query_string_value_for_id(
899 const TSQuery *self,
900 uint32_t index,
901 uint32_t *length
902);
903
904/**
905 * Disable a certain capture within a query.
906 *
907 * This prevents the capture from being returned in matches, and also avoids
908 * any resource usage associated with recording the capture. Currently, there
909 * is no way to undo this.
910 */
911void ts_query_disable_capture(TSQuery *self, const char *name, uint32_t length);
912
913/**
914 * Disable a certain pattern within a query.
915 *
916 * This prevents the pattern from matching and removes most of the overhead
917 * associated with the pattern. Currently, there is no way to undo this.
918 */
919void ts_query_disable_pattern(TSQuery *self, uint32_t pattern_index);
920
921/**
922 * Create a new cursor for executing a given query.
923 *
924 * The cursor stores the state that is needed to iteratively search
925 * for matches. To use the query cursor, first call [`ts_query_cursor_exec`]
926 * to start running a given query on a given syntax node. Then, there are
927 * two options for consuming the results of the query:
928 * 1. Repeatedly call [`ts_query_cursor_next_match`] to iterate over all of the
929 * *matches* in the order that they were found. Each match contains the
930 * index of the pattern that matched, and an array of captures. Because
931 * multiple patterns can match the same set of nodes, one match may contain
932 * captures that appear *before* some of the captures from a previous match.
933 * 2. Repeatedly call [`ts_query_cursor_next_capture`] to iterate over all of the
934 * individual *captures* in the order that they appear. This is useful if
935 * don't care about which pattern matched, and just want a single ordered
936 * sequence of captures.
937 *
938 * If you don't care about consuming all of the results, you can stop calling
939 * [`ts_query_cursor_next_match`] or [`ts_query_cursor_next_capture`] at any point.
940 * You can then start executing another query on another node by calling
941 * [`ts_query_cursor_exec`] again.
942 */
943TSQueryCursor *ts_query_cursor_new(void);
944
945/**
946 * Delete a query cursor, freeing all of the memory that it used.
947 */
948void ts_query_cursor_delete(TSQueryCursor *self);
949
950/**
951 * Start running a given query on a given node.
952 */
953void ts_query_cursor_exec(TSQueryCursor *self, const TSQuery *query, TSNode node);
954
955/**
956 * Manage the maximum number of in-progress matches allowed by this query
957 * cursor.
958 *
959 * Query cursors have an optional maximum capacity for storing lists of
960 * in-progress captures. If this capacity is exceeded, then the
961 * earliest-starting match will silently be dropped to make room for further
962 * matches. This maximum capacity is optional โ by default, query cursors allow
963 * any number of pending matches, dynamically allocating new space for them as
964 * needed as the query is executed.
965 */
966bool ts_query_cursor_did_exceed_match_limit(const TSQueryCursor *self);
967uint32_t ts_query_cursor_match_limit(const TSQueryCursor *self);
968void ts_query_cursor_set_match_limit(TSQueryCursor *self, uint32_t limit);
969
970/**
971 * Set the range of bytes or (row, column) positions in which the query
972 * will be executed.
973 */
974void ts_query_cursor_set_byte_range(TSQueryCursor *self, uint32_t start_byte, uint32_t end_byte);
975void ts_query_cursor_set_point_range(TSQueryCursor *self, TSPoint start_point, TSPoint end_point);
976
977/**
978 * Advance to the next match of the currently running query.
979 *
980 * If there is a match, write it to `*match` and return `true`.
981 * Otherwise, return `false`.
982 */
983bool ts_query_cursor_next_match(TSQueryCursor *self, TSQueryMatch *match);
984void ts_query_cursor_remove_match(TSQueryCursor *self, uint32_t match_id);
985
986/**
987 * Advance to the next capture of the currently running query.
988 *
989 * If there is a capture, write its match to `*match` and its index within
990 * the matche's capture list to `*capture_index`. Otherwise, return `false`.
991 */
992bool ts_query_cursor_next_capture(
993 TSQueryCursor *self,
994 TSQueryMatch *match,
995 uint32_t *capture_index
996);
997
998/**
999 * Set the maximum start depth for a query cursor.
1000 *
1001 * This prevents cursors from exploring children nodes at a certain depth.
1002 * Note if a pattern includes many children, then they will still be checked.
1003 *
1004 * The zero max start depth value can be used as a special behavior and
1005 * it helps to destructure a subtree by staying on a node and using captures
1006 * for interested parts. Note that the zero max start depth only limit a search
1007 * depth for a pattern's root node but other nodes that are parts of the pattern
1008 * may be searched at any depth what defined by the pattern structure.
1009 *
1010 * Set to `UINT32_MAX` to remove the maximum start depth.
1011 */
1012void ts_query_cursor_set_max_start_depth(TSQueryCursor *self, uint32_t max_start_depth);
1013
1014/**********************/
1015/* Section - Language */
1016/**********************/
1017
1018/**
1019 * Get another reference to the given language.
1020 */
1021const TSLanguage *ts_language_copy(const TSLanguage *self);
1022
1023/**
1024 * Free any dynamically-allocated resources for this language, if
1025 * this is the last reference.
1026 */
1027void ts_language_delete(const TSLanguage *self);
1028
1029/**
1030 * Get the number of distinct node types in the language.
1031 */
1032uint32_t ts_language_symbol_count(const TSLanguage *self);
1033
1034/**
1035 * Get the number of valid states in this language.
1036*/
1037uint32_t ts_language_state_count(const TSLanguage *self);
1038
1039/**
1040 * Get a node type string for the given numerical id.
1041 */
1042const char *ts_language_symbol_name(const TSLanguage *self, TSSymbol symbol);
1043
1044/**
1045 * Get the numerical id for the given node type string.
1046 */
1047TSSymbol ts_language_symbol_for_name(
1048 const TSLanguage *self,
1049 const char *string,
1050 uint32_t length,
1051 bool is_named
1052);
1053
1054/**
1055 * Get the number of distinct field names in the language.
1056 */
1057uint32_t ts_language_field_count(const TSLanguage *self);
1058
1059/**
1060 * Get the field name string for the given numerical id.
1061 */
1062const char *ts_language_field_name_for_id(const TSLanguage *self, TSFieldId id);
1063
1064/**
1065 * Get the numerical id for the given field name string.
1066 */
1067TSFieldId ts_language_field_id_for_name(const TSLanguage *self, const char *name, uint32_t name_length);
1068
1069/**
1070 * Check whether the given node type id belongs to named nodes, anonymous nodes,
1071 * or a hidden nodes.
1072 *
1073 * See also [`ts_node_is_named`]. Hidden nodes are never returned from the API.
1074 */
1075TSSymbolType ts_language_symbol_type(const TSLanguage *self, TSSymbol symbol);
1076
1077/**
1078 * Get the ABI version number for this language. This version number is used
1079 * to ensure that languages were generated by a compatible version of
1080 * Tree-sitter.
1081 *
1082 * See also [`ts_parser_set_language`].
1083 */
1084uint32_t ts_language_version(const TSLanguage *self);
1085
1086/**
1087 * Get the next parse state. Combine this with lookahead iterators to generate
1088 * completion suggestions or valid symbols in error nodes. Use
1089 * [`ts_node_grammar_symbol`] for valid symbols.
1090*/
1091TSStateId ts_language_next_state(const TSLanguage *self, TSStateId state, TSSymbol symbol);
1092
1093/********************************/
1094/* Section - Lookahead Iterator */
1095/********************************/
1096
1097/**
1098 * Create a new lookahead iterator for the given language and parse state.
1099 *
1100 * This returns `NULL` if state is invalid for the language.
1101 *
1102 * Repeatedly using [`ts_lookahead_iterator_next`] and
1103 * [`ts_lookahead_iterator_current_symbol`] will generate valid symbols in the
1104 * given parse state. Newly created lookahead iterators will contain the `ERROR`
1105 * symbol.
1106 *
1107 * Lookahead iterators can be useful to generate suggestions and improve syntax
1108 * error diagnostics. To get symbols valid in an ERROR node, use the lookahead
1109 * iterator on its first leaf node state. For `MISSING` nodes, a lookahead
1110 * iterator created on the previous non-extra leaf node may be appropriate.
1111*/
1112TSLookaheadIterator *ts_lookahead_iterator_new(const TSLanguage *self, TSStateId state);
1113
1114/**
1115 * Delete a lookahead iterator freeing all the memory used.
1116*/
1117void ts_lookahead_iterator_delete(TSLookaheadIterator *self);
1118
1119/**
1120 * Reset the lookahead iterator to another state.
1121 *
1122 * This returns `true` if the iterator was reset to the given state and `false`
1123 * otherwise.
1124*/
1125bool ts_lookahead_iterator_reset_state(TSLookaheadIterator *self, TSStateId state);
1126
1127/**
1128 * Reset the lookahead iterator.
1129 *
1130 * This returns `true` if the language was set successfully and `false`
1131 * otherwise.
1132*/
1133bool ts_lookahead_iterator_reset(TSLookaheadIterator *self, const TSLanguage *language, TSStateId state);
1134
1135/**
1136 * Get the current language of the lookahead iterator.
1137*/
1138const TSLanguage *ts_lookahead_iterator_language(const TSLookaheadIterator *self);
1139
1140/**
1141 * Advance the lookahead iterator to the next symbol.
1142 *
1143 * This returns `true` if there is a new symbol and `false` otherwise.
1144*/
1145bool ts_lookahead_iterator_next(TSLookaheadIterator *self);
1146
1147/**
1148 * Get the current symbol of the lookahead iterator;
1149*/
1150TSSymbol ts_lookahead_iterator_current_symbol(const TSLookaheadIterator *self);
1151
1152/**
1153 * Get the current symbol type of the lookahead iterator as a null terminated
1154 * string.
1155*/
1156const char *ts_lookahead_iterator_current_symbol_name(const TSLookaheadIterator *self);
1157
1158/*************************************/
1159/* Section - WebAssembly Integration */
1160/************************************/
1161
1162typedef struct wasm_engine_t TSWasmEngine;
1163typedef struct TSWasmStore TSWasmStore;
1164
1165typedef enum {
1166 TSWasmErrorKindNone = 0,
1167 TSWasmErrorKindParse,
1168 TSWasmErrorKindCompile,
1169 TSWasmErrorKindInstantiate,
1170 TSWasmErrorKindAllocate,
1171} TSWasmErrorKind;
1172
1173typedef struct {
1174 TSWasmErrorKind kind;
1175 char *message;
1176} TSWasmError;
1177
1178/**
1179 * Create a Wasm store.
1180 */
1181TSWasmStore *ts_wasm_store_new(
1182 TSWasmEngine *engine,
1183 TSWasmError *error
1184);
1185
1186/**
1187 * Free the memory associated with the given Wasm store.
1188 */
1189void ts_wasm_store_delete(TSWasmStore *);
1190
1191/**
1192 * Create a language from a buffer of Wasm. The resulting language behaves
1193 * like any other Tree-sitter language, except that in order to use it with
1194 * a parser, that parser must have a Wasm store. Note that the language
1195 * can be used with any Wasm store, it doesn't need to be the same store that
1196 * was used to originally load it.
1197 */
1198const TSLanguage *ts_wasm_store_load_language(
1199 TSWasmStore *,
1200 const char *name,
1201 const char *wasm,
1202 uint32_t wasm_len,
1203 TSWasmError *error
1204);
1205
1206/**
1207 * Get the number of languages instantiated in the given wasm store.
1208 */
1209size_t ts_wasm_store_language_count(const TSWasmStore *);
1210
1211/**
1212 * Check if the language came from a Wasm module. If so, then in order to use
1213 * this language with a Parser, that parser must have a Wasm store assigned.
1214 */
1215bool ts_language_is_wasm(const TSLanguage *);
1216
1217/**
1218 * Assign the given Wasm store to the parser. A parser must have a Wasm store
1219 * in order to use Wasm languages.
1220 */
1221void ts_parser_set_wasm_store(TSParser *, TSWasmStore *);
1222
1223/**
1224 * Remove the parser's current Wasm store and return it. This returns NULL if
1225 * the parser doesn't have a Wasm store.
1226 */
1227TSWasmStore *ts_parser_take_wasm_store(TSParser *);
1228
1229/**********************************/
1230/* Section - Global Configuration */
1231/**********************************/
1232
1233/**
1234 * Set the allocation functions used by the library.
1235 *
1236 * By default, Tree-sitter uses the standard libc allocation functions,
1237 * but aborts the process when an allocation fails. This function lets
1238 * you supply alternative allocation functions at runtime.
1239 *
1240 * If you pass `NULL` for any parameter, Tree-sitter will switch back to
1241 * its default implementation of that function.
1242 *
1243 * If you call this function after the library has already been used, then
1244 * you must ensure that either:
1245 * 1. All the existing objects have been freed.
1246 * 2. The new allocator shares its state with the old one, so it is capable
1247 * of freeing memory that was allocated by the old allocator.
1248 */
1249void ts_set_allocator(
1250 void *(*new_malloc)(size_t),
1251 void *(*new_calloc)(size_t, size_t),
1252 void *(*new_realloc)(void *, size_t),
1253 void (*new_free)(void *)
1254);
1255
1256#ifdef __cplusplus
1257}
1258#endif
1259
1260#ifndef TREE_SITTER_HIDE_SYMBOLS
1261#if defined(__GNUC__) || defined(__clang__)
1262#pragma GCC visibility pop
1263#endif
1264#endif
1265
1266#endif // TREE_SITTER_API_H_