Documentation Index
Fetch the complete documentation index at: https://mintlify.com/Neumenon/glyph/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The glyph Go package implements GLYPH, a token-optimized codec designed for LLM interactions. GLYPH provides a dual encoding system (GLYPH-T for text and GLYPH-B for binary) with strong typing, schema validation, and streaming support.
Installation
go get github.com/Neumenon/glyph
Import
import "github.com/Neumenon/glyph"
Key Features
- LLM-friendly syntax: Easy for models to emit and repair
- Token-efficient: Short keys, no quotes, structural compression
- Strongly typed: Schema-driven validation with constraints
- Streamable: Frame-based incremental parsing
- Deterministic: Canonical representation for stable hashing
- Round-trippable: Seamless JSON and SJSON interop
Quick Start
Creating Values
// Scalars
null := glyph.Null()
bool := glyph.Bool(true)
num := glyph.Int(42)
float := glyph.Float(3.14)
str := glyph.Str("hello")
ref := glyph.ID("m", "2024-01-15")
// Containers
list := glyph.List(
glyph.Int(1),
glyph.Int(2),
glyph.Int(3),
)
map_ := glyph.Map(
glyph.FieldVal("name", glyph.Str("Arsenal")),
glyph.FieldVal("score", glyph.Int(2)),
)
struct_ := glyph.Struct("Team",
glyph.FieldVal("id", glyph.ID("t", "ARS")),
glyph.FieldVal("name", glyph.Str("Arsenal")),
)
Parsing GLYPH-T Text
// Parse with error tolerance (default)
result, err := glyph.Parse(`Team{id=^t:ARS name="Arsenal" score=2}`)
if err != nil {
return err
}
if result.HasErrors() {
// Handle parse errors
for _, e := range result.Errors {
fmt.Printf("Error: %s\n", e.Message)
}
}
value := result.Value
Emitting GLYPH-T Text
// Emit canonical GLYPH-T
team := glyph.Struct("Team",
glyph.FieldVal("id", glyph.ID("t", "ARS")),
glyph.FieldVal("name", glyph.Str("Arsenal")),
)
text := glyph.Emit(team)
// Output: Team{id=^t:ARS name=Arsenal}
Working with Values
// Type checking
if value.Type() == glyph.TypeStruct {
structVal, _ := value.AsStruct()
fmt.Println("Type:", structVal.TypeName)
}
// Field access
name := value.Get("name")
if name != nil {
str, _ := name.AsStr()
fmt.Println("Name:", str)
}
// List iteration
list, _ := value.AsList()
for i, elem := range list {
fmt.Printf("Element %d: %v\n", i, elem)
}
Data Model
GLYPH supports the following types:
Scalars
null - Null value (∅)bool - Boolean (t/f)int - 64-bit integerfloat - 64-bit floatstr - UTF-8 stringbytes - Binary datatime - ISO-8601 timestampid - Reference ID (^prefix:value)
Containers
list - Ordered array of valuesmap - Unordered key-value pairsstruct - Typed struct with named fields
Special
sum - Tagged union (variant type)ref - Reference to another value
GLYPH-T Syntax
// Struct
Team{id=^t:ARS name="Arsenal" league=EPL}
// Map
{name:"Arsenal" score:2 points:6}
// List
[1 2 3 4 5]
// Sum/Union
Result(Success{value=42})
// References
^m:2024-01-15:ARS-LIV
^t:ARS
// Null
∅
// Booleans
t
f
// Strings
bare_word
"quoted string"
Error Handling
The Go API uses both error returns and result types:
// Parse returns ParseResult with errors and warnings
result, err := glyph.Parse(input)
if err != nil {
// Fatal parse error
return err
}
if result.HasErrors() {
// Non-fatal errors during parsing
for _, e := range result.Errors {
fmt.Printf("%s at %s\n", e.Message, e.Pos)
}
}
// Value accessors return errors for type mismatches
intVal, err := value.AsInt()
if err != nil {
// Type mismatch
return err
}
JSON Interop
// GLYPH → JSON
value := glyph.Struct("Team",
glyph.FieldVal("name", glyph.Str("Arsenal")),
)
jsonBytes, err := glyph.ToJSON(value)
// JSON → GLYPH
value, err := glyph.FromJSON(jsonBytes)
Binary Encoding
// GLYPH → Binary (via SJSON)
value := glyph.Int(42)
binary, err := glyph.EncodeBinary(value)
// Binary → GLYPH
value, err := glyph.DecodeBinary(binary)
Next Steps