All of the examples in this document assume the following two lines of setup code exist first:
var Snapdragon = require('snapdragon');var snapdragon = new Snapdragon();
Parse a string
var ast = snapdragon.parser // parser handlers (essentially middleware) // used for parsing substrings to create tokens .set('foo', function () {}) .set('bar', function () {}) .parse('some string', options);
Compile an AST returned from .parse()
var result = snapdragon.compiler // compiler handlers (essentially middleware), // called on a node when the `node.type` matches // the name of the handler .set('foo', function () {}) .set('bar', function () {}) // pass the `ast` from the parse method .compile(ast)// the compiled stringconsole.log(result.output);
Parser handlers are middleware functions responsible for matching substrings to create tokens:
Example handler
var ast = snapdragon.parser .set('dot', function() { var pos = this.position(); var m = this.match(/^\./); if (!m) return; return pos({ // the "type" will be used by the compiler later on, // we'll go over this in the compiler docs type: 'dot', // "val" is the string captured by ".match", // in this case that would be '.' val: m[0] }); }) .parse('.'[, options])
As a side node, it's not scrictly required to set the type on the token, since the parser will add it to the token if it's undefined, based on the name of the handler. But it's good practice since tokens aren't always returned.
Example token
And the resulting tokens look something like this:
{ type: 'dot', val: '.'}
Position
Next, pos() is called on the token as it's returned, which patches the token with the position of the string that was captured:
When the token is returned, the parser pushes it onto the nodes array of the "previous" node (since we're in a tree, the "previous" node might be literally the last node that was created, or it might be the "parent" node inside a nested context, like when parsing brackets or something with an open or close), at which point the token begins its life as an AST node.
Wrapping up
In the parser calls all handlers and cannot find a match for a substring, an error is thrown.
Assuming the parser finished parsing the entire string, an AST is returned.
Compiling
The compiler's job is to take the AST created by the parser and convert it to a new string. It does this by iterating over each node on the AST and calling a function on the node based on its type.
This function is called a "handler".
Compiler handlers
Handlers are named middleware functions that are called on a node when node.type matches the name of a registered handler.
var result = snapdragon.compiler .set('dot', function (node) { console.log(node.val) //=> '.' return this.emit(node.val); })
If node.type does not match a registered handler, an error is thrown.
Source maps
If you want source map support, make sure to emit the entire node as the second argument as well (this allows the compiler to get the node.position).
var res = snapdragon.compiler .set('dot', function (node) { return this.emit(node.val, node); })
All together
This is a very basic example, but it shows how to parse a dot, then compile it as an escaped dot.
var Snapdragon = require('..');var snapdragon = new Snapdragon();var ast = snapdragon.parser .set('dot', function () { var pos = this.position(); var m = this.match(/^\./); if (!m) return; return pos({ type: 'dot', val: m[0] }) }) .parse('.')var result = snapdragon.compiler .set('dot', function (node) { return this.emit('\\' + node.val); }) .compile(ast)console.log(result.output);//=> '\.'
returns{Function}: Returns a function that takes a node
Example
parser.set('foo', function(node) { var pos = this.position(); var match = this.match(/foo/); if (match) { // call `pos` with the node return pos(this.node(match[0])); }});
Return true if inside a "set" of the given type. Sets are created manually by adding a type to parser.sets. A node is "inside" a set when an *.open node for the given type was previously pushed onto the set. The type is removed from the set by popping it off when the *.close node for the given type is reached.
Params
type{String}
returns{Boolean}
Example
parser.set('close', function() { var pos = this.position(); var m = this.match(/^\}/); if (!m) return; if (!this.isInside('bracket')) { throw new Error('missing opening bracket'); }});
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.
Renderer was renamed to Compiler
the .render method was renamed to .compile
About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running Tests
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:
$ npm install && npm test
Building docs
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command: