diff options
Diffstat (limited to 'node_modules/snapdragon-node/README.md')
| -rw-r--r-- | node_modules/snapdragon-node/README.md | 453 |
1 files changed, 453 insertions, 0 deletions
diff --git a/node_modules/snapdragon-node/README.md b/node_modules/snapdragon-node/README.md new file mode 100644 index 0000000..2300a3c --- /dev/null +++ b/node_modules/snapdragon-node/README.md @@ -0,0 +1,453 @@ +# snapdragon-node [](https://www.npmjs.com/package/snapdragon-node) [](https://npmjs.org/package/snapdragon-node) [](https://npmjs.org/package/snapdragon-node) [](https://travis-ci.org/jonschlinkert/snapdragon-node) + +> Snapdragon utility for creating a new AST node in custom code, such as plugins. + +## Install + +Install with [npm](https://www.npmjs.com/): + +```sh +$ npm install --save snapdragon-node +``` + +## Usage + +With [snapdragon](https://github.com/jonschlinkert/snapdragon) v0.9.0 and higher you can use `this.node()` to create a new `Node`, whenever it makes sense. + +```js +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() { + // get the current "start" position + var pos = this.position(); + + // returns the match if regex matches the substring + // at the current position on `parser.input` + var match = this.match(/foo/); + if (match) { + // call "pos" on the node, to set the start and end + // positions, and return the node to push it onto the AST + // (snapdragon will push the node onto the correct + // nodes array, based on the stack) + return pos(new Node({type: 'bar', val: match[0]})); + } +}); +``` + +## API + +### [Node](index.js#L22) + +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** + +```js +var node = new Node('*', 'Star'); +var node = new Node({type: 'star', val: '*'}); +``` + +### [.isNode](index.js#L61) + +Returns true if the given value is a node. + +**Params** + +* `node` **{Object}** +* `returns` **{Boolean}** + +**Example** + +```js +var Node = require('snapdragon-node'); +var node = new Node({type: 'foo'}); +console.log(Node.isNode(node)); //=> true +console.log(Node.isNode({})); //=> false +``` + +### [.define](index.js#L80) + +Define a non-enumberable property on the node instance. Useful for adding properties that shouldn't be extended or visible during debugging. + +**Params** + +* `name` **{String}** +* `val` **{any}** +* `returns` **{Object}**: returns the node instance + +**Example** + +```js +var node = new Node(); +node.define('foo', 'something non-enumerable'); +``` + +### [.isEmpty](index.js#L100) + +Returns true if `node.val` is an empty string, or `node.nodes` does not contain any non-empty text nodes. + +**Params** + +* `fn` **{Function}**: (optional) Filter function that is called on `node` and/or child nodes. `isEmpty` will return false immediately when the filter function returns false on any nodes. +* `returns` **{Boolean}** + +**Example** + +```js +var node = new Node({type: 'text'}); +node.isEmpty(); //=> true +node.val = 'foo'; +node.isEmpty(); //=> false +``` + +### [.push](index.js#L118) + +Given node `foo` and node `bar`, push node `bar` onto `foo.nodes`, and set `foo` as `bar.parent`. + +**Params** + +* `node` **{Object}** +* `returns` **{Number}**: Returns the length of `node.nodes` + +**Example** + +```js +var foo = new Node({type: 'foo'}); +var bar = new Node({type: 'bar'}); +foo.push(bar); +``` + +### [.unshift](index.js#L140) + +Given node `foo` and node `bar`, unshift node `bar` onto `foo.nodes`, and set `foo` as `bar.parent`. + +**Params** + +* `node` **{Object}** +* `returns` **{Number}**: Returns the length of `node.nodes` + +**Example** + +```js +var foo = new Node({type: 'foo'}); +var bar = new Node({type: 'bar'}); +foo.unshift(bar); +``` + +### [.pop](index.js#L167) + +Pop a node from `node.nodes`. + +* `returns` **{Number}**: Returns the popped `node` + +**Example** + +```js +var node = new Node({type: 'foo'}); +node.push(new Node({type: 'a'})); +node.push(new Node({type: 'b'})); +node.push(new Node({type: 'c'})); +node.push(new Node({type: 'd'})); +console.log(node.nodes.length); +//=> 4 +node.pop(); +console.log(node.nodes.length); +//=> 3 +``` + +### [.shift](index.js#L190) + +Shift a node from `node.nodes`. + +* `returns` **{Object}**: Returns the shifted `node` + +**Example** + +```js +var node = new Node({type: 'foo'}); +node.push(new Node({type: 'a'})); +node.push(new Node({type: 'b'})); +node.push(new Node({type: 'c'})); +node.push(new Node({type: 'd'})); +console.log(node.nodes.length); +//=> 4 +node.shift(); +console.log(node.nodes.length); +//=> 3 +``` + +### [.remove](index.js#L205) + +Remove `node` from `node.nodes`. + +**Params** + +* `node` **{Object}** +* `returns` **{Object}**: Returns the removed node. + +**Example** + +```js +node.remove(childNode); +``` + +### [.find](index.js#L231) + +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** + +```js +var child = node.find(1); //<= index of the node to get +var child = node.find('foo'); //<= node.type of a child node +var child = node.find(/^(foo|bar)$/); //<= regex to match node.type +var child = node.find(['foo', 'bar']); //<= array of node.type(s) +``` + +### [.isType](index.js#L249) + +Return true if the node is the given `type`. + +**Params** + +* `type` **{String}** +* `returns` **{Boolean}** + +**Example** + +```js +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](index.js#L270) + +Return true if the `node.nodes` has the given `type`. + +**Params** + +* `type` **{String}** +* `returns` **{Boolean}** + +**Example** + +```js +var foo = new Node({type: 'foo'}); +var bar = new Node({type: 'bar'}); +foo.push(bar); + +cosole.log(foo.hasType('qux')); // false +cosole.log(foo.hasType(/^(qux|bar)$/)); // true +cosole.log(foo.hasType(['qux', 'bar'])); // true +``` + +* `returns` **{Array}** + +**Example** + +```js +var foo = new Node({type: 'foo'}); +var bar = new Node({type: 'bar'}); +var baz = new Node({type: 'baz'}); +foo.push(bar); +foo.push(baz); + +console.log(bar.siblings.length) // 2 +console.log(baz.siblings.length) // 2 +``` + +* `returns` **{Number}** + +**Example** + +```js +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.push(bar); +foo.push(baz); +foo.unshift(qux); + +console.log(bar.index) // 1 +console.log(baz.index) // 2 +console.log(qux.index) // 0 +``` + +* `returns` **{Object}** + +**Example** + +```js +var foo = new Node({type: 'foo'}); +var bar = new Node({type: 'bar'}); +var baz = new Node({type: 'baz'}); +foo.push(bar); +foo.push(baz); + +console.log(baz.prev.type) // 'bar' +``` + +* `returns` **{Object}** + +**Example** + +```js +var foo = new Node({type: 'foo'}); +var bar = new Node({type: 'bar'}); +var baz = new Node({type: 'baz'}); +foo.push(bar); +foo.push(baz); + +console.log(bar.siblings.length) // 2 +console.log(baz.siblings.length) // 2 +``` + +* `returns` **{Object}**: The first node, or undefiend + +**Example** + +```js +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.push(bar); +foo.push(baz); +foo.push(qux); + +console.log(foo.first.type) // 'bar' +``` + +* `returns` **{Object}**: The last node, or undefiend + +**Example** + +```js +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.push(bar); +foo.push(baz); +foo.push(qux); + +console.log(foo.last.type) // 'qux' +``` + +* `returns` **{Object}**: The last node, or undefiend + +**Example** + +```js +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.push(bar); +foo.push(baz); +foo.push(qux); + +console.log(foo.last.type) // 'qux' +``` + +## Release history + +Changelog entries are classified using the following labels from [keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog): + +* `added`: for new features +* `changed`: for changes in existing functionality +* `deprecated`: for once-stable features removed in upcoming releases +* `removed`: for deprecated features removed in this release +* `fixed`: for any bug fixes + +Custom labels used in this changelog: + +* `dependencies`: bumps dependencies +* `housekeeping`: code re-organization, minor edits, or other changes that don't fit in one of the other categories. + +### [2.0.0] - 2017-05-01 + +**Changed** + +* `.unshiftNode` was renamed to [.unshift](#unshift) +* `.pushNode` was renamed to [.push](#push) +* `.getNode` was renamed to [.find](#find) + +**Added** + +* [.isNode](#isNode) +* [.isEmpty](#isEmpty) +* [.pop](#pop) +* [.shift](#shift) +* [.remove](#remove) + +### [0.1.0] + +First release. + +## About + +### Related projects + +* [breakdance](https://www.npmjs.com/package/breakdance): Breakdance is a node.js library for converting HTML to markdown. Highly pluggable, flexible and easy… [more](http://breakdance.io) | [homepage](http://breakdance.io "Breakdance is a node.js library for converting HTML to markdown. Highly pluggable, flexible and easy to use. It's time for your markup to get down.") +* [snapdragon-capture](https://www.npmjs.com/package/snapdragon-capture): Snapdragon plugin that adds a capture method to the parser instance. | [homepage](https://github.com/jonschlinkert/snapdragon-capture "Snapdragon plugin that adds a capture method to the parser instance.") +* [snapdragon-cheerio](https://www.npmjs.com/package/snapdragon-cheerio): Snapdragon plugin for converting a cheerio AST to a snapdragon AST. | [homepage](https://github.com/jonschlinkert/snapdragon-cheerio "Snapdragon plugin for converting a cheerio AST to a snapdragon AST.") +* [snapdragon-util](https://www.npmjs.com/package/snapdragon-util): Utilities for the snapdragon parser/compiler. | [homepage](https://github.com/jonschlinkert/snapdragon-util "Utilities for the snapdragon parser/compiler.") +* [snapdragon](https://www.npmjs.com/package/snapdragon): Easy-to-use plugin system for creating powerful, fast and versatile parsers and compilers, with built-in source-map… [more](https://github.com/jonschlinkert/snapdragon) | [homepage](https://github.com/jonschlinkert/snapdragon "Easy-to-use plugin system for creating powerful, fast and versatile parsers and compilers, with built-in source-map support.") + +### Contributing + +Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new). + +Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards. + +### Building docs + +_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_ + +To generate the readme, run the following command: + +```sh +$ 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: + +```sh +$ npm install && npm test +``` + +### Author + +**Jon Schlinkert** + +* [github/jonschlinkert](https://github.com/jonschlinkert) +* [twitter/jonschlinkert](https://twitter.com/jonschlinkert) + +### License + +Copyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert). +Released under the [MIT License](LICENSE). + +*** + +_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on June 25, 2017._
\ No newline at end of file |