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._