snapdragon-parser

Easily parse a string to create an AST.

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

Table of Contents

Install

Install with npm:

$ npm install --save snapdragon-parser

Usage

Parser

Create a new Parser with the given input and options.

Params

• input {String}
• options {Object}

Example

const Parser = require('snapdragon-parser');
const parser = new Parser();

.node

Create a new Node with the given value and type.

Params

• node {Object}: The object to use to create a node
• returns {Object}: returns the created Node instance.

Example

const node = parser.node({type: 'slash', value: '/'});
// sugar for
const Node = require('snapdragon-node');
const node = Node({type: 'slash', value: '/'});

.isNode

Returns true if the given value is an instance of snapdragon-node.

Params

• node {Object}
• returns {Boolean}

.set

Register handler of the given type.

Params

• type {String}
• handler {Function}

Example

parser.set('all', function(tok) {
  // do stuff to tok
  return tok;
});

.get

Get a registered handler function.

Params

• type {String}
• fn {Function}: The handler function to register.

Example

handlers.set('star', function() {
  // do parser, lexer, or compiler stuff
});
const star = handlers.get('star');

.has

Returns true if the parser has a registered handler of the given type.

Params

• {String}: type
• returns {Boolean}

Example

parser.set('star', function() {});
console.log(parser.has('star')); // true

.capture

Capture a node of the given type.

Params

• type {String}: (required)
• regex {RegExp}: (optional)
• lexerFn {Function}: (optional)
• parserFn {Function}: (optional)
• returns {Object}: Returns the Parser instance for chaining.

.isInside

Returns true if the parser is currently "inside" a node of the given type.

Params

• type {String}
• returns {Boolean}

.isBlock

Returns true if node is a "block" node. Block nodes have a nodes array for keeping child nodes.

Params

• node {Object}
• returns {Boolean}

Example

parser.isBlock(new Node()); //=> false
parser.isBlock(new Node({ nodes: [] })); //=> true

.isBlock

Returns true if node is a new "block" node, with either no child nodes, or only an open node.

Params

• node {Object}
• returns {Boolean}

Example

parser.isBlock(new Node()); //=> false
parser.isBlock(new Node({ nodes: [] })); //=> true

.isOpen

Returns true if the given node is an "open" node.

Params

• node {Object}
• returns {Object} parentNode

.isClose

Returns true if the given node is a "close" node.

Params

• node {Object}
• returns {Object} parentNode

.push

Push a child node onto the node.nodes array of the current node on the stack.

Params

• node {Object}: (required)
• returns {Object} node

Events

• emits: push

Example

parser.set('default', function(tok) {
  return this.push(this.node(tok));
});

.pop

Pop the last node from the stack. If a

Params

• node {Object}: (optional)
• returns {Object} node

Events

• emits: pop

Example

parser.set('default', function(tok) {
  return this.push(this.node(tok));
});

.next

Get the next token from the lexer, then calls the registered parser handler for token.type on the token.

• returns {Any}: Returns whatever value the handler returns.

Expect the given type, or throw an exception.

Params

• type {String}

Accept the given type.

Params

• {String}: type

.parse

Parses the given input string and returns an AST object.

Params

• input {String}
• returns {Object}: Returns an AST (abstract syntax tree).

Example

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

Creates a new Parser instance with the given options, and copy the handlers from the current instance to the new instance.

Params

• options {Object}
• parent {Object}: Optionally pass a different parser instance to copy handlers from.
• returns {Object}: Returns a new Parser instance

Concat nodes from another AST to node.nodes.

Params

• node {Object}
• ast {Object}
• returns {Object}

.hasListeners

Returns true if listeners are registered for even name.

Params

• name {String}
• returns {Boolean}

Params

• fn {Function}
• returns {Parser}: Returns the Parser instance.

Example

const myParser = new Parser();
const plugin = parser => {
  // do stuff to parser instance
};
myParser.use(plugin);

.error

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

Params

• msg {String}: Message to use in the Error.
• node {Object}
• returns {Undefined}

Example

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

Get the part of the input string has has already been parsed.

• returns {String}

Params

• parser {Object}
• returns {Boolean}

Example

const Parser = require('parser');
const parser = new Parser();
console.log(Parser.isParser(parser)); //=> true
console.log(Parser.isParser({})); //=> false

About

Related projects

You might also be interested in these projects:

• snapdragon-lexer: Converts a string into an array of tokens, with useful methods for looking ahead and… more | homepage
• snapdragon-node: Snapdragon utility for creating a new AST node in custom code, such as plugins. | homepage
• snapdragon-position: Snapdragon util and plugin for patching the position on an AST node. | homepage
• snapdragon-token: Create a snapdragon token. Used by the snapdragon lexer, but can also be used by… more | homepage

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

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

This file was generated by verb-generate-readme, v0.8.0, on November 24, 2018.