iLib Tree Node

Simple class to build, construct, and deconstruct an arbitrary tree
structure.

A node in the tree may have an arbitrary number of children. Each node
must have a type property and can optionally have any number of other
properties. There will also be a "children" property which will contain
any possible children, as well as a "use" and a "parent" property, so
the properties "children" and "use" and "parent" are reserved.

There is no tree structure per-se, only nodes. Any node can be considered
to be the root of a tree. Even a single node is a tree of size 1.

$3

To build a tree from scratch, you can use the following methods:

``
node.add() - add a child node to the current node
`

To create a tree, create a new Node instance and then add it as
a child to another Node instance.

Example of building a tree from scratch:

`
import Node from 'ilib-tree-node';

let parent = new Node({
type: 'x'
});

let child = new Node({
type: 'text',
value: "this is a string"
});

parent.add(child);

// add an anonymous node
parent.add(new Node({
type: 'text',
value: "another string"
}));
`

$3

To deconstruct (flatten) the tree into an array of nodes, simply use:

`
node.toArray() - deconstruct the tree into an array of nodes
`

If a node has children, the toArray method will add a start node with
the "use" property set to "start", followed
by the children within that node, followed finally by an end node with
the "use" property set to "end". This happens recursively for all the
children such that the entire tree underneath the node is flattened as
well.

The array can be reconstructed back
into a tree using the information in the "use" property. Any node that
does not have children will get added to the array as-is.

$3

To reconstruct a tree from an array of nodes, use the following static method:

`
Node.fromArray(array) - reconstruct the tree from an array of nodes
`

This method will use the "use" property to rebuild a tree of varying depths.

You may add a "use" property to any
nodes in your array, as long as the start and end nodes for any
node type are balanced and well-formed. (ie. they are properly nested
like XML open and closing tags.). If they are not well-formed, this
method will create a tree with an unexpected structure. Any array
that is a result of a toArray call is guaranteed to be well-formed.

$3

Note that this type of tree follows the unist
interface for a tree, and therefore any of the unist utilities may be
used to manipulate the tree.

To convert a regular unist tree into a ilib-tree-node tree, simply
do the following:

`
import Node from 'ilib-tree-node';
import map from 'unist-utils-map';

let ast = X; // some unist tree, probably from a parser

let treeNode = map(ast, node => new Node(node));
``

License

Copyright © 2018-2024, JEDLSoft

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and
limitations under the License.

Release Notes

See CHANGELOG.md