reflect
Inspect struct and enum payload snapshots without depending on their native memory layout.
Struct snapshots#
Fields(value any) returns array<reflect.Field> in declaration order. Each returned Field contains the field name in Name string and a boxed copy of its value in Value any. Private fields and immutable value-parameter fields are included.
Reflection is useful when code needs to inspect fields without hard-coding a particular struct declaration. The result is a snapshot: it records field names and boxed field values at the time of the call. It is not a mutable view through which the original struct can be edited.
Each result element is a reflect.Field. Name identifies the field, and Value holds a boxed copy whose concrete type can be recovered with an assertion or type switch. Declaration order is preserved, including private fields and immutable value-parameter fields.
package main;
import "io";
import "reflect";
struct Person { name string; age int; }
func main() {
person := Person{"Ada", 36};
for (i, field := range reflect.Fields(person)) {
io.Printfln("{}: {}", field.Name, field.Value);
}
}
The program prints name: Ada and age: 36 in that order. io can format each boxed value here without the caller writing a concrete assertion for every possible field type.
Copy behavior#
Field values are independent deep copies, while pointer fields retain their non-owning addresses. reflect.Fields returns an empty array for inputs other than structs and enums. A pointer to a struct counts as a pointer input, not a struct input; the function does not dereference it automatically. IsStruct(value any) distinguishes an empty struct from a non-struct.
An owned string or nested array in a field is deep-copied into the snapshot. Later changes to the original struct do not change that stored field value. A pointer field copies only its address, so the snapshot is not a deep clone of an arbitrary graph of pointed-to objects.
IsStruct is useful before interpreting an empty Fields result. An empty struct has no fields but is still a struct; a unit enum variant and other values also return no fields. Passing a pointer to a struct does not automatically inspect its pointee. Dereference a valid pointer explicitly if that is what you intend to inspect.
// Inside a function:
isStruct := reflect.IsStruct(Person{"Ada", 36});
fields := reflect.Fields(Person{"Ada", 36});
name := fields[0].Value.(string);
The assertion .Value.(string) requests the field’s concrete string value. In this particular struct the first field is known to be a string. For general-purpose inspection, use a type switch rather than assuming that every field has the same concrete type.
Enum snapshots#
reflect.IsEnum(value any) identifies enum values, including generic enums,
Optional<T>, and Result<T>. reflect.EnumVariant(value any) returns the
qualified declaration name such as Event.Key (without generic arguments), or
an empty string for a non-enum. Pointers are not dereferenced.
reflect.Fields also snapshots the active enum payload: record fields keep
their names, tuple entries have empty names, fixed payloads return one unnamed
field, and unit variants return no fields. The same deep-copy rules apply.
reflect.IsStruct returns false for enum values.
io.Print, io.Println, io.Sprint, and formatted output use this reflection
to print enums recursively: Event.Load, Event.Key(65), and
Event.Click(x: 2, y: 3). Fixed payloads print as Number.One(1).
enum Event { Load, Key(i8), Click{x, y int} }
// Inside a function:
event := Event.Key(65);
name := reflect.EnumVariant(event); // "Event.Key"
fields := reflect.Fields(event); // one unnamed field
io.Println(event); // Event.Key(65)
Trusted library implementation#
The compiler permits its internal reflection operations only in the reflect package loaded from the configured standard-library source root. Those operations are called compiler primitives; they are implementation hooks rather than ordinary functions available to application packages. Ordinary code uses the public Fields, IsStruct, IsEnum, and EnumVariant API. Copying a package or giving it the same name does not grant intrinsic access.
The public API is implemented with compiler primitives restricted to the configured standard-library root. This restriction concerns how the package is implemented, not who may import it: ordinary Ocean packages can call reflect.Fields and reflect.IsStruct.
A package named reflect elsewhere does not receive the same primitive access. Neither a copied implementation nor a module replacement grants it. OCEAN_SRC explicitly changes the trusted library root during development, so configure it to the library checkout you intend to use.
For application code, depend on the public snapshot behavior rather than the internal primitive names or the native layout of a boxed value. That keeps ordinary reflection code independent of those implementation details.