Class NodeNavigator
Package: grammarkdown
Navigates the syntax-tree of a SourceFile.
Remarks
Nodes in Grammarkdown's syntax tree are immutable and do not maintain pointers to their parents. This can make traversing through a document somewhat difficult. The NodeNavigator class is intended to improve this process by providing an API that can traverse a syntax tree starting from the root.
A NodeNavigator focuses on a specific Node within a syntax tree, and maintains the path to that node from the root. Various methods on the navigator move the focus, allowing you to navigate to any other node within the syntax tree.
Constructors
constructor(sourceFile)
Constructs a new instance of the NodeNavigator
class
Declaration
constructor(sourceFile: SourceFile);
Parameters
constructor(other)
Constructs a new instance of the NodeNavigator
class
Declaration
constructor(other: NodeNavigator);
Parameters
Methods
clone()
Creates a copy of this NodeNavigator at the same position.
Declaration
clone(): NodeNavigator;
Returns
getArray()
Gets the containing node array of Node the navigator is currently focused on.
Declaration
getArray(): readonly Node<SyntaxKind>[] | undefined;
Returns
getDepth()
Gets the current depth within the syntax-tree of the current focus of the navigator.
Declaration
getDepth(): number;
Returns
getKind()
Gets the SyntaxKind of the Node the navigator is currently focused on.
Declaration
getKind(): SyntaxKind;
Returns
getKindString()
Gets the string representation of the SyntaxKind of the Node the navigator is currently focused on.
Declaration
getKindString(): string;
Returns
getName()
Gets the name of the property on the parent Node the navigator is currently focused on.
Declaration
getName(): string | undefined;
Returns
getNode()
Gets the Node the navigator is currently focused on.
Declaration
getNode(): Node<SyntaxKind>;
Returns
getOffset()
Gets the ordinal offset within the containing node array of Node the navigator is currently focused on.
Declaration
getOffset(): number;
Returns
getParent()
Declaration
getParent(): Node<SyntaxKind> | undefined;
Returns
getRoot()
Gets the root SourceFile node for this navigator.
Declaration
getRoot(): SourceFile;
Returns
getTextContent()
If the Node the navigator is currently focused on is a TextContentNode, returns the text
of the node; Otherwise, returns undefined
.
Declaration
getTextContent(): string | undefined;
Returns
hasAncestor(predicate)
Determines whether the focused Node has an ancestor that matches the supplied predicate.
Declaration
hasAncestor(predicate?: (ancestor: Node) => boolean): boolean;
Parameters
- predicate
- (ancestor: Node) => boolean
An optional callback used to filter the ancestors of the node.
Returns
true
if the focused Node contains an ancestor that matches the supplied predicate; otherwise, false
.
hasAncestor(kind)
Determines whether the focused Node has an ancestor that matches the supplied predicate.
Declaration
hasAncestor(kind: SyntaxKind): boolean;
Parameters
- kind
- SyntaxKind
Returns
true
if the focused Node contains an ancestor that matches the supplied predicate; otherwise, false
.
hasChildren(predicate)
Determines whether the focused Node has any children that match the supplied predicate.
Declaration
hasChildren(predicate?: (child: Node) => boolean): boolean;
Parameters
- predicate
- (child: Node) => boolean
An optional callback that can be used to filter the children of the node.
Returns
true
if the focused Node contains a child that matches the supplied predicate; otherwise, false
.
hasChildren(kind)
Determines whether the focused Node has any children with the provided SyntaxKind.
Declaration
hasChildren(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the focused Node contains a matching child; otherwise, false
.
isArray()
Returns a value indicating whether the focus of the navigator points to a Node in an array.
Declaration
isArray(): boolean;
Returns
isMatch(predicate)
Determines whether the focused Node matches the supplied predicate.
Declaration
isMatch(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the focused Node matches; otherwise, false
.
isMatch(kind)
Determines whether the focused Node matches the supplied SyntaxKind.
Declaration
isMatch(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the focused Node matches; otherwise, false
.
isSamePosition(other)
Determines whether this navigator is focused on the same location within the tree as another navigator.
Declaration
isSamePosition(other: NodeNavigator): boolean;
Parameters
Returns
true
if both navigators are focused on the same location within the tree; otherwise, false
.
isToken()
Returns a value indicating whether the focus of the navigator points to either a Token, TextContentNode, or InvalidSymbol.
Declaration
isToken(): boolean;
Returns
moveTo(other)
Moves the focus of this navigator to the same position within the syntax tree as another navigator.
Declaration
moveTo(other: NodeNavigator): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToAncestor(predicate)
Moves the focus of the navigator to the nearest ancestor matching the supplied predicate.
Declaration
moveToAncestor(predicate: (ancestor: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToAncestor(kind)
Moves the focus of the navigator to the nearest ancestor matching the supplied SyntaxKind.
Declaration
moveToAncestor(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToAncestorOrSelf(predicate)
Moves the focus of the navigator to the nearest ancestor matching the supplied predicate. If the current node matches the predicate, the focus does not change.
Declaration
moveToAncestorOrSelf(predicate: (ancestorOrSelf: Node) => boolean): boolean;
Parameters
Returns
true
if the current node matched the predicate or the navigator's focus changed; otherwise, false
.
moveToAncestorOrSelf(kind)
Moves the focus of the navigator to the nearest ancestor matching the supplied predicate. If the current node matches the predicate, the focus does not change.
Declaration
moveToAncestorOrSelf(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the current node matched the predicate or the navigator's focus changed; otherwise, false
.
moveToDeclaration()
Moves the focus of the navigator to the parent of the focused Node if that parent is either a Parameter or a Production.
Declaration
moveToDeclaration(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstChild()
Moves the focus of the navigator to the first child of the focused Node.
Declaration
moveToFirstChild(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstChild(name)
Moves the focus of the navigator to the first child of the focused Node with the provided property name.
Declaration
moveToFirstChild(name: string): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstChild(predicate)
Moves the focus of the navigator to the first child of the focused Node matching the supplied predicate.
Declaration
moveToFirstChild(predicate: (child: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstChild(kind)
Moves the focus of the navigator to the first child of the focused Node matching the provided SyntaxKind.
Declaration
moveToFirstChild(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstElement(predicate)
Moves the focus of the navigator to the first element of the containing array of the focused Node matching the supplied predicate.
Declaration
moveToFirstElement(predicate?: (element: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstElement(kind)
Moves the focus of the navigator to the first element of the containing array of the focused Node matching the provided SyntaxKind.
Declaration
moveToFirstElement(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstSibling()
Moves the focus of the navigator to the first sibling of the focused Node.
Declaration
moveToFirstSibling(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstSibling(name)
Moves the focus of the navigator to the first sibling of the focused Node with the provided property name.
Declaration
moveToFirstSibling(name: string): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstSibling(predicate)
Moves the focus of the navigator to the first sibling of the focused Node that matches the provided predicate.
Declaration
moveToFirstSibling(predicate: (sibling: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstSibling(kind)
Moves the focus of the navigator to the first sibling of the focused Node matching the provided SyntaxKind.
Declaration
moveToFirstSibling(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToFirstToken()
Moves the focus of the navigator to the first Token, TextContent or InvalidSymbol descendant (or self) of the focused Node.
Declaration
moveToFirstToken(): boolean;
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToFirstToken(predicate)
Moves the focus of the navigator to the first Token, TextContent or InvalidSymbol descendant (or self) of the focused Node.
Declaration
moveToFirstToken(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToFirstToken(kind)
Moves the focus of the navigator to the first Token, TextContent or InvalidSymbol descendant (or self) of the focused Node.
Declaration
moveToFirstToken(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToLastChild()
Moves the focus of the navigator to the last child of the focused Node.
Declaration
moveToLastChild(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastChild(name)
Moves the focus of the navigator to the last child of the focused Node with the provided property name.
Declaration
moveToLastChild(name: string): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastChild(predicate)
Moves the focus of the navigator to the last child of the focused Node matching the supplied predicate.
Declaration
moveToLastChild(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastChild(kind)
Moves the focus of the navigator to the last child of the focused Node matching the provided SyntaxKind.
Declaration
moveToLastChild(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastElement(predicate)
Moves the focus of the navigator to the last element of the containing array of the focused Node matching the supplied predicate.
Declaration
moveToLastElement(predicate?: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastElement(kind)
Moves the focus of the navigator to the last element of the containing array of the focused Node matching the provided SyntaxKind.
Declaration
moveToLastElement(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastSibling()
Moves the focus of the navigator to the last sibling of the focused Node.
Declaration
moveToLastSibling(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastSibling(name)
Moves the focus of the navigator to the last sibling of the focused Node with the provided property name.
Declaration
moveToLastSibling(name: string): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastSibling(predicate)
Moves the focus of the navigator to the last sibling of the focused Node that matches the provided predicate.
Declaration
moveToLastSibling(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastSibling(kind)
Moves the focus of the navigator to the last sibling of the focused Node matching the provided SyntaxKind.
Declaration
moveToLastSibling(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToLastToken()
Moves the focus of the navigator to the last Token, TextContent or InvalidSymbol descendant (or self) of the focused Node.
Declaration
moveToLastToken(): boolean;
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToLastToken(predicate)
Moves the focus of the navigator to the last Token, TextContent or InvalidSymbol descendant (or self) of the focused Node.
Declaration
moveToLastToken(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToLastToken(kind)
Moves the focus of the navigator to the last Token, TextContent or InvalidSymbol descendant (or self) of the focused Node.
Declaration
moveToLastToken(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToName()
Moves the focus of the navigator to the nearest Identifier.
Declaration
moveToName(): boolean;
Returns
true
if the current node is an Identifier or the navigator's focus changed; otherwise, false
.
Remarks
The "nearest Identifier" is determined using the following rules:
- If the focus or its nearest ancestor is a Parameter, move to the
name
of the Parameter. - If the focus or its nearest ancestor is an Argument, move to the
name
of the Argument. - If the focus or its nearest ancestor is a Nonterminal, move to the
name
of the Nonterminal. - If the focus or its nearest ancestor is a LexicalGoalAssertion, move to the
symbol
of the of the LexicalGoalAssertion. - If the focus or its nearest ancestor is a Define, move to the
key
of the Define. - If the focus or its nearest ancestor is a Constraints, move to the
name
of the of the first Argument of the Constraints. - If the focus is not within the
body
of a Production and the focus or its nearest ancestor is a Production, move to thename
of the Production.
moveToNextElement(predicate)
Moves the focus of the navigator to the next element in the containing array of the focused Node matching the supplied predicate.
Declaration
moveToNextElement(predicate?: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToNextElement(kind)
Moves the focus of the navigator to the next element in the containing array of the focused Node matching the provided SyntaxKind.
Declaration
moveToNextElement(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToNextSibling()
Moves the focus of the navigator to the next sibling of the focused Node.
Declaration
moveToNextSibling(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToNextSibling(name)
Moves the focus of the navigator to the next sibling of the focused Node with the provided property name.
Declaration
moveToNextSibling(name: string): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToNextSibling(predicate)
Moves the focus of the navigator to the next sibling of the focused Node that matches the provided predicate.
Declaration
moveToNextSibling(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToNextSibling(kind)
Moves the focus of the navigator to the next sibling of the focused Node matching the provided SyntaxKind.
Declaration
moveToNextSibling(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToNextToken()
Moves the focus of the navigator to the next Token, TextContent or InvalidSymbol following the focused Node in document order.
Declaration
moveToNextToken(): boolean;
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToNextToken(predicate)
Moves the focus of the navigator to the next Token, TextContent or InvalidSymbol following the focused Node in document order.
Declaration
moveToNextToken(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToNextToken(kind)
Moves the focus of the navigator to the next Token, TextContent or InvalidSymbol following the focused Node in document order.
Declaration
moveToNextToken(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToParent(predicate)
Declaration
moveToParent(predicate?: (parent: Node) => boolean): boolean;
Parameters
- predicate
- (parent: Node) => boolean
An optional callback that determines whether the focus should move to the parent node.
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToParent(kind)
Declaration
moveToParent(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPosition(position, outermost)
Moves the focus of the navigator to the Node that contains the provided [Position](xref:grammarkdown!Position:interface).
Declaration
moveToPosition(position: Position, outermost?: boolean): boolean;
Parameters
- position
- Position
The [Position](xref:grammarkdown!Position:interface) at which to focus the navigator.
- outermost
- boolean
When true
, moves to the outermost node containing the provided position. When false
or not specified, moves to the innermost node containing the provided position.
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPreviousElement(predicate)
Moves the focus of the navigator to the previous element in the containing array of the focused Node matching the supplied predicate.
Declaration
moveToPreviousElement(predicate?: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPreviousElement(kind)
Moves the focus of the navigator to the previous element in the containing array of the focused Node matching the provided SyntaxKind.
Declaration
moveToPreviousElement(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPreviousSibling()
Moves the focus of the navigator to the previous sibling of the focused Node.
Declaration
moveToPreviousSibling(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPreviousSibling(name)
Moves the focus of the navigator to the previous sibling of the focused Node with the provided property name.
Declaration
moveToPreviousSibling(name: string): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPreviousSibling(predicate)
Moves the focus of the navigator to the previous sibling of the focused Node that matches the provided predicate.
Declaration
moveToPreviousSibling(predicate: (sibling: Node) => boolean): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPreviousSibling(kind)
Moves the focus of the navigator to the previous sibling of the focused Node matching the provided SyntaxKind.
Declaration
moveToPreviousSibling(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToPreviousToken()
Moves the focus of the navigator to the previous Token, TextContent or InvalidSymbol preceding the focused Node in document order.
Declaration
moveToPreviousToken(): boolean;
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToPreviousToken(predicate)
Moves the focus of the navigator to the previous Token, TextContent or InvalidSymbol preceding the focused Node in document order.
Declaration
moveToPreviousToken(predicate: (node: Node) => boolean): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToPreviousToken(kind)
Moves the focus of the navigator to the previous Token, TextContent or InvalidSymbol preceding the focused Node in document order.
Declaration
moveToPreviousToken(kind: SyntaxKind): boolean;
Parameters
Returns
true
if the current focus is a Token, TextContent or InvalidSymbol or if the navigator's focus changed; otherwise, false
.
moveToRoot()
Moves the focus of the navigator to the root of the syntax tree.
Declaration
moveToRoot(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.
moveToSourceElement()
Moves the focus of the navigator to the parent of the focused Node if that parent is a SourceElement.
Declaration
moveToSourceElement(): boolean;
Returns
true
if the navigator's focus changed; otherwise, false
.