@lezer/common
Advanced tools
Comparing version
1118
dist/index.d.ts
@@ -1,3 +0,1115 @@ | ||
export { DefaultBufferLength, NodeProp, MountedTree, NodePropSource, NodeType, NodeSet, Tree, TreeBuffer, SyntaxNode, SyntaxNodeRef, TreeCursor, BufferCursor, NodeWeakMap, IterMode } from "./tree"; | ||
export { ChangedRange, TreeFragment, PartialParse, Parser, Input, ParseWrapper } from "./parse"; | ||
export { NestedParse, parseMixed } from "./mix"; | ||
/** | ||
The [`TreeFragment.applyChanges`](#common.TreeFragment^applyChanges) | ||
method expects changed ranges in this format. | ||
*/ | ||
interface ChangedRange { | ||
/** | ||
The start of the change in the start document | ||
*/ | ||
fromA: number; | ||
/** | ||
The end of the change in the start document | ||
*/ | ||
toA: number; | ||
/** | ||
The start of the replacement in the new document | ||
*/ | ||
fromB: number; | ||
/** | ||
The end of the replacement in the new document | ||
*/ | ||
toB: number; | ||
} | ||
/** | ||
Tree fragments are used during [incremental | ||
parsing](#common.Parser.startParse) to track parts of old trees | ||
that can be reused in a new parse. An array of fragments is used | ||
to track regions of an old tree whose nodes might be reused in new | ||
parses. Use the static | ||
[`applyChanges`](#common.TreeFragment^applyChanges) method to | ||
update fragments for document changes. | ||
*/ | ||
declare class TreeFragment { | ||
/** | ||
The start of the unchanged range pointed to by this fragment. | ||
This refers to an offset in the _updated_ document (as opposed | ||
to the original tree). | ||
*/ | ||
readonly from: number; | ||
/** | ||
The end of the unchanged range. | ||
*/ | ||
readonly to: number; | ||
/** | ||
The tree that this fragment is based on. | ||
*/ | ||
readonly tree: Tree; | ||
/** | ||
The offset between the fragment's tree and the document that | ||
this fragment can be used against. Add this when going from | ||
document to tree positions, subtract it to go from tree to | ||
document positions. | ||
*/ | ||
readonly offset: number; | ||
/** | ||
Construct a tree fragment. You'll usually want to use | ||
[`addTree`](#common.TreeFragment^addTree) and | ||
[`applyChanges`](#common.TreeFragment^applyChanges) instead of | ||
calling this directly. | ||
*/ | ||
constructor( | ||
/** | ||
The start of the unchanged range pointed to by this fragment. | ||
This refers to an offset in the _updated_ document (as opposed | ||
to the original tree). | ||
*/ | ||
from: number, | ||
/** | ||
The end of the unchanged range. | ||
*/ | ||
to: number, | ||
/** | ||
The tree that this fragment is based on. | ||
*/ | ||
tree: Tree, | ||
/** | ||
The offset between the fragment's tree and the document that | ||
this fragment can be used against. Add this when going from | ||
document to tree positions, subtract it to go from tree to | ||
document positions. | ||
*/ | ||
offset: number, openStart?: boolean, openEnd?: boolean); | ||
/** | ||
Whether the start of the fragment represents the start of a | ||
parse, or the end of a change. (In the second case, it may not | ||
be safe to reuse some nodes at the start, depending on the | ||
parsing algorithm.) | ||
*/ | ||
get openStart(): boolean; | ||
/** | ||
Whether the end of the fragment represents the end of a | ||
full-document parse, or the start of a change. | ||
*/ | ||
get openEnd(): boolean; | ||
/** | ||
Create a set of fragments from a freshly parsed tree, or update | ||
an existing set of fragments by replacing the ones that overlap | ||
with a tree with content from the new tree. When `partial` is | ||
true, the parse is treated as incomplete, and the resulting | ||
fragment has [`openEnd`](#common.TreeFragment.openEnd) set to | ||
true. | ||
*/ | ||
static addTree(tree: Tree, fragments?: readonly TreeFragment[], partial?: boolean): readonly TreeFragment[]; | ||
/** | ||
Apply a set of edits to an array of fragments, removing or | ||
splitting fragments as necessary to remove edited ranges, and | ||
adjusting offsets for fragments that moved. | ||
*/ | ||
static applyChanges(fragments: readonly TreeFragment[], changes: readonly ChangedRange[], minGap?: number): readonly TreeFragment[]; | ||
} | ||
/** | ||
Interface used to represent an in-progress parse, which can be | ||
moved forward piece-by-piece. | ||
*/ | ||
interface PartialParse { | ||
/** | ||
Advance the parse state by some amount. Will return the finished | ||
syntax tree when the parse completes. | ||
*/ | ||
advance(): Tree | null; | ||
/** | ||
The position up to which the document has been parsed. Note | ||
that, in multi-pass parsers, this will stay back until the last | ||
pass has moved past a given position. | ||
*/ | ||
readonly parsedPos: number; | ||
/** | ||
Tell the parse to not advance beyond the given position. | ||
`advance` will return a tree when the parse has reached the | ||
position. Note that, depending on the parser algorithm and the | ||
state of the parse when `stopAt` was called, that tree may | ||
contain nodes beyond the position. It is an error to call | ||
`stopAt` with a higher position than it's [current | ||
value](#common.PartialParse.stoppedAt). | ||
*/ | ||
stopAt(pos: number): void; | ||
/** | ||
Reports whether `stopAt` has been called on this parse. | ||
*/ | ||
readonly stoppedAt: number | null; | ||
} | ||
/** | ||
A superclass that parsers should extend. | ||
*/ | ||
declare abstract class Parser { | ||
/** | ||
Start a parse for a single tree. This is the method concrete | ||
parser implementations must implement. Called by `startParse`, | ||
with the optional arguments resolved. | ||
*/ | ||
abstract createParse(input: Input, fragments: readonly TreeFragment[], ranges: readonly { | ||
from: number; | ||
to: number; | ||
}[]): PartialParse; | ||
/** | ||
Start a parse, returning a [partial parse](#common.PartialParse) | ||
object. [`fragments`](#common.TreeFragment) can be passed in to | ||
make the parse incremental. | ||
By default, the entire input is parsed. You can pass `ranges`, | ||
which should be a sorted array of non-empty, non-overlapping | ||
ranges, to parse only those ranges. The tree returned in that | ||
case will start at `ranges[0].from`. | ||
*/ | ||
startParse(input: Input | string, fragments?: readonly TreeFragment[], ranges?: readonly { | ||
from: number; | ||
to: number; | ||
}[]): PartialParse; | ||
/** | ||
Run a full parse, returning the resulting tree. | ||
*/ | ||
parse(input: Input | string, fragments?: readonly TreeFragment[], ranges?: readonly { | ||
from: number; | ||
to: number; | ||
}[]): Tree; | ||
} | ||
/** | ||
This is the interface parsers use to access the document. To run | ||
Lezer directly on your own document data structure, you have to | ||
write an implementation of it. | ||
*/ | ||
interface Input { | ||
/** | ||
The length of the document. | ||
*/ | ||
readonly length: number; | ||
/** | ||
Get the chunk after the given position. The returned string | ||
should start at `from` and, if that isn't the end of the | ||
document, may be of any length greater than zero. | ||
*/ | ||
chunk(from: number): string; | ||
/** | ||
Indicates whether the chunks already end at line breaks, so that | ||
client code that wants to work by-line can avoid re-scanning | ||
them for line breaks. When this is true, the result of `chunk()` | ||
should either be a single line break, or the content between | ||
`from` and the next line break. | ||
*/ | ||
readonly lineChunks: boolean; | ||
/** | ||
Read the part of the document between the given positions. | ||
*/ | ||
read(from: number, to: number): string; | ||
} | ||
/** | ||
Parse wrapper functions are supported by some parsers to inject | ||
additional parsing logic. | ||
*/ | ||
type ParseWrapper = (inner: PartialParse, input: Input, fragments: readonly TreeFragment[], ranges: readonly { | ||
from: number; | ||
to: number; | ||
}[]) => PartialParse; | ||
/** | ||
The default maximum length of a `TreeBuffer` node. | ||
*/ | ||
declare const DefaultBufferLength = 1024; | ||
/** | ||
Each [node type](#common.NodeType) or [individual tree](#common.Tree) | ||
can have metadata associated with it in props. Instances of this | ||
class represent prop names. | ||
*/ | ||
declare class NodeProp<T> { | ||
/** | ||
Indicates whether this prop is stored per [node | ||
type](#common.NodeType) or per [tree node](#common.Tree). | ||
*/ | ||
perNode: boolean; | ||
/** | ||
A method that deserializes a value of this prop from a string. | ||
Can be used to allow a prop to be directly written in a grammar | ||
file. | ||
*/ | ||
deserialize: (str: string) => T; | ||
/** | ||
Create a new node prop type. | ||
*/ | ||
constructor(config?: { | ||
/** | ||
The [deserialize](#common.NodeProp.deserialize) function to | ||
use for this prop, used for example when directly providing | ||
the prop from a grammar file. Defaults to a function that | ||
raises an error. | ||
*/ | ||
deserialize?: (str: string) => T; | ||
/** | ||
By default, node props are stored in the [node | ||
type](#common.NodeType). It can sometimes be useful to directly | ||
store information (usually related to the parsing algorithm) | ||
in [nodes](#common.Tree) themselves. Set this to true to enable | ||
that for this prop. | ||
*/ | ||
perNode?: boolean; | ||
}); | ||
/** | ||
This is meant to be used with | ||
[`NodeSet.extend`](#common.NodeSet.extend) or | ||
[`LRParser.configure`](#lr.ParserConfig.props) to compute | ||
prop values for each node type in the set. Takes a [match | ||
object](#common.NodeType^match) or function that returns undefined | ||
if the node type doesn't get this prop, and the prop's value if | ||
it does. | ||
*/ | ||
add(match: { | ||
[selector: string]: T; | ||
} | ((type: NodeType) => T | undefined)): NodePropSource; | ||
/** | ||
Prop that is used to describe matching delimiters. For opening | ||
delimiters, this holds an array of node names (written as a | ||
space-separated string when declaring this prop in a grammar) | ||
for the node types of closing delimiters that match it. | ||
*/ | ||
static closedBy: NodeProp<readonly string[]>; | ||
/** | ||
The inverse of [`closedBy`](#common.NodeProp^closedBy). This is | ||
attached to closing delimiters, holding an array of node names | ||
of types of matching opening delimiters. | ||
*/ | ||
static openedBy: NodeProp<readonly string[]>; | ||
/** | ||
Used to assign node types to groups (for example, all node | ||
types that represent an expression could be tagged with an | ||
`"Expression"` group). | ||
*/ | ||
static group: NodeProp<readonly string[]>; | ||
/** | ||
The hash of the [context](#lr.ContextTracker.constructor) | ||
that the node was parsed in, if any. Used to limit reuse of | ||
contextual nodes. | ||
*/ | ||
static contextHash: NodeProp<number>; | ||
/** | ||
The distance beyond the end of the node that the tokenizer | ||
looked ahead for any of the tokens inside the node. (The LR | ||
parser only stores this when it is larger than 25, for | ||
efficiency reasons.) | ||
*/ | ||
static lookAhead: NodeProp<number>; | ||
/** | ||
This per-node prop is used to replace a given node, or part of a | ||
node, with another tree. This is useful to include trees from | ||
different languages in mixed-language parsers. | ||
*/ | ||
static mounted: NodeProp<MountedTree>; | ||
} | ||
/** | ||
A mounted tree, which can be [stored](#common.NodeProp^mounted) on | ||
a tree node to indicate that parts of its content are | ||
represented by another tree. | ||
*/ | ||
declare class MountedTree { | ||
/** | ||
The inner tree. | ||
*/ | ||
readonly tree: Tree; | ||
/** | ||
If this is null, this tree replaces the entire node (it will | ||
be included in the regular iteration instead of its host | ||
node). If not, only the given ranges are considered to be | ||
covered by this tree. This is used for trees that are mixed in | ||
a way that isn't strictly hierarchical. Such mounted trees are | ||
only entered by [`resolveInner`](#common.Tree.resolveInner) | ||
and [`enter`](#common.SyntaxNode.enter). | ||
*/ | ||
readonly overlay: readonly { | ||
from: number; | ||
to: number; | ||
}[] | null; | ||
/** | ||
The parser used to create this subtree. | ||
*/ | ||
readonly parser: Parser; | ||
constructor( | ||
/** | ||
The inner tree. | ||
*/ | ||
tree: Tree, | ||
/** | ||
If this is null, this tree replaces the entire node (it will | ||
be included in the regular iteration instead of its host | ||
node). If not, only the given ranges are considered to be | ||
covered by this tree. This is used for trees that are mixed in | ||
a way that isn't strictly hierarchical. Such mounted trees are | ||
only entered by [`resolveInner`](#common.Tree.resolveInner) | ||
and [`enter`](#common.SyntaxNode.enter). | ||
*/ | ||
overlay: readonly { | ||
from: number; | ||
to: number; | ||
}[] | null, | ||
/** | ||
The parser used to create this subtree. | ||
*/ | ||
parser: Parser); | ||
} | ||
/** | ||
Type returned by [`NodeProp.add`](#common.NodeProp.add). Describes | ||
whether a prop should be added to a given node type in a node set, | ||
and what value it should have. | ||
*/ | ||
type NodePropSource = (type: NodeType) => null | [NodeProp<any>, any]; | ||
/** | ||
Each node in a syntax tree has a node type associated with it. | ||
*/ | ||
declare class NodeType { | ||
/** | ||
The name of the node type. Not necessarily unique, but if the | ||
grammar was written properly, different node types with the | ||
same name within a node set should play the same semantic | ||
role. | ||
*/ | ||
readonly name: string; | ||
/** | ||
The id of this node in its set. Corresponds to the term ids | ||
used in the parser. | ||
*/ | ||
readonly id: number; | ||
/** | ||
Define a node type. | ||
*/ | ||
static define(spec: { | ||
/** | ||
The ID of the node type. When this type is used in a | ||
[set](#common.NodeSet), the ID must correspond to its index in | ||
the type array. | ||
*/ | ||
id: number; | ||
/** | ||
The name of the node type. Leave empty to define an anonymous | ||
node. | ||
*/ | ||
name?: string; | ||
/** | ||
[Node props](#common.NodeProp) to assign to the type. The value | ||
given for any given prop should correspond to the prop's type. | ||
*/ | ||
props?: readonly ([NodeProp<any>, any] | NodePropSource)[]; | ||
/** | ||
Whether this is a [top node](#common.NodeType.isTop). | ||
*/ | ||
top?: boolean; | ||
/** | ||
Whether this node counts as an [error | ||
node](#common.NodeType.isError). | ||
*/ | ||
error?: boolean; | ||
/** | ||
Whether this node is a [skipped](#common.NodeType.isSkipped) | ||
node. | ||
*/ | ||
skipped?: boolean; | ||
}): NodeType; | ||
/** | ||
Retrieves a node prop for this type. Will return `undefined` if | ||
the prop isn't present on this node. | ||
*/ | ||
prop<T>(prop: NodeProp<T>): T | undefined; | ||
/** | ||
True when this is the top node of a grammar. | ||
*/ | ||
get isTop(): boolean; | ||
/** | ||
True when this node is produced by a skip rule. | ||
*/ | ||
get isSkipped(): boolean; | ||
/** | ||
Indicates whether this is an error node. | ||
*/ | ||
get isError(): boolean; | ||
/** | ||
When true, this node type doesn't correspond to a user-declared | ||
named node, for example because it is used to cache repetition. | ||
*/ | ||
get isAnonymous(): boolean; | ||
/** | ||
Returns true when this node's name or one of its | ||
[groups](#common.NodeProp^group) matches the given string. | ||
*/ | ||
is(name: string | number): boolean; | ||
/** | ||
An empty dummy node type to use when no actual type is available. | ||
*/ | ||
static none: NodeType; | ||
/** | ||
Create a function from node types to arbitrary values by | ||
specifying an object whose property names are node or | ||
[group](#common.NodeProp^group) names. Often useful with | ||
[`NodeProp.add`](#common.NodeProp.add). You can put multiple | ||
names, separated by spaces, in a single property name to map | ||
multiple node names to a single value. | ||
*/ | ||
static match<T>(map: { | ||
[selector: string]: T; | ||
}): (node: NodeType) => T | undefined; | ||
} | ||
/** | ||
A node set holds a collection of node types. It is used to | ||
compactly represent trees by storing their type ids, rather than a | ||
full pointer to the type object, in a numeric array. Each parser | ||
[has](#lr.LRParser.nodeSet) a node set, and [tree | ||
buffers](#common.TreeBuffer) can only store collections of nodes | ||
from the same set. A set can have a maximum of 2**16 (65536) node | ||
types in it, so that the ids fit into 16-bit typed array slots. | ||
*/ | ||
declare class NodeSet { | ||
/** | ||
The node types in this set, by id. | ||
*/ | ||
readonly types: readonly NodeType[]; | ||
/** | ||
Create a set with the given types. The `id` property of each | ||
type should correspond to its position within the array. | ||
*/ | ||
constructor( | ||
/** | ||
The node types in this set, by id. | ||
*/ | ||
types: readonly NodeType[]); | ||
/** | ||
Create a copy of this set with some node properties added. The | ||
arguments to this method can be created with | ||
[`NodeProp.add`](#common.NodeProp.add). | ||
*/ | ||
extend(...props: NodePropSource[]): NodeSet; | ||
} | ||
/** | ||
Options that control iteration. Can be combined with the `|` | ||
operator to enable multiple ones. | ||
*/ | ||
declare enum IterMode { | ||
/** | ||
When enabled, iteration will only visit [`Tree`](#common.Tree) | ||
objects, not nodes packed into | ||
[`TreeBuffer`](#common.TreeBuffer)s. | ||
*/ | ||
ExcludeBuffers = 1, | ||
/** | ||
Enable this to make iteration include anonymous nodes (such as | ||
the nodes that wrap repeated grammar constructs into a balanced | ||
tree). | ||
*/ | ||
IncludeAnonymous = 2, | ||
/** | ||
By default, regular [mounted](#common.NodeProp^mounted) nodes | ||
replace their base node in iteration. Enable this to ignore them | ||
instead. | ||
*/ | ||
IgnoreMounts = 4, | ||
/** | ||
This option only applies in | ||
[`enter`](#common.SyntaxNode.enter)-style methods. It tells the | ||
library to not enter mounted overlays if one covers the given | ||
position. | ||
*/ | ||
IgnoreOverlays = 8 | ||
} | ||
/** | ||
A piece of syntax tree. There are two ways to approach these | ||
trees: the way they are actually stored in memory, and the | ||
convenient way. | ||
Syntax trees are stored as a tree of `Tree` and `TreeBuffer` | ||
objects. By packing detail information into `TreeBuffer` leaf | ||
nodes, the representation is made a lot more memory-efficient. | ||
However, when you want to actually work with tree nodes, this | ||
representation is very awkward, so most client code will want to | ||
use the [`TreeCursor`](#common.TreeCursor) or | ||
[`SyntaxNode`](#common.SyntaxNode) interface instead, which provides | ||
a view on some part of this data structure, and can be used to | ||
move around to adjacent nodes. | ||
*/ | ||
declare class Tree { | ||
/** | ||
The type of the top node. | ||
*/ | ||
readonly type: NodeType; | ||
/** | ||
This node's child nodes. | ||
*/ | ||
readonly children: readonly (Tree | TreeBuffer)[]; | ||
/** | ||
The positions (offsets relative to the start of this tree) of | ||
the children. | ||
*/ | ||
readonly positions: readonly number[]; | ||
/** | ||
The total length of this tree | ||
*/ | ||
readonly length: number; | ||
/** | ||
Construct a new tree. See also [`Tree.build`](#common.Tree^build). | ||
*/ | ||
constructor( | ||
/** | ||
The type of the top node. | ||
*/ | ||
type: NodeType, | ||
/** | ||
This node's child nodes. | ||
*/ | ||
children: readonly (Tree | TreeBuffer)[], | ||
/** | ||
The positions (offsets relative to the start of this tree) of | ||
the children. | ||
*/ | ||
positions: readonly number[], | ||
/** | ||
The total length of this tree | ||
*/ | ||
length: number, | ||
/** | ||
Per-node [node props](#common.NodeProp) to associate with this node. | ||
*/ | ||
props?: readonly [NodeProp<any> | number, any][]); | ||
/** | ||
The empty tree | ||
*/ | ||
static empty: Tree; | ||
/** | ||
Get a [tree cursor](#common.TreeCursor) positioned at the top of | ||
the tree. Mode can be used to [control](#common.IterMode) which | ||
nodes the cursor visits. | ||
*/ | ||
cursor(mode?: IterMode): TreeCursor; | ||
/** | ||
Get a [tree cursor](#common.TreeCursor) pointing into this tree | ||
at the given position and side (see | ||
[`moveTo`](#common.TreeCursor.moveTo). | ||
*/ | ||
cursorAt(pos: number, side?: -1 | 0 | 1, mode?: IterMode): TreeCursor; | ||
/** | ||
Get a [syntax node](#common.SyntaxNode) object for the top of the | ||
tree. | ||
*/ | ||
get topNode(): SyntaxNode; | ||
/** | ||
Get the [syntax node](#common.SyntaxNode) at the given position. | ||
If `side` is -1, this will move into nodes that end at the | ||
position. If 1, it'll move into nodes that start at the | ||
position. With 0, it'll only enter nodes that cover the position | ||
from both sides. | ||
Note that this will not enter | ||
[overlays](#common.MountedTree.overlay), and you often want | ||
[`resolveInner`](#common.Tree.resolveInner) instead. | ||
*/ | ||
resolve(pos: number, side?: -1 | 0 | 1): SyntaxNode; | ||
/** | ||
Like [`resolve`](#common.Tree.resolve), but will enter | ||
[overlaid](#common.MountedTree.overlay) nodes, producing a syntax node | ||
pointing into the innermost overlaid tree at the given position | ||
(with parent links going through all parent structure, including | ||
the host trees). | ||
*/ | ||
resolveInner(pos: number, side?: -1 | 0 | 1): SyntaxNode; | ||
/** | ||
Iterate over the tree and its children, calling `enter` for any | ||
node that touches the `from`/`to` region (if given) before | ||
running over such a node's children, and `leave` (if given) when | ||
leaving the node. When `enter` returns `false`, that node will | ||
not have its children iterated over (or `leave` called). | ||
*/ | ||
iterate(spec: { | ||
enter(node: SyntaxNodeRef): boolean | void; | ||
leave?(node: SyntaxNodeRef): void; | ||
from?: number; | ||
to?: number; | ||
mode?: IterMode; | ||
}): void; | ||
/** | ||
Get the value of the given [node prop](#common.NodeProp) for this | ||
node. Works with both per-node and per-type props. | ||
*/ | ||
prop<T>(prop: NodeProp<T>): T | undefined; | ||
/** | ||
Returns the node's [per-node props](#common.NodeProp.perNode) in a | ||
format that can be passed to the [`Tree`](#common.Tree) | ||
constructor. | ||
*/ | ||
get propValues(): readonly [NodeProp<any> | number, any][]; | ||
/** | ||
Balance the direct children of this tree, producing a copy of | ||
which may have children grouped into subtrees with type | ||
[`NodeType.none`](#common.NodeType^none). | ||
*/ | ||
balance(config?: { | ||
/** | ||
Function to create the newly balanced subtrees. | ||
*/ | ||
makeTree?: (children: readonly (Tree | TreeBuffer)[], positions: readonly number[], length: number) => Tree; | ||
}): Tree; | ||
/** | ||
Build a tree from a postfix-ordered buffer of node information, | ||
or a cursor over such a buffer. | ||
*/ | ||
static build(data: BuildData): Tree; | ||
} | ||
type BuildData = { | ||
/** | ||
The buffer or buffer cursor to read the node data from. | ||
When this is an array, it should contain four values for every | ||
node in the tree. | ||
- The first holds the node's type, as a node ID pointing into | ||
the given `NodeSet`. | ||
- The second holds the node's start offset. | ||
- The third the end offset. | ||
- The fourth the amount of space taken up in the array by this | ||
node and its children. Since there's four values per node, | ||
this is the total number of nodes inside this node (children | ||
and transitive children) plus one for the node itself, times | ||
four. | ||
Parent nodes should appear _after_ child nodes in the array. As | ||
an example, a node of type 10 spanning positions 0 to 4, with | ||
two children, of type 11 and 12, might look like this: | ||
[11, 0, 1, 4, 12, 2, 4, 4, 10, 0, 4, 12] | ||
*/ | ||
buffer: BufferCursor | readonly number[]; | ||
/** | ||
The node types to use. | ||
*/ | ||
nodeSet: NodeSet; | ||
/** | ||
The id of the top node type. | ||
*/ | ||
topID: number; | ||
/** | ||
The position the tree should start at. Defaults to 0. | ||
*/ | ||
start?: number; | ||
/** | ||
The position in the buffer where the function should stop | ||
reading. Defaults to 0. | ||
*/ | ||
bufferStart?: number; | ||
/** | ||
The length of the wrapping node. The end offset of the last | ||
child is used when not provided. | ||
*/ | ||
length?: number; | ||
/** | ||
The maximum buffer length to use. Defaults to | ||
[`DefaultBufferLength`](#common.DefaultBufferLength). | ||
*/ | ||
maxBufferLength?: number; | ||
/** | ||
An optional array holding reused nodes that the buffer can refer | ||
to. | ||
*/ | ||
reused?: readonly Tree[]; | ||
/** | ||
The first node type that indicates repeat constructs in this | ||
grammar. | ||
*/ | ||
minRepeatType?: number; | ||
}; | ||
/** | ||
This is used by `Tree.build` as an abstraction for iterating over | ||
a tree buffer. A cursor initially points at the very last element | ||
in the buffer. Every time `next()` is called it moves on to the | ||
previous one. | ||
*/ | ||
interface BufferCursor { | ||
/** | ||
The current buffer position (four times the number of nodes | ||
remaining). | ||
*/ | ||
pos: number; | ||
/** | ||
The node ID of the next node in the buffer. | ||
*/ | ||
id: number; | ||
/** | ||
The start position of the next node in the buffer. | ||
*/ | ||
start: number; | ||
/** | ||
The end position of the next node. | ||
*/ | ||
end: number; | ||
/** | ||
The size of the next node (the number of nodes inside, counting | ||
the node itself, times 4). | ||
*/ | ||
size: number; | ||
/** | ||
Moves `this.pos` down by 4. | ||
*/ | ||
next(): void; | ||
/** | ||
Create a copy of this cursor. | ||
*/ | ||
fork(): BufferCursor; | ||
} | ||
/** | ||
Tree buffers contain (type, start, end, endIndex) quads for each | ||
node. In such a buffer, nodes are stored in prefix order (parents | ||
before children, with the endIndex of the parent indicating which | ||
children belong to it). | ||
*/ | ||
declare class TreeBuffer { | ||
/** | ||
The buffer's content. | ||
*/ | ||
readonly buffer: Uint16Array; | ||
/** | ||
The total length of the group of nodes in the buffer. | ||
*/ | ||
readonly length: number; | ||
/** | ||
The node set used in this buffer. | ||
*/ | ||
readonly set: NodeSet; | ||
/** | ||
Create a tree buffer. | ||
*/ | ||
constructor( | ||
/** | ||
The buffer's content. | ||
*/ | ||
buffer: Uint16Array, | ||
/** | ||
The total length of the group of nodes in the buffer. | ||
*/ | ||
length: number, | ||
/** | ||
The node set used in this buffer. | ||
*/ | ||
set: NodeSet); | ||
} | ||
/** | ||
The set of properties provided by both [`SyntaxNode`](#common.SyntaxNode) | ||
and [`TreeCursor`](#common.TreeCursor). Note that, if you need | ||
an object that is guaranteed to stay stable in the future, you | ||
need to use the [`node`](#common.SyntaxNodeRef.node) accessor. | ||
*/ | ||
interface SyntaxNodeRef { | ||
/** | ||
The start position of the node. | ||
*/ | ||
readonly from: number; | ||
/** | ||
The end position of the node. | ||
*/ | ||
readonly to: number; | ||
/** | ||
The type of the node. | ||
*/ | ||
readonly type: NodeType; | ||
/** | ||
The name of the node (`.type.name`). | ||
*/ | ||
readonly name: string; | ||
/** | ||
Get the [tree](#common.Tree) that represents the current node, | ||
if any. Will return null when the node is in a [tree | ||
buffer](#common.TreeBuffer). | ||
*/ | ||
readonly tree: Tree | null; | ||
/** | ||
Retrieve a stable [syntax node](#common.SyntaxNode) at this | ||
position. | ||
*/ | ||
readonly node: SyntaxNode; | ||
/** | ||
Test whether the node matches a given context. | ||
*/ | ||
matchContext(context: readonly string[]): boolean; | ||
} | ||
/** | ||
A syntax node provides an immutable pointer to a given node in a | ||
tree. When iterating over large amounts of nodes, you may want to | ||
use a mutable [cursor](#common.TreeCursor) instead, which is more | ||
efficient. | ||
*/ | ||
interface SyntaxNode extends SyntaxNodeRef { | ||
/** | ||
The node's parent node, if any. | ||
*/ | ||
parent: SyntaxNode | null; | ||
/** | ||
The first child, if the node has children. | ||
*/ | ||
firstChild: SyntaxNode | null; | ||
/** | ||
The node's last child, if available. | ||
*/ | ||
lastChild: SyntaxNode | null; | ||
/** | ||
The first child that ends after `pos`. | ||
*/ | ||
childAfter(pos: number): SyntaxNode | null; | ||
/** | ||
The last child that starts before `pos`. | ||
*/ | ||
childBefore(pos: number): SyntaxNode | null; | ||
/** | ||
Enter the child at the given position. If side is -1 the child | ||
may end at that position, when 1 it may start there. | ||
This will by default enter | ||
[overlaid](#common.MountedTree.overlay) | ||
[mounted](#common.NodeProp^mounted) trees. You can set | ||
`overlays` to false to disable that. | ||
Similarly, when `buffers` is false this will not enter | ||
[buffers](#common.TreeBuffer), only [nodes](#common.Tree) (which | ||
is mostly useful when looking for props, which cannot exist on | ||
buffer-allocated nodes). | ||
*/ | ||
enter(pos: number, side: -1 | 0 | 1, mode?: IterMode): SyntaxNode | null; | ||
/** | ||
This node's next sibling, if any. | ||
*/ | ||
nextSibling: SyntaxNode | null; | ||
/** | ||
This node's previous sibling. | ||
*/ | ||
prevSibling: SyntaxNode | null; | ||
/** | ||
A [tree cursor](#common.TreeCursor) starting at this node. | ||
*/ | ||
cursor(mode?: IterMode): TreeCursor; | ||
/** | ||
Find the node around, before (if `side` is -1), or after (`side` | ||
is 1) the given position. Will look in parent nodes if the | ||
position is outside this node. | ||
*/ | ||
resolve(pos: number, side?: -1 | 0 | 1): SyntaxNode; | ||
/** | ||
Similar to `resolve`, but enter | ||
[overlaid](#common.MountedTree.overlay) nodes. | ||
*/ | ||
resolveInner(pos: number, side?: -1 | 0 | 1): SyntaxNode; | ||
/** | ||
Move the position to the innermost node before `pos` that looks | ||
like it is unfinished (meaning it ends in an error node or has a | ||
child ending in an error node right at its end). | ||
*/ | ||
enterUnfinishedNodesBefore(pos: number): SyntaxNode; | ||
/** | ||
Get a [tree](#common.Tree) for this node. Will allocate one if it | ||
points into a buffer. | ||
*/ | ||
toTree(): Tree; | ||
/** | ||
Get the first child of the given type (which may be a [node | ||
name](#common.NodeType.name) or a [group | ||
name](#common.NodeProp^group)). If `before` is non-null, only | ||
return children that occur somewhere after a node with that name | ||
or group. If `after` is non-null, only return children that | ||
occur somewhere before a node with that name or group. | ||
*/ | ||
getChild(type: string | number, before?: string | number | null, after?: string | number | null): SyntaxNode | null; | ||
/** | ||
Like [`getChild`](#common.SyntaxNode.getChild), but return all | ||
matching children, not just the first. | ||
*/ | ||
getChildren(type: string | number, before?: string | number | null, after?: string | number | null): SyntaxNode[]; | ||
/** | ||
Test whether the node matches a given context—a sequence of | ||
direct parent nodes. Empty strings in the context array act as | ||
wildcards, other strings must match the ancestor node's name. | ||
*/ | ||
matchContext(context: readonly string[]): boolean; | ||
} | ||
/** | ||
A tree cursor object focuses on a given node in a syntax tree, and | ||
allows you to move to adjacent nodes. | ||
*/ | ||
declare class TreeCursor implements SyntaxNodeRef { | ||
/** | ||
The node's type. | ||
*/ | ||
type: NodeType; | ||
/** | ||
Shorthand for `.type.name`. | ||
*/ | ||
get name(): string; | ||
/** | ||
The start source offset of this node. | ||
*/ | ||
from: number; | ||
/** | ||
The end source offset. | ||
*/ | ||
to: number; | ||
private stack; | ||
private bufferNode; | ||
private yieldNode; | ||
private yieldBuf; | ||
private yield; | ||
/** | ||
Move the cursor to this node's first child. When this returns | ||
false, the node has no child, and the cursor has not been moved. | ||
*/ | ||
firstChild(): boolean; | ||
/** | ||
Move the cursor to this node's last child. | ||
*/ | ||
lastChild(): boolean; | ||
/** | ||
Move the cursor to the first child that ends after `pos`. | ||
*/ | ||
childAfter(pos: number): boolean; | ||
/** | ||
Move to the last child that starts before `pos`. | ||
*/ | ||
childBefore(pos: number): boolean; | ||
/** | ||
Move the cursor to the child around `pos`. If side is -1 the | ||
child may end at that position, when 1 it may start there. This | ||
will also enter [overlaid](#common.MountedTree.overlay) | ||
[mounted](#common.NodeProp^mounted) trees unless `overlays` is | ||
set to false. | ||
*/ | ||
enter(pos: number, side: -1 | 0 | 1, mode?: IterMode): boolean; | ||
/** | ||
Move to the node's parent node, if this isn't the top node. | ||
*/ | ||
parent(): boolean; | ||
/** | ||
Move to this node's next sibling, if any. | ||
*/ | ||
nextSibling(): boolean; | ||
/** | ||
Move to this node's previous sibling, if any. | ||
*/ | ||
prevSibling(): boolean; | ||
private atLastNode; | ||
private move; | ||
/** | ||
Move to the next node in a | ||
[pre-order](https://en.wikipedia.org/wiki/Tree_traversal#Pre-order,_NLR) | ||
traversal, going from a node to its first child or, if the | ||
current node is empty or `enter` is false, its next sibling or | ||
the next sibling of the first parent node that has one. | ||
*/ | ||
next(enter?: boolean): boolean; | ||
/** | ||
Move to the next node in a last-to-first pre-order traveral. A | ||
node is followed by its last child or, if it has none, its | ||
previous sibling or the previous sibling of the first parent | ||
node that has one. | ||
*/ | ||
prev(enter?: boolean): boolean; | ||
/** | ||
Move the cursor to the innermost node that covers `pos`. If | ||
`side` is -1, it will enter nodes that end at `pos`. If it is 1, | ||
it will enter nodes that start at `pos`. | ||
*/ | ||
moveTo(pos: number, side?: -1 | 0 | 1): this; | ||
/** | ||
Get a [syntax node](#common.SyntaxNode) at the cursor's current | ||
position. | ||
*/ | ||
get node(): SyntaxNode; | ||
/** | ||
Get the [tree](#common.Tree) that represents the current node, if | ||
any. Will return null when the node is in a [tree | ||
buffer](#common.TreeBuffer). | ||
*/ | ||
get tree(): Tree | null; | ||
/** | ||
Iterate over the current node and all its descendants, calling | ||
`enter` when entering a node and `leave`, if given, when leaving | ||
one. When `enter` returns `false`, any children of that node are | ||
skipped, and `leave` isn't called for it. | ||
*/ | ||
iterate(enter: (node: SyntaxNodeRef) => boolean | void, leave?: (node: SyntaxNodeRef) => void): void; | ||
/** | ||
Test whether the current node matches a given context—a sequence | ||
of direct parent node names. Empty strings in the context array | ||
are treated as wildcards. | ||
*/ | ||
matchContext(context: readonly string[]): boolean; | ||
} | ||
/** | ||
Provides a way to associate values with pieces of trees. As long | ||
as that part of the tree is reused, the associated values can be | ||
retrieved from an updated tree. | ||
*/ | ||
declare class NodeWeakMap<T> { | ||
private map; | ||
private setBuffer; | ||
private getBuffer; | ||
/** | ||
Set the value for this syntax node. | ||
*/ | ||
set(node: SyntaxNode, value: T): void; | ||
/** | ||
Retrieve value for this syntax node, if it exists in the map. | ||
*/ | ||
get(node: SyntaxNode): T | undefined; | ||
/** | ||
Set the value for the node that a cursor currently points to. | ||
*/ | ||
cursorSet(cursor: TreeCursor, value: T): void; | ||
/** | ||
Retrieve the value for the node that a cursor currently points | ||
to. | ||
*/ | ||
cursorGet(cursor: TreeCursor): T | undefined; | ||
} | ||
/** | ||
Objects returned by the function passed to | ||
[`parseMixed`](#common.parseMixed) should conform to this | ||
interface. | ||
*/ | ||
interface NestedParse { | ||
/** | ||
The parser to use for the inner region. | ||
*/ | ||
parser: Parser; | ||
/** | ||
When this property is not given, the entire node is parsed with | ||
this parser, and it is [mounted](#common.NodeProp^mounted) as a | ||
non-overlay node, replacing its host node in tree iteration. | ||
When an array of ranges is given, only those ranges are parsed, | ||
and the tree is mounted as an | ||
[overlay](#common.MountedTree.overlay). | ||
When a function is given, that function will be called for | ||
descendant nodes of the target node, not including child nodes | ||
that are covered by another nested parse, to determine the | ||
overlay ranges. When it returns true, the entire descendant is | ||
included, otherwise just the range given. The mixed parser will | ||
optimize range-finding in reused nodes, which means it's a good | ||
idea to use a function here when the target node is expected to | ||
have a large, deep structure. | ||
*/ | ||
overlay?: readonly { | ||
from: number; | ||
to: number; | ||
}[] | ((node: SyntaxNodeRef) => { | ||
from: number; | ||
to: number; | ||
} | boolean); | ||
} | ||
/** | ||
Create a parse wrapper that, after the inner parse completes, | ||
scans its tree for mixed language regions with the `nest` | ||
function, runs the resulting [inner parses](#common.NestedParse), | ||
and then [mounts](#common.NodeProp^mounted) their results onto the | ||
tree. | ||
*/ | ||
declare function parseMixed(nest: (node: SyntaxNodeRef, input: Input) => NestedParse | null): ParseWrapper; | ||
export { BufferCursor, ChangedRange, DefaultBufferLength, Input, IterMode, MountedTree, NestedParse, NodeProp, NodePropSource, NodeSet, NodeType, NodeWeakMap, ParseWrapper, Parser, PartialParse, SyntaxNode, SyntaxNodeRef, Tree, TreeBuffer, TreeCursor, TreeFragment, parseMixed }; |
{ | ||
"name": "@lezer/common", | ||
"version": "1.0.3", | ||
"version": "1.0.4", | ||
"description": "Syntax tree data structure and parser interfaces for the lezer parser", | ||
@@ -17,10 +17,5 @@ "main": "dist/index.cjs", | ||
"ist": "^1.1.1", | ||
"rollup": "^2.52.2", | ||
"@rollup/plugin-commonjs": "^15.1.0", | ||
"@rollup/plugin-node-resolve": "^9.0.0", | ||
"rollup-plugin-typescript2": "^0.34.1", | ||
"typescript": "^4.3.4", | ||
"@marijn/buildtool": "^0.1.5", | ||
"@types/mocha": "^5.2.6", | ||
"ts-node": "^10.0.0", | ||
"mocha": "^9.0.1" | ||
"mocha": "^10.2.0" | ||
}, | ||
@@ -33,6 +28,6 @@ "files": ["dist"], | ||
"scripts": { | ||
"watch": "rollup -w -c rollup.config.js", | ||
"prepare": "rollup -c rollup.config.js", | ||
"watch": "node build.js --watch", | ||
"prepare": "node build.js", | ||
"test": "mocha" | ||
} | ||
} |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
228492
36.23%4
-55.56%5198
30.57%7
-22.22%