nupp.reflect

Annotationrecord#

record Annotation ...

A typed annotation application, retaining source order.

name: string

arguments: {AnnotationArgument}

AnnotationArgumentrecord#

record AnnotationArgument ...

A checked member supplied to a reflected typed annotation.

value is present for kind = "value"; type is an index into the owning Info.types graph for kind = "type". kind = "nil" preserves an explicitly supplied nil without pretending an absent table field contains it.

@annotation(targets = {"field"})
local record serialized
    name: string?
    @ref
    codec: any
end

local record StringCodec
end

local record User
    @serialized(name = "user_id", codec = StringCodec)
    id: integer
end

const Serialization: string = comptime do
    local info = nupp.reflect(User)
    local arguments = info.fields[1].annotations[1].arguments
    assert(arguments[1].kind == "value")
    assert(arguments[2].kind == "type")
    local codec = info.types[arguments[2].type as integer]
    return (arguments[1].value as string) .. ":" .. (codec.name as string)
end

assert(Serialization == "user_id:StringCodec")

name: string

kind: "value" | "nil" | "type"

value: any?

type: integer?

Entryrecord#

record Entry ...

A named or positional edge in the indexed semantic type graph.

name: string?

type: integer?

read: integer?

write: integer?

stored: boolean?

readable: boolean?

writable: boolean?

hasDefault: boolean?

defaultValue: any

mode: string?

bound: integer?

answer: integer?

default: boolean?

annotations: {Annotation}?

ExtensionKeyinterface#

interface ExtensionKey<T> ...

A typed identity for data derived lazily from a reflection descriptor, schema, or binding.

It has the shape of nupp.util.Key<T>, declared here because the prelude is read before any module is. _valueType is never present; it mentions T in both positions so that keys are invariant.

Type parameters

id: integer

name: string?

Fieldrecord#

record Field ...

A visible field projected directly from the reflected root type.

The projection preserves declaration order, access capabilities, defaults, and annotations without requiring a lookup in Info.types. stored distinguishes stored fields, including callbacks, from methods.

local record Options
    format: string = "compact"
    retries: integer
end

const DefaultFormat: string = comptime do
    local field = nupp.reflect(Options).fields[1]
    assert(field.name == "format" and field.hasDefault)
    assert(field.readable and field.writable)
    return field.defaultValue as string
end

assert(DefaultFormat == "compact")

name: string

kind: string

typeName: string?

type: integer?

stored: boolean

readable: boolean

writable: boolean

hasDefault: boolean

defaultValue: any

annotations: {Annotation}

FieldCodecrecord#

record FieldCodec<T> ...

A keyed runtime codec materialized from a reflected record.

encode copies present declared fields into a plain keyed table. decode selects the same fields from a keyed table and restores the record's runtime identity. Both operations are shallow. The stable fingerprint records the field names in declaration order.

local record Position
    x: number
    y: number
end

const PositionCodec: nupp.reflect.FieldCodec<Position> = comptime do
    return nupp.reflect.fieldCodec(nupp.reflect(Position))
end

local encoded = PositionCodec:encode(new Position(x = 3, y = 4))
assert(encoded.x == 3 and encoded.y == 4)
assert(PositionCodec.fingerprint == "t:x,y")

Type parameters

encode: function(self, value: T): {[string]: any}

decode: function(self, value: {[string]: any}): (T?, string?)

fingerprint: string

FieldCodecBlueprintrecord#

record FieldCodecBlueprint

An opaque field-codec recipe returned inside comptime.

Inforecord#

record Info ...

An immutable compile-time description of a resolved semantic type.

Info can cross typed comptime helper boundaries. Its fingerprint is suitable for cache keys because it changes with the canonical type graph, defaults, and checked annotations rather than with compiler-local identities.

local record Pair
    left: string
    right: integer
end

