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

   1 # snapdragon-util [![NPM version](https://img.shields.io/npm/v/snapdragon-util.svg?style=flat)](https://www.npmjs.com/package/snapdragon-util) [![NPM monthly downloads](https://img.shields.io/npm/dm/snapdragon-util.svg?style=flat)](https://npmjs.org/package/snapdragon-util) [![NPM total downloads](https://img.shields.io/npm/dt/snapdragon-util.svg?style=flat)](https://npmjs.org/package/snapdragon-util) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/snapdragon-util.svg?style=flat&label=Travis)](https://travis-ci.org/jonschlinkert/snapdragon-util)
   2
   3 > Utilities for the snapdragon parser/compiler.
   4
   5 <details>
   6 <summary><strong>Table of Contents</strong></summary>
   7
   8 - [Install](#install)
   9 - [Usage](#usage)
  10 - [API](#api)
  11 - [Release history](#release-history)
  12   * [[3.0.0] - 2017-05-01](#300---2017-05-01)
  13   * [[0.1.0]](#010)
  14 - [About](#about)
  15
  16 </details>
  17
  18 ## Install
  19
  20 Install with [npm](https://www.npmjs.com/):
  21
  22 ```sh
  23 $ npm install --save snapdragon-util
  24 ```
  25
  26 Install with [yarn](https://yarnpkg.com):
  27
  28 ```sh
  29 $ yarn add snapdragon-util
  30 ```
  31
  32 ## Usage
  33
  34 ```js
  35 var util = require('snapdragon-util');
  36 ```
  37
  38 ## API
  39
  40 ### [.isNode](index.js#L21)
  41
  42 Returns true if the given value is a node.
  43
  44 **Params**
  45
  46 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
  47 * `returns` **{Boolean}**
  48
  49 **Example**
  50
  51 ```js
  52 var Node = require('snapdragon-node');
  53 var node = new Node({type: 'foo'});
  54 console.log(utils.isNode(node)); //=> true
  55 console.log(utils.isNode({})); //=> false
  56 ```
  57
  58 ### [.noop](index.js#L37)
  59
  60 Emit an empty string for the given `node`.
  61
  62 **Params**
  63
  64 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
  65 * `returns` **{undefined}**
  66
  67 **Example**
  68
  69 ```js
  70 // do nothing for beginning-of-string
  71 snapdragon.compiler.set('bos', utils.noop);
  72 ```
  73
  74 ### [.identity](index.js#L53)
  75
  76 Appdend `node.val` to `compiler.output`, exactly as it was created by the parser.
  77
  78 **Params**
  79
  80 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
  81 * `returns` **{undefined}**
  82
  83 **Example**
  84
  85 ```js
  86 snapdragon.compiler.set('text', utils.identity);
  87 ```
  88
  89 ### [.append](index.js#L76)
  90
  91 Previously named `.emit`, this method appends the given `val` to `compiler.output` for the given node. Useful when you know what value should be appended advance, regardless of the actual value of `node.val`.
  92
  93 **Params**
  94
  95 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
  96 * `returns` **{Function}**: Returns a compiler middleware function.
  97
  98 **Example**
  99
 100 ```js
 101 snapdragon.compiler
 102   .set('i', function(node) {
 103     this.mapVisit(node);
 104   })
 105   .set('i.open', utils.append('<i>'))
 106   .set('i.close', utils.append('</i>'))
 107 ```
 108
 109 ### [.toNoop](index.js#L99)
 110
 111 Used in compiler middleware, this onverts an AST node into an empty `text` node and deletes `node.nodes` if it exists. The advantage of this method is that, as opposed to completely removing the node, indices will not need to be re-calculated in sibling nodes, and nothing is appended to the output.
 112
 113 **Params**
 114
 115 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 116 * `nodes` **{Array}**: Optionally pass a new `nodes` value, to replace the existing `node.nodes` array.
 117
 118 **Example**
 119
 120 ```js
 121 utils.toNoop(node);
 122 // convert `node.nodes` to the given value instead of deleting it
 123 utils.toNoop(node, []);
 124 ```
 125
 126 ### [.visit](index.js#L128)
 127
 128 Visit `node` with the given `fn`. The built-in `.visit` method in snapdragon automatically calls registered compilers, this allows you to pass a visitor function.
 129
 130 **Params**
 131
 132 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 133 * `fn` **{Function}**
 134 * `returns` **{Object}**: returns the node after recursively visiting all child nodes.
 135
 136 **Example**
 137
 138 ```js
 139 snapdragon.compiler.set('i', function(node) {
 140   utils.visit(node, function(childNode) {
 141     // do stuff with "childNode"
 142     return childNode;
 143   });
 144 });
 145 ```
 146
 147 ### [.mapVisit](index.js#L155)
 148
 149 Map [visit](#visit) the given `fn` over `node.nodes`. This is called by [visit](#visit), use this method if you do not want `fn` to be called on the first node.
 150
 151 **Params**
 152
 153 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 154 * `options` **{Object}**
 155 * `fn` **{Function}**
 156 * `returns` **{Object}**: returns the node
 157
 158 **Example**
 159
 160 ```js
 161 snapdragon.compiler.set('i', function(node) {
 162   utils.mapVisit(node, function(childNode) {
 163     // do stuff with "childNode"
 164     return childNode;
 165   });
 166 });
 167 ```
 168
 169 ### [.addOpen](index.js#L194)
 170
 171 Unshift an `*.open` node onto `node.nodes`.
 172
 173 **Params**
 174
 175 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 176 * `Node` **{Function}**: (required) Node constructor function from [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node).
 177 * `filter` **{Function}**: Optionaly specify a filter function to exclude the node.
 178 * `returns` **{Object}**: Returns the created opening node.
 179
 180 **Example**
 181
 182 ```js
 183 var Node = require('snapdragon-node');
 184 snapdragon.parser.set('brace', function(node) {
 185   var match = this.match(/^{/);
 186   if (match) {
 187     var parent = new Node({type: 'brace'});
 188     utils.addOpen(parent, Node);
 189     console.log(parent.nodes[0]):
 190     // { type: 'brace.open', val: '' };
 191
 192     // push the parent "brace" node onto the stack
 193     this.push(parent);
 194
 195     // return the parent node, so it's also added to the AST
 196     return brace;
 197   }
 198 });
 199 ```
 200
 201 ### [.addClose](index.js#L244)
 202
 203 Push a `*.close` node onto `node.nodes`.
 204
 205 **Params**
 206
 207 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 208 * `Node` **{Function}**: (required) Node constructor function from [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node).
 209 * `filter` **{Function}**: Optionaly specify a filter function to exclude the node.
 210 * `returns` **{Object}**: Returns the created closing node.
 211
 212 **Example**
 213
 214 ```js
 215 var Node = require('snapdragon-node');
 216 snapdragon.parser.set('brace', function(node) {
 217   var match = this.match(/^}/);
 218   if (match) {
 219     var parent = this.parent();
 220     if (parent.type !== 'brace') {
 221       throw new Error('missing opening: ' + '}');
 222     }
 223
 224     utils.addClose(parent, Node);
 225     console.log(parent.nodes[parent.nodes.length - 1]):
 226     // { type: 'brace.close', val: '' };
 227
 228     // no need to return a node, since the parent
 229     // was already added to the AST
 230     return;
 231   }
 232 });
 233 ```
 234
 235 ### [.wrapNodes](index.js#L274)
 236
 237 Wraps the given `node` with `*.open` and `*.close` nodes.
 238
 239 **Params**
 240
 241 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 242 * `Node` **{Function}**: (required) Node constructor function from [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node).
 243 * `filter` **{Function}**: Optionaly specify a filter function to exclude the node.
 244 * `returns` **{Object}**: Returns the node
 245
 246 ### [.pushNode](index.js#L299)
 247
 248 Push the given `node` onto `parent.nodes`, and set `parent` as `node.parent.
 249
 250 **Params**
 251
 252 * `parent` **{Object}**
 253 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 254 * `returns` **{Object}**: Returns the child node
 255
 256 **Example**
 257
 258 ```js
 259 var parent = new Node({type: 'foo'});
 260 var node = new Node({type: 'bar'});
 261 utils.pushNode(parent, node);
 262 console.log(parent.nodes[0].type) // 'bar'
 263 console.log(node.parent.type) // 'foo'
 264 ```
 265
 266 ### [.unshiftNode](index.js#L325)
 267
 268 Unshift `node` onto `parent.nodes`, and set `parent` as `node.parent.
 269
 270 **Params**
 271
 272 * `parent` **{Object}**
 273 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 274 * `returns` **{undefined}**
 275
 276 **Example**
 277
 278 ```js
 279 var parent = new Node({type: 'foo'});
 280 var node = new Node({type: 'bar'});
 281 utils.unshiftNode(parent, node);
 282 console.log(parent.nodes[0].type) // 'bar'
 283 console.log(node.parent.type) // 'foo'
 284 ```
 285
 286 ### [.popNode](index.js#L354)
 287
 288 Pop the last `node` off of `parent.nodes`. The advantage of using this method is that it checks for `node.nodes` and works with any version of `snapdragon-node`.
 289
 290 **Params**
 291
 292 * `parent` **{Object}**
 293 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 294 * `returns` **{Number|Undefined}**: Returns the length of `node.nodes` or undefined.
 295
 296 **Example**
 297
 298 ```js
 299 var parent = new Node({type: 'foo'});
 300 utils.pushNode(parent, new Node({type: 'foo'}));
 301 utils.pushNode(parent, new Node({type: 'bar'}));
 302 utils.pushNode(parent, new Node({type: 'baz'}));
 303 console.log(parent.nodes.length); //=> 3
 304 utils.popNode(parent);
 305 console.log(parent.nodes.length); //=> 2
 306 ```
 307
 308 ### [.shiftNode](index.js#L382)
 309
 310 Shift the first `node` off of `parent.nodes`. The advantage of using this method is that it checks for `node.nodes` and works with any version of `snapdragon-node`.
 311
 312 **Params**
 313
 314 * `parent` **{Object}**
 315 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 316 * `returns` **{Number|Undefined}**: Returns the length of `node.nodes` or undefined.
 317
 318 **Example**
 319
 320 ```js
 321 var parent = new Node({type: 'foo'});
 322 utils.pushNode(parent, new Node({type: 'foo'}));
 323 utils.pushNode(parent, new Node({type: 'bar'}));
 324 utils.pushNode(parent, new Node({type: 'baz'}));
 325 console.log(parent.nodes.length); //=> 3
 326 utils.shiftNode(parent);
 327 console.log(parent.nodes.length); //=> 2
 328 ```
 329
 330 ### [.removeNode](index.js#L409)
 331
 332 Remove the specified `node` from `parent.nodes`.
 333
 334 **Params**
 335
 336 * `parent` **{Object}**
 337 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 338 * `returns` **{Object|undefined}**: Returns the removed node, if successful, or undefined if it does not exist on `parent.nodes`.
 339
 340 **Example**
 341
 342 ```js
 343 var parent = new Node({type: 'abc'});
 344 var foo = new Node({type: 'foo'});
 345 utils.pushNode(parent, foo);
 346 utils.pushNode(parent, new Node({type: 'bar'}));
 347 utils.pushNode(parent, new Node({type: 'baz'}));
 348 console.log(parent.nodes.length); //=> 3
 349 utils.removeNode(parent, foo);
 350 console.log(parent.nodes.length); //=> 2
 351 ```
 352
 353 ### [.isType](index.js#L443)
 354
 355 Returns true if `node.type` matches the given `type`. Throws a `TypeError` if `node` is not an instance of `Node`.
 356
 357 **Params**
 358
 359 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 360 * `type` **{String}**
 361 * `returns` **{Boolean}**
 362
 363 **Example**
 364
 365 ```js
 366 var Node = require('snapdragon-node');
 367 var node = new Node({type: 'foo'});
 368 console.log(utils.isType(node, 'foo')); // false
 369 console.log(utils.isType(node, 'bar')); // true
 370 ```
 371
 372 ### [.hasType](index.js#L486)
 373
 374 Returns true if the given `node` has the given `type` in `node.nodes`. Throws a `TypeError` if `node` is not an instance of `Node`.
 375
 376 **Params**
 377
 378 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 379 * `type` **{String}**
 380 * `returns` **{Boolean}**
 381
 382 **Example**
 383
 384 ```js
 385 var Node = require('snapdragon-node');
 386 var node = new Node({
 387   type: 'foo',
 388   nodes: [
 389     new Node({type: 'bar'}),
 390     new Node({type: 'baz'})
 391   ]
 392 });
 393 console.log(utils.hasType(node, 'xyz')); // false
 394 console.log(utils.hasType(node, 'baz')); // true
 395 ```
 396
 397 ### [.firstOfType](index.js#L519)
 398
 399 Returns the first node from `node.nodes` of the given `type`
 400
 401 **Params**
 402
 403 * `nodes` **{Array}**
 404 * `type` **{String}**
 405 * `returns` **{Object|undefined}**: Returns the first matching node or undefined.
 406
 407 **Example**
 408
 409 ```js
 410 var node = new Node({
 411   type: 'foo',
 412   nodes: [
 413     new Node({type: 'text', val: 'abc'}),
 414     new Node({type: 'text', val: 'xyz'})
 415   ]
 416 });
 417
 418 var textNode = utils.firstOfType(node.nodes, 'text');
 419 console.log(textNode.val);
 420 //=> 'abc'
 421 ```
 422
 423 ### [.findNode](index.js#L556)
 424
 425 Returns the node at the specified index, or the first node of the given `type` from `node.nodes`.
 426
 427 **Params**
 428
 429 * `nodes` **{Array}**
 430 * `type` **{String|Number}**: Node type or index.
 431 * `returns` **{Object}**: Returns a node or undefined.
 432
 433 **Example**
 434
 435 ```js
 436 var node = new Node({
 437   type: 'foo',
 438   nodes: [
 439     new Node({type: 'text', val: 'abc'}),
 440     new Node({type: 'text', val: 'xyz'})
 441   ]
 442 });
 443
 444 var nodeOne = utils.findNode(node.nodes, 'text');
 445 console.log(nodeOne.val);
 446 //=> 'abc'
 447
 448 var nodeTwo = utils.findNode(node.nodes, 1);
 449 console.log(nodeTwo.val);
 450 //=> 'xyz'
 451 ```
 452
 453 ### [.isOpen](index.js#L584)
 454
 455 Returns true if the given node is an "*.open" node.
 456
 457 **Params**
 458
 459 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 460 * `returns` **{Boolean}**
 461
 462 **Example**
 463
 464 ```js
 465 var Node = require('snapdragon-node');
 466 var brace = new Node({type: 'brace'});
 467 var open = new Node({type: 'brace.open'});
 468 var close = new Node({type: 'brace.close'});
 469
 470 console.log(utils.isOpen(brace)); // false
 471 console.log(utils.isOpen(open)); // true
 472 console.log(utils.isOpen(close)); // false
 473 ```
 474
 475 ### [.isClose](index.js#L607)
 476
 477 Returns true if the given node is a "*.close" node.
 478
 479 **Params**
 480
 481 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 482 * `returns` **{Boolean}**
 483
 484 **Example**
 485
 486 ```js
 487 var Node = require('snapdragon-node');
 488 var brace = new Node({type: 'brace'});
 489 var open = new Node({type: 'brace.open'});
 490 var close = new Node({type: 'brace.close'});
 491
 492 console.log(utils.isClose(brace)); // false
 493 console.log(utils.isClose(open)); // false
 494 console.log(utils.isClose(close)); // true
 495 ```
 496
 497 ### [.hasOpen](index.js#L633)
 498
 499 Returns true if `node.nodes` **has** an `.open` node
 500
 501 **Params**
 502
 503 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 504 * `returns` **{Boolean}**
 505
 506 **Example**
 507
 508 ```js
 509 var Node = require('snapdragon-node');
 510 var brace = new Node({
 511   type: 'brace',
 512   nodes: []
 513 });
 514
 515 var open = new Node({type: 'brace.open'});
 516 console.log(utils.hasOpen(brace)); // false
 517
 518 brace.pushNode(open);
 519 console.log(utils.hasOpen(brace)); // true
 520 ```
 521
 522 ### [.hasClose](index.js#L663)
 523
 524 Returns true if `node.nodes` **has** a `.close` node
 525
 526 **Params**
 527
 528 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 529 * `returns` **{Boolean}**
 530
 531 **Example**
 532
 533 ```js
 534 var Node = require('snapdragon-node');
 535 var brace = new Node({
 536   type: 'brace',
 537   nodes: []
 538 });
 539
 540 var close = new Node({type: 'brace.close'});
 541 console.log(utils.hasClose(brace)); // false
 542
 543 brace.pushNode(close);
 544 console.log(utils.hasClose(brace)); // true
 545 ```
 546
 547 ### [.hasOpenAndClose](index.js#L697)
 548
 549 Returns true if `node.nodes` has both `.open` and `.close` nodes
 550
 551 **Params**
 552
 553 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 554 * `returns` **{Boolean}**
 555
 556 **Example**
 557
 558 ```js
 559 var Node = require('snapdragon-node');
 560 var brace = new Node({
 561   type: 'brace',
 562   nodes: []
 563 });
 564
 565 var open = new Node({type: 'brace.open'});
 566 var close = new Node({type: 'brace.close'});
 567 console.log(utils.hasOpen(brace)); // false
 568 console.log(utils.hasClose(brace)); // false
 569
 570 brace.pushNode(open);
 571 brace.pushNode(close);
 572 console.log(utils.hasOpen(brace)); // true
 573 console.log(utils.hasClose(brace)); // true
 574 ```
 575
 576 ### [.addType](index.js#L719)
 577
 578 Push the given `node` onto the `state.inside` array for the given type. This array is used as a specialized "stack" for only the given `node.type`.
 579
 580 **Params**
 581
 582 * `state` **{Object}**: The `compiler.state` object or custom state object.
 583 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 584 * `returns` **{Array}**: Returns the `state.inside` stack for the given type.
 585
 586 **Example**
 587
 588 ```js
 589 var state = { inside: {}};
 590 var node = new Node({type: 'brace'});
 591 utils.addType(state, node);
 592 console.log(state.inside);
 593 //=> { brace: [{type: 'brace'}] }
 594 ```
 595
 596 ### [.removeType](index.js#L759)
 597
 598 Remove the given `node` from the `state.inside` array for the given type. This array is used as a specialized "stack" for only the given `node.type`.
 599
 600 **Params**
 601
 602 * `state` **{Object}**: The `compiler.state` object or custom state object.
 603 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 604 * `returns` **{Array}**: Returns the `state.inside` stack for the given type.
 605
 606 **Example**
 607
 608 ```js
 609 var state = { inside: {}};
 610 var node = new Node({type: 'brace'});
 611 utils.addType(state, node);
 612 console.log(state.inside);
 613 //=> { brace: [{type: 'brace'}] }
 614 utils.removeType(state, node);
 615 //=> { brace: [] }
 616 ```
 617
 618 ### [.isEmpty](index.js#L788)
 619
 620 Returns true if `node.val` is an empty string, or `node.nodes` does not contain any non-empty text nodes.
 621
 622 **Params**
 623
 624 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 625 * `fn` **{Function}**
 626 * `returns` **{Boolean}**
 627
 628 **Example**
 629
 630 ```js
 631 var node = new Node({type: 'text'});
 632 utils.isEmpty(node); //=> true
 633 node.val = 'foo';
 634 utils.isEmpty(node); //=> false
 635 ```
 636
 637 ### [.isInsideType](index.js#L833)
 638
 639 Returns true if the `state.inside` stack for the given type exists and has one or more nodes on it.
 640
 641 **Params**
 642
 643 * `state` **{Object}**
 644 * `type` **{String}**
 645 * `returns` **{Boolean}**
 646
 647 **Example**
 648
 649 ```js
 650 var state = { inside: {}};
 651 var node = new Node({type: 'brace'});
 652 console.log(utils.isInsideType(state, 'brace')); //=> false
 653 utils.addType(state, node);
 654 console.log(utils.isInsideType(state, 'brace')); //=> true
 655 utils.removeType(state, node);
 656 console.log(utils.isInsideType(state, 'brace')); //=> false
 657 ```
 658
 659 ### [.isInside](index.js#L867)
 660
 661 Returns true if `node` is either a child or grand-child of the given `type`, or `state.inside[type]` is a non-empty array.
 662
 663 **Params**
 664
 665 * `state` **{Object}**: Either the `compiler.state` object, if it exists, or a user-supplied state object.
 666 * `node` **{Object}**: Instance of [snapdragon-node](https://github.com/jonschlinkert/snapdragon-node)
 667 * `type` **{String}**: The `node.type` to check for.
 668 * `returns` **{Boolean}**
 669
 670 **Example**
 671
 672 ```js
 673 var state = { inside: {}};
 674 var node = new Node({type: 'brace'});
 675 var open = new Node({type: 'brace.open'});
 676 console.log(utils.isInside(state, open, 'brace')); //=> false
 677 utils.pushNode(node, open);
 678 console.log(utils.isInside(state, open, 'brace')); //=> true
 679 ```
 680
 681 ### [.last](index.js#L915)
 682
 683 Get the last `n` element from the given `array`. Used for getting
 684 a node from `node.nodes.`
 685
 686 **Params**
 687
 688 * `array` **{Array}**
 689 * `n` **{Number}**
 690 * `returns` **{undefined}**
 691
 692 ### [.arrayify](index.js#L935)
 693
 694 Cast the given `val` to an array.
 695
 696 **Params**
 697
 698 * `val` **{any}**
 699 * `returns` **{Array}**
 700
 701 **Example**
 702
 703 ```js
 704 console.log(utils.arraify(''));
 705 //=> []
 706 console.log(utils.arraify('foo'));
 707 //=> ['foo']
 708 console.log(utils.arraify(['foo']));
 709 //=> ['foo']
 710 ```
 711
 712 ### [.stringify](index.js#L948)
 713
 714 Convert the given `val` to a string by joining with `,`. Useful
 715 for creating a cheerio/CSS/DOM-style selector from a list of strings.
 716
 717 **Params**
 718
 719 * `val` **{any}**
 720 * `returns` **{Array}**
 721
 722 ### [.trim](index.js#L961)
 723
 724 Ensure that the given value is a string and call `.trim()` on it,
 725 or return an empty string.
 726
 727 **Params**
 728
 729 * `str` **{String}**
 730 * `returns` **{String}**
 731
 732 ## Release history
 733
 734 Changelog entries are classified using the following labels from [keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog):
 735
 736 * `added`: for new features
 737 * `changed`: for changes in existing functionality
 738 * `deprecated`: for once-stable features removed in upcoming releases
 739 * `removed`: for deprecated features removed in this release
 740 * `fixed`: for any bug fixes
 741
 742 Custom labels used in this changelog:
 743
 744 * `dependencies`: bumps dependencies
 745 * `housekeeping`: code re-organization, minor edits, or other changes that don't fit in one of the other categories.
 746
 747 ### [3.0.0] - 2017-05-01
 748
 749 **Changed**
 750
 751 * `.emit` was renamed to [.append](#append)
 752 * `.addNode` was renamed to [.pushNode](#pushNode)
 753 * `.getNode` was renamed to [.findNode](#findNode)
 754 * `.isEmptyNodes` was renamed to [.isEmpty](#isEmpty): also now works with `node.nodes` and/or `node.val`
 755
 756 **Added**
 757
 758 * [.identity](#identity)
 759 * [.removeNode](#removeNode)
 760 * [.shiftNode](#shiftNode)
 761 * [.popNode](#popNode)
 762
 763 ### [0.1.0]
 764
 765 First release.
 766
 767 ## About
 768
 769 ### Contributing
 770
 771 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
 772
 773 Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.
 774
 775 ### Building docs
 776
 777 _(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.)_
 778
 779 To generate the readme, run the following command:
 780
 781 ```sh
 782 $ npm install -g verbose/verb#dev verb-generate-readme && verb
 783 ```
 784
 785 ### Running tests
 786
 787 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:
 788
 789 ```sh
 790 $ npm install && npm test
 791 ```
 792
 793 ### Author
 794
 795 **Jon Schlinkert**
 796
 797 * [github/jonschlinkert](https://github.com/jonschlinkert)
 798 * [twitter/jonschlinkert](https://twitter.com/jonschlinkert)
 799
 800 ### License
 801
 802 Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).
 803 Released under the [MIT License](LICENSE).
 804
 805 ***
 806
 807 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on May 01, 2017._