Crate hedl

Crate hedl 

Source
Expand description

§HEDL - Hierarchical Entity Data Language

HEDL is a text-based data serialization format optimized for AI/ML data representation. It combines the token efficiency of CSV-style tables with the semantic richness of hierarchical structures.

§Quick Start

use hedl::{parse, canonicalize, to_json};

let hedl_doc = r#"
%VERSION: 1.0
%STRUCT: User: [id,name,email]
---
users: @User
  | alice, Alice, alice@example.com
  | bob, Bob, bob@example.com
"#;

// Parse the document
let doc = parse(hedl_doc).expect("Failed to parse");

// Convert to canonical form
let canonical = canonicalize(&doc).expect("Failed to canonicalize");

// Convert to JSON
let json = to_json(&doc).expect("Failed to convert to JSON");

§Features

  • Type-scoped IDs: IDs are unique within their type namespace
  • Matrix lists: CSV-like tables for homogeneous collections
  • Ditto operator: ^ copies values from previous row
  • References: @id or @Type:id for graph relationships
  • Tensor literals: [1, 2, 3] for numerical arrays
  • Expressions: $(...) for deferred computation
  • Aliases: %key for constant substitution

§Modules

  • core: Core parsing and data model
  • lex: Lexical analysis utilities
  • csv: CSV field parsing (internal row parsing)
  • tensor: Tensor literal parsing
  • c14n: Canonicalization
  • json: JSON conversion
  • lint: Linting and best practices

§Optional Format Converters (feature-gated)

  • yaml: YAML conversion (feature = “yaml”)
  • xml: XML conversion (feature = “xml”)
  • csv_file: CSV file conversion (feature = “csv”)
  • parquet: Parquet conversion (feature = “parquet”)

Modules§

c14n
Canonicalization utilities
csv
CSV field parsing
csv_file
CSV file conversion utilities (requires csv feature). Distinct from internal row parsing.
json
JSON conversion utilities
lex
Lexical analysis utilities
lint
Linting utilities
neo4j
Neo4j/Cypher conversion utilities (requires neo4j feature). Provides bidirectional conversion between HEDL documents and Neo4j graph databases.
parquet
Parquet conversion utilities (requires parquet feature)
tensor
Tensor literal parsing
toon
TOON conversion utilities (requires toon feature).
xml
XML conversion utilities (requires xml feature)
yaml
YAML conversion utilities (requires yaml feature)

Structs§

Document
A parsed HEDL document.
HedlError
An error that occurred during HEDL parsing.
Limits
Configurable limits for parser security.
MatrixList
A typed matrix list with schema.
Node
A node in a matrix list.
ParseOptions
Parsing options for configuring HEDL document parsing behavior.
Reference
A reference to another node.

Enums§

HedlErrorKind
The kind of error that occurred during parsing.
Item
An item in the document body.
ReferenceMode
Reference resolution mode for controlling validation behavior.
Tensor
A multi-dimensional numerical array.
Value
A scalar value in HEDL.

Constants§

SUPPORTED_VERSION
HEDL format version supported by this library.
VERSION
Library version.

Traits§

HedlResultExt
Extension trait for adding context to Result<T, HedlError>.

Functions§

canonicalize
Canonicalize a HEDL document to a string.
core_parse
Parse a HEDL document from bytes.
from_json
Convert JSON to a HEDL document.
lint
Lint a HEDL document for best practices.
parse
Parse a HEDL document from a string.
parse_lenient
Parse a HEDL document with lenient reference handling.
parse_with_limits
Parse a HEDL document with custom options.
to_json
Convert a HEDL document to JSON.
validate
Validate a HEDL string without fully parsing.