Snapdragon utility for creating a new AST node in custom code, such as plugins.
Install
Install with npm:
$ npm install --save snapdragon-node
Usage
With snapdragon v0.9.0 and higher you can use this.node()
to create a new Node
, whenever it makes sense.
var Node = require('snapdragon-node');
var Snapdragon = require('snapdragon');
var snapdragon = new Snapdragon();
// example usage inside a parser visitor function
snapdragon.parser.set('foo', function() {
// get the current "start" position
var pos = this.position();
// returns the match if regex matches the substring
// at the current position on `parser.input`
var match = this.match(/foo/);
if (match) {
// call "pos" on the node, to set the start and end
// positions, and return the node to push it onto the AST
// (snapdragon will push the node onto the correct
// nodes array, based on the stack)
return pos(new Node({type: 'bar', val: match[0]}));
}
});
API
<a href="index.js#L22">Node</a>
Create a new AST Node
with the given val
and type
.
Params
val
**{String|Object}**: Pass a matched substring, or an object to merge onto the node.
type
**{String}**: The node type to use when val
is a string.
returns
**{Object}**: node instance
Example
var node = new Node('*', 'Star');
var node = new Node({type: 'star', val: '*'});
<a href="index.js#L61">.isNode</a>
Returns true if the given value is a node.
Params
node
**{Object}**
returns
**{Boolean}**
Example
var Node = require('snapdragon-node');
var node = new Node({type: 'foo'});
console.log(Node.isNode(node)); //=> true
console.log(Node.isNode({})); //=> false
<a href="index.js#L80">.define</a>
Define a non-enumberable property on the node instance. Useful for adding properties that shouldn't be extended or visible during debugging.
Params
name
**{String}**
val
**{any}**
returns
**{Object}**: returns the node instance
Example
var node = new Node();
node.define('foo', 'something non-enumerable');
<a href="index.js#L100">.isEmpty</a>
Returns true if node.val
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.
returns
**{Boolean}**
Example
var node = new Node({type: 'text'});
node.isEmpty(); //=> true
node.val = 'foo';
node.isEmpty(); //=> false
<a href="index.js#L118">.push</a>
Given node foo
and node bar
, push node bar
onto foo.nodes
, and set foo
as bar.parent
.
Params
node
**{Object}**
returns
**{Number}**: Returns the length of node.nodes
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
foo.push(bar);
<a href="index.js#L140">.unshift</a>
Given node foo
and node bar
, unshift node bar
onto foo.nodes
, and set foo
as bar.parent
.
Params
node
**{Object}**
returns
**{Number}**: Returns the length of node.nodes
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
foo.unshift(bar);
<a href="index.js#L167">.pop</a>
Pop a node from node.nodes
.
returns
**{Number}**: Returns the popped node
Example
var node = new Node({type: 'foo'});
node.push(new Node({type: 'a'}));
node.push(new Node({type: 'b'}));
node.push(new Node({type: 'c'}));
node.push(new Node({type: 'd'}));
console.log(node.nodes.length);
//=> 4
node.pop();
console.log(node.nodes.length);
//=> 3
<a href="index.js#L190">.shift</a>
Shift a node from node.nodes
.
returns
**{Object}**: Returns the shifted node
Example
var node = new Node({type: 'foo'});
node.push(new Node({type: 'a'}));
node.push(new Node({type: 'b'}));
node.push(new Node({type: 'c'}));
node.push(new Node({type: 'd'}));
console.log(node.nodes.length);
//=> 4
node.shift();
console.log(node.nodes.length);
//=> 3
<a href="index.js#L205">.remove</a>
Remove node
from node.nodes
.
Params
node
**{Object}**
returns
**{Object}**: Returns the removed node.
Example
<a href="index.js#L231">.find</a>
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
var child = node.find(1); //<= index of the node to get
var child = node.find('foo'); //<= node.type of a child node
var child = node.find(/^(foo|bar)$/); //<= regex to match node.type
var child = node.find(['foo', 'bar']); //<= array of node.type(s)
<a href="index.js#L249">.isType</a>
Return true if the node is the given type
.
Params
type
**{String}**
returns
**{Boolean}**
Example
var node = new Node({type: 'bar'});
cosole.log(node.isType('foo')); // false
cosole.log(node.isType(/^(foo|bar)$/)); // true
cosole.log(node.isType(['foo', 'bar'])); // true
<a href="index.js#L270">.hasType</a>
Return true if the node.nodes
has the given type
.
Params
type
**{String}**
returns
**{Boolean}**
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
foo.push(bar);
cosole.log(foo.hasType('qux')); // false
cosole.log(foo.hasType(/^(qux|bar)$/)); // true
cosole.log(foo.hasType(['qux', 'bar'])); // true
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
foo.push(bar);
foo.push(baz);
console.log(bar.siblings.length) // 2
console.log(baz.siblings.length) // 2
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
var qux = new Node({type: 'qux'});
foo.push(bar);
foo.push(baz);
foo.unshift(qux);
console.log(bar.index) // 1
console.log(baz.index) // 2
console.log(qux.index) // 0
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
foo.push(bar);
foo.push(baz);
console.log(baz.prev.type) // 'bar'
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
foo.push(bar);
foo.push(baz);
console.log(bar.siblings.length) // 2
console.log(baz.siblings.length) // 2
returns
**{Object}**: The first node, or undefiend
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
var qux = new Node({type: 'qux'});
foo.push(bar);
foo.push(baz);
foo.push(qux);
console.log(foo.first.type) // 'bar'
returns
**{Object}**: The last node, or undefiend
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
var qux = new Node({type: 'qux'});
foo.push(bar);
foo.push(baz);
foo.push(qux);
console.log(foo.last.type) // 'qux'
returns
**{Object}**: The last node, or undefiend
Example
var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
var qux = new Node({type: 'qux'});
foo.push(bar);
foo.push(baz);
foo.push(qux);
console.log(foo.last.type) // 'qux'
Release history
Changelog entries are classified using the following labels from keep-a-changelog:
added
: for new features
changed
: for changes in existing functionality
deprecated
: for once-stable features removed in upcoming releases
removed
: for deprecated features removed in this release
fixed
: for any bug fixes
Custom labels used in this changelog:
dependencies
: bumps dependencies
housekeeping
: code re-organization, minor edits, or other changes that don't fit in one of the other categories.
[2.0.0] - 2017-05-01
Changed
.unshiftNode
was renamed to .unshift
.pushNode
was renamed to .push
.getNode
was renamed to .find
Added
[0.1.0]
First release.
About
Related projects
Contributing
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.
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:
$ npm install -g verbose/verb#dev verb-generate-readme && verb
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
Author
Jon Schlinkert
License
Copyright © 2017, Jon Schlinkert. Released under the [MIT License](LICENSE).
This file was generated by verb-generate-readme, v0.6.0, on June 25, 2017.