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)
2
3> Snapdragon utility for creating a new AST node in custom code, such as plugins.
4
5## Install
6
7Install with [npm](https://www.npmjs.com/):
8
9```sh
10$ npm install --save snapdragon-node
11```
12
13## Usage
14
15With [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.
16
17```js
18var Node = require('snapdragon-node');
19var Snapdragon = require('snapdragon');
20var snapdragon = new Snapdragon();
21
22// example usage inside a parser visitor function
23snapdragon.parser.set('foo', function() {
24  // get the current "start" position
25  var pos = this.position();
26
27  // returns the match if regex matches the substring
28  // at the current position on `parser.input`
29  var match = this.match(/foo/);
30  if (match) {
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]}));
36  }
37});
38```
39
40## API
41
42### [Node](index.js#L22)
43
44Create a new AST `Node` with the given `val` and `type`.
45
46**Params**
47
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
51
52**Example**
53
54```js
55var node = new Node('*', 'Star');
56var node = new Node({type: 'star', val: '*'});
57```
58
59### [.isNode](index.js#L61)
60
61Returns true if the given value is a node.
62
63**Params**
64
65* `node` **{Object}**
66* `returns` **{Boolean}**
67
68**Example**
69
70```js
71var Node = require('snapdragon-node');
72var node = new Node({type: 'foo'});
73console.log(Node.isNode(node)); //=> true
74console.log(Node.isNode({})); //=> false
75```
76
77### [.define](index.js#L80)
78
79Define a non-enumberable property on the node instance. Useful for adding properties that shouldn't be extended or visible during debugging.
80
81**Params**
82
83* `name` **{String}**
84* `val` **{any}**
85* `returns` **{Object}**: returns the node instance
86
87**Example**
88
89```js
90var node = new Node();
91node.define('foo', 'something non-enumerable');
92```
93
94### [.isEmpty](index.js#L100)
95
96Returns true if `node.val` is an empty string, or `node.nodes` does not contain any non-empty text nodes.
97
98**Params**
99
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}**
102
103**Example**
104
105```js
106var node = new Node({type: 'text'});
107node.isEmpty(); //=> true
108node.val = 'foo';
109node.isEmpty(); //=> false
110```
111
112### [.push](index.js#L118)
113
114Given node `foo` and node `bar`, push node `bar` onto `foo.nodes`, and set `foo` as `bar.parent`.
115
116**Params**
117
118* `node` **{Object}**
119* `returns` **{Number}**: Returns the length of `node.nodes`
120
121**Example**
122
123```js
124var foo = new Node({type: 'foo'});
125var bar = new Node({type: 'bar'});
126foo.push(bar);
127```
128
129### [.unshift](index.js#L140)
130
131Given node `foo` and node `bar`, unshift node `bar` onto `foo.nodes`, and set `foo` as `bar.parent`.
132
133**Params**
134
135* `node` **{Object}**
136* `returns` **{Number}**: Returns the length of `node.nodes`
137
138**Example**
139
140```js
141var foo = new Node({type: 'foo'});
142var bar = new Node({type: 'bar'});
143foo.unshift(bar);
144```
145
146### [.pop](index.js#L167)
147
148Pop a node from `node.nodes`.
149
150* `returns` **{Number}**: Returns the popped `node`
151
152**Example**
153
154```js
155var node = new Node({type: 'foo'});
156node.push(new Node({type: 'a'}));
157node.push(new Node({type: 'b'}));
158node.push(new Node({type: 'c'}));
159node.push(new Node({type: 'd'}));
160console.log(node.nodes.length);
161//=> 4
162node.pop();
163console.log(node.nodes.length);
164//=> 3
165```
166
167### [.shift](index.js#L190)
168
169Shift a node from `node.nodes`.
170
171* `returns` **{Object}**: Returns the shifted `node`
172
173**Example**
174
175```js
176var node = new Node({type: 'foo'});
177node.push(new Node({type: 'a'}));
178node.push(new Node({type: 'b'}));
179node.push(new Node({type: 'c'}));
180node.push(new Node({type: 'd'}));
181console.log(node.nodes.length);
182//=> 4
183node.shift();
184console.log(node.nodes.length);
185//=> 3
186```
187
188### [.remove](index.js#L205)
189
190Remove `node` from `node.nodes`.
191
192**Params**
193
194* `node` **{Object}**
195* `returns` **{Object}**: Returns the removed node.
196
197**Example**
198
199```js
200node.remove(childNode);
201```
202
203### [.find](index.js#L231)
204
205Get 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.
206
207**Params**
208
209* `type` **{String}**
210* `returns` **{Object}**: Returns a child node or undefined.
211
212**Example**
213
214```js
215var child = node.find(1); //<= index of the node to get
216var child = node.find('foo'); //<= node.type of a child node
217var child = node.find(/^(foo|bar)$/); //<= regex to match node.type
218var child = node.find(['foo', 'bar']); //<= array of node.type(s)
219```
220
221### [.isType](index.js#L249)
222
223Return true if the node is the given `type`.
224
225**Params**
226
227* `type` **{String}**
228* `returns` **{Boolean}**
229
230**Example**
231
232```js
233var node = new Node({type: 'bar'});
234cosole.log(node.isType('foo'));          // false
235cosole.log(node.isType(/^(foo|bar)$/));  // true
236cosole.log(node.isType(['foo', 'bar'])); // true
237```
238
239### [.hasType](index.js#L270)
240
241Return true if the `node.nodes` has the given `type`.
242
243**Params**
244
245* `type` **{String}**
246* `returns` **{Boolean}**
247
248**Example**
249
250```js
251var foo = new Node({type: 'foo'});
252var bar = new Node({type: 'bar'});
253foo.push(bar);
254
255cosole.log(foo.hasType('qux'));          // false
256cosole.log(foo.hasType(/^(qux|bar)$/));  // true
257cosole.log(foo.hasType(['qux', 'bar'])); // true
258```
259
260* `returns` **{Array}**
261
262**Example**
263
264```js
265var foo = new Node({type: 'foo'});
266var bar = new Node({type: 'bar'});
267var baz = new Node({type: 'baz'});
268foo.push(bar);
269foo.push(baz);
270
271console.log(bar.siblings.length) // 2
272console.log(baz.siblings.length) // 2
273```
274
275* `returns` **{Number}**
276
277**Example**
278
279```js
280var foo = new Node({type: 'foo'});
281var bar = new Node({type: 'bar'});
282var baz = new Node({type: 'baz'});
283var qux = new Node({type: 'qux'});
284foo.push(bar);
285foo.push(baz);
286foo.unshift(qux);
287
288console.log(bar.index) // 1
289console.log(baz.index) // 2
290console.log(qux.index) // 0
291```
292
293* `returns` **{Object}**
294
295**Example**
296
297```js
298var foo = new Node({type: 'foo'});
299var bar = new Node({type: 'bar'});
300var baz = new Node({type: 'baz'});
301foo.push(bar);
302foo.push(baz);
303
304console.log(baz.prev.type) // 'bar'
305```
306
307* `returns` **{Object}**
308
309**Example**
310
311```js
312var foo = new Node({type: 'foo'});
313var bar = new Node({type: 'bar'});
314var baz = new Node({type: 'baz'});
315foo.push(bar);
316foo.push(baz);
317
318console.log(bar.siblings.length) // 2
319console.log(baz.siblings.length) // 2
320```
321
322* `returns` **{Object}**: The first node, or undefiend
323
324**Example**
325
326```js
327var foo = new Node({type: 'foo'});
328var bar = new Node({type: 'bar'});
329var baz = new Node({type: 'baz'});
330var qux = new Node({type: 'qux'});
331foo.push(bar);
332foo.push(baz);
333foo.push(qux);
334
335console.log(foo.first.type) // 'bar'
336```
337
338* `returns` **{Object}**: The last node, or undefiend
339
340**Example**
341
342```js
343var foo = new Node({type: 'foo'});
344var bar = new Node({type: 'bar'});
345var baz = new Node({type: 'baz'});
346var qux = new Node({type: 'qux'});
347foo.push(bar);
348foo.push(baz);
349foo.push(qux);
350
351console.log(foo.last.type) // 'qux'
352```
353
354* `returns` **{Object}**: The last node, or undefiend
355
356**Example**
357
358```js
359var foo = new Node({type: 'foo'});
360var bar = new Node({type: 'bar'});
361var baz = new Node({type: 'baz'});
362var qux = new Node({type: 'qux'});
363foo.push(bar);
364foo.push(baz);
365foo.push(qux);
366
367console.log(foo.last.type) // 'qux'
368```
369
370## Release history
371
372Changelog entries are classified using the following labels from [keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog):
373
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
379
380Custom labels used in this changelog:
381
382* `dependencies`: bumps dependencies
383* `housekeeping`: code re-organization, minor edits, or other changes that don't fit in one of the other categories.
384
385### [2.0.0] - 2017-05-01
386
387**Changed**
388
389* `.unshiftNode` was renamed to [.unshift](#unshift)
390* `.pushNode` was renamed to [.push](#push)
391* `.getNode` was renamed to [.find](#find)
392
393**Added**
394
395* [.isNode](#isNode)
396* [.isEmpty](#isEmpty)
397* [.pop](#pop)
398* [.shift](#shift)
399* [.remove](#remove)
400
401### [0.1.0]
402
403First release.
404
405## About
406
407### Related projects
408
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.")
414
415### Contributing
416
417Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
418
419Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.
420
421### Building docs
422
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.)_
424
425To generate the readme, run the following command:
426
427```sh
428$ npm install -g verbose/verb#dev verb-generate-readme && verb
429```
430
431### Running tests
432
433Running 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:
434
435```sh
436$ npm install && npm test
437```
438
439### Author
440
441**Jon Schlinkert**
442
443* [github/jonschlinkert](https://github.com/jonschlinkert)
444* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
445
446### License
447
448Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
449Released under the [MIT License](LICENSE).
450
451***
452
453_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on June 25, 2017._