@lezer/common 0.15.10 → 0.16.0

package/dist/index.cjs

@@ -214,6 +214,28 @@ class NodeSet {
     }
 }
 const CachedNode = new WeakMap(), CachedInnerNode = new WeakMap();
+/// Options that control iteration. Can be combined with the `|`
+/// operator to enable multiple ones.
+exports.IterMode = void 0;
+(function (IterMode) {
+    /// When enabled, iteration will only visit [`Tree`](#common.Tree)
+    /// objects, not nodes packed into
+    /// [`TreeBuffer`](#common.TreeBuffer)s.
+    IterMode[IterMode["ExcludeBuffers"] = 1] = "ExcludeBuffers";
+    /// Enable this to make iteration include anonymous nodes (such as
+    /// the nodes that wrap repeated grammar constructs into a balanced
+    /// tree).
+    IterMode[IterMode["IncludeAnonymous"] = 2] = "IncludeAnonymous";
+    /// By default, regular [mounted](#common.NodeProp^mounted) nodes
+    /// replace their base node in iteration. Enable this to ignore them
+    /// instead.
+    IterMode[IterMode["IgnoreMounts"] = 4] = "IgnoreMounts";
+    /// 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.
+    IterMode[IterMode["IgnoreOverlays"] = 8] = "IgnoreOverlays";
+})(exports.IterMode || (exports.IterMode = {}));
 /// 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.
@@ -272,25 +294,22 @@ class Tree {
             (/\W/.test(this.type.name) && !this.type.isError ? JSON.stringify(this.type.name) : this.type.name) +
                 (children.length ? "(" + children + ")" : "");
     }
-    /// Get a [tree cursor](#common.TreeCursor) rooted at this tree. When
-    /// `pos` is given, the cursor is [moved](#common.TreeCursor.moveTo)
-    /// to the given position and side.
-    cursor(pos, side = 0) {
-        let scope = (pos != null && CachedNode.get(this)) || this.topNode;
+    /// 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 = 0) {
+        return new TreeCursor(this.topNode, mode);
+    }
+    /// Get a [tree cursor](#common.TreeCursor) pointing into this tree
+    /// at the given position and side (see
+    /// [`moveTo`](#common.TreeCursor.moveTo).
+    cursorAt(pos, side = 0, mode = 0) {
+        let scope = CachedNode.get(this) || this.topNode;
         let cursor = new TreeCursor(scope);
-        if (pos != null) {
-            cursor.moveTo(pos, side);
-            CachedNode.set(this, cursor._tree);
-        }
+        cursor.moveTo(pos, side);
+        CachedNode.set(this, cursor._tree);
         return cursor;
     }
