吕君喜 406d880ac6 first | %!s(int64=3) %!d(string=hai) anos | |
---|---|---|
.. | ||
lib | %!s(int64=3) %!d(string=hai) anos | |
node_modules | %!s(int64=3) %!d(string=hai) anos | |
LICENSE | %!s(int64=3) %!d(string=hai) anos | |
README.md | %!s(int64=3) %!d(string=hai) anos | |
index.js | %!s(int64=3) %!d(string=hai) anos | |
package.json | %!s(int64=3) %!d(string=hai) anos |
Fast, pluggable and easy-to-use parser-renderer factory.
Install with npm:
$ npm install --save snapdragon
Created by jonschlinkert and doowb.
Features
Breaking changes
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.
Compiler
.render
method was renamed to .compile
var Snapdragon = require('snapdragon');
var snapdragon = new Snapdragon();
Parse
var ast = snapdragon.parser('some string', options)
// parser middleware that can be called by other middleware
.set('foo', function () {})
// parser middleware, runs immediately in the order defined
.use(bar())
.use(baz())
Render
// pass the `ast` from the parse method
var res = snapdragon.compiler(ast)
// compiler middleware, called when the name of the middleware
// matches the `node.type` (defined in a parser middleware)
.set('bar', function () {})
.set('baz', function () {})
.compile()
See the examples.
Parsers
Parsers are middleware functions used for parsing a string into an ast node.
var ast = snapdragon.parser(str, options)
.use(function() {
var pos = this.position();
var m = this.match(/^\./);
if (!m) return;
return pos({
// `type` specifies the compiler to use
type: 'dot',
val: m[0]
});
})
AST node
When the parser finds a match, pos()
is called, pushing a token for that node onto the ast that looks something like:
{ type: 'dot',
val: '.',
position:
{ start: { lineno: 1, column: 1 },
end: { lineno: 1, column: 2 } }}
Renderers
Renderers are named middleware functions that visit over an array of ast nodes to compile a string.
var res = snapdragon.compiler(ast)
.set('dot', function (node) {
console.log(node.val)
//=> '.'
return this.emit(node.val);
})
Source maps
If you want source map support, make sure to emit the position as well.
var res = snapdragon.compiler(ast)
.set('dot', function (node) {
return this.emit(node.val, node.position);
})
A parser middleware is a function that returns an abject called a token
. This token is pushed onto the AST as a node.
Example token
{ type: 'dot',
val: '.',
position:
{ start: { lineno: 1, column: 1 },
end: { lineno: 1, column: 2 } }}
Example parser middleware
Match a single .
in a string:
this.position()
.match
methodundefined
pos()
is called, which returns a token with:
type
: the name of the [compiler] to useval
: 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].Renderers are run when the name of the compiler middleware matches the type
defined on an ast node
(which is defined in a parser).
Example
Exercise: Parse a dot, then compile it as an escaped dot.
var ast = snapdragon.parser('.')
.use(function () {
var pos = this.position();
var m = this.match(/^\./);
if (!m) return;
return pos({
// define the `type` of compiler to use
type: 'dot',
val: m[0]
})
})
var result = snapdragon.compiler(ast)
.set('dot', function (node) {
return this.emit('\\' + node.val);
})
.compile()
console.log(result.output);
//=> '\.'
Create a new Parser
with the given input
and options
.
Params
input
{String}options
{Object}Define a non-enumberable property on the Parser
instance.
Example
parser.define('foo', 'bar');
Params
key
{String}: propery nameval
{any}: property valuereturns
{Object}: Returns the Parser instance for chaining.Set parser name
with the given fn
Params
name
{String}fn
{Function}Get parser name
Params
name
{String}Push a token
onto the type
stack.
Params
type
{String}returns
{Object} token
Pop a token off of the type
stack
Params
type
{String}returns
{Object}: Returns a tokenReturn true if inside a stack
node. Types are braces
, parens
or brackets
.
Params
type
{String}returns
{Boolean}Example
parser.isType(node, 'brace');
Params
node
{Object}type
{String}returns
{Boolean}Define a non-enumberable property on the Compiler
instance.
Example
compiler.define('foo', 'bar');
Params
key
{String}: propery nameval
{any}: property valuereturns
{Object}: Returns the Compiler instance for chaining.Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
| Commits | Contributor
|
| --- | --- |
| 106 | jonschlinkert |
| 2 | doowb |
(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)
To generate the readme and API documentation with verb:
$ npm install -g verb verb-generate-readme && verb
Install dev dependencies:
$ npm install -d && npm test
Jon Schlinkert
Copyright © 2016, Jon Schlinkert. Released under the MIT license.
This file was generated by verb-generate-readme, v0.1.31, on October 10, 2016.