Skip to main content

GValue

The universal value container for GLYPH data. All GLYPH values are represented as GValue instances.

Type Property

type
GType
required
The type of this value (null, bool, int, float, str, bytes, time, id, list, map, struct, sum)

Type Constructors

Static methods for creating GValue instances:

null()

Create a null value.
from glyph import GValue

v = GValue.null()
print(v.is_null())  # True
Returns: GValue - A null value

bool_(v: bool)

Create a boolean value.
v
bool
required
Boolean value (True or False)
v = GValue.bool_(True)
print(v.as_bool())  # True
Returns: GValue - A boolean value

int_(v: int)

Create an integer value.
v
int
required
Integer value
v = GValue.int_(42)
print(v.as_int())  # 42
Returns: GValue - An integer value

float_(v: float)

Create a floating-point value.
v
float
required
Float value
v = GValue.float_(3.14)
print(v.as_float())  # 3.14
Returns: GValue - A float value

str_(v: str)

Create a string value.
v
str
required
String value
v = GValue.str_("hello world")
print(v.as_str())  # "hello world"
Returns: GValue - A string value

bytes_(v: bytes)

Create a bytes value.
v
bytes
required
Bytes value
v = GValue.bytes_(b"\x00\x01\x02")
print(v.as_bytes())  # b'\x00\x01\x02'
Returns: GValue - A bytes value

time(v: datetime)

Create a timestamp value.
v
datetime
required
Python datetime object (with or without timezone)
from datetime import datetime, timezone

dt = datetime(2025, 1, 13, 12, 0, 0, tzinfo=timezone.utc)
v = GValue.time(dt)
print(v.as_time())  # 2025-01-13 12:00:00+00:00
Returns: GValue - A time value

id(prefix: str, value: str)

Create a reference ID value.
prefix
str
required
ID prefix (can be empty string)
value
str
required
ID value
# With prefix
user_id = GValue.id("user", "123")
ref = user_id.as_id()
print(ref.prefix)  # "user"
print(ref.value)   # "123"

# Without prefix
simple_id = GValue.id("", "abc")
Returns: GValue - An ID reference value

list_(*values: GValue)

Create a list value.
values
GValue...
required
Variable number of GValue elements
v = GValue.list_(
    GValue.int_(1),
    GValue.int_(2),
    GValue.int_(3)
)
print(len(v))  # 3
Returns: GValue - A list value

map_(*entries: MapEntry)

Create a map value.
entries
MapEntry...
required
Variable number of key-value pairs
from glyph import MapEntry

v = GValue.map_(
    MapEntry("name", GValue.str_("Alice")),
    MapEntry("age", GValue.int_(30))
)
print(v.get("name").as_str())  # "Alice"
Returns: GValue - A map value

struct(type_name: str, *fields: MapEntry)

Create a struct value with a type name.
type_name
str
required
Name of the struct type
fields
MapEntry...
required
Variable number of field entries
from glyph import MapEntry

v = GValue.struct("Person",
    MapEntry("name", GValue.str_("Alice")),
    MapEntry("age", GValue.int_(30))
)
struct = v.as_struct()
print(struct.type_name)  # "Person"
Returns: GValue - A struct value

sum(tag: str, value: Optional[GValue])

Create a sum type (tagged union) value.
tag
str
required
Tag identifying the variant
value
GValue | None
required
Optional payload value
# Sum with value
some = GValue.sum("Some", GValue.int_(42))
sum_val = some.as_sum()
print(sum_val.tag)    # "Some"
print(sum_val.value.as_int())  # 42

# Sum without value
none = GValue.sum("None", None)
Returns: GValue - A sum type value

Value Accessors

Methods for extracting typed values. All accessors raise TypeError if the value is not of the expected type.

is_null() → bool

Check if the value is null.
v = GValue.null()
if v.is_null():
    print("Value is null")
Returns: bool - True if value is null

as_bool() → bool

Extract boolean value.
v = GValue.bool_(True)
result = v.as_bool()  # True
Returns: bool - The boolean value Raises: TypeError - If value is not a boolean

as_int() → int

