.config/coc/extensions/node_modules/coc-prettier/node_modules/gonzales-pe/README.md

   1 # Gonzales PE @dev
   2
   3 [![NPM version][npm-img]][npm]
   4 [![Build Status][travis-img]][travis]
   5 [![AppVeyor Build Status][appveyor-img]][appveyor]
   6
   7 [npm-img]:      https://img.shields.io/npm/v/gonzales-pe.svg
   8 [npm]:          https://www.npmjs.com/package/gonzales-pe
   9 [travis-img]:   https://travis-ci.org/tonyganch/gonzales-pe.svg
  10 [travis]:       https://travis-ci.org/tonyganch/gonzales-pe
  11 [appveyor-img]: https://ci.appveyor.com/api/projects/status/m29jphtrqt398v2o/branch/dev?svg=true
  12 [appveyor]:     https://ci.appveyor.com/project/tonyganch/gonzales-pe/branch/dev
  13
  14 Gonzales PE is a CSS parser which plays nicely with preprocessors.
  15 Currently those are supported: SCSS, Sass, LESS.
  16 Try out Gonzales PE online: [Gonzales PE Playground](https://tonyganch.io/gonzales-pe/).
  17
  18 ## Install
  19
  20 (1) To install command-line tool globally:
  21
  22 ```bash
  23 npm install -g git://github.com/tonyganch/gonzales-pe.git#dev
  24 ```
  25
  26 (2) To install parser as a project dependency:
  27
  28 ```bash
  29 npm install --save git://github.com/tonyganch/gonzales-pe.git#dev
  30 ```
  31
  32 (3) If for some reason you want to build files yourself:
  33
  34 ```bash
  35 # Clone the repo.
  36 git clone git@github.com:tonyganch/gonzales-pe.git
  37 # Go to dev branch.
  38 git checkout dev
  39 # Install project dependencies.
  40 npm install
  41 # Install git hooks and build files.
  42 npm run init
  43 ```
  44
  45 ## API
  46
  47 Basically there are a few things you can do:
  48
  49 1. parse css string and get a parse tree in return;
  50 2. modify tree nodes;
  51 3. remove tree nodes;
  52 4. add new nodes to the tree;
  53 5. convert modified tree back to a string.
  54
  55 The different type of tree nodes can be found in [docs/node-types.md](https://github.com/tonyganch/gonzales-pe/blob/dev/docs/node-types.md).
  56
  57 In examples below I assume that `gonzales` is a parser module and `parseTree`
  58 is some parsed css:
  59
  60 ```js
  61 let gonzales = require('gonzales-pe');
  62 let parseTree = gonzales.parse(css);
  63 ```
  64
  65 ### gonzales.createNode(options)
  66
  67 ##### Description
  68
  69 Creates a new node. Useful when you need to add something to a tree.
  70
  71 ##### Parameters
  72
  73 <table>
  74   <tr>
  75     <td><i>{Object}</i></td>
  76     <td>options</td>
  77     <td>Options to pass to a `Node` constructor.</td>
  78   </tr>
  79   <tr>
  80 </table>
  81
  82 ##### Returns
  83
  84 <table>
  85   <tr>
  86     <td><i>{Object}</i></td>
  87     <td>A new node.</td>
  88   </tr>
  89 </table>
  90
  91 ##### Examples
  92
  93 ```js
  94 let css = 'a {color: tomato}';
  95 let parseTree = gonzales.parse(css);
  96 let node = gonzales.createNode({ type: 'animal', content: 'panda' });
  97 parseTree.content.push(node);
  98 ```
  99
 100
 101 ### gonzales.parse(css[, options])
 102
 103 ##### Description
 104
 105 Parses a css string.
 106
 107 ##### Parameters
 108
 109 <table>
 110   <tr>
 111     <td><i>{string}</i></td>
 112     <td>css</td>
 113     <td>A string to parse.</td>
 114   </tr>
 115   <tr>
 116     <td><i>{Object=}</i></td>
 117     <td>options</td>
 118     <td>Optional. Additional options:
 119       <ul>
 120         <li>
 121           <code>{string} syntax</code> — any of the following: <code>css</code>,
 122           <code>less</code>, <code>sass</code>, <code>scss</code>.
 123           Default one is <code>css</code>.
 124         </li>
 125         <li>
 126           <code>{string} context</code> — root node's type. For a list of available
 127           values see <a href="docs/node-types.md">"Node types"</a>. Default
 128           one is <code>stylesheet</code>.
 129         </li>
 130         <li>
 131           <code>{number} tabSize</code> — size of a tab character in spaces.
 132           Default one is 1.
 133         </li>
 134       </ul>
 135     </td>
 136   </tr>
 137 </table>
 138
 139 ##### Returns
 140
 141 <table>
 142   <tr>
 143     <td><i>{Object}</i></td>
 144     <td>Parse tree.</td>
 145   </tr>
 146 </table>
 147
 148 ##### Examples
 149
 150 ```js
 151 let css = 'a {color: tomato}';
 152 let parseTree = gonzales.parse(css);
 153 ```
 154
 155 ```js
 156 let less = 'a {$color: tomato}';
 157 let parseTree = gonzales.parse(less, {syntax: 'less'});
 158 ```
 159
 160 ```js
 161 let less = '$color: tomato';
 162 let parseTree = gonzales.parse(less, {syntax: 'less', rule: 'declaration'});
 163 ```
 164
 165 ### parseTree.contains(type)
 166
 167 ##### Description
 168
 169 Checks whether there is a child node of given type.
 170
 171 ##### Parameters
 172
 173 <table>
 174   <tr>
 175     <td><i>{string}</i></td>
 176     <td>type</td>
 177     <td>
 178       Node type we're looking for. For a list of available values see
 179       <a href="docs/node-types.md">"Node types"</a>.
 180     </td>
 181   </tr>
 182 </table>
 183
 184 ##### Returns
 185
 186 <table>
 187   <tr>
 188     <td><i>{boolean}</i></td>
 189     <td>
 190       <code>true</code> if a tree contains a child node of a given type,
 191       <code>false</code> otherwise.
 192     </td>
 193   </tr>
 194 </table>
 195
 196 ##### Examples
 197
 198 ```js
 199 if (parseTree.contains('space')) {
 200   doSomething();
 201 }
 202 ```
 203
 204 ### parseTree.content
 205
 206 ##### Returns
 207
 208 <table>
 209   <tr>
 210     <td><i>{string|Array}</i></td>
 211     <td>Node's content (child nodes or a string).</td>
 212   </tr>
 213 </table>
 214
 215 ### parseTree.eachFor([type, ]callback)
 216
 217 ##### Description
 218
 219 Calls a function for every child node in tree. If `type` parameter is passed,
 220 calls a function only for child nodes of a given type. The main difference from
 221 `parseTree.forEach()` is that this method loops through node list from the end
 222 to beginning.
 223
 224 ##### Parameters
 225
 226 <table>
 227   <tr>
 228     <td><i>{string=}</i></td>
 229     <td>type</td>
 230     <td>
 231       Optional. A node type by which to filter child nodes before applying
 232       a callback function. For a list of available values see
 233       <a href="docs/node-types.md">"Node types"</a>.
 234     </td>
 235   </tr>
 236   <tr>
 237     <td><i>{Function}</i></td>
 238     <td>callback</td>
 239     <td>
 240       Function to call for every child node. Accepts following parameters:
 241       <ul>
 242         <li><code>{Object}</code> — a child node;</li>
 243         <li><code>{number}</code> — index of the child node in node list;</li>
 244         <li>
 245           <code>{Object}</code> — parent node (equals to <code>parseTree</code>).
 246         </li>
 247       </ul>
 248     </td>
 249   </tr>
 250 </table>
 251
 252 ##### Examples
 253
 254 ```js
 255 parseTree.eachFor(function(childNode) {
 256   doSomething(childNode);
 257 });
 258 ```
 259
 260 ```js
 261 // Remove all child spaces.
 262 parseTree.eachFor('space', function(spaceNode, i) {
 263   parseTree.removeChild(i);
 264 });
 265 ```
 266
 267 ### parseTree.end
 268
 269 ##### Returns
 270
 271 <table>
 272   <tr>
 273     <td><i>{Object}</i></td>
 274     <td>
 275       End position of the node. Contains following info:
 276       <ul>
 277         <li>
 278           <code>{number} line</code> — last symbol's line number
 279           (1-based index);
 280         </li>
 281         <li>
 282           <code>{number} column</code> — last symbol's column number
 283           (1-based index).
 284         </li>
 285       </ul>
 286     </td>
 287   </tr>
 288 </table>
 289
 290 ### parseTree.first([type])
 291
 292 ##### Description
 293
 294 Gets the first child node. If `type` parameter is passed, gets the first child
 295 node of a given type. If no node has been found, returns `null`.
 296
 297 ##### Parameters
 298
 299 <table>
 300   <tr>
 301     <td><i>{string=}</i></td>
 302     <td>type</td>
 303     <td>
 304       Optional. Node type to look for. For a list of available values see
 305       <a href="docs/node-types.md">"Node types"</a>.
 306     </td>
 307   </tr>
 308 </table>
 309
 310 ##### Returns
 311
 312 <table>
 313   <tr>
 314     <td><i>{?Object}</i></td>
 315     <td>A node.</td>
 316   </tr>
 317 </table>
 318
 319 ##### Examples
 320
 321 ```js
 322 let node = parseTree.first();
 323 node.content = 'panda';
 324 ```
 325
 326 ```js
 327 let node = parseTree.first('multilineComment');
 328 node.content = 'panda';
 329 ```
 330
 331 ### parseTree.forEach([type, ]callback)
 332
 333 ##### Description
 334
 335 Calls a function for every child node in tree. If `type` parameter is passed,
 336 calls a function only for child nodes of a given type. The main difference from
 337 `parseTree.eachFor()` is that this method loops through node list from the
 338 beginnig to end.
 339
 340 ##### Parameters
 341
 342 <table>
 343   <tr>
 344     <td><i>{string=}</i></td>
 345     <td>type</td>
 346     <td>
 347       Optional. A node type by which to filter child nodes before applying
 348       a callback function. For a list of available values see
 349       <a href="docs/node-types.md">"Node types"</a>.
 350     </td>
 351   </tr>
 352   <tr>
 353     <td><i>{Function}</i></td>
 354     <td>callback</td>
 355     <td>
 356       Function to call for every child node. Accepts following parameters:
 357       <ul>
 358         <li><code>{Object}</code> — a child node;</li>
 359         <li><code>{number}</code> — index of the child node in node list;</li>
 360         <li>
 361           <code>{Object}</code> — parent node (equals to <code>parseTree</code>).
 362         </li>
 363       </ul>
 364     </td>
 365   </tr>
 366 </table>
 367
 368 ##### Examples
 369
 370 ```js
 371 parseTree.forEach(function(childNode) {
 372   doSomething();
 373 });
 374 ```
 375
 376 ```js
 377 parseTree.forEach('space', function(spaceNode) {
 378   doSomething();
 379 });
 380 ```
 381
 382 ### parseTree.get(index)
 383
 384 ##### Description
 385
 386 Gets *nth* child of the `parseTree`. If no node has been found, returns `null`.
 387
 388 ##### Parameters
 389
 390 <table>
 391   <tr>
 392     <td><i>{number}</i></td>
 393     <td>index</td>
 394     <td>Index number of node which we're looking for.</td>
 395   </tr>
 396 </table>
 397
 398 ##### Returns
 399
 400 <table>
 401   <tr>
 402     <td><i>{?Object}</i></td>
 403     <td>A node.</td>
 404   </tr>
 405 </table>
 406
 407 ##### Examples
 408
 409 ```js
 410 var node = parseTree.get(2);
 411 doSomething(node);
 412 ```
 413
 414 ### parseTree.insert(index, node)
 415
 416 ##### Description
 417
 418 Inserts a node to a given position in `parseTree`.
 419
 420 ##### Parameters
 421
 422 <table>
 423   <tr>
 424     <td><i>{number}</i></td>
 425     <td>index</td>
 426     <td>Index of position where to insert the node.</td>
 427   </tr>
 428   <tr>
 429     <td><i>{Object}</i></td>
 430     <td>node</td>
 431     <td>A node to insert.</td>
 432   </tr>
 433 </table>
 434
 435 ##### Examples
 436
 437 ```js
 438 let node = gonzales.createNode({type: 'animal', content: 'panda'});
 439 parseTree.insert(2, node);
 440 ```
 441
 442 ### parseTree.is(type)
 443
 444 ##### Description
 445
 446 Checks whether the node is of given type.
 447
 448 ##### Parameters
 449
 450 <table>
 451   <tr>
 452     <td><i>{string}</i></td>
 453     <td>type</td>
 454     <td>
 455       A node type against which to check type of <code>parseTree</code>.
 456       For a list of available values see
 457       <a href="docs/node-types.md">"Node types"</a>.
 458     </td>
 459   </tr>
 460 </table>
 461
 462 ##### Returns
 463
 464 <table>
 465   <tr>
 466     <td><i>{boolean}</i></td>
 467     <td>
 468       <code>true</code> if types are equal, <code>false</code> otherwise.
 469     </td>
 470   </tr>
 471 </table>
 472
 473 ##### Examples
 474
 475 ```js
 476 if (node.is('space')) {
 477   node.content = '';
 478 }
 479 ```
 480
 481 ### parseTree.last(type)
 482
 483 Gets the last child node. If `type` parameter is passed, gets the last child
 484 node of a given type. If no node has been found, returns `null`.
 485
 486 ##### Parameters
 487
 488 <table>
 489   <tr>
 490     <td><i>{string=}</i></td>
 491     <td>type</td>
 492     <td>
 493       Optional. Node type to look for. For a list of available values see
 494       <a href="docs/node-types.md">"Node types"</a>.
 495     </td>
 496   </tr>
 497 </table>
 498
 499 ##### Returns
 500
 501 <table>
 502   <tr>
 503     <td><i>{?Object}</i></td>
 504     <td>A node.</td>
 505   </tr>
 506 </table>
 507
 508 ##### Examples
 509
 510 ```js
 511 let node = parseTree.last();
 512 node.content = 'panda';
 513 ```
 514
 515 ```js
 516 let node = parseTree.last('multilineComment');
 517 node.content = 'panda';
 518 ```
 519
 520 ### parseTree.length
 521
 522 ##### Returns
 523
 524 <table>
 525   <tr>
 526     <td><i>{number}</i></td>
 527     <td>Number of child nodes.</td>
 528   </tr>
 529 </table>
 530
 531 ### parseTree.removeChild(index)
 532
 533 ##### Description
 534
 535 Removes a child node at a given position.
 536
 537 ##### Parameters
 538
 539 <table>
 540   <tr>
 541     <td><i>{number}</i></td>
 542     <td>index</td>
 543     <td>Index of a child node we need to remove.</td>
 544   </tr>
 545 </table>
 546
 547 ##### Returns
 548
 549 <table>
 550   <tr>
 551     <td><i>{Object}</i></td>
 552     <td>Removed node.</td>
 553   </tr>
 554 </table>
 555 ##### Examples
 556
 557 ```js
 558 // Swap nodes.
 559 var node = parseTree.removeChild(1);
 560 parseTree.insert(0, node);
 561 ```
 562
 563 ### parseTree.start
 564
 565 ##### Returns
 566
 567 <table>
 568   <tr>
 569     <td><i>{Object}</i></td>
 570     <td>
 571       Start position of the node. Contains following info:
 572       <ul>
 573         <li>
 574           <code>{number} line</code> — first symbol's line number
 575           (1-based index);
 576         </li>
 577         <li>
 578           <code>{number} column</code> — first symbol's column number
 579           (1-based index).
 580         </li>
 581       </ul>
 582     </td>
 583   </tr>
 584 </table>
 585
 586
 587 ### parseTree.syntax
 588
 589 ##### Returns
 590
 591 <table>
 592   <tr>
 593     <td><i>{string}</i></td>
 594     <td>Syntax of original parsed string.</td>
 595   </tr>
 596 </table>
 597
 598 ### parseTree.toJson()
 599
 600 ##### Description
 601
 602 Converts parse tree to JSON. Useful for printing.
 603
 604 ##### Returns
 605
 606 <table>
 607   <tr>
 608     <td><i>{Object}</i></td>
 609     <td>Parse tree in JSON</td>
 610   </tr>
 611 </table>
 612
 613 ### parseTree.toString()
 614
 615 ##### Description
 616
 617 Converts parse tree back to string according to original syntax.
 618
 619 ##### Returns
 620
 621 <table>
 622   <tr>
 623     <td><i>{string}</i></td>
 624     <td>A compiled string.</td>
 625   </tr>
 626 </table>
 627
 628 ##### Examples
 629
 630 ```js
 631 let css = parseTree.toString();
 632 ```
 633
 634 ### parseTree.traverse(callback)
 635
 636 ##### Description
 637
 638 Calls the function for every node in a tree including `parseTree` itself.
 639
 640 ##### Parameters
 641
 642 <table>
 643   <tr>
 644     <td><i>{Function}</i></td>
 645     <td>callback</td>
 646     <td>
 647       Function to apply to every node. Accepts following parameters:
 648       <ul>
 649         <li><code>{Object}</code> — a node to which we apply callback;</li>
 650         <li><code>{number}</code> — node's index number inside its parent;</li>
 651         <li><code>{Object}</code> — a node's parent;</li>
 652         <li>
 653           <code>{number}</code> — node's nesting level relative to its parent.
 654         </li>
 655       </ul>
 656     </td>
 657   </tr>
 658 </table>
 659
 660 ##### Examples
 661
 662 ```js
 663 parseTree.traverse(function(node, index, parent) {
 664   if (node.is('multilineComment')) {
 665     parent.removeChild(index);
 666   } else if (node.is('space')) {
 667     node.content = ' ';
 668   }
 669 });
 670 ```
 671
 672 ### parseTree.traverseByType(type, callback)
 673
 674 ##### Description
 675
 676 This method should be called for a root node, because calling it for a child
 677 will be more time consuming.
 678 Calls the function for every node of a given type. This means not just child
 679 nodes, but grandchilds and so on.
 680
 681 ##### Parameters
 682
 683 <table>
 684   <tr>
 685     <td><i>{string}</i></td>
 686     <td>type</td>
 687     <td>
 688       Node type. For a list of available values please see
 689       <a href="docs/node-types.md">"Node types"</a>.
 690     </td>
 691   </tr>
 692   <tr>
 693     <td><i>{Function}</i></td>
 694     <td>callback</td>
 695     <td>
 696       Function to apply to every node of a given type.
 697       Accepts following parameters:
 698       <ul>
 699         <li><code>{Object}</code> — a node to which we apply callback;</li>
 700         <li><code>{number}</code> — node's index number inside its parent;</li>
 701         <li><code>{Object}</code> — a node's parent.</li>
 702       </ul>
 703     </td>
 704   </tr>
 705 </table>
 706
 707 ##### Examples
 708
 709 ```js
 710 // Remove all comments.
 711 parseTree.traverseByType('multilineComment', function(node, index, parent) {
 712   parent.removeChild(index);
 713 });
 714 ```
 715
 716 ### parseTree.traverseByTypes(types, callback)
 717
 718 ##### Description
 719
 720 This method should be called for a root node, because calling it for a child
 721 will be more time consuming.
 722 Calls the function for every node of given types. This means not just child
 723 nodes, but grandchilds and so on.
 724
 725 ##### Parameters
 726
 727 <table>
 728   <tr>
 729     <td><i>{Array.string}</i></td>
 730     <td>types</td>
 731     <td>
 732       List of node types. For a list of available values please see
 733       <a href="docs/node-types.md">"Node types"</a>.
 734     </td>
 735   </tr>
 736   <tr>
 737     <td><i>{Function}</i></td>
 738     <td>callback</td>
 739     <td>
 740       Function to apply to every node of given types.
 741       Accepts following parameters:
 742       <ul>
 743         <li><code>{Object}</code> — a node to which we apply callback;</li>
 744         <li><code>{number}</code> — node's index number inside its parent;</li>
 745         <li><code>{Object}</code> — a node's parent.</li>
 746       </ul>
 747     </td>
 748   </tr>
 749 </table>
 750
 751 ##### Examples
 752
 753 ```js
 754 // Remove all comments and spaces.
 755 let types = ['multilineComment', 'space'];
 756 parseTree.traverseByTypes(types, function(node, index, parent) {
 757   parent.removeChild(index);
 758 });
 759 ```
 760
 761 ### parseTree.type
 762
 763 ##### Returns
 764
 765 <table>
 766   <tr>
 767     <td><i>{string}</i></td>
 768     <td>
 769       Node type. For a list of available values see
 770       <a href="docs/node-types.md">"Node types"</a>.
 771     </td>
 772   </tr>
 773 </table>
 774
 775
 776 ## Test
 777
 778 To run tests:
 779
 780     npm test
 781
 782 This command will build library files from sources and run tests on all files
 783 in syntax directories.
 784
 785 Every test has 3 files: source stylesheet, expected parse tree and expected
 786 string compiled back from parse tree to css.
 787
 788 If some tests fail, you can find information in test logs:
 789
 790 - `log/test.log` contains all information from stdout;
 791 - `log/expected.txt` contains only expected text;
 792 - `log/result.txt` contains only result text.
 793
 794 The last two are made for your convenience: you can use any diff app to see
 795 the defference between them.
 796
 797 If you want to test one specific string or get a general idea of how Gonzales
 798 works, you can use `test/ast.js` file.
 799 Simply change the first two strings (`css` and `syntax` vars) and run:
 800
 801     node test/single-test.js
 802
 803 ## Report
 804
 805 If you find a bug or want to add a feature, welcome to [Issues](https://github.com/tonyganch/gonzales-pe/issues).
 806
 807 If you are shy but have a question, feel free to [drop me a
 808 line](mailto:tonyganch+gonzales@gmail.com).