scrumpy

Scrumps all of the juiciest nodes from your trees!

• You what?
• What's it useful for?
• How do I install it?
• How do I use it?
  • Loading the library
  • Finding nodes
  • Options
  • Examples
• Does it handle recursive/circular tree structures?
• Is there a change log?
• How do I set up the dev environment?
• What license is it released under?

You what?

Given a tree of data and criteria to identify interesting nodes, scrumpy will find matching nodes in the tree.

What's it useful for?

One use is for finding nodes in abstract syntax trees.

For instance, if you want to find nodes representing particular tokens in the Mozilla-format AST returned by acorn and esprima, you have to walk the tree and interrogate every node.

Instead of doing that yourself, scrumpy takes a root node and some search criteria, then returns an array of matching nodes.

How do I install it?

Via npm:

npm i scrumpy --save

Or if you just want the git repo:

git clone [email protected]:philbooth/scrumpy.git

How do I use it?

Loading the library

Use require:

const scrumpy = require('scrumpy');

Finding nodes

Call scrumpy(tree, criteria), where tree is the root node to start the search from and criteria is a subtree of properties to match against:

const nodes = scrumpy(tree, criteria)

Options

There is also an optional third argument to scrumpy. You can use it to tweak the search behaviour:

const nodes = scrumpy(tree, criteria, {
  recursive: false, // Set to false to only search the root level for matches.
  array: false,     // Set to false to ignore array items when searching.
  all: false        // Set to false to only return the first match (depth-first).
})

Examples

Find assignments to module.exports in an abstract syntax tree:

const nodes = scrumpy(ast, {
  type: 'ExpressionStatement',
  left: {
    type: 'MemberExpression',
    object: {
      type: 'Identifier',
      name: 'module'
    },
    property: {
      type: 'Identifier',
      name: 'exports'
    }
  }
})

Find returns from a function, discounting those from any nested functions:

const nodes = scrumpy(functionNode.body.body, {
  type: 'ReturnStatement'
}, {
  recursive: false
})

Find the first const declaration:

const node = scrumpy(ast, {
  type: 'VariableDeclaration',
  kind: 'const'
}, {
  all: false
})

Does it handle recursive/circular tree structures?

Yep.

Is there a change log?

Yes.

How do I set up the dev environment?

To install the dependencies:

npm i

To run the tests:

npm t

To lint the code:

npm run lint

What license is it released under?

MIT.