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