@gram-data/gram-ast

()-[define]->(ast)

Gram abstract syntax tree definitions, tokenizing regexes, and utilities like type guards.

How to gram-ast

Install:

npm install @gram-data/gram-ast

Use [[gram-parse]] to create an AST, then introspect with gram-ast:

import { isGramSeq, isGramNode, isGramEdge } from '@gram-data/gram-ast';
import { toAST } from '@gram-data/gram-parse';  

const src = '(a)-->(b)';
const parsed = toAST(src);

// the top-level of the AST is a sequence of paths
console.assert(isGramSeq(parsed));

// the first path should be an edge
const firstPath = parsed.children[0];
console.assert(isGramEdge(firstPath));

// the children of an edge are nodes
console.assert(isGramNode(firstPath.children[0]));
console.assert(isGramNode(firstPath.children[1]));

Syntax Tree

The gram AST is based on the unist specification for syntax trees. Many of the tools and techniques of the unified ecosystem can be applied to working with gram.

Gram represents data using two basic elements: paths and sequences.

Paths provide structure. Sequences provide order.

{@linkcode gram-ast.GramSeq | GramSeq}

A gram sequence is the root element of an AST. It is exactly what it sounds like: a sequence of elements where each element is a path.

The AST type is useful in returning a well-rooted tree that can be processed by general-purpose AST tools like unist-util-visit.

In practice this is equivalent to a GramPath[]. Most gram functions will accept either.

{@linkcode gram-ast.GramPath | GramPath}

A gram path is either an empty path, or the composition of two other paths. The data structure of a path is like a list which remembers how it was assembled. The list elements are other paths.

Each path has its own identity, labels and a data record.

record

In the AST, records are a multimap presented as an array of name/value properties. That means a property name may appear more than once, with different or the same values.

When mapping to a data model, choose one of these strageies for handling the multimapped properties:

• single-state: pick the first or last value (recommended)
• join: accumulate the values into an array
• reduce: aggregate the values into a single value

Next Steps

• Learn more about parsing with [[gram-ast]]
• Transform to js objects using [[gram-value]]
• Serialize back to text using [[gram-stringify]]