1 # snapdragon-node [![NPM version](https://img.shields.io/npm/v/snapdragon-node.svg?style=flat)](https://www.npmjs.com/package/snapdragon-node) [![NPM monthly downloads](https://img.shields.io/npm/dm/snapdragon-node.svg?style=flat)](https://npmjs.org/package/snapdragon-node) [![NPM total downloads](https://img.shields.io/npm/dt/snapdragon-node.svg?style=flat)](https://npmjs.org/package/snapdragon-node) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/snapdragon-node.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/snapdragon-node)
3 > Snapdragon utility for creating a new AST node in custom code, such as plugins.
7 Install with [npm](https://www.npmjs.com/):
10 $ npm install --save snapdragon-node
15 With [snapdragon](https://github.com/jonschlinkert/snapdragon) v0.9.0 and higher you can use `this.node()` to create a new `Node`, whenever it makes sense.
18 var Node = require('snapdragon-node');
19 var Snapdragon = require('snapdragon');
20 var snapdragon = new Snapdragon();
22 // example usage inside a parser visitor function
23 snapdragon.parser.set('foo', function() {
24 // get the current "start" position
25 var pos = this.position();
27 // returns the match if regex matches the substring
28 // at the current position on `parser.input`
29 var match = this.match(/foo/);
31 // call "pos" on the node, to set the start and end
32 // positions, and return the node to push it onto the AST
33 // (snapdragon will push the node onto the correct
34 // nodes array, based on the stack)
35 return pos(new Node({type: 'bar', val: match[0]}));
42 ### [Node](index.js#L22)
44 Create a new AST `Node` with the given `val` and `type`.
48 * `val` **{String|Object}**: Pass a matched substring, or an object to merge onto the node.
49 * `type` **{String}**: The node type to use when `val` is a string.
50 * `returns` **{Object}**: node instance
55 var node = new Node('*', 'Star');
56 var node = new Node({type: 'star', val: '*'});
59 ### [.isNode](index.js#L61)
61 Returns true if the given value is a node.
66 * `returns` **{Boolean}**
71 var Node = require('snapdragon-node');
72 var node = new Node({type: 'foo'});
73 console.log(Node.isNode(node)); //=> true
74 console.log(Node.isNode({})); //=> false
77 ### [.define](index.js#L80)
79 Define a non-enumberable property on the node instance. Useful for adding properties that shouldn't be extended or visible during debugging.
85 * `returns` **{Object}**: returns the node instance
90 var node = new Node();
91 node.define('foo', 'something non-enumerable');
94 ### [.isEmpty](index.js#L100)
96 Returns true if `node.val` is an empty string, or `node.nodes` does not contain any non-empty text nodes.
100 * `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.
101 * `returns` **{Boolean}**
106 var node = new Node({type: 'text'});
107 node.isEmpty(); //=> true
109 node.isEmpty(); //=> false
112 ### [.push](index.js#L118)
114 Given node `foo` and node `bar`, push node `bar` onto `foo.nodes`, and set `foo` as `bar.parent`.
118 * `node` **{Object}**
119 * `returns` **{Number}**: Returns the length of `node.nodes`
124 var foo = new Node({type: 'foo'});
125 var bar = new Node({type: 'bar'});
129 ### [.unshift](index.js#L140)
131 Given node `foo` and node `bar`, unshift node `bar` onto `foo.nodes`, and set `foo` as `bar.parent`.
135 * `node` **{Object}**
136 * `returns` **{Number}**: Returns the length of `node.nodes`
141 var foo = new Node({type: 'foo'});
142 var bar = new Node({type: 'bar'});
146 ### [.pop](index.js#L167)
148 Pop a node from `node.nodes`.
150 * `returns` **{Number}**: Returns the popped `node`
155 var node = new Node({type: 'foo'});
156 node.push(new Node({type: 'a'}));
157 node.push(new Node({type: 'b'}));
158 node.push(new Node({type: 'c'}));
159 node.push(new Node({type: 'd'}));
160 console.log(node.nodes.length);
163 console.log(node.nodes.length);
167 ### [.shift](index.js#L190)
169 Shift a node from `node.nodes`.
171 * `returns` **{Object}**: Returns the shifted `node`
176 var node = new Node({type: 'foo'});
177 node.push(new Node({type: 'a'}));
178 node.push(new Node({type: 'b'}));
179 node.push(new Node({type: 'c'}));
180 node.push(new Node({type: 'd'}));
181 console.log(node.nodes.length);
184 console.log(node.nodes.length);
188 ### [.remove](index.js#L205)
190 Remove `node` from `node.nodes`.
194 * `node` **{Object}**
195 * `returns` **{Object}**: Returns the removed node.
200 node.remove(childNode);
203 ### [.find](index.js#L231)
205 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.
209 * `type` **{String}**
210 * `returns` **{Object}**: Returns a child node or undefined.
215 var child = node.find(1); //<= index of the node to get
216 var child = node.find('foo'); //<= node.type of a child node
217 var child = node.find(/^(foo|bar)$/); //<= regex to match node.type
218 var child = node.find(['foo', 'bar']); //<= array of node.type(s)
221 ### [.isType](index.js#L249)
223 Return true if the node is the given `type`.
227 * `type` **{String}**
228 * `returns` **{Boolean}**
233 var node = new Node({type: 'bar'});
234 cosole.log(node.isType('foo')); // false
235 cosole.log(node.isType(/^(foo|bar)$/)); // true
236 cosole.log(node.isType(['foo', 'bar'])); // true
239 ### [.hasType](index.js#L270)
241 Return true if the `node.nodes` has the given `type`.
245 * `type` **{String}**
246 * `returns` **{Boolean}**
251 var foo = new Node({type: 'foo'});
252 var bar = new Node({type: 'bar'});
255 cosole.log(foo.hasType('qux')); // false
256 cosole.log(foo.hasType(/^(qux|bar)$/)); // true
257 cosole.log(foo.hasType(['qux', 'bar'])); // true
260 * `returns` **{Array}**
265 var foo = new Node({type: 'foo'});
266 var bar = new Node({type: 'bar'});
267 var baz = new Node({type: 'baz'});
271 console.log(bar.siblings.length) // 2
272 console.log(baz.siblings.length) // 2
275 * `returns` **{Number}**
280 var foo = new Node({type: 'foo'});
281 var bar = new Node({type: 'bar'});
282 var baz = new Node({type: 'baz'});
283 var qux = new Node({type: 'qux'});
288 console.log(bar.index) // 1
289 console.log(baz.index) // 2
290 console.log(qux.index) // 0
293 * `returns` **{Object}**
298 var foo = new Node({type: 'foo'});
299 var bar = new Node({type: 'bar'});
300 var baz = new Node({type: 'baz'});
304 console.log(baz.prev.type) // 'bar'
307 * `returns` **{Object}**
312 var foo = new Node({type: 'foo'});
313 var bar = new Node({type: 'bar'});
314 var baz = new Node({type: 'baz'});
318 console.log(bar.siblings.length) // 2
319 console.log(baz.siblings.length) // 2
322 * `returns` **{Object}**: The first node, or undefiend
327 var foo = new Node({type: 'foo'});
328 var bar = new Node({type: 'bar'});
329 var baz = new Node({type: 'baz'});
330 var qux = new Node({type: 'qux'});
335 console.log(foo.first.type) // 'bar'
338 * `returns` **{Object}**: The last node, or undefiend
343 var foo = new Node({type: 'foo'});
344 var bar = new Node({type: 'bar'});
345 var baz = new Node({type: 'baz'});
346 var qux = new Node({type: 'qux'});
351 console.log(foo.last.type) // 'qux'
354 * `returns` **{Object}**: The last node, or undefiend
359 var foo = new Node({type: 'foo'});
360 var bar = new Node({type: 'bar'});
361 var baz = new Node({type: 'baz'});
362 var qux = new Node({type: 'qux'});
367 console.log(foo.last.type) // 'qux'
372 Changelog entries are classified using the following labels from [keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog):
374 * `added`: for new features
375 * `changed`: for changes in existing functionality
376 * `deprecated`: for once-stable features removed in upcoming releases
377 * `removed`: for deprecated features removed in this release
378 * `fixed`: for any bug fixes
380 Custom labels used in this changelog:
382 * `dependencies`: bumps dependencies
383 * `housekeeping`: code re-organization, minor edits, or other changes that don't fit in one of the other categories.
385 ### [2.0.0] - 2017-05-01
389 * `.unshiftNode` was renamed to [.unshift](#unshift)
390 * `.pushNode` was renamed to [.push](#push)
391 * `.getNode` was renamed to [.find](#find)
396 * [.isEmpty](#isEmpty)
409 * [breakdance](https://www.npmjs.com/package/breakdance): Breakdance is a node.js library for converting HTML to markdown. Highly pluggable, flexible and easy… [more](http://breakdance.io) | [homepage](http://breakdance.io "Breakdance is a node.js library for converting HTML to markdown. Highly pluggable, flexible and easy to use. It's time for your markup to get down.")
410 * [snapdragon-capture](https://www.npmjs.com/package/snapdragon-capture): Snapdragon plugin that adds a capture method to the parser instance. | [homepage](https://github.com/jonschlinkert/snapdragon-capture "Snapdragon plugin that adds a capture method to the parser instance.")
411 * [snapdragon-cheerio](https://www.npmjs.com/package/snapdragon-cheerio): Snapdragon plugin for converting a cheerio AST to a snapdragon AST. | [homepage](https://github.com/jonschlinkert/snapdragon-cheerio "Snapdragon plugin for converting a cheerio AST to a snapdragon AST.")
412 * [snapdragon-util](https://www.npmjs.com/package/snapdragon-util): Utilities for the snapdragon parser/compiler. | [homepage](https://github.com/jonschlinkert/snapdragon-util "Utilities for the snapdragon parser/compiler.")
413 * [snapdragon](https://www.npmjs.com/package/snapdragon): Easy-to-use plugin system for creating powerful, fast and versatile parsers and compilers, with built-in source-map… [more](https://github.com/jonschlinkert/snapdragon) | [homepage](https://github.com/jonschlinkert/snapdragon "Easy-to-use plugin system for creating powerful, fast and versatile parsers and compilers, with built-in source-map support.")
417 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
419 Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.
423 _(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
425 To generate the readme, run the following command:
428 $ npm install -g verbose/verb#dev verb-generate-readme && verb
433 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:
436 $ npm install && npm test
443 * [github/jonschlinkert](https://github.com/jonschlinkert)
444 * [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
448 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
449 Released under the [MIT License](LICENSE).
453 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on June 25, 2017._