Crate gram_codec 

Gram Codec

Bidirectional codec between Gram notation (human-readable text format) and Pattern data structures.

This crate provides:

• Parsing: Transform Gram notation text into Pattern structures
• Serialization: Transform Pattern structures into valid Gram notation

Features

• Full support for all Gram syntax forms (nodes, relationships, subject patterns, annotations)
• Round-trip correctness (parse → serialize → parse produces equivalent pattern)
• Error recovery (reports all syntax errors, not just the first)
• Multi-platform support (native Rust, WebAssembly, Python)

Example Usage

use gram_codec::{parse_gram_notation, to_gram_pattern};

// Parse gram notation into patterns
let gram_text = "(alice:Person {name: \"Alice\"})-[:KNOWS]->(bob:Person {name: \"Bob\"})";
let patterns = parse_gram_notation(gram_text)?;

// Serialize patterns back to gram notation
for pattern in &patterns {
    let output = to_gram_pattern(pattern)?;
    println!("{}", output);
}

Grammar Authority

This codec uses tree-sitter-gram as the authoritative grammar specification. The parser implementation is pure Rust using nom parser combinators, validated for 100% conformance with the tree-sitter-gram test corpus.

Re-exports

pub use ast::AstPattern;

pub use ast::AstSubject;

pub use ast::ParseWithHeaderResult;

pub use json::gram_parse_to_json;

pub use json::gram_stringify_from_json;

pub use json::gram_validate_to_json;

pub use cst::lower;

pub use cst::parse_gram_cst;

pub use cst::CstParseResult;

pub use parse_gram as parse_gram_notation;

pub use standard_graph::FromGram;

Modules

ast

Abstract Syntax Tree (AST) types for gram notation

cst

CST parser API and foundational syntax-node types.

json

JSON interchange functions for the gram codec.

standard_graph

Extension trait providing from_gram for StandardGraph.

Structs

Location

Location in source code (1-indexed line and column)

Pattern

A recursive, nested structure (s-expression-like) that is generic over value type V.

Subject

Self-descriptive object with identity, labels, and properties.

Enums

ParseError

Errors that can occur during parsing

SerializeError

Error during pattern serialization to gram notation

Value

Represents all possible value types in Gram notation property records. Supports all value types defined in the tree-sitter-gram grammar.

Functions

parse_gram

Parse gram notation text into a collection of Pattern structures.

parse_gram_with_header

Parse gram notation, separating an optional header record from the patterns.

parse_single_pattern

Parse a single Gram pattern from text.

parse_to_ast

Parse gram notation to AST (Abstract Syntax Tree).

to_gram

Serialize a sequence of patterns to gram notation.

to_gram_pattern

Serialize a Pattern structure to Gram notation

to_gram_with_header

Serializes patterns with a leading header record.

validate_gram

Validate gram notation syntax without constructing patterns.

Type Aliases

Record

Property record type alias.