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
• Usage
• About

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

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

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

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

(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

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.