Maps lines of text to Nodes
.
Allows you to efficiently access and manipulate the tree using Nodes or
using text ranges. Changes can be grouped for efficiency using Tree#beginUpdates
Manages the Classification process that determins node
attributes and structure (parent, child, etc) based on the node's line
of text. Use Tree#ensureClassified
to
make sure the classification process is up to date.
Methods
Nodes
- nodes() → Array.<Node>
- nodeCount() → Number
- nodeForID(id) → Node
- firstLineNode() → Node
- lastLineNode() → Node
- createNode(line, dontPreclassifiy) → Node
- evaluateNodePath(nodePath) → Array.<Node>
- nodeToLineNumber(node) → Number
- lineNumberToNode(line) → Node
- insertNodeBefore(node, referenceNode)
- appendNode(node)
- appendNodes(nodes)
- insertNodesBefore(nodes, referenceNode)
- removeNode(node)
- removeNodes(nodes)
Text
- text() → String
- textLength() → Number
- textInRange(range) → String
- setText(newText)
- replaceTextInRange(range, insertedText)
- appendText(text)
- nodeOffsetToTextOffset(node, offset) → Number
- textOffsetToNodeOffset(textOffset) → Object
Grouping Changes
- isUpdating() → Boolean
- beginUpdates()
- endUpdates()
Creating Ranges
- createRangeFromNodes(startNode, startOffset, endNode, endOffset, anchoredAtEnd) → Range
- createRangeFromLocation(location, length, anchoredAtEnd) → Range
Classification
- ensureClassified(fromNode, toNode)
Tags
- tags(onlyIncludeParsedTags) → Array.<string>
Util
Method Details
-
nodes() → {Array.<module:ft/core/node.Node>}
-
Return all nodes in tree (except root) in line order.
Returns:
- Type
- Array.<module:ft/core/node.Node>
-
nodeCount() → {Number}
-
Return number of nodes in this tree.
Returns:
- Type
- Number
-
nodeForID(id) → {module:ft/core/node.Node}
-
Return the node associated with the given node ID in this tree.
Parameters:
Name Type Description id
String Node ID
Returns:
-
firstLineNode() → {module:ft/core/node.Node}
-
Return node representing the first line in this tree.
Returns:
-
lastLineNode() → {module:ft/core/node.Node}
-
Return the node representing the last line in this tree.
Returns:
-
createNode(line, dontPreclassifiy) → {module:ft/core/node.Node}
-
Create a new node not yet inserted into the tree.
Parameters:
Name Type Argument Description line
String Node's line of text.
dontPreclassifiy
Boolean <optional>
Normally when you create a node the classification process will be run so that the node's structure information (type, etc) is up-to-date. Use this flag to disable that default behavior.
Returns:
-
evaluateNodePath(nodePath) → {Array.<module:ft/core/node.Node>}
-
Evaluate the NodePath starting with this tree's root node and return all matches.
Parameters:
Name Type Description nodePath
String Node path
- Tutorials:
-
- Tutorial: Node Paths
Returns:
- Type
- Array.<module:ft/core/node.Node>
-
nodeToLineNumber(node) → {Number}
-
Return the line number of the given node in this tree.
Parameters:
Name Type Description node
module:ft/core/node.Node Returns:
- Type
- Number
-
lineNumberToNode(line) → {module:ft/core/node.Node}
-
Return the node at the given line number.
Parameters:
Name Type Description line
Number Returns:
-
insertNodeBefore(node, referenceNode)
-
Insert the given node (and its children) before the given reference node in this tree.
Parameters:
Name Type Description node
module:ft/core/node.Node referenceNode
module:ft/core/node.Node -
appendNode(node)
-
Add the given node to the end of this tree's nodes.
Parameters:
Name Type Description node
module:ft/core/node.Node -
appendNodes(nodes)
-
Add the given nodes to the end of this tree's nodes.
Parameters:
Name Type Description nodes
Array.<module:ft/core/node.Node> -
insertNodesBefore(nodes, referenceNode)
-
Insert the given nodes (and their children) before the given reference node in this tree.
Parameters:
Name Type Description nodes
Array.<module:ft/core/node.Node> referenceNode
module:ft/core/node.Node -
removeNode(node)
-
Remove the given node from this tree's nodes.
Parameters:
Name Type Description node
module:ft/core/node.Node -
removeNodes(nodes)
-
Remove the given nodes from this tree's nodes.
Parameters:
Name Type Description nodes
Array.<module:ft/core/node.Node> -
text() → {String}
-
Tree's entire text content.
Returns:
- Type
- String
-
textLength() → {Number}
-
Length of tree's text content.
Returns:
- Type
- Number
-
textInRange(range) → {String}
-
Return tree's text content in the given range.
Parameters:
Name Type Description range
module:ft/core/range.Range Returns:
- Type
- String
-
setText(newText)
-
Replace tree's entire text content with new text.
Parameters:
Name Type Description newText
String -
replaceTextInRange(range, insertedText)
-
Replace the tree's text content in the given range.
Parameters:
Name Type Description range
module:ft/core/range.Range insertedText
String -
appendText(text)
-
Append text to the end of this tree.
Parameters:
Name Type Description text
String Text to append.
-
nodeOffsetToTextOffset(node, offset) → {Number}
-
Returns the text offset in this tree's text for the given node, and offset into that node's line of text.
Parameters:
Name Type Description node
module:ft/core/node.Node offset
Number Offset into node's line of text.
Returns:
- Type
- Number
-
textOffsetToNodeOffset(textOffset) → {Object}
-
Returns an object with node and offset properties for the given text offset into the tree's text.
Parameters:
Name Type Description textOffset
Number Offset into tree's text content.
Returns:
- node, offset
- Type
- Object
-
isUpdating() → {Boolean}
-
Return true if tree is currently updating.
Returns:
- Type
- Boolean
-
beginUpdates()
-
Call before making changes to the tree. All changes that you make between calls to
beginUpdates
andendUpdates
are grouped into a single module:ft/core/treechangedevent.TreeChangedEvent|TreeChangedEvent}. -
endUpdates()
-
Call after you've finished making changes to the tree. All changes that you make between calls to
beginUpdates
andendUpdates
are grouped into a single module:ft/core/treechangedevent.TreeChangedEvent|TreeChangedEvent}. -
createRangeFromNodes(startNode, startOffset, endNode, endOffset, anchoredAtEnd) → {module:ft/core/range.Range}
-
Create a range from a position in a start node and position in an end node.
Parameters:
Name Type Argument Default Description startNode
module:ft/core/node.Node Range start node.
startOffset
Number Offset into range start node, -1 to start at end of line.
endNode
module:ft/core/node.Node <optional>
startNode Range end node.
endOffset
Number <optional>
startOffset Offset into range end node, -1 to end at end of line.
anchoredAtEnd
Boolean <optional>
false Is range anchored at end.
Returns:
-
createRangeFromLocation(location, length, anchoredAtEnd) → {module:ft/core/range.Range}
-
Create a range from a text offset location and length of characters to include.
Parameters:
Name Type Argument Default Description location
Number Use -1 for end of document.
length
Number Use -1 for end of document.
anchoredAtEnd
Boolean <optional>
false Is range anchored at end.
Returns:
-
ensureClassified(fromNode, toNode)
-
Ensure that the classifier process has run.
For example if you've replaced some text then you might need to call this if you immediately need to get right node types and other parsed information. If you don't call this method the classifier will run in background and eventually get everything classified, but maybe only after your code has run.
Parameters:
Name Type Argument Description fromNode
module:ft/core/node.Node <optional>
From node, if undefined then will start on first line in document.
toNode
module:ft/core/node.Node <optional>
To node, if undefined then will end on last line in document.
- Tutorials:
-
tags(onlyIncludeParsedTags) → {Array.<string>}
-
Return list of the names of all tags used in this tree.
Parameters:
Name Type Argument Default Description onlyIncludeParsedTags
Boolean <optional>
false Only inclused parsed
@
style tags.Returns:
- Type
- Array.<string>
-
cleanupForCollection()
-
Used when writing specs. Removes scheduled timers and things like that.