-    /// Get a [tree cursor](#common.TreeCursor) that, unlike regular
-    /// cursors, doesn't skip through
-    /// [anonymous](#common.NodeType.isAnonymous) nodes and doesn't
-    /// automatically enter mounted nodes.
-    fullCursor() {
-        return new TreeCursor(this.topNode, 1 /* Full */);
-    }
     /// Get a [syntax node](#common.SyntaxNode) object for the top of the
     /// tree.
     get topNode() {
@@ -323,23 +342,21 @@ class Tree {
     /// not have its children iterated over (or `leave` called).
     iterate(spec) {
         let { enter, leave, from = 0, to = this.length } = spec;
-        for (let c = this.cursor(), get = () => c.node;;) {
-            let mustLeave = false;
-            if (c.from <= to && c.to >= from && (c.type.isAnonymous || enter(c.type, c.from, c.to, get) !== false)) {
+        for (let c = this.cursor((spec.mode || 0) | exports.IterMode.IncludeAnonymous);;) {
+            let entered = false;
+            if (c.from <= to && c.to >= from && (c.type.isAnonymous || enter(c) !== false)) {
                 if (c.firstChild())
                     continue;
-                if (!c.type.isAnonymous)
-                    mustLeave = true;
+                entered = true;
             }
             for (;;) {
-                if (mustLeave && leave)
-                    leave(c.type, c.from, c.to, get);
-                mustLeave = c.type.isAnonymous;
+                if (entered && leave && !c.type.isAnonymous)
+                    leave(c);
                 if (c.nextSibling())
                     break;
                 if (!c.parent())
                     return;
-                mustLeave = true;
+                entered = true;
             }
         }
     }
@@ -490,72 +507,73 @@ function resolveNode(node, pos, side, overlays) {
             return node;
         node = parent;
     }
+    let mode = overlays ? 0 : exports.IterMode.IgnoreOverlays;
     // Must go up out of overlays when those do not overlap with pos
     if (overlays)
         for (let scan = node, parent = scan.parent; parent; scan = parent, parent = scan.parent) {
-            if (scan instanceof TreeNode && scan.index < 0 && ((_a = parent.enter(pos, side, true)) === null || _a === void 0 ? void 0 : _a.from) != scan.from)
+            if (scan instanceof TreeNode && scan.index < 0 && ((_a = parent.enter(pos, side, mode)) === null || _a === void 0 ? void 0 : _a.from) != scan.from)
                 node = parent;
         }
     for (;;) {
-        let inner = node.enter(pos, side, overlays);
+        let inner = node.enter(pos, side, mode);
         if (!inner)
             return node;
         node = inner;
     }
 }
 class TreeNode {
-    constructor(node, _from, 
+    constructor(_tree, from, 
     // Index in parent node, set to -1 if the node is not a direct child of _parent.node (overlay)
     index, _parent) {
-        this.node = node;
-        this._from = _from;
+        this._tree = _tree;
+        this.from = from;
         this.index = index;
         this._parent = _parent;
     }
-    get type() { return this.node.type; }
-    get name() { return this.node.type.name; }
-    get from() { return this._from; }
-    get to() { return this._from + this.node.length; }
+    get type() { return this._tree.type; }
+    get name() { return this._tree.type.name; }
+    get to() { return this.from + this._tree.length; }
     nextChild(i, dir, pos, side, mode = 0) {
         for (let parent = this;;) {
-            for (let { children, positions } = parent.node, e = dir > 0 ? children.length : -1; i != e; i += dir) {
-                let next = children[i], start = positions[i] + parent._from;
+            for (let { children, positions } = parent._tree, e = dir > 0 ? children.length : -1; i != e; i += dir) {
+                let next = children[i], start = positions[i] + parent.from;
                 if (!checkSide(side, pos, start, start + next.length))
                     continue;
                 if (next instanceof TreeBuffer) {
-                    if (mode & 2 /* NoEnterBuffer */)
+                    if (mode & exports.IterMode.ExcludeBuffers)
                         continue;
                     let index = next.findChild(0, next.buffer.length, dir, pos - start, side);
                     if (index > -1)
                         return new BufferNode(new BufferContext(parent, next, i, start), null, index);
                 }
-                else if ((mode & 1 /* Full */) || (!next.type.isAnonymous || hasChild(next))) {
+                else if ((mode & exports.IterMode.IncludeAnonymous) || (!next.type.isAnonymous || hasChild(next))) {
                     let mounted;
-                    if (!(mode & 1 /* Full */) && next.props && (mounted = next.prop(NodeProp.mounted)) && !mounted.overlay)
+                    if (!(mode & exports.IterMode.IgnoreMounts) &&
+                        next.props && (mounted = next.prop(NodeProp.mounted)) && !mounted.overlay)
                         return new TreeNode(mounted.tree, start, i, parent);
                     let inner = new TreeNode(next, start, i, parent);
-                    return (mode & 1 /* Full */) || !inner.type.isAnonymous ? inner
+                    return (mode & exports.IterMode.IncludeAnonymous) || !inner.type.isAnonymous ? inner
                         : inner.nextChild(dir < 0 ? next.children.length - 1 : 0, dir, pos, side);
                 }
             }
-            if ((mode & 1 /* Full */) || !parent.type.isAnonymous)
+            if ((mode & exports.IterMode.IncludeAnonymous) || !parent.type.isAnonymous)
                 return null;
             if (parent.index >= 0)
                 i = parent.index + dir;
             else
-                i = dir < 0 ? -1 : parent._parent.node.children.length;
+                i = dir < 0 ? -1 : parent._parent._tree.children.length;
             parent = parent._parent;
             if (!parent)
                 return null;
         }
     }
     get firstChild() { return this.nextChild(0, 1, 0, 4 /* DontCare */); }
-    get lastChild() { return this.nextChild(this.node.children.length - 1, -1, 0, 4 /* DontCare */); }
+    get lastChild() { return this.nextChild(this._tree.children.length - 1, -1, 0, 4 /* DontCare */); }
     childAfter(pos) { return this.nextChild(0, 1, pos, 2 /* After */); }
-    childBefore(pos) { return this.nextChild(this.node.children.length - 1, -1, pos, -2 /* Before */); }
-    enter(pos, side, overlays = true, buffers = true) {
+    childBefore(pos) { return this.nextChild(this._tree.children.length - 1, -1, pos, -2 /* Before */); }
+    enter(pos, side, mode = 0) {
         let mounted;
-        if (overlays && (mounted = this.node.prop(NodeProp.mounted)) && mounted.overlay) {
+        if (!(mode & exports.IterMode.IgnoreOverlays) && (mounted = this._tree.prop(NodeProp.mounted)) && mounted.overlay) {
             let rPos = pos - this.from;
             for (let { from, to } of mounted.overlay) {
                 if ((side > 0 ? from <= rPos : from < rPos) &&
@@ -563,7 +581,7 @@ class TreeNode {
                     return new TreeNode(mounted.tree, mounted.overlay[0].from + this.from, -1, this);
             }
         }
-        return this.nextChild(0, 1, pos, side, buffers ? 0 : 2 /* NoEnterBuffer */);
+        return this.nextChild(0, 1, pos, side, mode);
     }
     nextSignificantParent() {
         let val = this;
@@ -580,9 +598,9 @@ class TreeNode {
     get prevSibling() {
         return this._parent && this.index >= 0 ? this._parent.nextChild(this.index - 1, -1, 0, 4 /* DontCare */) : null;
     }
-    get cursor() { return new TreeCursor(this); }
-    get tree() { return this.node; }
-    toTree() { return this.node; }
+    cursor(mode = 0) { return new TreeCursor(this, mode); }
+    get tree() { return this._tree; }
+    toTree() { return this._tree; }
     resolve(pos, side = 0) {
         return resolveNode(this, pos, side, false);
     }
@@ -598,10 +616,12 @@ class TreeNode {
         return getChildren(this, type, before, after);
     }
     /// @internal
-    toString() { return this.node.toString(); }
+    toString() { return this._tree.toString(); }
+    get node() { return this; }
+    matchContext(context) { return matchNodeContext(this, context); }
 }
 function getChildren(node, type, before, after) {
-    let cur = node.cursor, result = [];
+    let cur = node.cursor(), result = [];
     if (!cur.firstChild())
         return result;
     if (before != null)
@@ -617,6 +637,18 @@ function getChildren(node, type, before, after) {
             return after == null ? result : [];
     }
 }
+function matchNodeContext(node, context, i = context.length - 1) {
+    for (let p = node.parent; i >= 0; p = p.parent) {
+        if (!p)
+            return false;
+        if (!p.type.isAnonymous) {
+            if (context[i] && context[i] != p.name)
+                return false;
+            i--;
+        }
+    }
+    return true;
+}
 class BufferContext {
     constructor(parent, buffer, index, start) {
         this.parent = parent;
@@ -644,8 +676,8 @@ class BufferNode {
     get lastChild() { return this.child(-1, 0, 4 /* DontCare */); }
     childAfter(pos) { return this.child(1, pos, 2 /* After */); }
     childBefore(pos) { return this.child(-1, pos, -2 /* Before */); }
-    enter(pos, side, overlays, buffers = true) {
-        if (!buffers)
+    enter(pos, side, mode = 0) {
+        if (mode & exports.IterMode.ExcludeBuffers)
             return null;
         let { buffer } = this.context;
         let index = buffer.findChild(this.index + 4, buffer.buffer[this.index + 3], side > 0 ? 1 : -1, pos - this.context.start, side);
@@ -671,7 +703,7 @@ class BufferNode {
             return this.externalSibling(-1);
         return new BufferNode(this.context, this._parent, buffer.findChild(parentStart, this.index, -1, 0, 4 /* DontCare */));
     }
-    get cursor() { return new TreeCursor(this); }
+    cursor(mode = 0) { return new TreeCursor(this, mode); }
     get tree() { return null; }
     toTree() {
         let children = [], positions = [];
@@ -700,6 +732,8 @@ class BufferNode {
     getChildren(type, before = null, after = null) {
         return getChildren(this, type, before, after);
     }
+    get node() { return this; }
+    matchContext(context) { return matchNodeContext(this, context); }
 }
 /// A tree cursor object focuses on a given node in a syntax tree, and
 /// allows you to move to adjacent nodes.
@@ -709,8 +743,10 @@ class TreeCursor {
     /// @internal
     mode = 0) {
         this.mode = mode;
+        /// @internal
         this.buffer = null;
         this.stack = [];
+        /// @internal
         this.index = 0;
         this.bufferNode = null;
         if (node instanceof TreeNode) {
@@ -761,7 +797,7 @@ class TreeCursor {
     /// @internal
     enterChild(dir, pos, side) {
         if (!this.buffer)
-            return this.yield(this._tree.nextChild(dir < 0 ? this._tree.node.children.length - 1 : 0, dir, pos, side, this.mode));
+            return this.yield(this._tree.nextChild(dir < 0 ? this._tree._tree.children.length - 1 : 0, dir, pos, side, this.mode));
         let { buffer } = this.buffer;
         let index = buffer.findChild(this.index + 4, buffer.buffer[this.index + 3], dir, pos - this.buffer.start, side);
         if (index < 0)
@@ -783,18 +819,18 @@ class TreeCursor {
     /// will also enter [overlaid](#common.MountedTree.overlay)
     /// [mounted](#common.NodeProp^mounted) trees unless `overlays` is
     /// set to false.
-    enter(pos, side, overlays = true, buffers = true) {
+    enter(pos, side, mode = this.mode) {
         if (!this.buffer)
-            return this.yield(this._tree.enter(pos, side, overlays && !(this.mode & 1 /* Full */), buffers));
-        return buffers ? this.enterChild(1, pos, side) : false;
+            return this.yield(this._tree.enter(pos, side, mode));
+        return mode & exports.IterMode.ExcludeBuffers ? false : this.enterChild(1, pos, side);
     }
     /// Move to the node's parent node, if this isn't the top node.
     parent() {
         if (!this.buffer)
-            return this.yieldNode((this.mode & 1 /* Full */) ? this._tree._parent : this._tree.parent);
+            return this.yieldNode((this.mode & exports.IterMode.IncludeAnonymous) ? this._tree._parent : this._tree.parent);
         if (this.stack.length)
             return this.yieldBuf(this.stack.pop());
-        let parent = (this.mode & 1 /* Full */) ? this.buffer.parent : this.buffer.parent.nextSignificantParent();
+        let parent = (this.mode & exports.IterMode.IncludeAnonymous) ? this.buffer.parent : this.buffer.parent.nextSignificantParent();
         this.buffer = null;
         return this.yieldNode(parent);
     }
@@ -840,9 +876,12 @@ class TreeCursor {
         }
         for (; parent; { index, _parent: parent } = parent) {
             if (index > -1)
-                for (let i = index + dir, e = dir < 0 ? -1 : parent.node.children.length; i != e; i += dir) {
-                    let child = parent.node.children[i];
-                    if ((this.mode & 1 /* Full */) || child instanceof TreeBuffer || !child.type.isAnonymous || hasChild(child))
+                for (let i = index + dir, e = dir < 0 ? -1 : parent._tree.children.length; i != e; i += dir) {
+                    let child = parent._tree.children[i];
+                    if ((this.mode & exports.IterMode.IncludeAnonymous) ||
+                        child instanceof TreeBuffer ||
+                        !child.type.isAnonymous ||
+                        hasChild(child))
                         return false;
                 }
         }
@@ -910,7 +949,55 @@ class TreeCursor {
     /// any. Will return null when the node is in a [tree
     /// buffer](#common.TreeBuffer).
     get tree() {
-        return this.buffer ? null : this._tree.node;
+        return this.buffer ? null : this._tree._tree;
+    }
+    /// 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, leave) {
+        for (let depth = 0;;) {
+            let mustLeave = false;
+            if (this.type.isAnonymous || enter(this) !== false) {
+                if (this.firstChild()) {
+                    depth++;
+                    continue;
+                }
+                if (!this.type.isAnonymous)
+                    mustLeave = true;
+            }
+            for (;;) {
+                if (mustLeave && leave)
+                    leave(this);
+                mustLeave = this.type.isAnonymous;
+                if (this.nextSibling())
+                    break;
+                if (!depth)
+                    return;
+                this.parent();
+                depth--;
+                mustLeave = true;
+            }
+        }
+    }
+    /// 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) {
+        if (!this.buffer)
+            return matchNodeContext(this.node, context);
+        let { buffer } = this.buffer, { types } = buffer.set;
+        for (let i = context.length - 1, d = this.stack.length - 1; i >= 0; d--) {
+            if (d < 0)
+                return matchNodeContext(this.node, context, i);
+            let type = types[buffer.buffer[this.stack[d]]];
+            if (!type.isAnonymous) {
+                if (context[i] && context[i] != type.name)
+                    return false;
+                i--;
+            }
+        }
+        return true;
     }
 }
 function hasChild(tree) {
@@ -1170,6 +1257,48 @@ mkTree) {
     divide(children, positions, from, to, 0);
     return (mkTop || mkTree)(localChildren, localPositions, length);
 }
+/// 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.
+class NodeWeakMap {
+    constructor() {
+        this.map = new WeakMap();
+    }
+    setBuffer(buffer, index, value) {
+        let inner = this.map.get(buffer);
+        if (!inner)
+            this.map.set(buffer, inner = new Map);
+        inner.set(index, value);
+    }
+    getBuffer(buffer, index) {
+        let inner = this.map.get(buffer);
+        return inner && inner.get(index);
+    }
+    /// Set the value for this syntax node.
+    set(node, value) {
+        if (node instanceof BufferNode)
+            this.setBuffer(node.context.buffer, node.index, value);
+        else if (node instanceof TreeNode)
+            this.map.set(node.tree, value);
+    }
+    /// Retrieve value for this syntax node, if it exists in the map.
+    get(node) {
+        return node instanceof BufferNode ? this.getBuffer(node.context.buffer, node.index)
+            : node instanceof TreeNode ? this.map.get(node.tree) : undefined;
+    }
+    /// Set the value for the node that a cursor currently points to.
+    cursorSet(cursor, value) {
+        if (cursor.buffer)
+            this.setBuffer(cursor.buffer.buffer, cursor.index, value);
+        else
+            this.map.set(cursor.tree, value);
+    }
+    /// Retrieve the value for the node that a cursor currently points
+    /// to.
+    cursorGet(cursor) {
+        return cursor.buffer ? this.getBuffer(cursor.buffer.buffer, cursor.index) : this.map.get(cursor.tree);
+    }
+}
 
 /// Tree fragments are used during [incremental
 /// parsing](#common.Parser.startParse) to track parts of old trees
@@ -1390,7 +1519,7 @@ class MixedParse {
         let fragmentCursor = new FragmentCursor(this.fragments);
         let overlay = null;
         let covered = null;
-        let cursor = new TreeCursor(new TreeNode(this.baseTree, this.ranges[0].from, 0, null), 1 /* Full */);
+        let cursor = new TreeCursor(new TreeNode(this.baseTree, this.ranges[0].from, 0, null), exports.IterMode.IncludeAnonymous | exports.IterMode.IgnoreMounts);
         scan: for (let nest, isCovered; this.stoppedAt == null || cursor.from < this.stoppedAt;) {
             let enter = true, range;
             if (fragmentCursor.hasNode(cursor)) {
@@ -1399,7 +1528,7 @@ class MixedParse {
                     if (match)
                         for (let r of match.mount.overlay) {
                             let from = r.from + match.pos, to = r.to + match.pos;
-                            if (from >= cursor.from && to <= cursor.to)
+                            if (from >= cursor.from && to <= cursor.to && !overlay.ranges.some(r => r.from < to && r.to > from))
                                 overlay.ranges.push({ from, to });
                         }
                 }
@@ -1496,20 +1625,20 @@ function materialize(cursor) {
     let buf = base.children[i], b = buf.buffer;
     // Split a level in the buffer, putting the nodes before and after
     // the child that contains `node` into new buffers.
-    function split(startI, endI, type, innerOffset) {
+    function split(startI, endI, type, innerOffset, length) {
         let i = startI;
         while (b[i + 2] + off <= node.from)
             i = b[i + 3];
         let children = [], positions = [];
         sliceBuf(buf, startI, i, children, positions, innerOffset);
-        let isTarget = b[i + 1] + off == node.from && b[i + 2] + off == node.to && b[i] == node.type.id;
-        children.push(isTarget ? node.toTree() : split(i + 4, b[i + 3], buf.set.types[b[i]], b[i + 1]));
-        positions.push(b[i + 1] - innerOffset);
+        let from = b[i + 1], to = b[i + 2];
+        let isTarget = from + off == node.from && to + off == node.to && b[i] == node.type.id;
+        children.push(isTarget ? node.toTree() : split(i + 4, b[i + 3], buf.set.types[b[i]], from, to - from));
+        positions.push(from - innerOffset);
         sliceBuf(buf, b[i + 3], endI, children, positions, innerOffset);
-        let last = children.length - 1;
-        return new Tree(type, children, positions, positions[last] + children[last].length);
+        return new Tree(type, children, positions, length);
     }
-    base.children[i] = split(0, b.length, NodeType.none, 0);
+    base.children[i] = split(0, b.length, NodeType.none, 0, buf.length);
     // Move the cursor back to the target node
     for (let d = 0; d <= depth; d++)
         cursor.childAfter(node.from);
@@ -1518,13 +1647,13 @@ class StructureCursor {
     constructor(root, offset) {
         this.offset = offset;
         this.done = false;
-        this.cursor = root.fullCursor();
+        this.cursor = root.cursor(exports.IterMode.IncludeAnonymous | exports.IterMode.IgnoreMounts);
     }
     // Move to the first node (in pre-order) that starts at or after `pos`.
     moveTo(pos) {
         let { cursor } = this, p = pos - this.offset;
         while (!this.done && cursor.from < p) {
-            if (cursor.to >= pos && cursor.enter(p, 1, false, false)) ;
+            if (cursor.to >= pos && cursor.enter(p, 1, exports.IterMode.IgnoreOverlays | exports.IterMode.ExcludeBuffers)) ;
             else if (!cursor.next(false))
                 this.done = true;
         }
@@ -1693,6 +1822,7 @@ exports.MountedTree = MountedTree;
 exports.NodeProp = NodeProp;
 exports.NodeSet = NodeSet;
 exports.NodeType = NodeType;
+exports.NodeWeakMap = NodeWeakMap;
 exports.Parser = Parser;
 exports.Tree = Tree;
 exports.TreeBuffer = TreeBuffer;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { DefaultBufferLength, NodeProp, MountedTree, NodePropSource, NodeType, NodeSet, Tree, TreeBuffer, SyntaxNode, TreeCursor, BufferCursor } from "./tree";
+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";