Class: Tree

ft/core/tree. Tree

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

Text

Grouping Changes

Creating Ranges

Classification

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:
Type
module:ft/core/node.Node

firstLineNode() → {module:ft/core/node.Node}

Return node representing the first line in this tree.

Returns:
Type
module:ft/core/node.Node

lastLineNode() → {module:ft/core/node.Node}

Return the node representing the last line in this tree.

Returns:
Type
module:ft/core/node.Node

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:
Type
module:ft/core/node.Node

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:
Type
module:ft/core/node.Node

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 and endUpdates 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 and endUpdates 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:
Type
module:ft/core/range.Range

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:
Type
module:ft/core/range.Range

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.