ast-monkey-util

🐒
ast-monkey-util

Utility library to traverse parsed HTML (AST's) or anything nested (plain objects within arrays within plain objects)

• Check out the parent library which does even more: ast-monkey (npm/monorepo)

Table of Contents

• Install
• Idea
• API - pathNext
• API - pathPrev
• API - pathUp
• object-path notation
• Contributing
• Licence

Install

npm i ast-monkey-util

Consume via a require():

const { pathNext, pathPrev, pathUp } = require("ast-monkey-util");

or as an ES Module:

import { pathNext, pathPrev, pathUp } from "ast-monkey-util";

or for web pages, as a production-ready minified script file (so-called "UMD build"), straight from CDN:

<script src="https://cdn.jsdelivr.net/npm/ast-monkey-util/dist/ast-monkey-util.umd.js"></script>

// in which case you get a global variable "astMonkeyUtil" which you consume like this:
const { pathNext, pathPrev, pathUp } = astMonkeyUtil;

This package has three builds in dist/ folder:

Type	Key in package.json	Path	Size
Main export - CommonJS version, transpiled to ES5, contains require and module.exports	main	dist/ast-monkey-util.cjs.js	2 KB
ES module build that Webpack/Rollup understands. Untranspiled ES6 code with import/export.	module	dist/ast-monkey-util.esm.js	1 KB
UMD build for browsers, transpiled, minified, containing iife's and has all dependencies baked-in	browser	dist/ast-monkey-util.umd.js	1 KB

⬆ back to top

Idea

codsen-parser (npm/monorepo) and emlint (npm/monorepo) both use object-path notation. This utility program contains helper functions to traverse the paths.

Conceptually, we'd use ast-monkey-traverse (npm/monorepo), identify the node we need, then get its path (from the same program, from callbacks), then amend that path (using this program), then use object-path to get/set/delete that path.

⬆ back to top

API - pathNext

It takes (a string) path and increments the last digit:

console.log(pathNext("0"));
// => "1"

console.log(pathNext("9.children.3"));
// => "9.children.4"

console.log(pathNext("9.children.1.children.0"));
// => "9.children.1.children.1"

⬆ back to top

API - pathPrev

It takes (a string) path and decrements the last digit:

console.log(pathPrev("0"));
// => null

console.log(pathPrev("9.children.33"));
// => "9.children.32"

console.log(pathPrev("9.children.1.children.2"));
// => "9.children.1.children.1"

⬆ back to top

API - pathUp

It takes (a string) path and goes "one level" up:

console.log(pathUp("1"));
// => null

console.log(pathUp("9.children.3"));
// => "9"

console.log(pathUp("9.children.1.children.2"));
// => "9.children.1"

Practically, if you think, codsen-parser (npm/monorepo) root is array. The first element thusly is always a number - that some object, a node, meaning tag or text or whatever.

In codsen-parser (npm/monorepo) AST's, child nodes are nested within children key - its value is array:

The following HTML:

<a>text</a>

Would yield AST (many keys omitted):

[
  {
    "type": "tag",
    "start": 0,
    "end": 3,
    "value": "<a>",
    "attribs": [],
    "children": [
      {
        "type": "text",
        "start": 3,
        "end": 7,
        "value": "text"
      }
    ]
  },
  {
    "type": "tag",
    "start": 7,
    "end": 11,
    "value": "</a>",
    "attribs": [],
    "children": []
  }
]

Thus, text node for value "text" is at the path 0.children.0 and "going up" would mean "0" - that's splitting by dot into an array and discarding the last two elements from that array, then joining it back with a dot.

0 . children . 0
        ^      ^
    these two are removed during the "go up" action

⬆ back to top

object-path notation

The notation used in this program is based on object-path - an array elements are marked with dot - if object's key value is an array and we want to a path of the fourth element in there, it's key.3, not key[3].

A drawback of this notation is that keys can't be numeric strings. But the advantage of this notation is that all children are now separated with a dot - you can split by dot String.split(".") and quickly process the path elements, unlike JS notation with square brackets.

⬆ back to top

Contributing

• If you see an error, raise an issue.
• If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
• If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
• If you want to contribute some code, fork the monorepo via GitLab, then write code, then file a pull request on GitLab. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command-line application).

The npm script "dev", the "dev": "rollup -c --dev" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License

Copyright (c) 2015-2020 Roy Revelt and other contributors