gram.js API

Globals / gram-ast

Package: 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.

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.

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

Index

Interfaces

• BooleanLiteral
• DateLiteral
• DateTimeLiteral
• DecimalLiteral
• DurationLiteral
• GramEdge
• GramEmptyPath
• GramNode
• GramPath
• GramProperty
• GramSeq
• HexadecimalLiteral
• IntegerLiteral
• MeasurementLiteral
• OctalLiteral
• StringLiteral
• TaggedTextLiteral
• TimeIntervalLiteral
• TimeLiteral
• UriLiteral
• WellKnownTextLiteral

Type aliases

• CombinationKind
• GramLiteral
• GramPathlike
• GramRecord
• GramRecordValue
• PathKind
• RelationshipKind
• TaggedLiteral

Variables

• EMPTY_PATH_ID
• boolean
• decimal
• doubleQuotedString
• hexadecimal
• identifier
• integer
• measurement
• octal
• singleQuotedString
• symbol
• taggedString
• tickedString

Functions

• isBooleanLiteral
• isDateLiteral
• isDateTimeLiteral
• isDecimalLiteral
• isDuration
• isGramEdge
• isGramEmptyPath
• isGramLiteral
• isGramLiteralArray
• isGramNode
• isGramPath
• isGramProperty
• isGramRecord
• isGramSeq
• isHexadecimalLiteral
• isIntegerLiteral
• isMeasurementLiteral
• isOctalLiteral
• isStringLiteral
• isTaggedLiteral
• isTimeInterval
• isTimeLiteral
• isUriLiteral
• isValidIdentifier
• isWellKnownTextLiteral

Type aliases

CombinationKind

Ƭ CombinationKind: "pair"

Defined in packages/gram-ast/src/index.ts:196

Kind of path which combines two paths together without implying any semantics.

One of:

• pair (a),(b)

GramLiteral

Ƭ GramLiteral: BooleanLiteral | StringLiteral | TaggedTextLiteral | IntegerLiteral | MeasurementLiteral | DecimalLiteral | HexadecimalLiteral | OctalLiteral

Defined in packages/gram-ast/src/index.ts:283

Discrimination union of all possible literals.

GramPathlike

Ƭ GramPathlike: GramPath | GramNode | GramEdge

Defined in packages/gram-ast/src/index.ts:213

GramPathlike is a discriminated union of GramPath with its two primary specializations, GramNode and GramEdge.

GramRecord

Ƭ GramRecord: Map<string, GramRecordValue>

Defined in packages/gram-ast/src/index.ts:228

A GramRecord is a map of name/value pairs.

GramRecordValue

Ƭ GramRecordValue: GramLiteral | GramRecord | GramRecordValue[]

Defined in packages/gram-ast/src/index.ts:222

GramRecordValue is a union of literals, literal arrays and nested records. This forms a familiar OO-style structure.

PathKind

Ƭ PathKind: RelationshipKind | CombinationKind

Defined in packages/gram-ast/src/index.ts:207

PathKind describes the nature of the path composition.

One of:

• RelationshipKind: ‘left’, ‘right’, ‘either’
• CombinationKind: pair

RelationshipKind

Ƭ RelationshipKind: "left" | "right" | "either"

Defined in packages/gram-ast/src/index.ts:185

Kind of path which forms a graph relationship.

One of:

• left (a)<--(b)
• right (a)-->(b)
• either (a)--(b)

TaggedLiteral

Ƭ TaggedLiteral: DateLiteral | TimeLiteral | DateTimeLiteral | TimeIntervalLiteral | DurationLiteral | WellKnownTextLiteral | UriLiteral

Defined in packages/gram-ast/src/index.ts:429

Variables

EMPTY_PATH_ID

• Const EMPTY_PATH_ID: "ø" = “ø”

Defined in packages/gram-ast/src/index.ts:100

Constant identity for empty paths: ø.

boolean

• Const boolean: RegExp = /true|false|TRUE|FALSE\b(?!@)/

Defined in packages/gram-ast/src/gram-tokens.ts:1

decimal

• Const decimal: RegExp = /-?(?:[0-9]|[1-9][0-9]+).[0-9]+(?:[eE][-+]?[0-9]+)?\b(?!@)/

