Home

Awesome

snapdragon NPM version NPM monthly downloads NPM total downloads Linux Build Status

Easy-to-use plugin system for creating powerful, fast and versatile parsers and compilers, with built-in source-map support.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Table of Contents

<details> <summary><strong>Details</strong></summary> </details>

Install

Install with npm:

$ npm install --save snapdragon

Created by jonschlinkert and doowb.

Features

Quickstart example

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 string
console.log(result.output);

See the examples.

Parsing

Parser handlers

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:

{ type: 'dot',
  val: '.',
  position:
   { start: { lineno: 1, column: 1 },
     end: { lineno: 1, column: 2 } }}

Life as an AST node

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);
//=> '\.'

API

Parser

Create a new Parser with the given input and options.

Params

Example

var Snapdragon = require('snapdragon');
var Parser = Snapdragon.Parser;
var parser = new Parser();

.error

Throw a formatted error message with details including the cursor position.

Params

Example

parser.set('foo', function(node) {
  if (node.val !== 'foo') {
    throw this.error('expected node.val to be "foo"', node);
  }
});

.define

Define a non-enumberable property on the Parser instance. This is useful in plugins, for exposing methods inside handlers.

Params

Example

parser.define('foo', 'bar');

.node

Create a new Node with the given val and type.

Params

Example

parser.node('/', 'slash');

.position

Mark position and patch node.position.

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]));
  }
});

.set

Add parser type with the given visitor fn.

Params

Example

 parser.set('all', function() {
   var match = this.match(/^./);
   if (match) {
     return this.node(match[0]);
   }
 });

.get

Get parser type.

Params

Example

var fn = parser.get('slash');

.push

Push a node onto the stack for the given type.

Params

Example

parser.set('all', function() {
  var match = this.match(/^./);
  if (match) {
    var node = this.node(match[0]);
    this.push(node);
    return node;
  }
});

.pop

Pop a token off of the stack of the given type.

Params

Example

parser.set('close', function() {
  var match = this.match(/^\}/);
  if (match) {
    var node = this.node({
      type: 'close',
      val: match[0]
    });

    this.pop(node.type);
    return node;
  }
});

.isInside

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

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');
  }
});

.isType

Return true if node is the given type.

Params

Example

parser.isType(node, 'brace');

.prev

Get the previous AST node from the parser.stack (when inside a nested context) or parser.nodes.

Example

var prev = this.prev();

.prev

Match regex, return captures, and update the cursor position by match[0] length.

Params

Example

// make sure to use the starting regex boundary: "^"
var match = this.match(/^\./);

Params

Example

var ast = parser.parse('foo/bar');

Compiler

Create a new Compiler with the given options.

Params

Example

var Snapdragon = require('snapdragon');
var Compiler = Snapdragon.Compiler;
var compiler = new Compiler();

.error

Throw a formatted error message with details including the cursor position.

Params

Example

compiler.set('foo', function(node) {
  if (node.val !== 'foo') {
    throw this.error('expected node.val to be "foo"', node);
  }
});

.emit

Concat the given string to compiler.output.

Params

Example

compiler.set('foo', function(node) {
  this.emit(node.val, node);
});

.noop

Emit an empty string to effectively "skip" the string for the given node, but still emit the position and node type.

Params

Example

// example: do nothing for beginning-of-string
snapdragon.compiler.set('bos', compiler.noop);

.define

Define a non-enumberable property on the Compiler instance. This is useful in plugins, for exposing methods inside handlers.

Params

Example

compiler.define('customMethod', function() {
  // do stuff
});

.set

Add a compiler fn for the given type. Compilers are called when the .compile method encounters a node of the given type to generate the output string.

Params

Example

compiler
  .set('comma', function(node) {
    this.emit(',');
  })
  .set('dot', function(node) {
    this.emit('.');
  })
  .set('slash', function(node) {
    this.emit('/');
  });

.get

Get the compiler of the given type.

Params

Example

var fn = compiler.get('slash');

.visit

Visit node using the registered compiler function associated with the node.type.

Params

Example

compiler
  .set('i', function(node) {
    this.visit(node);
  })

.mapVisit

Iterate over node.nodes, calling visit on each node.

Params

Example

compiler
  .set('i', function(node) {
    utils.mapVisit(node);
  })

.compile

Compile the given AST and return a string. Iterates over ast.nodes with mapVisit.

Params

Example

var ast = parser.parse('foo');
var str = compiler.compile(ast);

Snapdragon in the wild

A few of the libraries that use snapdragon:

History

v0.9.0

Breaking changes!

In an attempt to make snapdragon lighter, more versatile, and more pluggable, some major changes were made in this release.

v0.5.0

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.

About

<details> <summary><strong>Contributing</strong></summary>

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

</details> <details> <summary><strong>Running Tests</strong></summary>

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
</details> <details> <summary><strong>Building docs</strong></summary>

(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:

$ npm install -g verbose/verb#dev verb-generate-readme && verb
</details>

Related projects

A few of the libraries that use snapdragon:

Contributors

CommitsContributor
156jonschlinkert
3doowb
2danez
1EdwardBetts

Author

Jon Schlinkert

License

Copyright © 2018, Jon Schlinkert. Released under the MIT License.


This file was generated by verb-generate-readme, v0.6.0, on March 20, 2018.