source: trip-planner-front/node_modules/snapdragon/README.md@ eed0bf8

Last change on this file since eed0bf8 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 8.7 KB
Line 
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
7Install with [npm](https://www.npmjs.com/):
8
9```sh
10$ npm install --save snapdragon
11```
12
13Created 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
27Substantial 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
36var Snapdragon = require('snapdragon');
37var snapdragon = new Snapdragon();
38```
39
40**Parse**
41
42```js
43var 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
55var 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
63See the [examples](./examples/).
64
65## Getting started
66
67**Parsers**
68
69Parsers are middleware functions used for parsing a string into an ast node.
70
71```js
72var 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
87When 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
99Renderers are _named_ middleware functions that visit over an array of ast nodes to compile a string.
100
101```js
102var 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
112If you want source map support, make sure to emit the position as well.
113
114```js
115var 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
125A 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
139Match a single `.` in a string:
140
1411. Get the starting position by calling `this.position()`
1422. pass a regex for matching a single dot to the `.match` method
1433. if **no match** is found, return `undefined`
1444. 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
151Renderers 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
155Exercise: Parse a dot, then compile it as an escaped dot.
156
157```js
158var 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
170var result = snapdragon.compiler(ast)
171 .set('dot', function (node) {
172 return this.emit('\\' + node.val);
173 })
174 .compile()
175
176console.log(result.output);
177//=> '\.'
178```
179
180## API
181
182### [Parser](lib/parser.js#L19)
183
184Create 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
193Define a non-enumberable property on the `Parser` instance.
194
195**Example**
196
197```js
198parser.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
207Set parser `name` with the given `fn`
208
209**Params**
210
211* `name` **{String}**
212* `fn` **{Function}**
213
214Get parser `name`
215
216**Params**
217
218* `name` **{String}**
219
220Push a `token` onto the `type` stack.
221
222**Params**
223
224* `type` **{String}**
225* `returns` **{Object}** `token`
226
227Pop a token off of the `type` stack
228
229**Params**
230
231* `type` **{String}**
232* `returns` **{Object}**: Returns a token
233
234Return 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
244parser.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
255Define a non-enumberable property on the `Compiler` instance.
256
257**Example**
258
259```js
260compiler.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
280Pull 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
293To 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
301Install 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
316Copyright © 2016, [Jon Schlinkert](https://github.com/jonschlinkert).
317Released 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._
Note: See TracBrowser for help on using the repository browser.