const Node = require('snapdragon-node');// either pass on object with "type" and (optional) "val"const node1 = new Node({type: 'star', val: '*'});// or pass "val" (first) and "type" (second) as stringconst node2 = new Node('*', 'star');// both result in => Node { type: 'star', val: '*' }
Snapdragon usage
With snapdragon v0.9.0 and higher, it's recommended that you use this.node() to create a new Node inside parser handlers (instead of doing new Node()).
Snapdragon ^1.0.0
Example usage inside a snapdragon parser handler function.
const Node = require('snapdragon-node');const Token = require('snapdragon-token');// create a new AST nodeconst node = new Node({ type: 'star', value: '*' });// convert a Lexer Token into an AST Nodeconst token = new Token({ type: 'star', value: '*' });const node = new Node(token);
Node objects
AST Nodes are represented as Node objects that implement the following interface:
type{string} - A string representing the node variant type. This property is often used for classifying the purpose or nature of the node, so that parsers or compilers can determine what to do with it.
value{string|undefined} (optional) - In general, value should only be a string when node.nodes is undefined. This is not reinforced, but is considered good practice. Use a different property name to store arbitrary strings on the node when node.nodes is an array.
nodes{array|undefined} (optional) - array of child nodes
A number of useful methods and non-enumerable properties are also exposed for adding, finding and removing child nodes, etc.
Continue reading the API documentation for more details.
Create a new AST Node with the given type and value, or an object to initialize with.
Params
type{object|string}: Either an object to initialize with, or a string to be used as the node.type.
value{string|boolean}: If the first argument is a string, the second argument may be a string value to set on node.value.
clone{boolean}: When an object is passed as the first argument, pass true as the last argument to deep clone values before assigning them to the new node.
returns{Object}: node instance
Example
console.log(new Node({ type: 'star', value: '*' }));console.log(new Node('star', '*'));// both result in => Node { type: 'star', value: '*' }
Get the first child node from node.nodes that matches the given type. If type is a number, the child node at that index is returned.
Params
type{String}
returns{Object}: Returns a child node or undefined.
Example
const child = node.find(1); //<= index of the node to getconst child = node.find('foo'); //<= node.type of a child nodeconst child = node.find(/^(foo|bar)$/); //<= regex to match node.typeconst child = node.find(['foo', 'bar']); //<= array of node.type(s)
Returns true if node.nodes array contains the given node.
Params
type{String}
returns{Boolean}
Example
const foo = new Node({type: 'foo'});const bar = new Node({type: 'bar'});cosole.log(foo.has(bar)); // falsefoo.push(bar);cosole.log(foo.has(bar)); // true
Returns true if node.value is an empty string, or node.nodes does not contain any non-empty text nodes.
Params
fn{Function}: (optional) Filter function that is called on node and/or child nodes. isEmpty will return false immediately when the filter function returns false on any nodes.
Get the siblings array, or null if it doesn't exist.
returns{Array}
Example
const foo = new Node({type: 'foo'});const bar = new Node({type: 'bar'});const baz = new Node({type: 'baz'});foo.push(bar);foo.push(baz);console.log(bar.siblings.length) // 2console.log(baz.siblings.length) // 2
Get the previous node from the siblings array or null.
returns{Object}
Example
const foo = new Node({type: 'foo'});const bar = new Node({type: 'bar'});const baz = new Node({type: 'baz'});foo.push(bar);foo.push(baz);console.log(baz.prev.type) // 'bar'
Get the next element from the siblings array, or null if a next node does not exist.
returns{Object}
Example
const parent = new Node({type: 'root'});const foo = new Node({type: 'foo'});const bar = new Node({type: 'bar'});const baz = new Node({type: 'baz'});parent.push(foo);parent.push(bar);parent.push(baz);console.log(foo.next.type) // 'bar'console.log(bar.next.type) // 'baz'
const foo = new Node({type: 'foo'});const bar = new Node({type: 'bar'});const baz = new Node({type: 'baz'});const qux = new Node({type: 'qux'});foo.push(bar);foo.push(baz);foo.push(qux);console.log(foo.first.type) // 'bar'
const foo = new Node({type: 'foo'});const bar = new Node({type: 'bar'});const baz = new Node({type: 'baz'});const qux = new Node({type: 'qux'});foo.push(bar);foo.push(baz);foo.push(qux);console.log(foo.last.type) // 'qux'
node.isNode{boolean} - this value is set to true when a node is created. This can be useful in situationas as a fast alternative to using instanceof Node if you need to determine if a value is a node object.
node.size{number} - the number of child nodes that have been pushed or unshifted onto node.nodes using the node's API. This is useful for determining if nodes were added to node.nodes without using node.push() or node.unshift() (for example: if (node.nodes && node.size !== node.nodes.length))
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for advice on opening issues, pull requests, and coding standards.
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command: