ast-get-object

Getter/setter for nested parsed HTML AST's, querying objects by key/value pairs

Table of Contents

• Install
• Purpose
• API
• For example, reading or querying parsed trees (GET)
• Writing-over example (SET)
• Contributing
• Licence

Install

npm i ast-get-object

// consume via CommonJS require:
const getObj = require("ast-get-object");
// or import as an ES Module:
import getObj from "ast-get-object";

Here's what you'll get:

⬆ back to top

Purpose

When you parse some HTML using posthtml-parser, you get an array which contains a nested tree of strings, objects and arrays. This library lets you query that tree. Later, if you amend and feed this query result again into the get as a third argument, you can overwrite the search results. Basically, search and overwrite right away.

In short, two arguments is GET the results, three arguments is SET (or write over) whatever was queried.

Normally you would use this library to get tags from parsed HTML trees, edit the result and later write it over.

⬆ back to top

API

getObj(input, keyValPair, replacementContentsArr);

API - Input

⬆ back to top

API - Output

Output depends on is it GET mode — 2 arguments, or SET mode — 3 arguments.

• If it's GET mode, result will be an array of parent objects that hold key/value pairs you asked.

• If it's SET mode, result will be of the same type as your input, but with all plain objects that had your key/value pairs replaced with contents of third, replacement array. Mind you, if you will supply too few elements in the replacements array, this library won't do anything to those findings.

⬆ back to top

For example, reading or querying parsed trees (GET)

Let's GET all plain objects that contain key tag and value meta. In a true parsed-HTML fashion, everything is in an array, and there are other plain objects around:

const result = getObj(
  [
    // <- search in this, the first argument, in this case, a nested array
    {
      tag: "meta",
      content: "UTF-8",
      something: "else"
    },
    {
      tag: "title",
      attrs: "Text of the title"
    }
  ],
  {
    // <- search for this object, the second argument
    tag: "meta"
  }
);

result — each parent object that holds your requested key/value pair(s) is put into an array:

[
  {
    tag: "meta",
    content: "UTF-8",
    something: "else"
  }
];

All findings are always wrapped in an array, even if there's just one finding as above.

⬆ back to top

Writing-over example (SET)

Task: take this nested array of plain objects:

[
  {
    tag: ["two", "values"],
    content: "UTF-8",
    something: "else"
  },
  {
    tag: "title",
    attrs: "Text of the title"
  }
];

Find all plain objects that contain key tag and value ['two', 'values'] (so value is an array!).

Replace all those plain objects with:

{
  tag: ['three', 'values', 'here'],
  content: 'UTF-8',
  something: 'else'
}

Solution:

getObj(
  [
    {
      tag: ["two", "values"],
      content: "UTF-8",
      something: "else"
    },
    {
      tag: "title",
      attrs: "Text of the title"
    }
  ],
  {
    tag: ["two", "values"]
  },
  [
    {
      tag: ["three", "values", "here"],
      content: "UTF-8",
      something: "else"
    }
  ]
);

PS. Notice that replacement is put into an array. Also, keep in mind that array is like a cartridge — it will expect a separate value for each finding, so we're OK in this case — there was one finding, and one replacement in our array "cartridge".

Result of the above will be:

[
  {
    tag: ["three", "values", "here"],
    content: "UTF-8",
    something: "else"
  },
  {
    tag: "title",
    attrs: "Text of the title"
  }
];

⬆ back to top

Contributing

• If you want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.

• If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.

• If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)

Copyright © 2018 Codsen Ltd, Roy Revelt