Defined in packages/gram-ast/src/gram-tokens.ts:5

doubleQuotedString

• Const doubleQuotedString: RegExp = /”(?:\[“bfnrt/\]|\u[a-fA-F0-9]{4}|[^”\])*”/

Defined in packages/gram-ast/src/gram-tokens.ts:8

hexadecimal

• Const hexadecimal: RegExp = /-?0x(?:[0-9a-fA-F]+)\b(?!@)/

Defined in packages/gram-ast/src/gram-tokens.ts:2

identifier

• Const identifier: RegExp = /[0-9a-zA-Z_@]+\b@*/

Defined in packages/gram-ast/src/gram-tokens.ts:12

integer

• Const integer: RegExp = /-?(?:[0-9]|[1-9][0-9]+)(?:[eE][-+]?[0-9]+)?\b(?!@)/

Defined in packages/gram-ast/src/gram-tokens.ts:6

measurement

• Const measurement: RegExp = /-?(?:[0-9]|[1-9][0-9]+)(?:.[0-9]+)?[a-zA-Z]+\b(?!@)/

Defined in packages/gram-ast/src/gram-tokens.ts:4

octal

• Const octal: RegExp = /-?0(?:[0-7]+)\b(?!@)/

Defined in packages/gram-ast/src/gram-tokens.ts:3

singleQuotedString

• Const singleQuotedString: RegExp = /’(?:\[‘bfnrt/\]|\u[a-fA-F0-9]{4}|[^’\])*’/

Defined in packages/gram-ast/src/gram-tokens.ts:9

symbol

• Const symbol: RegExp = /[a-zA-Z_][0-9a-zA-Z_]*\b(?!@)/

Defined in packages/gram-ast/src/gram-tokens.ts:11

taggedString

