diffdown.com
Diffdown is a real-time collaborative Markdown editor/previewer built on the AT Protocol
diffdown.com
1/**
2The [`TreeFragment.applyChanges`](#common.TreeFragment^applyChanges)
3method expects changed ranges in this format.
4*/
5interface ChangedRange {
6 /**
7 The start of the change in the start document
8 */
9 fromA: number;
10 /**
11 The end of the change in the start document
12 */
13 toA: number;
14 /**
15 The start of the replacement in the new document
16 */
17 fromB: number;
18 /**
19 The end of the replacement in the new document
20 */
21 toB: number;
22}
23/**
24Tree fragments are used during [incremental
25parsing](#common.Parser.startParse) to track parts of old trees
26that can be reused in a new parse. An array of fragments is used
27to track regions of an old tree whose nodes might be reused in new
28parses. Use the static
29[`applyChanges`](#common.TreeFragment^applyChanges) method to
30update fragments for document changes.
31*/
32declare class TreeFragment {
33 /**
34 The start of the unchanged range pointed to by this fragment.
35 This refers to an offset in the _updated_ document (as opposed
36 to the original tree).
37 */
38 readonly from: number;
39 /**
40 The end of the unchanged range.
41 */
42 readonly to: number;
43 /**
44 The tree that this fragment is based on.
45 */
46 readonly tree: Tree;
47 /**
48 The offset between the fragment's tree and the document that
49 this fragment can be used against. Add this when going from
50 document to tree positions, subtract it to go from tree to
51 document positions.
52 */
53 readonly offset: number;
54 /**
55 Construct a tree fragment. You'll usually want to use
56 [`addTree`](#common.TreeFragment^addTree) and
57 [`applyChanges`](#common.TreeFragment^applyChanges) instead of
58 calling this directly.
59 */
60 constructor(
61 /**
62 The start of the unchanged range pointed to by this fragment.
63 This refers to an offset in the _updated_ document (as opposed
64 to the original tree).
65 */
66 from: number,
67 /**
68 The end of the unchanged range.
69 */
70 to: number,
71 /**
72 The tree that this fragment is based on.
73 */
74 tree: Tree,
75 /**
76 The offset between the fragment's tree and the document that
77 this fragment can be used against. Add this when going from
78 document to tree positions, subtract it to go from tree to
79 document positions.
80 */
81 offset: number, openStart?: boolean, openEnd?: boolean);
82 /**
83 Whether the start of the fragment represents the start of a
84 parse, or the end of a change. (In the second case, it may not
85 be safe to reuse some nodes at the start, depending on the
86 parsing algorithm.)
87 */
88 get openStart(): boolean;
89 /**
90 Whether the end of the fragment represents the end of a
91 full-document parse, or the start of a change.
92 */
93 get openEnd(): boolean;
94 /**
95 Create a set of fragments from a freshly parsed tree, or update
96 an existing set of fragments by replacing the ones that overlap
97 with a tree with content from the new tree. When `partial` is
98 true, the parse is treated as incomplete, and the resulting
99 fragment has [`openEnd`](#common.TreeFragment.openEnd) set to
100 true.
101 */
102 static addTree(tree: Tree, fragments?: readonly TreeFragment[], partial?: boolean): readonly TreeFragment[];
103 /**
104 Apply a set of edits to an array of fragments, removing or
105 splitting fragments as necessary to remove edited ranges, and
106 adjusting offsets for fragments that moved.
107 */
108 static applyChanges(fragments: readonly TreeFragment[], changes: readonly ChangedRange[], minGap?: number): readonly TreeFragment[];
109}
110/**
111Interface used to represent an in-progress parse, which can be
112moved forward piece-by-piece.
113*/
114interface PartialParse {
115 /**
116 Advance the parse state by some amount. Will return the finished
117 syntax tree when the parse completes.
118 */
119 advance(): Tree | null;
120 /**
121 The position up to which the document has been parsed. Note
122 that, in multi-pass parsers, this will stay back until the last
123 pass has moved past a given position.
124 */
125 readonly parsedPos: number;
126 /**
127 Tell the parse to not advance beyond the given position.
128 `advance` will return a tree when the parse has reached the
129 position. Note that, depending on the parser algorithm and the
130 state of the parse when `stopAt` was called, that tree may
131 contain nodes beyond the position. It is an error to call
132 `stopAt` with a higher position than it's [current
133 value](#common.PartialParse.stoppedAt).
134 */
135 stopAt(pos: number): void;
136 /**
137 Reports whether `stopAt` has been called on this parse.
138 */
139 readonly stoppedAt: number | null;
140}
141/**
142A superclass that parsers should extend.
143*/
144declare abstract class Parser {
145 /**
146 Start a parse for a single tree. This is the method concrete
147 parser implementations must implement. Called by `startParse`,
148 with the optional arguments resolved.
149 */
150 abstract createParse(input: Input, fragments: readonly TreeFragment[], ranges: readonly {
151 from: number;
152 to: number;
153 }[]): PartialParse;
154 /**
155 Start a parse, returning a [partial parse](#common.PartialParse)
156 object. [`fragments`](#common.TreeFragment) can be passed in to
157 make the parse incremental.
158
159 By default, the entire input is parsed. You can pass `ranges`,
160 which should be a sorted array of non-empty, non-overlapping
161 ranges, to parse only those ranges. The tree returned in that
162 case will start at `ranges[0].from`.
163 */
164 startParse(input: Input | string, fragments?: readonly TreeFragment[], ranges?: readonly {
165 from: number;
166 to: number;
167 }[]): PartialParse;
168 /**
169 Run a full parse, returning the resulting tree.
170 */
171 parse(input: Input | string, fragments?: readonly TreeFragment[], ranges?: readonly {
172 from: number;
173 to: number;
174 }[]): Tree;
175}
176/**
177This is the interface parsers use to access the document. To run
178Lezer directly on your own document data structure, you have to
179write an implementation of it.
180*/
181interface Input {
182 /**
183 The length of the document.
184 */
185 readonly length: number;
186 /**
187 Get the chunk after the given position. The returned string
188 should start at `from` and, if that isn't the end of the
189 document, may be of any length greater than zero.
190 */
191 chunk(from: number): string;
192 /**
193 Indicates whether the chunks already end at line breaks, so that
194 client code that wants to work by-line can avoid re-scanning
195 them for line breaks. When this is true, the result of `chunk()`
196 should either be a single line break, or the content between
197 `from` and the next line break.
198 */
199 readonly lineChunks: boolean;
200 /**
201 Read the part of the document between the given positions.
202 */
203 read(from: number, to: number): string;
204}
205/**
206Parse wrapper functions are supported by some parsers to inject
207additional parsing logic.
208*/
209type ParseWrapper = (inner: PartialParse, input: Input, fragments: readonly TreeFragment[], ranges: readonly {
210 from: number;
211 to: number;
212}[]) => PartialParse;
213
214/**
215The default maximum length of a `TreeBuffer` node.
216*/
217declare const DefaultBufferLength = 1024;
218/**
219Each [node type](#common.NodeType) or [individual tree](#common.Tree)
220can have metadata associated with it in props. Instances of this
221class represent prop names.
222*/
223declare class NodeProp<T> {
224 /**
225 Indicates whether this prop is stored per [node
226 type](#common.NodeType) or per [tree node](#common.Tree).
227 */
228 perNode: boolean;
229 /**
230 A method that deserializes a value of this prop from a string.
231 Can be used to allow a prop to be directly written in a grammar
232 file.
233 */
234 deserialize: (str: string) => T;
235 /**
236 Create a new node prop type.
237 */
238 constructor(config?: {
239 /**
240 The [deserialize](#common.NodeProp.deserialize) function to
241 use for this prop, used for example when directly providing
242 the prop from a grammar file. Defaults to a function that
243 raises an error.
244 */
245 deserialize?: (str: string) => T;
246 /**
247 If configuring another value for this prop when it already
248 exists on a node should combine the old and new values, rather
249 than overwrite the old value, you can pass a function that
250 does the combining here.
251 */
252 combine?: (a: T, b: T) => T;
253 /**
254 By default, node props are stored in the [node
255 type](#common.NodeType). It can sometimes be useful to directly
256 store information (usually related to the parsing algorithm)
257 in [nodes](#common.Tree) themselves. Set this to true to enable
258 that for this prop.
259 */
260 perNode?: boolean;
261 });
262 /**
263 This is meant to be used with
264 [`NodeSet.extend`](#common.NodeSet.extend) or
265 [`LRParser.configure`](#lr.ParserConfig.props) to compute
266 prop values for each node type in the set. Takes a [match
267 object](#common.NodeType^match) or function that returns undefined
268 if the node type doesn't get this prop, and the prop's value if
269 it does.
270 */
271 add(match: {
272 [selector: string]: T;
273 } | ((type: NodeType) => T | undefined)): NodePropSource;
274 /**
275 Prop that is used to describe matching delimiters. For opening
276 delimiters, this holds an array of node names (written as a
277 space-separated string when declaring this prop in a grammar)
278 for the node types of closing delimiters that match it.
279 */
280 static closedBy: NodeProp<readonly string[]>;
281 /**
282 The inverse of [`closedBy`](#common.NodeProp^closedBy). This is
283 attached to closing delimiters, holding an array of node names
284 of types of matching opening delimiters.
285 */
286 static openedBy: NodeProp<readonly string[]>;
287 /**
288 Used to assign node types to groups (for example, all node
289 types that represent an expression could be tagged with an
290 `"Expression"` group).
291 */
292 static group: NodeProp<readonly string[]>;
293 /**
294 Attached to nodes to indicate these should be
295 [displayed](https://codemirror.net/docs/ref/#language.syntaxTree)
296 in a bidirectional text isolate, so that direction-neutral
297 characters on their sides don't incorrectly get associated with
298 surrounding text. You'll generally want to set this for nodes
299 that contain arbitrary text, like strings and comments, and for
300 nodes that appear _inside_ arbitrary text, like HTML tags. When
301 not given a value, in a grammar declaration, defaults to
302 `"auto"`.
303 */
304 static isolate: NodeProp<"rtl" | "ltr" | "auto">;
305 /**
306 The hash of the [context](#lr.ContextTracker.constructor)
307 that the node was parsed in, if any. Used to limit reuse of
308 contextual nodes.
309 */
310 static contextHash: NodeProp<number>;
311 /**
312 The distance beyond the end of the node that the tokenizer
313 looked ahead for any of the tokens inside the node. (The LR
314 parser only stores this when it is larger than 25, for
315 efficiency reasons.)
316 */
317 static lookAhead: NodeProp<number>;
318 /**
319 This per-node prop is used to replace a given node, or part of a
320 node, with another tree. This is useful to include trees from
321 different languages in mixed-language parsers.
322 */
323 static mounted: NodeProp<MountedTree>;
324}
325/**
326A mounted tree, which can be [stored](#common.NodeProp^mounted) on
327a tree node to indicate that parts of its content are
328represented by another tree.
329*/
330declare class MountedTree {
331 /**
332 The inner tree.
333 */
334 readonly tree: Tree;
335 /**
336 If this is null, this tree replaces the entire node (it will
337 be included in the regular iteration instead of its host
338 node). If not, only the given ranges are considered to be
339 covered by this tree. This is used for trees that are mixed in
340 a way that isn't strictly hierarchical. Such mounted trees are
341 only entered by [`resolveInner`](#common.Tree.resolveInner)
342 and [`enter`](#common.SyntaxNode.enter).
343 */
344 readonly overlay: readonly {
345 from: number;
346 to: number;
347 }[] | null;
348 /**
349 The parser used to create this subtree.
350 */
351 readonly parser: Parser;
352 /**
353 [Indicates](#common.IterMode.EnterBracketed) that the nested
354 content is delineated with some kind
355 of bracket token.
356 */
357 readonly bracketed: boolean;
358 constructor(
359 /**
360 The inner tree.
361 */
362 tree: Tree,
363 /**
364 If this is null, this tree replaces the entire node (it will
365 be included in the regular iteration instead of its host
366 node). If not, only the given ranges are considered to be
367 covered by this tree. This is used for trees that are mixed in
368 a way that isn't strictly hierarchical. Such mounted trees are
369 only entered by [`resolveInner`](#common.Tree.resolveInner)
370 and [`enter`](#common.SyntaxNode.enter).
371 */
372 overlay: readonly {
373 from: number;
374 to: number;
375 }[] | null,
376 /**
377 The parser used to create this subtree.
378 */
379 parser: Parser,
380 /**
381 [Indicates](#common.IterMode.EnterBracketed) that the nested
382 content is delineated with some kind
383 of bracket token.
384 */
385 bracketed?: boolean);
386}
387/**
388Type returned by [`NodeProp.add`](#common.NodeProp.add). Describes
389whether a prop should be added to a given node type in a node set,
390and what value it should have.
391*/
392type NodePropSource = (type: NodeType) => null | [NodeProp<any>, any];
393/**
394Each node in a syntax tree has a node type associated with it.
395*/
396declare class NodeType {
397 /**
398 The name of the node type. Not necessarily unique, but if the
399 grammar was written properly, different node types with the
400 same name within a node set should play the same semantic
401 role.
402 */
403 readonly name: string;
404 /**
405 The id of this node in its set. Corresponds to the term ids
406 used in the parser.
407 */
408 readonly id: number;
409 /**
410 Define a node type.
411 */
412 static define(spec: {
413 /**
414 The ID of the node type. When this type is used in a
415 [set](#common.NodeSet), the ID must correspond to its index in
416 the type array.
417 */
418 id: number;
419 /**
420 The name of the node type. Leave empty to define an anonymous
421 node.
422 */
423 name?: string;
424 /**
425 [Node props](#common.NodeProp) to assign to the type. The value
426 given for any given prop should correspond to the prop's type.
427 */
428 props?: readonly ([NodeProp<any>, any] | NodePropSource)[];
429 /**
430 Whether this is a [top node](#common.NodeType.isTop).
431 */
432 top?: boolean;
433 /**
434 Whether this node counts as an [error
435 node](#common.NodeType.isError).
436 */
437 error?: boolean;
438 /**
439 Whether this node is a [skipped](#common.NodeType.isSkipped)
440 node.
441 */
442 skipped?: boolean;
443 }): NodeType;
444 /**
445 Retrieves a node prop for this type. Will return `undefined` if
446 the prop isn't present on this node.
447 */
448 prop<T>(prop: NodeProp<T>): T | undefined;
449 /**
450 True when this is the top node of a grammar.
451 */
452 get isTop(): boolean;
453 /**
454 True when this node is produced by a skip rule.
455 */
456 get isSkipped(): boolean;
457 /**
458 Indicates whether this is an error node.
459 */
460 get isError(): boolean;
461 /**
462 When true, this node type doesn't correspond to a user-declared
463 named node, for example because it is used to cache repetition.
464 */
465 get isAnonymous(): boolean;
466 /**
467 Returns true when this node's name or one of its
468 [groups](#common.NodeProp^group) matches the given string.
469 */
470 is(name: string | number): boolean;
471 /**
472 An empty dummy node type to use when no actual type is available.
473 */
474 static none: NodeType;
475 /**
476 Create a function from node types to arbitrary values by
477 specifying an object whose property names are node or
478 [group](#common.NodeProp^group) names. Often useful with
479 [`NodeProp.add`](#common.NodeProp.add). You can put multiple
480 names, separated by spaces, in a single property name to map
481 multiple node names to a single value.
482 */
483 static match<T>(map: {
484 [selector: string]: T;
485 }): (node: NodeType) => T | undefined;
486}
487/**
488A node set holds a collection of node types. It is used to
489compactly represent trees by storing their type ids, rather than a
490full pointer to the type object, in a numeric array. Each parser
491[has](#lr.LRParser.nodeSet) a node set, and [tree
492buffers](#common.TreeBuffer) can only store collections of nodes
493from the same set. A set can have a maximum of 2**16 (65536) node
494types in it, so that the ids fit into 16-bit typed array slots.
495*/
496declare class NodeSet {
497 /**
498 The node types in this set, by id.
499 */
500 readonly types: readonly NodeType[];
501 /**
502 Create a set with the given types. The `id` property of each
503 type should correspond to its position within the array.
504 */
505 constructor(
506 /**
507 The node types in this set, by id.
508 */
509 types: readonly NodeType[]);
510 /**
511 Create a copy of this set with some node properties added. The
512 arguments to this method can be created with
513 [`NodeProp.add`](#common.NodeProp.add).
514 */
515 extend(...props: NodePropSource[]): NodeSet;
516}
517/**
518Options that control iteration. Can be combined with the `|`
519operator to enable multiple ones.
520*/
521declare enum IterMode {
522 /**
523 When enabled, iteration will only visit [`Tree`](#common.Tree)
524 objects, not nodes packed into
525 [`TreeBuffer`](#common.TreeBuffer)s.
526 */
527 ExcludeBuffers = 1,
528 /**
529 Enable this to make iteration include anonymous nodes (such as
530 the nodes that wrap repeated grammar constructs into a balanced
531 tree).
532 */
533 IncludeAnonymous = 2,
534 /**
535 By default, regular [mounted](#common.NodeProp^mounted) nodes
536 replace their base node in iteration. Enable this to ignore them
537 instead.
538 */
539 IgnoreMounts = 4,
540 /**
541 This option only applies in
542 [`enter`](#common.SyntaxNode.enter)-style methods. It tells the
543 library to not enter mounted overlays if one covers the given
544 position.
545 */
546 IgnoreOverlays = 8,
547 /**
548 When set, positions on the boundary of a mounted overlay tree
549 that has its [`bracketed`](#common.NestedParse.bracketed) flag
550 set will enter that tree regardless of side. Only supported in
551 [`enter`](#common.SyntaxNode.enter), not in cursors.
552 */
553 EnterBracketed = 16
554}
555/**
556A piece of syntax tree. There are two ways to approach these
557trees: the way they are actually stored in memory, and the
558convenient way.
559
560Syntax trees are stored as a tree of `Tree` and `TreeBuffer`
561objects. By packing detail information into `TreeBuffer` leaf
562nodes, the representation is made a lot more memory-efficient.
563
564However, when you want to actually work with tree nodes, this
565representation is very awkward, so most client code will want to
566use the [`TreeCursor`](#common.TreeCursor) or
567[`SyntaxNode`](#common.SyntaxNode) interface instead, which provides
568a view on some part of this data structure, and can be used to
569move around to adjacent nodes.
570*/
571declare class Tree {
572 /**
573 The type of the top node.
574 */
575 readonly type: NodeType;
576 /**
577 This node's child nodes.
578 */
579 readonly children: readonly (Tree | TreeBuffer)[];
580 /**
581 The positions (offsets relative to the start of this tree) of
582 the children.
583 */
584 readonly positions: readonly number[];
585 /**
586 The total length of this tree
587 */
588 readonly length: number;
589 /**
590 Construct a new tree. See also [`Tree.build`](#common.Tree^build).
591 */
592 constructor(
593 /**
594 The type of the top node.
595 */
596 type: NodeType,
597 /**
598 This node's child nodes.
599 */
600 children: readonly (Tree | TreeBuffer)[],
601 /**
602 The positions (offsets relative to the start of this tree) of
603 the children.
604 */
605 positions: readonly number[],
606 /**
607 The total length of this tree
608 */
609 length: number,
610 /**
611 Per-node [node props](#common.NodeProp) to associate with this node.
612 */
613 props?: readonly [NodeProp<any> | number, any][]);
614 /**
615 The empty tree
616 */
617 static empty: Tree;
618 /**
619 Get a [tree cursor](#common.TreeCursor) positioned at the top of
620 the tree. Mode can be used to [control](#common.IterMode) which
621 nodes the cursor visits.
622 */
623 cursor(mode?: IterMode): TreeCursor;
624 /**
625 Get a [tree cursor](#common.TreeCursor) pointing into this tree
626 at the given position and side (see
627 [`moveTo`](#common.TreeCursor.moveTo).
628 */
629 cursorAt(pos: number, side?: -1 | 0 | 1, mode?: IterMode): TreeCursor;
630 /**
631 Get a [syntax node](#common.SyntaxNode) object for the top of the
632 tree.
633 */
634 get topNode(): SyntaxNode;
635 /**
636 Get the [syntax node](#common.SyntaxNode) at the given position.
637 If `side` is -1, this will move into nodes that end at the
638 position. If 1, it'll move into nodes that start at the
639 position. With 0, it'll only enter nodes that cover the position
640 from both sides.
641
642 Note that this will not enter
643 [overlays](#common.MountedTree.overlay), and you often want
644 [`resolveInner`](#common.Tree.resolveInner) instead.
645 */
646 resolve(pos: number, side?: -1 | 0 | 1): SyntaxNode;
647 /**
648 Like [`resolve`](#common.Tree.resolve), but will enter
649 [overlaid](#common.MountedTree.overlay) nodes, producing a syntax node
650 pointing into the innermost overlaid tree at the given position
651 (with parent links going through all parent structure, including
652 the host trees).
653 */
654 resolveInner(pos: number, side?: -1 | 0 | 1): SyntaxNode;
655 /**
656 In some situations, it can be useful to iterate through all
657 nodes around a position, including those in overlays that don't
658 directly cover the position. This method gives you an iterator
659 that will produce all nodes, from small to big, around the given
660 position.
661 */
662 resolveStack(pos: number, side?: -1 | 0 | 1): NodeIterator;
663 /**
664 Iterate over the tree and its children, calling `enter` for any
665 node that touches the `from`/`to` region (if given) before
666 running over such a node's children, and `leave` (if given) when
667 leaving the node. When `enter` returns `false`, that node will
668 not have its children iterated over (or `leave` called).
669 */
670 iterate(spec: {
671 enter(node: SyntaxNodeRef): boolean | void;
672 leave?(node: SyntaxNodeRef): void;
673 from?: number;
674 to?: number;
675 mode?: IterMode;
676 }): void;
677 /**
678 Get the value of the given [node prop](#common.NodeProp) for this
679 node. Works with both per-node and per-type props.
680 */
681 prop<T>(prop: NodeProp<T>): T | undefined;
682 /**
683 Returns the node's [per-node props](#common.NodeProp.perNode) in a
684 format that can be passed to the [`Tree`](#common.Tree)
685 constructor.
686 */
687 get propValues(): readonly [NodeProp<any> | number, any][];
688 /**
689 Balance the direct children of this tree, producing a copy of
690 which may have children grouped into subtrees with type
691 [`NodeType.none`](#common.NodeType^none).
692 */
693 balance(config?: {
694 /**
695 Function to create the newly balanced subtrees.
696 */
697 makeTree?: (children: readonly (Tree | TreeBuffer)[], positions: readonly number[], length: number) => Tree;
698 }): Tree;
699 /**
700 Build a tree from a postfix-ordered buffer of node information,
701 or a cursor over such a buffer.
702 */
703 static build(data: BuildData): Tree;
704}
705/**
706Represents a sequence of nodes.
707*/
708type NodeIterator = {
709 node: SyntaxNode;
710 next: NodeIterator | null;
711};
712type BuildData = {
713 /**
714 The buffer or buffer cursor to read the node data from.
715
716 When this is an array, it should contain four values for every
717 node in the tree.
718
719 - The first holds the node's type, as a node ID pointing into
720 the given `NodeSet`.
721 - The second holds the node's start offset.
722 - The third the end offset.
723 - The fourth the amount of space taken up in the array by this
724 node and its children. Since there's four values per node,
725 this is the total number of nodes inside this node (children
726 and transitive children) plus one for the node itself, times
727 four.
728
729 Parent nodes should appear _after_ child nodes in the array. As
730 an example, a node of type 10 spanning positions 0 to 4, with
731 two children, of type 11 and 12, might look like this:
732
733 [11, 0, 1, 4, 12, 2, 4, 4, 10, 0, 4, 12]
734 */
735 buffer: BufferCursor | readonly number[];
736 /**
737 The node types to use.
738 */
739 nodeSet: NodeSet;
740 /**
741 The id of the top node type.
742 */
743 topID: number;
744 /**
745 The position the tree should start at. Defaults to 0.
746 */
747 start?: number;
748 /**
749 The position in the buffer where the function should stop
750 reading. Defaults to 0.
751 */
752 bufferStart?: number;
753 /**
754 The length of the wrapping node. The end offset of the last
755 child is used when not provided.
756 */
757 length?: number;
758 /**
759 The maximum buffer length to use. Defaults to
760 [`DefaultBufferLength`](#common.DefaultBufferLength).
761 */
762 maxBufferLength?: number;
763 /**
764 An optional array holding reused nodes that the buffer can refer
765 to.
766 */
767 reused?: readonly Tree[];
768 /**
769 The first node type that indicates repeat constructs in this
770 grammar.
771 */
772 minRepeatType?: number;
773};
774/**
775This is used by `Tree.build` as an abstraction for iterating over
776a tree buffer. A cursor initially points at the very last element
777in the buffer. Every time `next()` is called it moves on to the
778previous one.
779*/
780interface BufferCursor {
781 /**
782 The current buffer position (four times the number of nodes
783 remaining).
784 */
785 pos: number;
786 /**
787 The node ID of the next node in the buffer.
788 */
789 id: number;
790 /**
791 The start position of the next node in the buffer.
792 */
793 start: number;
794 /**
795 The end position of the next node.
796 */
797 end: number;
798 /**
799 The size of the next node (the number of nodes inside, counting
800 the node itself, times 4).
801 */
802 size: number;
803 /**
804 Moves `this.pos` down by 4.
805 */
806 next(): void;
807 /**
808 Create a copy of this cursor.
809 */
810 fork(): BufferCursor;
811}
812/**
813Tree buffers contain (type, start, end, endIndex) quads for each
814node. In such a buffer, nodes are stored in prefix order (parents
815before children, with the endIndex of the parent indicating which
816children belong to it).
817*/
818declare class TreeBuffer {
819 /**
820 The buffer's content.
821 */
822 readonly buffer: Uint16Array;
823 /**
824 The total length of the group of nodes in the buffer.
825 */
826 readonly length: number;
827 /**
828 The node set used in this buffer.
829 */
830 readonly set: NodeSet;
831 /**
832 Create a tree buffer.
833 */
834 constructor(
835 /**
836 The buffer's content.
837 */
838 buffer: Uint16Array,
839 /**
840 The total length of the group of nodes in the buffer.
841 */
842 length: number,
843 /**
844 The node set used in this buffer.
845 */
846 set: NodeSet);
847}
848/**
849The set of properties provided by both [`SyntaxNode`](#common.SyntaxNode)
850and [`TreeCursor`](#common.TreeCursor). Note that, if you need
851an object that is guaranteed to stay stable in the future, you
852need to use the [`node`](#common.SyntaxNodeRef.node) accessor.
853*/
854interface SyntaxNodeRef {
855 /**
856 The start position of the node.
857 */
858 readonly from: number;
859 /**
860 The end position of the node.
861 */
862 readonly to: number;
863 /**
864 The type of the node.
865 */
866 readonly type: NodeType;
867 /**
868 The name of the node (`.type.name`).
869 */
870 readonly name: string;
871 /**
872 Get the [tree](#common.Tree) that represents the current node,
873 if any. Will return null when the node is in a [tree
874 buffer](#common.TreeBuffer).
875 */
876 readonly tree: Tree | null;
877 /**
878 Retrieve a stable [syntax node](#common.SyntaxNode) at this
879 position.
880 */
881 readonly node: SyntaxNode;
882 /**
883 Test whether the node matches a given context—a sequence of
884 direct parent nodes. Empty strings in the context array act as
885 wildcards, other strings must match the ancestor node's name.
886 */
887 matchContext(context: readonly string[]): boolean;
888}
889/**
890A syntax node provides an immutable pointer to a given node in a
891tree. When iterating over large amounts of nodes, you may want to
892use a mutable [cursor](#common.TreeCursor) instead, which is more
893efficient.
894*/
895interface SyntaxNode extends SyntaxNodeRef {
896 /**
897 The node's parent node, if any.
898 */
899 parent: SyntaxNode | null;
900 /**
901 The first child, if the node has children.
902 */
903 firstChild: SyntaxNode | null;
904 /**
905 The node's last child, if available.
906 */
907 lastChild: SyntaxNode | null;
908 /**
909 The first child that ends after `pos`.
910 */
911 childAfter(pos: number): SyntaxNode | null;
912 /**
913 The last child that starts before `pos`.
914 */
915 childBefore(pos: number): SyntaxNode | null;
916 /**
917 Enter the child at the given position. If side is -1 the child
918 may end at that position, when 1 it may start there.
919
920 This will by default enter
921 [overlaid](#common.MountedTree.overlay)
922 [mounted](#common.NodeProp^mounted) trees. You can set
923 `overlays` to false to disable that.
924
925 Similarly, when `buffers` is false this will not enter
926 [buffers](#common.TreeBuffer), only [nodes](#common.Tree) (which
927 is mostly useful when looking for props, which cannot exist on
928 buffer-allocated nodes).
929 */
930 enter(pos: number, side: -1 | 0 | 1, mode?: IterMode): SyntaxNode | null;
931 /**
932 This node's next sibling, if any.
933 */
934 nextSibling: SyntaxNode | null;
935 /**
936 This node's previous sibling.
937 */
938 prevSibling: SyntaxNode | null;
939 /**
940 Read the given node prop from this node.
941 */
942 prop<T>(prop: NodeProp<T>): T | undefined;
943 /**
944 A [tree cursor](#common.TreeCursor) starting at this node.
945 */
946 cursor(mode?: IterMode): TreeCursor;
947 /**
948 Find the node around, before (if `side` is -1), or after (`side`
949 is 1) the given position. Will look in parent nodes if the
950 position is outside this node.
951 */
952 resolve(pos: number, side?: -1 | 0 | 1): SyntaxNode;
953 /**
954 Similar to `resolve`, but enter
955 [overlaid](#common.MountedTree.overlay) nodes.
956 */
957 resolveInner(pos: number, side?: -1 | 0 | 1): SyntaxNode;
958 /**
959 Move the position to the innermost node before `pos` that looks
960 like it is unfinished (meaning it ends in an error node or has a
961 child ending in an error node right at its end).
962 */
963 enterUnfinishedNodesBefore(pos: number): SyntaxNode;
964 /**
965 Get a [tree](#common.Tree) for this node. Will allocate one if it
966 points into a buffer.
967 */
968 toTree(): Tree;
969 /**
970 Get the first child of the given type (which may be a [node
971 name](#common.NodeType.name) or a [group
972 name](#common.NodeProp^group)). If `before` is non-null, only
973 return children that occur somewhere after a node with that name
974 or group. If `after` is non-null, only return children that
975 occur somewhere before a node with that name or group.
976 */
977 getChild(type: string | number, before?: string | number | null, after?: string | number | null): SyntaxNode | null;
978 /**
979 Like [`getChild`](#common.SyntaxNode.getChild), but return all
980 matching children, not just the first.
981 */
982 getChildren(type: string | number, before?: string | number | null, after?: string | number | null): SyntaxNode[];
983}
984/**
985A tree cursor object focuses on a given node in a syntax tree, and
986allows you to move to adjacent nodes.
987*/
988declare class TreeCursor implements SyntaxNodeRef {
989 /**
990 The node's type.
991 */
992 type: NodeType;
993 /**
994 Shorthand for `.type.name`.
995 */
996 get name(): string;
997 /**
998 The start source offset of this node.
999 */
1000 from: number;
1001 /**
1002 The end source offset.
1003 */
1004 to: number;
1005 private stack;
1006 private bufferNode;
1007 private yieldNode;
1008 private yieldBuf;
1009 /**
1010 Move the cursor to this node's first child. When this returns
1011 false, the node has no child, and the cursor has not been moved.
1012 */
1013 firstChild(): boolean;
1014 /**
1015 Move the cursor to this node's last child.
1016 */
1017 lastChild(): boolean;
1018 /**
1019 Move the cursor to the first child that ends after `pos`.
1020 */
1021 childAfter(pos: number): boolean;
1022 /**
1023 Move to the last child that starts before `pos`.
1024 */
1025 childBefore(pos: number): boolean;
1026 /**
1027 Move the cursor to the child around `pos`. If side is -1 the
1028 child may end at that position, when 1 it may start there. This
1029 will also enter [overlaid](#common.MountedTree.overlay)
1030 [mounted](#common.NodeProp^mounted) trees unless `overlays` is
1031 set to false.
1032 */
1033 enter(pos: number, side: -1 | 0 | 1, mode?: IterMode): boolean;
1034 /**
1035 Move to the node's parent node, if this isn't the top node.
1036 */
1037 parent(): boolean;
1038 /**
1039 Move to this node's next sibling, if any.
1040 */
1041 nextSibling(): boolean;
1042 /**
1043 Move to this node's previous sibling, if any.
1044 */
1045 prevSibling(): boolean;
1046 private atLastNode;
1047 private move;
1048 /**
1049 Move to the next node in a
1050 [pre-order](https://en.wikipedia.org/wiki/Tree_traversal#Pre-order,_NLR)
1051 traversal, going from a node to its first child or, if the
1052 current node is empty or `enter` is false, its next sibling or
1053 the next sibling of the first parent node that has one.
1054 */
1055 next(enter?: boolean): boolean;
1056 /**
1057 Move to the next node in a last-to-first pre-order traversal. A
1058 node is followed by its last child or, if it has none, its
1059 previous sibling or the previous sibling of the first parent
1060 node that has one.
1061 */
1062 prev(enter?: boolean): boolean;
1063 /**
1064 Move the cursor to the innermost node that covers `pos`. If
1065 `side` is -1, it will enter nodes that end at `pos`. If it is 1,
1066 it will enter nodes that start at `pos`.
1067 */
1068 moveTo(pos: number, side?: -1 | 0 | 1): this;
1069 /**
1070 Get a [syntax node](#common.SyntaxNode) at the cursor's current
1071 position.
1072 */
1073 get node(): SyntaxNode;
1074 /**
1075 Get the [tree](#common.Tree) that represents the current node, if
1076 any. Will return null when the node is in a [tree
1077 buffer](#common.TreeBuffer).
1078 */
1079 get tree(): Tree | null;
1080 /**
1081 Iterate over the current node and all its descendants, calling
1082 `enter` when entering a node and `leave`, if given, when leaving
1083 one. When `enter` returns `false`, any children of that node are
1084 skipped, and `leave` isn't called for it.
1085 */
1086 iterate(enter: (node: SyntaxNodeRef) => boolean | void, leave?: (node: SyntaxNodeRef) => void): void;
1087 /**
1088 Test whether the current node matches a given context—a sequence
1089 of direct parent node names. Empty strings in the context array
1090 are treated as wildcards.
1091 */
1092 matchContext(context: readonly string[]): boolean;
1093}
1094/**
1095Provides a way to associate values with pieces of trees. As long
1096as that part of the tree is reused, the associated values can be
1097retrieved from an updated tree.
1098*/
1099declare class NodeWeakMap<T> {
1100 private map;
1101 private setBuffer;
1102 private getBuffer;
1103 /**
1104 Set the value for this syntax node.
1105 */
1106 set(node: SyntaxNode, value: T): void;
1107 /**
1108 Retrieve value for this syntax node, if it exists in the map.
1109 */
1110 get(node: SyntaxNode): T | undefined;
1111 /**
1112 Set the value for the node that a cursor currently points to.
1113 */
1114 cursorSet(cursor: TreeCursor, value: T): void;
1115 /**
1116 Retrieve the value for the node that a cursor currently points
1117 to.
1118 */
1119 cursorGet(cursor: TreeCursor): T | undefined;
1120}
1121
1122/**
1123Objects returned by the function passed to
1124[`parseMixed`](#common.parseMixed) should conform to this
1125interface.
1126*/
1127interface NestedParse {
1128 /**
1129 The parser to use for the inner region.
1130 */
1131 parser: Parser;
1132 /**
1133 When this property is not given, the entire node is parsed with
1134 this parser, and it is [mounted](#common.NodeProp^mounted) as a
1135 non-overlay node, replacing its host node in tree iteration.
1136
1137 When an array of ranges is given, only those ranges are parsed,
1138 and the tree is mounted as an
1139 [overlay](#common.MountedTree.overlay).
1140
1141 When a function is given, that function will be called for
1142 descendant nodes of the target node, not including child nodes
1143 that are covered by another nested parse, to determine the
1144 overlay ranges. When it returns true, the entire descendant is
1145 included, otherwise just the range given. The mixed parser will
1146 optimize range-finding in reused nodes, which means it's a good
1147 idea to use a function here when the target node is expected to
1148 have a large, deep structure.
1149 */
1150 overlay?: readonly {
1151 from: number;
1152 to: number;
1153 }[] | ((node: SyntaxNodeRef) => {
1154 from: number;
1155 to: number;
1156 } | boolean);
1157 /**
1158 When `true`, indicates that this nested language is surrounded
1159 by some kind of bracket token, which can be used to make
1160 iteration [eagerly](#common.IterMode.EnterBracketed) enter such
1161 trees.
1162 */
1163 bracketed?: boolean;
1164}
1165/**
1166Create a parse wrapper that, after the inner parse completes,
1167scans its tree for mixed language regions with the `nest`
1168function, runs the resulting [inner parses](#common.NestedParse),
1169and then [mounts](#common.NodeProp^mounted) their results onto the
1170tree.
1171*/
1172declare function parseMixed(nest: (node: SyntaxNodeRef, input: Input) => NestedParse | null): ParseWrapper;
1173
1174export { type BufferCursor, type ChangedRange, DefaultBufferLength, type Input, IterMode, MountedTree, type NestedParse, type NodeIterator, NodeProp, type NodePropSource, NodeSet, NodeType, NodeWeakMap, type ParseWrapper, Parser, type PartialParse, type SyntaxNode, type SyntaxNodeRef, Tree, TreeBuffer, TreeCursor, TreeFragment, parseMixed };