@comptime local function describe(info: nupp.reflect.Info): string
    return info.fingerprint .. ":" .. tostring(#info.fields)
end

const PairDescription: string = comptime do
    return describe(nupp.reflect(Pair))
end

assert(PairDescription:match(":2$") ~= nil)

schema: integer

root: integer

types: const{Node}

kind: string

name: string

qualifiedName: string

fields: const{Field}

annotations: const{Annotation}

soa: const SoAInfo

fingerprint: string

Noderecord#

record Node ...

A node in an Info semantic type graph.

Fields, parameters, results, union members, generic arguments, and wrappers point to other nodes by their integer index. Resolve only the edges relevant to the node's kind.

local type Handler = function(message: string, attempts: integer): boolean

const HandlerShape: string = comptime do
    local info = nupp.reflect(Handler)
    local handler = info.types[info.root]
    assert(handler.kind == "func")
    local first = (handler.parameters as {nupp.reflect.Entry})[1]
    local input = info.types[first.type as integer]
    local output = info.types[(handler.returns as {integer})[1]]
    return (first.name as string) .. ":" .. input.kind .. "->" .. output.kind
end

assert(HandlerShape == "message:string->boolean")

copyable: boolean?

kind: string

name: string?

nominal: boolean?

annotations: {Annotation}?

fields: {Entry}?

staticFields: {Entry}?

metamethods: {Entry}?

nestedTypes: {Entry}?

associatedTypes: {Entry}?

members: {integer}?

parameters: {Entry}?

returns: {integer}?

typeParameters: {integer}?

typeBounds: {integer}?

packParameters: {integer}?

constParameters: {integer}?

parameterKinds: {string}?

typeArguments: {integer}?

packArguments: {integer}?

constArguments: {integer}?

supertypes: {integer}?

element: integer?

body: integer?

of: integer?

origin: integer?

noReturn: boolean?

noYield: boolean?

SoAFieldrecord#

record SoAField ...

A top-level stored struct field available as a SoA column.

name: string

identity: string

ordinal: integer

type: integer?

ctype: string?

eligible: boolean

SoAInforecord#

record SoAInfo ...

Target-independent semantic inputs to SoA storage derivation.

This says whether the declaration can be split into columns and identifies those columns. It deliberately does not contain target sizes or offsets; use nupp.mem.soa.layoutof for those.

local struct Particle
    x: float
    y: float
end

const ParticleColumns: string = comptime do
    local soa = nupp.reflect(Particle).soa
    assert(soa.eligible and #soa.fields == 2)
    assert(soa.fields[1].ordinal == 1)
    return soa.fields[1].name .. "," .. soa.fields[2].name
end

assert(ParticleColumns == "x,y")

schema: integer

eligible: boolean

reason: string?

fields: {SoAField}

extensionKeyfunction#

local extensionKey: function<T>(build: function(host: any): T): ExtensionKey<T>

Creates an identity for a lazily derived metadata value.

A descriptor, schema, or binding builds a key's value once, then returns the same value from its private cache. Key identities and their slot numbers are process-local and must not be persisted.

Type parameters

Arguments

Returns

fieldCodeccomptime function#

local fieldCodec: @comptime function(info: Info): FieldCodecBlueprint

Builds a keyed field-codec recipe from a reflected record.

The opaque recipe must directly initialize a matching FieldCodec<Record> declaration. It may pass through typed comptime helpers on the way to that materialization boundary.

local record Message
    id: integer
    text: string
end

@comptime local function keyed(
    info: nupp.reflect.Info
): nupp.reflect.FieldCodecBlueprint
    return nupp.reflect.fieldCodec(info)
end

const MessageCodec: nupp.reflect.FieldCodec<Message> = comptime do
    return keyed(nupp.reflect(Message))
end

local encoded = MessageCodec:encode(new Message(id = 1, text = "hello"))
assert(encoded.id == 1 and encoded.text == "hello")

Arguments

Returns

runtimefunction#

local runtime: function<T>(typeObject: Type<T>): Info

Reads the semantic description carried by a first-class type witness. Generic consumers use the same descriptor as concrete callers.

Type parameters

Arguments

Returns

runtimeTypefunction#

local runtimeType: function(info: Info, index: integer): Type<unknown>?

Reads an available nominal witness reachable through stored fields or constructor parameters. An unresolved forward declaration returns nil.

Arguments

Returns