@junkio/brkt v0.2.0

brkt

brkt (pronounced "bracket") is a data transformation library and language designed around set-algebra. brkt implements the library generally and the language for data with solely string, number, and boolean types. The language minimally supports numeric operations, ternary expressions, string concatenation, and four set operations.

The object responsible for transforming data is called a Script short for description because it describes the final structure of the data. The keys in a Script are similar to
directories in a file hierarchy, and what brkt does, with the help of a script, is select the contents of those "directories".

When using the language features, a script can be specified as a string parsed by brkt. parseScript, or directly using the Script<K, V=K> and Descriptor<K> objects. The messiness of the latter way can be reduced using the script and desc wrapper functions.

When not using the language features, i.e., for data with custom keys and values, the script is specified directly using Script and Descriptor. The data for this script should be stored in a PolyTree<K, V=K>. Simply put, a PolyTree here can be thought of a tree of keys with optional values. More abstractly, it is a directed acyclic graph representing paths through a data tree, and the values stored at the end of them, making each key in the tree the root of an arborescence. A Script is just an extension of PolyTree that adds the describe method, used to filter the data.

import {PolyTree, ptree} from "./core";

let unixFileHierarchy: PolyTree<string> = ptree([
    ["/", ptree([
        ["bin"],
        ["boot"],
        ["dev"],
        ["etc", ptree([
            ["opt"],
            ["sgml"],
            ["X11"],
            ["xml"]
        ])],
        ["home"],
        ["lib"],
        ["lib<qual>"],
        ["media"],
        ["mnt"],
        ["opt"],
        ["proc"],
        ["root"],
        ["run"],
        ["sbin"],
        ["srv"],
        ["sys"],
        ["tmp"],
        ["usr", ptree([
            ["bin"],
            ["include"],
            ["lib"],
            ["lib<qual>"],
            ["local"],
            ["sbin"],
            ["share"],
            ["src"],
            ["X11R"],
        ])],
        ["var", ptree([
            ["cache"],
            ["lib"],
            ["lock"],
            ["log"],
            ["mail"],
            ["opt"],
            ["run"],
            ["spool"],
            ["tmp"]
        ])]
    ])]
])

unixScript: string = `
{
    "/"["root"]: {
        "bin",
        "boot",
        "dev",
        "home",
        "media",
        "etc",
        "expr": [(1 + 2 * 4) / 3],
        "set-alg": [$"/"] & [$"/"."var"],
        "str-con": ["hello "] + ["world"]
}
            `
let script: Script<string> = brkt.parseScript(unixScript);
let output: PolyTree<string> = script.describe(unixData);

console.log(output) //will not be pretty-printed like below
/*  {
        "root": {
                "bin",
                "boot",
                "dev",
                "home",
                "media",
                "etc": {
                    "opt", 
                    "sgml", 
                    "X11", 
                    "xml"
                }, 
                "expr": "3",
                "str-con": "hello world"
                "set-alg":{
                    "lib", 
                    "opt", 
                    "run", 
                    "tmp"
                }
        }
 */

What's happening:

• "/"["root"]

  • This is a key aliasing operation. What this does search for the key "/" in the data, and stores it's value in the output data under the key "root".

• "expr": [(1 + 2 * 4) / 3]

  • Simple numeric expression, brkt also supports ternary expressions of the form p ? t: f.

• ["hello "] + ["world"]

  • Concatenates two strings. Note, expressions return either a string or a subtree. Concatenation requires that both expressions resolve to a string.

• $"/"

  • This represents a path through the data tree. A path is a .-separated list of keys. It is valid in any expression context, and it's type is that of the value pointed to by the last key.

• [$"/"] & [$"/"."var"]

  • & is the symbol for set intersection, also supported is - (set difference), ^ (set symmetric difference) and | (set union). Similarly to string concatenation, the values returned by expressions in a set operation must be trees, and the operation will be performed on the keys of the set, regardless of what the value is. Set operators all have the same precedence and all operations are performed left-to-right.

• Also note, that in the description we moved where "home" and "media" originally appeared.