snapdragon-node

What is snapdragon-node?

The snapdragon-node npm package is a utility for creating, visiting, and manipulating AST (Abstract Syntax Tree) nodes. It is commonly used in conjunction with other libraries to parse and transform code or data structures.

What are snapdragon-node's main functionalities?

Creating Nodes

This feature allows you to create new AST nodes. In this example, a new node of type 'text' with the value 'Hello, world!' is created.

const Node = require('snapdragon-node');
const node = new Node({ type: 'text', value: 'Hello, world!' });
console.log(node);

Visiting Nodes

This feature allows you to visit nodes of a specific type within an AST. In this example, all 'text' nodes within the root node are visited, and their values are logged.

const Node = require('snapdragon-node');
const visit = require('snapdragon-visit');
const node = new Node({ type: 'root', nodes: [new Node({ type: 'text', value: 'Hello' }), new Node({ type: 'text', value: 'World' })] });
visit(node, 'text', (node) => console.log(node.value));

Manipulating Nodes

This feature allows you to manipulate existing nodes. In this example, the value of a 'text' node is changed from 'Hello' to 'Hello, world!'.

const Node = require('snapdragon-node');
const node = new Node({ type: 'text', value: 'Hello' });
node.value = 'Hello, world!';
console.log(node);

Other packages similar to snapdragon-node

unist

Unist (Universal Syntax Tree) is a project that provides a set of specifications for syntax trees. It is similar to snapdragon-node in that it deals with ASTs, but it is more focused on providing a universal format for different types of syntax trees.

babel-types

Babel-types is a utility library for AST nodes used by Babel. It provides methods for building, validating, and converting AST nodes. It is similar to snapdragon-node but is more specialized for use with Babel's ecosystem.

README

snapdragon-node

Snapdragon utility for creating a new AST node in custom code, such as plugins.

Install

Install with npm:

$ npm install --save snapdragon-node

Usage

With snapdragon v0.9.0 and higher you can use this.node() to create a new Node, whenever it makes sense.

var Node = require('snapdragon-node');
var Snapdragon = require('snapdragon');
var snapdragon = new Snapdragon();

// example usage inside a parser visitor function
snapdragon.parser.set('foo', function() {
  var pos = this.position();
  // if the regex matches the substring at the current position
  // on `this.input`, return the match
  var match = this.match(/foo/);
  if (match) {
    // if node.type is not defined on the node, the parser
    // will automatically add it
    var node = pos(new Node(match[0]));

    // or, explictly pass a type
    var node = pos(new Node(match[0], 'bar'));
    // or
    var node = pos(new Node({type: 'bar', val: match[0]}));
    return node;
  }
});

API

Node

Create a new AST Node with the given val and type.

Params

• val {String|Object}: Pass a matched substring, or an object to merge onto the node.
• type {String}: The node type to use when val is a string.
• returns {Object}: node instance

Example

var node = new Node('*', 'Star');
var node = new Node({type: 'star', val: '*'});

.define

Define a non-enumberable property on the node instance.

Params

• name {String}
• val {any}
• returns {Object}: returns the node instance

Example

var node = new Node();
node.define('foo', 'something non-enumerable');

.pushNode

Given node foo and node bar, push node bar onto foo.nodes, and set foo as bar.parent.

Params

• node {Object}
• returns {undefined}

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
foo.pushNode(bar);

.addNode

Alias for pushNode for backwards compatibility with 0.1.0.

.unshiftNode

Given node foo and node bar, unshift node bar onto foo.nodes, and set foo as bar.parent.

Params

• node {Object}
• returns {undefined}

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
foo.unshiftNode(bar);

.getNode

Get the first child node from node.nodes that matches the given type. If type is a number, the child node at that index is returned.

Params

• type {String}
• returns {Object}: Returns a child node or undefined.

Example

var child = node.getNode(1); //<= index of the node to get
var child = node.getNode('foo');
var child = node.getNode(/^(foo|bar)$/);
var child = node.getNode(['foo', 'bar']);

.isType

Return true if the node is the given type.

Params

• type {String}
• returns {Boolean}

Example

var node = new Node({type: 'bar'});
cosole.log(node.isType('foo'));          // false
cosole.log(node.isType(/^(foo|bar)$/));  // true
cosole.log(node.isType(['foo', 'bar'])); // true

.hasType

Return true if the node.nodes has the given type.

Params

• type {String}
• returns {Boolean}

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
foo.pushNode(bar);

cosole.log(foo.hasType('qux'));          // false
cosole.log(foo.hasType(/^(qux|bar)$/));  // true
cosole.log(foo.hasType(['qux', 'bar'])); // true

.siblings

Get the siblings array, or null if it doesn't exist.

• returns {Array}

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
foo.pushNode(bar);
foo.pushNode(baz);

console.log(bar.siblings.length) // 2
console.log(baz.siblings.length) // 2

.prev

Get the previous node from the siblings array or null.

• returns {Object}

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
foo.pushNode(bar);
foo.pushNode(baz);

console.log(baz.prev.type) // 'bar'

.next

Get the siblings array, or null if it doesn't exist.

• returns {Object}

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
foo.pushNode(bar);
foo.pushNode(baz);

console.log(bar.siblings.length) // 2
console.log(baz.siblings.length) // 2

.index

Get the node's current index from node.parent.nodes. This should always be correct, even when the parent adds nodes.

• returns {Number}

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
var qux = new Node({type: 'qux'});
foo.pushNode(bar);
foo.pushNode(baz);
foo.unshiftNode(qux);

console.log(bar.index) // 1
console.log(baz.index) // 2
console.log(qux.index) // 0

.first

Get the first node from node.nodes.

• returns {Object}: The first node, or undefiend

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
var qux = new Node({type: 'qux'});
foo.pushNode(bar);
foo.pushNode(baz);
foo.pushNode(qux);

console.log(foo.first.type) // 'bar'

.last

Get the last node from node.nodes.

• returns {Object}: The last node, or undefiend

Example

var foo = new Node({type: 'foo'});
var bar = new Node({type: 'bar'});
var baz = new Node({type: 'baz'});
var qux = new Node({type: 'qux'});
foo.pushNode(bar);
foo.pushNode(baz);
foo.pushNode(qux);

console.log(foo.last.type) // 'qux'

About

Related projects

• breakdance: Breakdance is a node.js library for converting HTML to markdown. Highly pluggable, flexible and easy… more | homepage
• snapdragon-capture: Snapdragon plugin that adds a capture method to the parser instance. | homepage
• snapdragon-cheerio: Snapdragon plugin for converting a cheerio AST to a snapdragon AST. | homepage
• snapdragon-util: Utilities for the snapdragon parser/compiler. | homepage
• snapdragon: Easy-to-use plugin system for creating powerful, fast and versatile parsers and compilers, with built-in source-map… more | homepage

Contributing

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.

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:

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

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

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. MIT

---

This file was generated by verb-generate-readme, v0.4.2, on February 15, 2017.