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

   1 # snapdragon [![NPM version](https://img.shields.io/npm/v/snapdragon.svg?style=flat)](https://www.npmjs.com/package/snapdragon) [![NPM downloads](https://img.shields.io/npm/dm/snapdragon.svg?style=flat)](https://npmjs.org/package/snapdragon) [![Build Status](https://img.shields.io/travis/jonschlinkert/snapdragon.svg?style=flat)](https://travis-ci.org/jonschlinkert/snapdragon)
   2
   3 > Fast, pluggable and easy-to-use parser-renderer factory.
   4
   5 ## Install
   6
   7 Install with [npm](https://www.npmjs.com/):
   8
   9 ```sh
  10 $ npm install --save snapdragon
  11 ```
  12
  13 Created by [jonschlinkert](https://github.com/jonschlinkert) and [doowb](https://github.com/doowb).
  14
  15 **Features**
  16
  17 * Bootstrap your own parser, get sourcemap support for free
  18 * All parsing and compiling is handled by simple, reusable middleware functions
  19 * Inspired by the parsers in [pug](http://jade-lang.com) and [css](https://github.com/reworkcss/css).
  20
  21 ## History
  22
  23 ### v0.5.0
  24
  25 **Breaking changes**
  26
  27 Substantial breaking changes were made in v0.5.0! Most of these changes are part of a larger refactor that will be finished in 0.6.0, including the introduction of a `Lexer` class.
  28
  29 * Renderer was renamed to `Compiler`
  30 * the `.render` method was renamed to `.compile`
  31 * Many other smaller changes. A more detailed overview will be provided in 0.6.0. If you don't have to time review code, I recommend you wait for the 0.6.0 release.
  32
  33 ## Usage examples
  34
  35 ```js
  36 var Snapdragon = require('snapdragon');
  37 var snapdragon = new Snapdragon();
  38 ```
  39
  40 **Parse**
  41
  42 ```js
  43 var ast = snapdragon.parser('some string', options)
  44   // parser middleware that can be called by other middleware
  45   .set('foo', function () {})
  46   // parser middleware, runs immediately in the order defined
  47   .use(bar())
  48   .use(baz())
  49 ```
  50
  51 **Render**
  52
  53 ```js
  54 // pass the `ast` from the parse method
  55 var res = snapdragon.compiler(ast)
  56   // compiler middleware, called when the name of the middleware
  57   // matches the `node.type` (defined in a parser middleware)
  58   .set('bar', function () {})
  59   .set('baz', function () {})
  60   .compile()
  61 ```
  62
  63 See the [examples](./examples/).
  64
  65 ## Getting started
  66
  67 **Parsers**
  68
  69 Parsers are middleware functions used for parsing a string into an ast node.
  70
  71 ```js
  72 var ast = snapdragon.parser(str, options)
  73   .use(function() {
  74     var pos = this.position();
  75     var m = this.match(/^\./);
  76     if (!m) return;
  77     return pos({
  78       // `type` specifies the compiler to use
  79       type: 'dot',
  80       val: m[0]
  81     });
  82   })
  83 ```
  84
  85 **AST node**
  86
  87 When the parser finds a match, `pos()` is called, pushing a token for that node onto the ast that looks something like:
  88
  89 ```js
  90 { type: 'dot',
  91   val: '.',
  92   position:
  93    { start: { lineno: 1, column: 1 },
  94      end: { lineno: 1, column: 2 } }}
  95 ```
  96
  97 **Renderers**
  98
  99 Renderers are _named_ middleware functions that visit over an array of ast nodes to compile a string.
 100
 101 ```js
 102 var res = snapdragon.compiler(ast)
 103   .set('dot', function (node) {
 104     console.log(node.val)
 105     //=> '.'
 106     return this.emit(node.val);
 107   })
 108 ```
 109
 110 **Source maps**
 111
 112 If you want source map support, make sure to emit the position as well.
 113
 114 ```js
 115 var res = snapdragon.compiler(ast)
 116   .set('dot', function (node) {
 117     return this.emit(node.val, node.position);
 118   })
 119 ```
 120
 121 ## Docs
 122
 123 ### Parser middleware
 124
 125 A parser middleware is a function that returns an abject called a `token`. This token is pushed onto the AST as a node.
 126
 127 **Example token**
 128
 129 ```js
 130 { type: 'dot',
 131   val: '.',
 132   position:
 133    { start: { lineno: 1, column: 1 },
 134      end: { lineno: 1, column: 2 } }}
 135 ```
 136
 137 **Example parser middleware**
 138
 139 Match a single `.` in a string:
 140
 141 1. Get the starting position by calling `this.position()`
 142 2. pass a regex for matching a single dot to the `.match` method
 143 3. if **no match** is found, return `undefined`
 144 4. if a **match** is found, `pos()` is called, which returns a token with:
 145   - `type`: the name of the [compiler] to use
 146   - `val`: The actual value captured by the regex. In this case, a `.`. Note that you can capture and return whatever will be needed by the corresponding [compiler].
 147   - The ending position: automatically calculated by adding the length of the first capture group to the starting position.
 148
 149 ## Renderer middleware
 150
 151 Renderers are run when the name of the compiler middleware matches the `type` defined on an ast `node` (which is defined in a parser).
 152
 153 **Example**
 154
 155 Exercise: Parse a dot, then compile it as an escaped dot.
 156
 157 ```js
 158 var ast = snapdragon.parser('.')
 159   .use(function () {
 160     var pos = this.position();
 161     var m = this.match(/^\./);
 162     if (!m) return;
 163     return pos({
 164       // define the `type` of compiler to use
 165       type: 'dot',
 166       val: m[0]
 167     })
 168   })
 169
 170 var result = snapdragon.compiler(ast)
 171   .set('dot', function (node) {
 172     return this.emit('\\' + node.val);
 173   })
 174   .compile()
 175
 176 console.log(result.output);
 177 //=> '\.'
 178 ```
 179
 180 ## API
 181
 182 ### [Parser](lib/parser.js#L19)
 183
 184 Create a new `Parser` with the given `input` and `options`.
 185
 186 **Params**
 187
 188 * `input` **{String}**
 189 * `options` **{Object}**
 190
 191 ### [.define](lib/parser.js#L103)
 192
 193 Define a non-enumberable property on the `Parser` instance.
 194
 195 **Example**
 196
 197 ```js
 198 parser.define('foo', 'bar');
 199 ```
 200
 201 **Params**
 202
 203 * `key` **{String}**: propery name
 204 * `val` **{any}**: property value
 205 * `returns` **{Object}**: Returns the Parser instance for chaining.
 206
 207 Set parser `name` with the given `fn`
 208
 209 **Params**
 210
 211 * `name` **{String}**
 212 * `fn` **{Function}**
 213
 214 Get parser `name`
 215
 216 **Params**
 217
 218 * `name` **{String}**
 219
 220 Push a `token` onto the `type` stack.
 221
 222 **Params**
 223
 224 * `type` **{String}**
 225 * `returns` **{Object}** `token`
 226
 227 Pop a token off of the `type` stack
 228
 229 **Params**
 230
 231 * `type` **{String}**
 232 * `returns` **{Object}**: Returns a token
 233
 234 Return true if inside a `stack` node. Types are `braces`, `parens` or `brackets`.
 235
 236 **Params**
 237
 238 * `type` **{String}**
 239 * `returns` **{Boolean}**
 240
 241 **Example**
 242
 243 ```js
 244 parser.isType(node, 'brace');
 245 ```
 246
 247 **Params**
 248
 249 * `node` **{Object}**
 250 * `type` **{String}**
 251 * `returns` **{Boolean}**
 252
 253 ### [.define](lib/compiler.js#L71)
 254
 255 Define a non-enumberable property on the `Compiler` instance.
 256
 257 **Example**
 258
 259 ```js
 260 compiler.define('foo', 'bar');
 261 ```
 262
 263 **Params**
 264
 265 * `key` **{String}**: propery name
 266 * `val` **{any}**: property value
 267 * `returns` **{Object}**: Returns the Compiler instance for chaining.
 268
 269 ## About
 270
 271 ### Related projects
 272
 273 * [braces](https://www.npmjs.com/package/braces): Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces… [more](https://github.com/jonschlinkert/braces) | [homepage](https://github.com/jonschlinkert/braces "Fastest brace expansion for node.js, with the most complete support for the Bash 4.3 braces specification.")
 274 * [expand-brackets](https://www.npmjs.com/package/expand-brackets): Expand POSIX bracket expressions (character classes) in glob patterns. | [homepage](https://github.com/jonschlinkert/expand-brackets "Expand POSIX bracket expressions (character classes) in glob patterns.")
 275 * [extglob](https://www.npmjs.com/package/extglob): Convert extended globs to regex-compatible strings. Add (almost) the expressive power of regular expressions to… [more](https://github.com/jonschlinkert/extglob) | [homepage](https://github.com/jonschlinkert/extglob "Convert extended globs to regex-compatible strings. Add (almost) the expressive power of regular expressions to glob patterns.")
 276 * [micromatch](https://www.npmjs.com/package/micromatch): Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch. | [homepage](https://github.com/jonschlinkert/micromatch "Glob matching for javascript/node.js. A drop-in replacement and faster alternative to minimatch and multimatch.")
 277
 278 ### Contributing
 279
 280 Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
 281
 282 ### Contributors
 283
 284 | **Commits** | **Contributor**<br/> |
 285 | --- | --- |
 286 | 106 | [jonschlinkert](https://github.com/jonschlinkert) |
 287 | 2 | [doowb](https://github.com/doowb) |
 288
 289 ### Building docs
 290
 291 _(This document was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme) (a [verb](https://github.com/verbose/verb) generator), please don't edit the readme directly. Any changes to the readme must be made in [.verb.md](.verb.md).)_
 292
 293 To generate the readme and API documentation with [verb](https://github.com/verbose/verb):
 294
 295 ```sh
 296 $ npm install -g verb verb-generate-readme && verb
 297 ```
 298
 299 ### Running tests
 300
 301 Install dev dependencies:
 302
 303 ```sh
 304 $ npm install -d && npm test
 305 ```
 306
 307 ### Author
 308
 309 **Jon Schlinkert**
 310
 311 * [github/jonschlinkert](https://github.com/jonschlinkert)
 312 * [twitter/jonschlinkert](http://twitter.com/jonschlinkert)
 313
 314 ### License
 315
 316 Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
 317 Released under the [MIT license](https://github.com/jonschlinkert/snapdragon/blob/master/LICENSE).
 318
 319 ***
 320
 321 _This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.1.31, on October 10, 2016._