Extract integer value.
v = GValue.int_(42)
result = v.as_int()  # 42
Returns: int - The integer value Raises: TypeError - If value is not an integer

as_float() → float

Extract float value.
v = GValue.float_(3.14)
result = v.as_float()  # 3.14
Returns: float - The float value Raises: TypeError - If value is not a float

as_str() → str

Extract string value.
v = GValue.str_("hello")
result = v.as_str()  # "hello"
Returns: str - The string value Raises: TypeError - If value is not a string

as_bytes() → bytes

Extract bytes value.
v = GValue.bytes_(b"data")
result = v.as_bytes()  # b"data"
Returns: bytes - The bytes value Raises: TypeError - If value is not bytes

as_time() → datetime

Extract datetime value.
from datetime import datetime, timezone

v = GValue.time(datetime.now(timezone.utc))
result = v.as_time()  # datetime object
Returns: datetime - The datetime value Raises: TypeError - If value is not a time

as_id() → RefID

Extract reference ID value.
v = GValue.id("user", "123")
ref = v.as_id()
print(ref.prefix)  # "user"
print(ref.value)   # "123"
Returns: RefID - The reference ID object Raises: TypeError - If value is not an ID

as_list() → List[GValue]

Extract list value.
v = GValue.list_(GValue.int_(1), GValue.int_(2))
lst = v.as_list()
for item in lst:
    print(item.as_int())
Returns: List[GValue] - The list of values Raises: TypeError - If value is not a list

as_map() → List[MapEntry]

Extract map entries.
from glyph import MapEntry

v = GValue.map_(MapEntry("a", GValue.int_(1)))
entries = v.as_map()
for entry in entries:
    print(f"{entry.key} = {entry.value.as_int()}")
Returns: List[MapEntry] - The map entries Raises: TypeError - If value is not a map

as_struct() → StructValue

Extract struct value.
v = GValue.struct("Person", MapEntry("name", GValue.str_("Alice")))
struct = v.as_struct()
print(struct.type_name)  # "Person"
for field in struct.fields:
    print(f"{field.key}: {field.value}")
Returns: StructValue - The struct object with type_name and fields Raises: TypeError - If value is not a struct

as_sum() → SumValue

Extract sum type value.
v = GValue.sum("Some", GValue.int_(42))
sum_val = v.as_sum()
print(sum_val.tag)     # "Some"
print(sum_val.value)   # GValue.int_(42)
Returns: SumValue - The sum object with tag and value Raises: TypeError - If value is not a sum type

as_number() → int | float

Extract numeric value (works for both int and float).
v1 = GValue.int_(42)
v2 = GValue.float_(3.14)

print(v1.as_number())  # 42
print(v2.as_number())  # 3.14
Returns: int | float - The numeric value Raises: TypeError - If value is not numeric

Collection Methods

get(key: str) → Optional[GValue]

Get field from struct or map by key.
key
str
required
Field or entry key
v = GValue.map_(MapEntry("name", GValue.str_("Alice")))
name = v.get("name")
if name:
    print(name.as_str())  # "Alice"
Returns: GValue | None - The value if found, None otherwise

index(i: int) → GValue

Get element from list by index.
i
int
required
Zero-based index
v = GValue.list_(GValue.int_(1), GValue.int_(2), GValue.int_(3))
print(v.index(0).as_int())  # 1
print(v.index(2).as_int())  # 3
Returns: GValue - The element at the index Raises: IndexError - If index is out of bounds

len() → int

Get length of list, map, or struct fields.
v = GValue.list_(GValue.int_(1), GValue.int_(2))
print(len(v))  # 2

v2 = GValue.map_(MapEntry("a", GValue.int_(1)))
print(len(v2))  # 1
Returns: int - Number of elements/fields

Mutators

set(key: str, value: GValue)

Set field on struct or map.
key
str
required
Field or entry key
value
GValue
required
Value to set
v = GValue.map_()
v.set("name", GValue.str_("Alice"))
v.set("age", GValue.int_(30))
Raises: TypeError - If value is not a struct or map

append(value: GValue)

