@lezer/common 1.0.2 → 1.0.4

package/dist/index.js

@@ -1,6 +1,8 @@
 // FIXME profile adding a per-Tree TreeNode cache, validating it by
 // parent pointer
-/// The default maximum length of a `TreeBuffer` node.
+/**
+The default maximum length of a `TreeBuffer` node.
+*/
 const DefaultBufferLength = 1024;
 let nextPropID = 0;
 class Range {
@@ -9,11 +11,15 @@ class Range {
         this.to = to;
     }
 }
-/// 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.
+/**
+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.
+*/
 class NodeProp {
-    /// Create a new node prop type.
+    /**
+    Create a new node prop type.
+    */
     constructor(config = {}) {
         this.id = nextPropID++;
         this.perNode = !!config.perNode;
@@ -21,13 +27,15 @@ class NodeProp {
             throw new Error("This node type doesn't define a deserialize function");
         });
     }
-    /// 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.
+    /**
+    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) {
         if (this.perNode)
             throw new RangeError("Can't add per-node props to node types");
@@ -39,48 +47,68 @@ class NodeProp {
         };
     }
 }
-/// 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.
+/**
+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.
+*/
 NodeProp.closedBy = new NodeProp({ deserialize: str => str.split(" ") });
-/// 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.
+/**
+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.
+*/
 NodeProp.openedBy = new NodeProp({ deserialize: str => str.split(" ") });
-/// Used to assign node types to groups (for example, all node
-/// types that represent an expression could be tagged with an
-/// `"Expression"` group).
+/**
+Used to assign node types to groups (for example, all node
+types that represent an expression could be tagged with an
+`"Expression"` group).
+*/
 NodeProp.group = new NodeProp({ deserialize: str => str.split(" ") });
-/// The hash of the [context](#lr.ContextTracker.constructor)
-/// that the node was parsed in, if any. Used to limit reuse of
-/// contextual nodes.
+/**
+The hash of the [context](#lr.ContextTracker.constructor)
+that the node was parsed in, if any. Used to limit reuse of
+contextual nodes.
+*/
 NodeProp.contextHash = new NodeProp({ perNode: true });
-/// 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.)
+/**
+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.)
+*/
 NodeProp.lookAhead = new NodeProp({ perNode: true });
-/// 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.
+/**
+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.
+*/
 NodeProp.mounted = new NodeProp({ perNode: true });
