Reflection
Reflection lets you write code that inspects types — counting fields, listing their names and types, turning enum values into names. GX’s reflection is fully compile-time, so there’s no runtime overhead and no metadata tables in your binary.
Getting the Number of Fields
@fields(T) returns the number of fields in a struct:
struct Player {
name:str
health:i32
score:f32
alive:bool
}
fn main() {
const N = @fields(Player)
print("Player has {N} fields\n") // 4
}
The value is computed at compile time — the generated C contains 4 as a literal.
Iterating Over Fields with #for
@field(T, i) is the name of field i, and @field_type(T, i) is the name of its type. Use them inside #for to generate one block per field:
struct Config {
port:i32
host:str
verbose:bool
}
fn main() {
#for (i = 0 : @fields(Config) - 1) {
print("field {i}: {@field(Config, i)} ({@field_type(Config, i)})\n")
}
}
Output:
field 0: port (i32)
field 1: host (str)
field 2: verbose (bool)
The #for loop unrolls at compile time — the compiler generates three separate print calls, one per field, with the names baked in as string literals. No runtime loop, no metadata lookup.
Ranges are inclusive, so the last index is @fields(Config) - 1. Leaving out the - 1 is a compile error (@field index 3 out of range), not a silent off-by-one.
Describing a Struct
A schema printer that never goes out of date:
struct Player {
name:str
health:i32
score:f32
target:*Player
}
fn describe_player() {
print("struct Player {\n")
#for (i = 0 : @fields(Player) - 1) {
#if (@field_is_ptr(Player, i)) {
print(" {@field(Player, i)}: pointer to {@field_type(Player, i)}\n")
} #else {
print(" {@field(Player, i)}: {@field_type(Player, i)}\n")
}
}
print("}\n")
}
fn main() {
describe_player()
}
Add or remove a field from Player, and describe_player handles it on the next compile — no manual updates.
Enum Members
@members(E) is the number of members of an enum and @member(E, i) is the name of member i. Together they give you an enum-to-string function with no table to maintain:
enum Color { Red, Green, Blue }
fn color_name:str(c:Color) {
#for (i = 0 : @members(Color) - 1) {
if ((i32)c == i) { return @member(Color, i) }
}
return "?"
}
fn main() {
var c:Color = Green
print("{color_name(c)}\n") // Green
print("{@members(Color)} colors\n") // 3 colors
}
The #for unrolls into one if per member. Add a member to Color and the function covers it.
Reflection + #if for Per-Field Logic
Combine reflection with compile-time conditionals to treat fields differently:
struct Stats {
strength:i32
agility:i32
luck:f32
}
fn main() {
#for (i = 0 : @fields(Stats) - 1) {
#if (@field_type(Stats, i) == "i32") {
print("{@field(Stats, i)} is a whole number\n")
} #else {
print("{@field(Stats, i)} is a {@field_type(Stats, i)}\n")
}
}
}
Practical Example: Column Headers
Field names are ordinary strings, so they can label data you print yourself:
struct GameState {
level:i32
player_hp:i32
enemy_count:i32
}
fn dump_state(s:*GameState) {
print("=== GameState ({@fields(GameState)} fields) ===\n")
print(" {@field(GameState, 0)} = {s.level}\n")
print(" {@field(GameState, 1)} = {s.player_hp}\n")
print(" {@field(GameState, 2)} = {s.enemy_count}\n")
}
fn main() {
var state = GameState{3, 85, 12}
dump_state(&state)
}
Output:
=== GameState (3 fields) ===
level = 3
player_hp = 85
enemy_count = 12
Rename a field and the label follows. Reflection gives you names, types and counts; the value of a field is still read by its name (s.level).
Try it — Define a struct with 3-4 fields, then write a function that prints each field’s name and type using
#forand@fieldin the Playground.
Expert Corner
How reflection compiles: @fields(T) is resolved to an integer literal during compilation. @field(T, i) and @field_type(T, i) become string literals. The generated C has no reflection machinery whatsoever: no runtime type info table, no RTTI.
The index must be a compile-time constant: You can’t do var i = 3; print(@field(Player, i)) because the lookup is resolved statically. The i must be known at compile time, which means you’ll almost always use reflection inside a #for loop, where the loop variable is a compile-time constant.
The full list: @fields(T), @field(T, i), @field_type(T, i), @field_is_ptr(T, i), @field_is_array(T, i) for structs; @members(E), @member(E, i) for enums. The first argument is always a type name, not a variable.
Why compile-time only: Runtime reflection (like Java or C#) requires metadata tables embedded in the binary — field names, types, offsets, attributes. For a systems language, this overhead isn’t worth it. Compile-time reflection gives you generative power without the runtime cost. The tradeoff: you can’t inspect arbitrary types at runtime based on user input.
Comparison to C++ template metaprogramming: C++ templates can inspect types through SFINAE and concepts, but the syntax is arcane and the error messages are legendary. GX’s reflection API is a handful of explicit @ queries. What you write is what the compiler does.
Comparison to Zig: Zig has @typeInfo(T) which returns a struct with fields like Struct.fields. More powerful (default values, nested type information) but more complex. GX’s version is deliberately small.
Common patterns that use reflection:
- Enum to string — one generated comparison per member
- Schema and debug output — field names and types that never go stale
- Labels — column headers, UI captions and log keys taken from field names
- Compile-time checks —
#ifon a field’s type to pick the right code path