• Const taggedString: RegExp = /[a-zA-Z][0-9a-zA-Z_@]`(?:\[`bfnrt/\]|\u[a-fA-F0-9]{4}|[^`\])`/

Defined in packages/gram-ast/src/gram-tokens.ts:7

tickedString

• Const tickedString: RegExp = /`(?:\[`bfnrt/\]|\u[a-fA-F0-9]{4}|[^`\])*`/

Defined in packages/gram-ast/src/gram-tokens.ts:10

Functions

isBooleanLiteral

▸ ConstisBooleanLiteral(o: any): o is TextLiteral

Defined in packages/gram-ast/src/index.ts:318

Type guard for BooleanLiteral.

Parameters:

Returns: o is TextLiteral

isDateLiteral

▸ ConstisDateLiteral(o: any): o is DateLiteral

Defined in packages/gram-ast/src/index.ts:483

Type guard for DateLiteral.

Note: this does not validate the text representation.

Parameters:

Returns: o is DateLiteral

isDateTimeLiteral

▸ ConstisDateTimeLiteral(o: any): o is DateTimeLiteral

Defined in packages/gram-ast/src/index.ts:522

Type guard for DateTimeLiteral.

Note: this does not validate the text representation.

Parameters:

Returns: o is DateTimeLiteral

isDecimalLiteral

▸ ConstisDecimalLiteral(o: any): o is DecimalLiteral

Defined in packages/gram-ast/src/index.ts:368

Type guard for DecimalLiteral.

Parameters:

Returns: o is DecimalLiteral

isDuration

▸ ConstisDuration(o: any): o is DurationLiteral

Defined in packages/gram-ast/src/index.ts:545

Type guard for DurationLiteral.

Note: this does not validate the text representation.

Parameters:

Returns: o is DurationLiteral

isGramEdge

▸ ConstisGramEdge(o: any): o is GramEdge

Defined in packages/gram-ast/src/index.ts:168

Type guard for GramEdge.

Parameters:

Returns: o is GramEdge

isGramEmptyPath

▸ ConstisGramEmptyPath(o: any): o is GramEmptyPath

Defined in packages/gram-ast/src/index.ts:122

Type guard for GramEmptyPath.

Parameters:

Returns: o is GramEmptyPath

isGramLiteral

▸ ConstisGramLiteral(o: any): o is GramLiteral

Defined in packages/gram-ast/src/index.ts:298

Type guard for GramLiteral.

Parameters:

Returns: o is GramLiteral

isGramLiteralArray

▸ ConstisGramLiteralArray(v: GramRecordValue): v is GramLiteral[]

Defined in packages/gram-ast/src/index.ts:240

Parameters:

Returns: v is GramLiteral[]

isGramNode

▸ ConstisGramNode(o: any): o is GramNode

Defined in packages/gram-ast/src/index.ts:142

Type guard for GramNode.

Parameters:

Returns: o is GramNode

isGramPath

▸ ConstisGramPath(o: any): o is GramPath

Defined in packages/gram-ast/src/index.ts:94

Type guard for a Path.

Parameters:

Returns: o is GramPath

isGramProperty

▸ ConstisGramProperty(o: any): o is GramProperty

Defined in packages/gram-ast/src/index.ts:268

Type guard for GramProperty.

Parameters:

Returns: o is GramProperty

isGramRecord

▸ ConstisGramRecord(v: any): v is GramRecord

Defined in packages/gram-ast/src/index.ts:237

A type guard to narrow a GramRecordValue to a GramRecord.

Warning: this is not a runtime guarantee

Parameters:

Returns: v is GramRecord

isGramSeq

▸ ConstisGramSeq(o: any): o is GramSeq

Defined in packages/gram-ast/src/index.ts:38

Type guard for GramSeq.

Parameters:

Returns: o is GramSeq

isHexadecimalLiteral

▸ ConstisHexadecimalLiteral(o: any): o is HexadecimalLiteral

Defined in packages/gram-ast/src/index.ts:385

Type guard for HexadecimalLiteral.

Parameters:

Returns: o is HexadecimalLiteral

isIntegerLiteral

▸ ConstisIntegerLiteral(o: any): o is IntegerLiteral

Defined in packages/gram-ast/src/index.ts:352

Type guard for IntegerLiteral.

Parameters:

Returns: o is IntegerLiteral

isMeasurementLiteral

▸ ConstisMeasurementLiteral(o: any): o is MeasurementLiteral

Defined in packages/gram-ast/src/index.ts:423

Type guard for MeasurementLiteral.

Parameters:

Returns: o is MeasurementLiteral

isOctalLiteral

▸ ConstisOctalLiteral(o: any): o is OctalLiteral

Defined in packages/gram-ast/src/index.ts:403

Type guard for OctalLiteral.

Parameters:

Returns: o is OctalLiteral

isStringLiteral

▸ ConstisStringLiteral(o: any): o is TextLiteral

Defined in packages/gram-ast/src/index.ts:336

Type guard for StringLiteral.

Parameters:

Returns: o is TextLiteral

isTaggedLiteral

▸ ConstisTaggedLiteral(o: any): o is TaggedLiteral

Defined in packages/gram-ast/src/index.ts:464

Type guard for TaggedTextLiteral.

Parameters:

Returns: o is TaggedLiteral

isTimeInterval

▸ ConstisTimeInterval(o: any): o is TimeIntervalLiteral

Defined in packages/gram-ast/src/index.ts:571

Type guard for TimeIntervalLiteral.

Note: this does not validate the text representation.

Parameters:

Returns: o is TimeIntervalLiteral

isTimeLiteral

▸ ConstisTimeLiteral(o: any): o is TaggedTextLiteral

Defined in packages/gram-ast/src/index.ts:502

Type guard for TimeLiteral.

Note: this does not validate the text representation.

Parameters:

Returns: o is TaggedTextLiteral

isUriLiteral

▸ ConstisUriLiteral(o: any): o is UriLiteral

Defined in packages/gram-ast/src/index.ts:651

Type guard for UriLiteral.

Parameters:

Returns: o is UriLiteral

isValidIdentifier

▸ ConstisValidIdentifier(s?: undefined | string): undefined | false | true | “”

Defined in packages/gram-ast/src/gram-tokens.ts:20

Checks whether the given string is a valid identifier.

Parameters:

Returns: undefined | false | true | “”

isWellKnownTextLiteral

▸ ConstisWellKnownTextLiteral(o: any): o is WellKnownTextLiteral

Defined in packages/gram-ast/src/index.ts:593

Type guard for WellKnownTextLiteral.

Parameters:

Returns: o is WellKnownTextLiteral