-/// 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.
+/**
+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.
+*/
 class MountedTree {
     constructor(
-    /// The inner tree.
+    /**
+    The inner 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).
+    /**
+    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, 
-    /// The parser used to create this subtree.
+    /**
+    The parser used to create this subtree.
+    */
     parser) {
         this.tree = tree;
         this.overlay = overlay;
@@ -88,28 +116,42 @@ class MountedTree {
     }
 }
 const noProps = Object.create(null);
-/// Each node in a syntax tree has a node type associated with it.
+/**
+Each node in a syntax tree has a node type associated with it.
+*/
 class NodeType {
-    /// @internal
+    /**
+    @internal
+    */
     constructor(
-    /// 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.
+    /**
+    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.
+    */
     name, 
-    /// @internal
+    /**
+    @internal
+    */
     props, 
-    /// The id of this node in its set. Corresponds to the term ids
-    /// used in the parser.
+    /**
+    The id of this node in its set. Corresponds to the term ids
+    used in the parser.
+    */
     id, 
-    /// @internal
+    /**
+    @internal
+    */
     flags = 0) {
         this.name = name;
         this.props = props;
         this.id = id;
         this.flags = flags;
     }
-    /// Define a node type.
+    /**
+    Define a node type.
+    */
     static define(spec) {
         let props = spec.props && spec.props.length ? Object.create(null) : noProps;
         let flags = (spec.top ? 1 /* NodeFlag.Top */ : 0) | (spec.skipped ? 2 /* NodeFlag.Skipped */ : 0) |
@@ -127,20 +169,32 @@ class NodeType {
             }
         return type;
     }
-    /// Retrieves a node prop for this type. Will return `undefined` if
-    /// the prop isn't present on this node.
+    /**
+    Retrieves a node prop for this type. Will return `undefined` if
+    the prop isn't present on this node.
+    */
     prop(prop) { return this.props[prop.id]; }
-    /// True when this is the top node of a grammar.
+    /**
+    True when this is the top node of a grammar.
+    */
     get isTop() { return (this.flags & 1 /* NodeFlag.Top */) > 0; }
-    /// True when this node is produced by a skip rule.
+    /**
+    True when this node is produced by a skip rule.
+    */
     get isSkipped() { return (this.flags & 2 /* NodeFlag.Skipped */) > 0; }
-    /// Indicates whether this is an error node.
+    /**
+    Indicates whether this is an error node.
+    */
     get isError() { return (this.flags & 4 /* NodeFlag.Error */) > 0; }
-    /// When true, this node type doesn't correspond to a user-declared
-    /// named node, for example because it is used to cache repetition.
+    /**
+    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() { return (this.flags & 8 /* NodeFlag.Anonymous */) > 0; }
-    /// Returns true when this node's name or one of its
-    /// [groups](#common.NodeProp^group) matches the given string.
+    /**
+    Returns true when this node's name or one of its
+    [groups](#common.NodeProp^group) matches the given string.
+    */
     is(name) {
         if (typeof name == 'string') {
             if (this.name == name)
@@ -150,12 +204,14 @@ class NodeType {
         }
         return this.id == name;
     }
-    /// 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.
+    /**
+    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(map) {
         let direct = Object.create(null);
         for (let prop in map)
@@ -170,29 +226,39 @@ class NodeType {
         };
     }
 }
-/// An empty dummy node type to use when no actual type is available.
+/**
+An empty dummy node type to use when no actual type is available.
+*/
 NodeType.none = new NodeType("", Object.create(null), 0, 8 /* NodeFlag.Anonymous */);
-/// 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.
+/**
+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.
+*/
 class NodeSet {
-    /// Create a set with the given types. The `id` property of each
-    /// type should correspond to its position within the array.
+    /**
+    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.
+    /**
+    The node types in this set, by id.
+    */
     types) {
         this.types = types;
         for (let i = 0; i < types.length; i++)
             if (types[i].id != i)
                 throw new RangeError("Node type ids should correspond to array positions when creating a node set");
     }
-    /// 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).
+    /**
+    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) {
         let newTypes = [];
         for (let type of this.types) {
@@ -211,61 +277,87 @@ class NodeSet {
     }
 }
 const CachedNode = new WeakMap(), CachedInnerNode = new WeakMap();
-/// Options that control iteration. Can be combined with the `|`
-/// operator to enable multiple ones.
+/**
+Options that control iteration. Can be combined with the `|`
+operator to enable multiple ones.
+*/
 var IterMode;
 (function (IterMode) {
-    /// When enabled, iteration will only visit [`Tree`](#common.Tree)
-    /// objects, not nodes packed into
-    /// [`TreeBuffer`](#common.TreeBuffer)s.
+    /**
+    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).
+    /**
+    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.
+    /**
+    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.
+    /**
+    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";
 })(IterMode || (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.
-///
-/// 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.
+/**
+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.
+*/
 class Tree {
-    /// Construct a new tree. See also [`Tree.build`](#common.Tree^build).
+    /**
+    Construct a new tree. See also [`Tree.build`](#common.Tree^build).
+    */
     constructor(
-    /// The type of the top node.
+    /**
+    The type of the top node.
+    */
     type, 
-    /// This node's child nodes.
+    /**
+    This node's child nodes.
+    */
     children, 
-    /// The positions (offsets relative to the start of this tree) of
-    /// the children.
+    /**
+    The positions (offsets relative to the start of this tree) of
+    the children.
+    */
     positions, 
-    /// The total length of this tree
+    /**
+    The total length of this tree
+    */
     length, 
-    /// Per-node [node props](#common.NodeProp) to associate with this node.
+    /**
+    Per-node [node props](#common.NodeProp) to associate with this node.
+    */
     props) {
         this.type = type;
         this.children = children;
         this.positions = positions;
         this.length = length;
-        /// @internal
+        /**
+        @internal
+        */
         this.props = null;
         if (props && props.length) {
             this.props = Object.create(null);
@@ -273,7 +365,9 @@ class Tree {
                 this.props[typeof prop == "number" ? prop : prop.id] = value;
         }
     }
-    /// @internal
+    /**
+    @internal
+    */
     toString() {
         let mounted = this.prop(NodeProp.mounted);
         if (mounted && !mounted.overlay)
@@ -291,15 +385,19 @@ 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) positioned at the top of
-    /// the tree. Mode can be used to [control](#common.IterMode) which
-    /// nodes the cursor visits.
+    /**
+    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).
+    /**
+    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);
@@ -307,51 +405,60 @@ class Tree {
         CachedNode.set(this, cursor._tree);
         return cursor;
     }
-    /// Get a [syntax node](#common.SyntaxNode) object for the top of the
-    /// tree.
+    /**
+    Get a [syntax node](#common.SyntaxNode) object for the top of the
+    tree.
+    */
     get topNode() {
         return new TreeNode(this, 0, 0, null);
     }
-    /// 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.
+    /**
+    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, side = 0) {
         let node = resolveNode(CachedNode.get(this) || this.topNode, pos, side, false);
         CachedNode.set(this, node);
         return node;
     }
-    /// 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).
+    /**
+    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, side = 0) {
         let node = resolveNode(CachedInnerNode.get(this) || this.topNode, pos, side, true);
         CachedInnerNode.set(this, node);
         return node;
     }
-    /// 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 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) {
         let { enter, leave, from = 0, to = this.length } = spec;
-        for (let c = this.cursor((spec.mode || 0) | IterMode.IncludeAnonymous);;) {
+        let mode = spec.mode || 0, anon = (mode & IterMode.IncludeAnonymous) > 0;
+        for (let c = this.cursor(mode | IterMode.IncludeAnonymous);;) {
             let entered = false;
-            if (c.from <= to && c.to >= from && (c.type.isAnonymous || enter(c) !== false)) {
+            if (c.from <= to && c.to >= from && (!anon && c.type.isAnonymous || enter(c) !== false)) {
                 if (c.firstChild())
                     continue;
                 entered = true;
             }
             for (;;) {
-                if (entered && leave && !c.type.isAnonymous)
+                if (entered && leave && (anon || !c.type.isAnonymous))
                     leave(c);
                 if (c.nextSibling())
                     break;
@@ -361,14 +468,18 @@ class Tree {
             }
         }
     }
-    /// Get the value of the given [node prop](#common.NodeProp) for this
-    /// node. Works with both per-node and per-type props.
+    /**
+    Get the value of the given [node prop](#common.NodeProp) for this
+    node. Works with both per-node and per-type props.
+    */
     prop(prop) {
         return !prop.perNode ? this.type.prop(prop) : this.props ? this.props[prop.id] : undefined;
     }
-    /// Returns the node's [per-node props](#common.NodeProp.perNode) in a
-    /// format that can be passed to the [`Tree`](#common.Tree)
-    /// constructor.
+    /**
+    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() {
         let result = [];
         if (this.props)
@@ -376,18 +487,24 @@ class Tree {
                 result.push([+id, this.props[id]]);
         return result;
     }
-    /// 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 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 = {}) {
         return this.children.length <= 8 /* Balance.BranchFactor */ ? this :
             balanceRange(NodeType.none, this.children, this.positions, 0, this.children.length, 0, this.length, (children, positions, length) => new Tree(this.type, children, positions, length, this.propValues), config.makeTree || ((children, positions, length) => new Tree(NodeType.none, children, positions, length)));
     }
-    /// Build a tree from a postfix-ordered buffer of node information,
-    /// or a cursor over such a buffer.
+    /**
+    Build a tree from a postfix-ordered buffer of node information,
+    or a cursor over such a buffer.
+    */
     static build(data) { return buildTree(data); }
 }
-/// The empty tree
+/**
+The empty tree
+*/
 Tree.empty = new Tree(NodeType.none, [], [], 0);
 class FlatBufferCursor {
     constructor(buffer, index) {
@@ -402,26 +519,40 @@ class FlatBufferCursor {
     next() { this.index -= 4; }
     fork() { return new FlatBufferCursor(this.buffer, this.index); }
 }
-/// 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).
+/**
+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).
+*/
 class TreeBuffer {
-    /// Create a tree buffer.
+    /**
+    Create a tree buffer.
+    */
     constructor(
-    /// The buffer's content.
+    /**
+    The buffer's content.
+    */
     buffer, 
-    /// The total length of the group of nodes in the buffer.
+    /**
+    The total length of the group of nodes in the buffer.
+    */
     length, 
-    /// The node set used in this buffer.
+    /**
+    The node set used in this buffer.
+    */
     set) {
         this.buffer = buffer;
         this.length = length;
         this.set = set;
     }
-    /// @internal
+    /**
+    @internal
+    */
     get type() { return NodeType.none; }
-    /// @internal
+    /**
+    @internal
+    */
     toString() {
         let result = [];
         for (let index = 0; index < this.buffer.length;) {
@@ -430,7 +561,9 @@ class TreeBuffer {
         }
         return result.join(",");
     }
-    /// @internal
+    /**
+    @internal
+    */
     childString(index) {
         let id = this.buffer[index], endIndex = this.buffer[index + 3];
         let type = this.set.types[id], result = type.name;
@@ -446,7 +579,9 @@ class TreeBuffer {
         }
         return result + "(" + children.join(",") + ")";
     }
-    /// @internal
+    /**
+    @internal
+    */
     findChild(startIndex, endIndex, dir, pos, side) {
         let { buffer } = this, pick = -1;
         for (let i = startIndex; i != endIndex; i = buffer[i + 3]) {
@@ -458,7 +593,9 @@ class TreeBuffer {
         }
         return pick;
     }
-    /// @internal
+    /**
+    @internal
+    */
     slice(startI, endI, from) {
         let b = this.buffer;
         let copy = new Uint16Array(endI - startI), len = 0;
@@ -617,7 +754,9 @@ class TreeNode {
     getChildren(type, before = null, after = null) {
         return getChildren(this, type, before, after);
     }
-    /// @internal
+    /**
+    @internal
+    */
     toString() { return this._tree.toString(); }
     get node() { return this; }
     matchContext(context) { return matchNodeContext(this, context); }
@@ -725,7 +864,9 @@ class BufferNode {
         return resolveNode(this, pos, side, true);
     }
     enterUnfinishedNodesBefore(pos) { return enterUnfinishedNodesBefore(this, pos); }
-    /// @internal
+    /**
+    @internal
+    */
     toString() { return this.context.buffer.childString(this.index); }
     getChild(type, before = null, after = null) {
         let r = getChildren(this, type, before, after);
@@ -737,20 +878,32 @@ class BufferNode {
     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.
+/**
+A tree cursor object focuses on a given node in a syntax tree, and
+allows you to move to adjacent nodes.
+*/
 class TreeCursor {
-    /// Shorthand for `.type.name`.
+    /**
+    Shorthand for `.type.name`.
+    */
     get name() { return this.type.name; }
-    /// @internal
+    /**
+    @internal
+    */
     constructor(node, 
-    /// @internal
+    /**
+    @internal
+    */
     mode = 0) {
         this.mode = mode;
-        /// @internal
+        /**
+        @internal
+        */
         this.buffer = null;
         this.stack = [];
-        /// @internal
+        /**
+        @internal
+        */
         this.index = 0;
         this.bufferNode = null;
         if (node instanceof TreeNode) {
@@ -792,11 +945,15 @@ class TreeCursor {
         this.buffer = node.context;
         return this.yieldBuf(node.index, node.type);
     }
-    /// @internal
+    /**
+    @internal
+    */
     toString() {
         return this.buffer ? this.buffer.buffer.childString(this.index) : this._tree.toString();
     }
-    /// @internal
+    /**
+    @internal
+    */
     enterChild(dir, pos, side) {
         if (!this.buffer)
             return this.yield(this._tree.nextChild(dir < 0 ? this._tree._tree.children.length - 1 : 0, dir, pos, side, this.mode));
@@ -807,26 +964,38 @@ class TreeCursor {
         this.stack.push(this.index);
         return this.yieldBuf(index);
     }
-    /// 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.
+    /**
+    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() { return this.enterChild(1, 0, 4 /* Side.DontCare */); }
-    /// Move the cursor to this node's last child.
+    /**
+    Move the cursor to this node's last child.
+    */
     lastChild() { return this.enterChild(-1, 0, 4 /* Side.DontCare */); }
-    /// Move the cursor to the first child that ends after `pos`.
+    /**
+    Move the cursor to the first child that ends after `pos`.
+    */
     childAfter(pos) { return this.enterChild(1, pos, 2 /* Side.After */); }
-    /// Move to the last child that starts before `pos`.
+    /**
+    Move to the last child that starts before `pos`.
+    */
     childBefore(pos) { return this.enterChild(-1, pos, -2 /* Side.Before */); }
-    /// 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.
+    /**
+    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, side, mode = this.mode) {
         if (!this.buffer)
             return this.yield(this._tree.enter(pos, side, mode));
         return mode & IterMode.ExcludeBuffers ? false : this.enterChild(1, pos, side);
     }
-    /// Move to the node's parent node, if this isn't the top node.
+    /**
+    Move to the node's parent node, if this isn't the top node.
+    */
     parent() {
         if (!this.buffer)
             return this.yieldNode((this.mode & IterMode.IncludeAnonymous) ? this._tree._parent : this._tree.parent);
@@ -836,7 +1005,9 @@ class TreeCursor {
         this.buffer = null;
         return this.yieldNode(parent);
     }
-    /// @internal
+    /**
+    @internal
+    */
     sibling(dir) {
         if (!this.buffer)
             return !this._tree._parent ? false
@@ -855,9 +1026,13 @@ class TreeCursor {
         }
         return d < 0 ? this.yield(this.buffer.parent.nextChild(this.buffer.index + dir, dir, 0, 4 /* Side.DontCare */, this.mode)) : false;
     }
-    /// Move to this node's next sibling, if any.
+    /**
+    Move to this node's next sibling, if any.
+    */
     nextSibling() { return this.sibling(1); }
-    /// Move to this node's previous sibling, if any.
+    /**
+    Move to this node's previous sibling, if any.
+    */
     prevSibling() { return this.sibling(-1); }
     atLastNode(dir) {
         let index, parent, { buffer } = this;
@@ -899,20 +1074,26 @@ class TreeCursor {
                 return false;
         }
     }
-    /// 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.
+    /**
+    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 = true) { return this.move(1, enter); }
-    /// 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.
+    /**
+    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 = true) { return this.move(-1, enter); }
-    /// 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`.
+    /**
+    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, side = 0) {
         // Move up to a node that actually holds the position, if possible
         while (this.from == this.to ||
@@ -924,8 +1105,10 @@ class TreeCursor {
         while (this.enterChild(1, pos, side)) { }
         return this;
     }
-    /// Get a [syntax node](#common.SyntaxNode) at the cursor's current
-    /// position.
+    /**
+    Get a [syntax node](#common.SyntaxNode) at the cursor's current
+    position.
+    */
     get node() {
         if (!this.buffer)
             return this._tree;
@@ -947,16 +1130,20 @@ class TreeCursor {
             result = new BufferNode(this.buffer, result, this.stack[i]);
         return this.bufferNode = new BufferNode(this.buffer, result, this.index);
     }
-    /// 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 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() {
         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 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;
@@ -982,9 +1169,11 @@ class TreeCursor {
             }
         }
     }
-    /// 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.
+    /**
+    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);
@@ -1259,9 +1448,11 @@ 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.
+/**
+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();
@@ -1276,57 +1467,77 @@ class NodeWeakMap {
         let inner = this.map.get(buffer);
         return inner && inner.get(index);
     }
-    /// Set the value for this syntax node.
+    /**
+    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.
+    /**
+    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.
+    /**
+    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.
+    /**
+    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
-/// 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.
+/**
+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.
+*/
 class TreeFragment {
-    /// Construct a tree fragment. You'll usually want to use
-    /// [`addTree`](#common.TreeFragment^addTree) and
-    /// [`applyChanges`](#common.TreeFragment^applyChanges) instead of
-    /// calling this directly.
+    /**
+    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).
+    /**
+    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, 
-    /// The end of the unchanged range.
+    /**
+    The end of the unchanged range.
+    */
     to, 
-    /// The tree that this fragment is based on.
+    /**
+    The tree that this fragment is based on.
+    */
     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.
+    /**
+    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, openStart = false, openEnd = false) {
         this.from = from;
         this.to = to;
@@ -1334,20 +1545,26 @@ class TreeFragment {
         this.offset = offset;
         this.open = (openStart ? 1 /* Open.Start */ : 0) | (openEnd ? 2 /* Open.End */ : 0);
     }
-    /// 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.)
+    /**
+    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() { return (this.open & 1 /* Open.Start */) > 0; }
-    /// Whether the end of the fragment represents the end of a
-    /// full-document parse, or the start of a change.
+    /**
+    Whether the end of the fragment represents the end of a
+    full-document parse, or the start of a change.
+    */
     get openEnd() { return (this.open & 2 /* Open.End */) > 0; }
-    /// 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.
+    /**
+    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, fragments = [], partial = false) {
         let result = [new TreeFragment(0, tree.length, tree, 0, false, partial)];
         for (let f of fragments)
@@ -1355,9 +1572,11 @@ class TreeFragment {
                 result.push(f);
         return result;
     }
-    /// 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.
+    /**
+    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, changes, minGap = 128) {
         if (!changes.length)
             return fragments;
@@ -1387,23 +1606,29 @@ class TreeFragment {
         return result;
     }
 }
-/// A superclass that parsers should extend.
+/**
+A superclass that parsers should extend.
+*/
 class Parser {
-    /// 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`.
+    /**
+    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, fragments, ranges) {
         if (typeof input == "string")
             input = new StringInput(input);
         ranges = !ranges ? [new Range(0, input.length)] : ranges.length ? ranges.map(r => new Range(r.from, r.to)) : [new Range(0, 0)];
         return this.createParse(input, fragments || [], ranges);
     }
-    /// Run a full parse, returning the resulting tree.
+    /**
+    Run a full parse, returning the resulting tree.
+    */
     parse(input, fragments, ranges) {
         let parse = this.startParse(input, fragments, ranges);
         for (;;) {
@@ -1423,11 +1648,13 @@ class StringInput {
     read(from, to) { return this.string.slice(from, to); }
 }
 
-/// 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.
+/**
+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.
+*/
 function parseMixed(nest) {
     return (parse, input, fragments, ranges) => new MixedParse(parse, nest, input, fragments, ranges);
 }
@@ -1438,6 +1665,8 @@ class InnerParse {
         this.overlay = overlay;
         this.target = target;
         this.ranges = ranges;
+        if (!ranges.length || ranges.some(r => r.from >= r.to))
+            throw new RangeError("Invalid inner parse ranges given: " + JSON.stringify(ranges));
     }
 }
 class ActiveOverlay {