QueryAST

A library to traverse/modify an AST

Documentation

Read the API documentation

Usage

1let createQueryWrapper = require('query-ast')
2let $ = createQueryWrapper(ast, options)

Getting Started

QueryAST aims to provide a jQuery like API for traversing an AST.

1let ast = {
2  type: 'program',
3  value: [{
4    type: 'item_container',
5    value: [{
6      type: 'item',
7      value: 'a'
8    }]
9  }, {
10    type: 'item_container',
11    value: []
12  }, {
13    type: 'item',
14    value: 'b'
15  }]
16}
17
18// Create a QueryWrapper that will be used to traverse/modify an AST
19let $ = createQueryWrapper(ast)
20
21// By default, the QueryWrapper is scoped to the root node
22$('item').length() // 2
23
24// The QueryWrapper can also be scoped to a NodeWrapper or array of NodeWrappers
25$('item_container').filter((n) => {
26  return $(n).has('item')
27}).length() // 1

Selectors

Most of the traversal functions take an optional QueryWrapper~Selector argument that will be use to filter the results.

A selector can be 1 of 3 types:

• string that is compared against the return value of options.getType()
• regexp that is compared against the return value of options.getType()
• function that will be passed a NodeWrapper and expected to return a boolean

1let ast = {
2  type: 'program',
3  value: [{
4    type: 'item_container',
5    value: [{
6      type: 'item',
7      value: 'a'
8    }]
9  }, {
10    type: 'item',
11    value: 'b'
12  }]
13}
14
15let $ = createQueryWrapper(ast)
16
17// String
18$('item').length() // 2
19
20// RegExp
21$(/item/).length() // 3
22
23// Function
24$((n) => n.node.value === 'a').length() // 1

Default format

By default, QueryAST assumes that an AST will be formatted as a node tree where each node has a type key and a value key that either contains the string value of the node or an array of child nodes.

1let ast = {
2  type: 'program',
3  value: [{
4    type: 'item',
5    value: 'a'
6  }]
7}

Alternate formats

Not every AST follows the same format, so QueryAST also provides a way to traverse any tree structure. Below are the default options used to handle the above AST structure.

1let options = {
2  /**
3   * Return true if the node has children
4   *
5   * @param {object} node
6   * @returns {boolean}
7   */
8  hasChildren: (node) => Array.isArray(node.value),
9  /**
10   * Return an array of child nodes
11   *
12   * @param {object} node
13   * @returns {object[]}
14   */
15  getChildren: (node) => node.value,
16  /**
17   * Return a string representation of the node's type
18   *
19   * @param {object} node
20   * @returns {string}
21   */
22  getType: (node) => node.type,
23  /**
24   * Convert the node back to JSON. This usually just means merging the
25   * children back into the node
26   *
27   * @param {object} node
28   * @param {object[]} [children]
29   * @returns {string}
30   */
31  toJSON: (node, children) => {
32    return Object.assign({}, node, {
33      value: children ? children : node.value
34    })
35  },
36  /**
37   * Convert the node to a string
38   *
39   * @param {object} node
40   * @returns {string}
41   */
42  toString: (node) => {
43    return typeof node.value === 'string' ? node.value : ''
44  }
45}

Running tests

Clone the repository, then:

1npm install
2# requires node >= 6.0.0
3npm test

Generate Documentation

1npm run doc