.config/coc/extensions/node_modules/coc-prettier/node_modules/snapdragon-node/README.md

   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
   7 Install with [npm](https://www.npmjs.com/):
   8
   9 ```sh
  10 $ npm install --save snapdragon-node
  11 ```
  12
  13 ## Usage
  14
  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.
  16
  17 ```js
  18 var Node = require('snapdragon-node');
  19 var Snapdragon = require('snapdragon');
  20 var snapdragon = new Snapdragon();
  21
  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();
  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
  44 Create 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
  55 var node = new Node('*', 'Star');
  56 var node = new Node({type: 'star', val: '*'});
  57 ```
  58
  59 ### [.isNode](index.js#L61)
  60
  61 Returns true if the given value is a node.
  62
  63 **Params**
  64
  65 * `node` **{Object}**
  66 * `returns` **{Boolean}**
  67
  68 **Example**
  69
  70 ```js
  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
  75 ```
  76
  77 ### [.define](index.js#L80)
  78
  79 Define 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
  90 var node = new Node();
  91 node.define('foo', 'something non-enumerable');
  92 ```
  93
  94 ### [.isEmpty](index.js#L100)
  95
  96 Returns 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
 106 var node = new Node({type: 'text'});
 107 node.isEmpty(); //=> true
 108 node.val = 'foo';
 109 node.isEmpty(); //=> false
 110 ```
 111
 112 ### [.push](index.js#L118)
 113
 114 Given 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
 124 var foo = new Node({type: 'foo'});
 125 var bar = new Node({type: 'bar'});
 126 foo.push(bar);
 127 ```
 128
 129 ### [.unshift](index.js#L140)
 130
 131 Given 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
 141 var foo = new Node({type: 'foo'});
 142 var bar = new Node({type: 'bar'});
 143 foo.unshift(bar);
 144 ```
 145
 146 ### [.pop](index.js#L167)
 147
 148 Pop a node from `node.nodes`.
 149
 150 * `returns` **{Number}**: Returns the popped `node`
 151
 152 **Example**
 153
 154 ```js
 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);
 161 //=> 4
 162 node.pop();
 163 console.log(node.nodes.length);
 164 //=> 3
 165 ```
 166
 167 ### [.shift](index.js#L190)
 168
 169 Shift a node from `node.nodes`.
 170
 171 * `returns` **{Object}**: Returns the shifted `node`
 172
 173 **Example**
 174
 175 ```js
 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);
 182 //=> 4
 183 node.shift();
 184 console.log(node.nodes.length);
 185 //=> 3
 186 ```
 187
 188 ### [.remove](index.js#L205)
 189
 190 Remove `node` from `node.nodes`.
 191
 192 **Params**
 193
 194 * `node` **{Object}**
 195 * `returns` **{Object}**: Returns the removed node.
 196
 197 **Example**
 198
 199 ```js
 200 node.remove(childNode);
 201 ```
 202
 203 ### [.find](index.js#L231)
 204
 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.
 206
 207 **Params**
 208
 209 * `type` **{String}**
 210 * `returns` **{Object}**: Returns a child node or undefined.
 211
 212 **Example**
 213
 214 ```js
 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)
 219 ```
 220
 221 ### [.isType](index.js#L249)
 222
 223 Return true if the node is the given `type`.
 224
 225 **Params**
 226
 227 * `type` **{String}**
 228 * `returns` **{Boolean}**
 229
 230 **Example**
 231
 232 ```js
 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
 237 ```
 238
 239 ### [.hasType](index.js#L270)
 240
 241 Return 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
 251 var foo = new Node({type: 'foo'});
 252 var bar = new Node({type: 'bar'});
 253 foo.push(bar);
 254
 255 cosole.log(foo.hasType('qux'));          // false
 256 cosole.log(foo.hasType(/^(qux|bar)$/));  // true
 257 cosole.log(foo.hasType(['qux', 'bar'])); // true
 258 ```
 259
 260 * `returns` **{Array}**
 261
 262 **Example**
 263
 264 ```js
 265 var foo = new Node({type: 'foo'});
 266 var bar = new Node({type: 'bar'});
 267 var baz = new Node({type: 'baz'});
 268 foo.push(bar);
 269 foo.push(baz);
 270
 271 console.log(bar.siblings.length) // 2
 272 console.log(baz.siblings.length) // 2
 273 ```
 274
 275 * `returns` **{Number}**
 276
 277 **Example**
 278
 279 ```js
 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'});
 284 foo.push(bar);
 285 foo.push(baz);
 286 foo.unshift(qux);
 287
 288 console.log(bar.index) // 1
 289 console.log(baz.index) // 2
 290 console.log(qux.index) // 0
 291 ```
 292
 293 * `returns` **{Object}**
 294
 295 **Example**
 296
 297 ```js
 298 var foo = new Node({type: 'foo'});
 299 var bar = new Node({type: 'bar'});
 300 var baz = new Node({type: 'baz'});
 301 foo.push(bar);
 302 foo.push(baz);
 303
 304 console.log(baz.prev.type) // 'bar'
 305 ```
 306
 307 * `returns` **{Object}**
 308
 309 **Example**
 310
 311 ```js
 312 var foo = new Node({type: 'foo'});
 313 var bar = new Node({type: 'bar'});
 314 var baz = new Node({type: 'baz'});
 315 foo.push(bar);
 316 foo.push(baz);
 317
 318 console.log(bar.siblings.length) // 2
 319 console.log(baz.siblings.length) // 2
 320 ```
 321
 322 * `returns` **{Object}**: The first node, or undefiend
 323
 324 **Example**
 325
 326 ```js
 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'});
 331 foo.push(bar);
 332 foo.push(baz);
 333 foo.push(qux);
 334
 335 console.log(foo.first.type) // 'bar'
 336 ```
 337
 338 * `returns` **{Object}**: The last node, or undefiend
 339
 340 **Example**
 341
 342 ```js
 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'});
 347 foo.push(bar);
 348 foo.push(baz);
 349 foo.push(qux);
 350
 351 console.log(foo.last.type) // 'qux'
 352 ```
 353
 354 * `returns` **{Object}**: The last node, or undefiend
 355
 356 **Example**
 357
 358 ```js
 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'});
 363 foo.push(bar);
 364 foo.push(baz);
 365 foo.push(qux);
 366
 367 console.log(foo.last.type) // 'qux'
 368 ```
 369
 370 ## Release history
 371
 372 Changelog 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
 380 Custom 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
 403 First 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
 417 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
 418
 419 Please 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
 425 To 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
 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:
 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
 448 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
 449 Released 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._