Append to list.
value
GValue
required
Value to append
v = GValue.list_()
v.append(GValue.int_(1))
v.append(GValue.int_(2))
print(len(v))  # 2
Raises: TypeError - If value is not a list

clone() → GValue

Create a deep copy of this value.
original = GValue.list_(GValue.int_(1), GValue.int_(2))
copy = original.clone()
copy.append(GValue.int_(3))

print(len(original))  # 2
print(len(copy))      # 3
Returns: GValue - A deep copy of the value

GType

Enumeration of GLYPH value types.
from glyph import GType

v = GValue.int_(42)
if v.type == GType.INT:
    print("It's an integer")

Values

  • GType.NULL - Null value
  • GType.BOOL - Boolean (true/false)
  • GType.INT - Integer number
  • GType.FLOAT - Floating-point number
  • GType.STR - String
  • GType.BYTES - Byte array
  • GType.TIME - Timestamp
  • GType.ID - Reference ID
  • GType.LIST - List of values
  • GType.MAP - Key-value map
  • GType.STRUCT - Typed struct
  • GType.SUM - Tagged union

Helper Classes

MapEntry

Key-value pair for maps and structs.
key
str
required
The entry key
value
GValue
required
The entry value
from glyph import MapEntry, GValue

entry = MapEntry("name", GValue.str_("Alice"))
print(entry.key)    # "name"
print(entry.value)  # GValue.str_("Alice")

RefID

Reference ID with optional prefix.
prefix
str
required
ID prefix (can be empty)
value
str
required
ID value
from glyph import RefID

ref = RefID("user", "123")
print(ref.prefix)  # "user"
print(ref.value)   # "123"
print(str(ref))    # "^user:123"

StructValue

Struct with type name and fields.
type_name
str
required
Name of the struct type
fields
List[MapEntry]
required
List of field entries

SumValue

Tagged union (sum type).
tag
str
required
Tag identifying the variant
value
GValue | None
required
Optional payload value

Shorthand Constructor: g

The g object provides shorthand constructors without the trailing underscore.
from glyph import g, field

# Instead of GValue.str_("hello")
v = g.str("hello")

# Build complex structures
person = g.struct("Person",
    field("name", g.str("Alice")),
    field("age", g.int(30)),
    field("scores", g.list(g.int(95), g.int(87), g.int(92)))
)

Available Methods

  • g.null() → GValue
  • g.bool(v: bool) → GValue
  • g.int(v: int) → GValue
  • g.float(v: float) → GValue
  • g.str(v: str) → GValue
  • g.bytes(v: bytes) → GValue
  • g.time(v: datetime) → GValue
  • g.id(prefix: str, value: str) → GValue
  • g.list(*values: GValue) → GValue
  • g.map(*entries: MapEntry) → GValue
  • g.struct(type_name: str, *fields: MapEntry) → GValue
  • g.sum(tag: str, value: Optional[GValue]) → GValue

field() Helper

Create a field entry for struct construction.
key
str
required
Field name
value
GValue
required
Field value
from glyph import field, g

# Create fields
name_field = field("name", g.str("Alice"))
age_field = field("age", g.int(30))

# Use in structs
person = g.struct("Person", name_field, age_field)
Returns: MapEntry - A field entry

Examples

Building Complex Structures

from glyph import g, field
import glyph

# Create a match result
match = g.struct("Match",
    field("home", g.str("Arsenal")),
    field("away", g.str("Liverpool")),
    field("score", g.list(g.int(2), g.int(1))),
    field("date", g.str("2025-03-15")),
    field("venue", g.struct("Venue",
        field("name", g.str("Emirates Stadium")),
        field("capacity", g.int(60704))
    ))
)

# Emit to GLYPH format
text = glyph.emit(match)
print(text)

Type Checking Pattern

from glyph import GType

def process_value(v):
    """Process different value types."""
    if v.type == GType.NULL:
        return None
    elif v.type == GType.INT:
        return v.as_int() * 2
    elif v.type == GType.STR:
        return v.as_str().upper()
    elif v.type == GType.LIST:
        return [process_value(item) for item in v.as_list()]
    else:
        return v

Build docs developers (and LLMs) love