← Index

x/type/type

Type-system reflection: construction, lookup, struct navigation, and handler-stack wiring on the Type class.

Mechanism in lib/x/type/struct.x, filed under catalog ns type; load-time wiring fetch-and-caches the helpers instead of calling the class.

(Type wrap t) makes a type interactive: (t name), (t cell ‘type-write-stack), (t fields), (t push-write f). Field names come from the layout contract (engine/tools/contract/base-paths.x); (Type fields) lists them.

Class Type

Type-system reflection: construction, lookup, struct navigation, and handler-stack wiring. (Type wrap t) clothes a handle or struct as an interactive instance: (t name), (t cell ‘type-write-stack), (t push-write f).

handle

The type’s handle atom – the name atom (Type of) answers and the type-alist keys.

Member: data carried by a Type instance.

raw

The raw type – what the cell walkers and push-* wiring consume.

Member: data carried by a Type instance.

(name)

This type’s registered name.

Instance method: called on a Type instance.

Returns: STRING — The name

Examples:

((Type wrap (Type of 0)) name) => "INTEGER"

(cell fname)

The object the layout contract’s path addresses for fname, walked from this type’s struct. A handler-stack cell’s first slot is the handler list.

Instance method: called on a Type instance.

Parameters:

• fname : SYMBOL — A type field name – see (Type fields)

Returns: ANY — The addressed cell/object

Examples:

(null? ((Type wrap (Type of 0)) cell 'type-write-stack)) => #f

(fields)

Every type field name from the layout contract.

Instance method: called on a Type instance.

Returns: LIST — Field name symbols, contract order

(push-write f)

Push a write handler onto this type’s write stack (shadows the current one).

Instance method: called on a Type instance.

Parameters:

• f : CALLABLE — Write handler (fn (_ obj) …)

Returns: ANY — nil

(push-display f)

Push a display handler onto this type’s display stack.

Instance method: called on a Type instance.

Parameters:

• f : CALLABLE — Display handler

Returns: ANY — nil

(push-call f)

Push a call handler onto this type’s call stack (overrides how (obj …) dispatches).

Instance method: called on a Type instance.

Parameters:

• f : CALLABLE — Call handler (fn (_ obj . args) …)

Returns: ANY — nil

(push-op op f)

Register a binary generic-operator handler on this type.

Instance method: called on a Type instance.

Parameters:

• op : ATOM — Operator symbol, e.g. ‘+
• f : CALLABLE — Binary handler (fn (_ a b) …)

Returns: ANY — nil

(%repr)

Inspection form: #.

Instance method: called on a Type instance.

Returns: STRING — The repr string

(Type %layout-entry fname paths)

The contract row for fname, or nil.

Returns: ANY — The (name root step…) row

(Type %layout-cell o fname root)

The object addressed by fname’s contract path, walked from o; errors unless the row’s root is root.

Returns: ANY — The addressed cell/object

(Type %layout-fields root)

Every contract field name whose row has root root, contract order.

Returns: LIST — Name symbols

(Type wrap t)

Clothe a type as a Type instance for interactive use.

Parameters:

• t : ANY — A type handle (from Type of) or the type itself (from Type by-atom)

Returns: OBJECT — The Type instance; handle/raw members hold both forms

Examples:

((Type wrap (Type of 0)) name) => "INTEGER"

(Type %kind-code k)

The engine’s numeric code for a unit kind.

Parameters:

• k : SYMBOL — A unit kind

Returns: INT — 0..3

(Type %kind-mask kinds)

Pack kinds into the engine’s two-bits-per-unit mask.

Parameters:

• kinds : LIST — Unit kinds, unit 0 first

Returns: INT — The mask

(Type set-shape! ts n kinds)

Declare what each of a type’s units IS, not just how many there are. The collector traces ref units and leaves the rest alone – which is what makes a unit holding bytes or a foreign address declarable at all, since the marker writes through any pointer it is handed.

A fixed count describes its own units; a count of -k describes k leading units plus the kind of the slot-0-counted payload that follows, so (Type set-shape! ts -1 ‘(word ref)) is the vector.

Parameters:

• ts : ANY — Type struct (from Type by-atom)
• n : INT — Unit count – fixed, or -k for the slot-0-counted convention
• kinds : LIST — One kind per unit (ref word bytes foreign); the last repeats

Returns: ANY — The type struct

Examples:

(let ((st (Type by-atom (Type of "s")))) (same? (Type set-shape! st 1 '(bytes)) st)) => #t

(Type fields)

Every type field name in the layout contract (type-rooted rows of engine/tools/contract/base-paths.x).

Returns: LIST — Field name symbols, contract order

(Type cell ts fname)

The layout-contract cell for name, walked from struct ts. Refuses non-type-rooted names.

Parameters:

• ts : ANY — Type struct (from Type by-atom)
• fname : SYMBOL — A field name – see (Type fields)

Returns: ANY — The addressed cell/object

(Type make name slots)

Create a new custom type with the given handler slots; the reader checks it before the built-ins.

Parameters:

• name : STRING — Type name (e.g. “POINT”)
• slots : LIST — Handler alist: (call write display analyse read delimit iter ops from to …)

Returns: ANY — The new type’s handle atom

(Type make-instance ts value)

Create an instance of a custom type wrapping VALUE.

Parameters:

• ts : ANY — Type handle (from Type make)
• value : ANY — Instance payload

Returns: ANY — The new instance (self-evaluating)

(Type ? v ts)

Test whether V is an instance of the type named by TS.

Parameters:

• v : ANY — Value to test
• ts : ANY — Type handle

Returns: BOOL — #t if V’s type is TS

(Type of v)

Return the type handle of a value (nil for nil).

Parameters:

• v : ANY — Value

Returns: ATOM — The type’s handle atom

(Type name handle)

Return the name string of a type handle.

Parameters:

• handle : ATOM — Type handle (from Type of)

Returns: STRING — The type’s registered name

(Type alist)

Return the interpreter’s type alist from the base object.

Returns: LIST — The ((handle . struct) …) registry, reader-priority order

(Type by-atom handle)

Look up a type by its handle atom.

Parameters:

• handle : ATOM — Type handle (from Type of)

Returns: ANY — The type, or nil if unregistered

(Type io ts)

Navigate to a type’s IO group: (analyse (delimit (read (write (display))))).

Parameters:

• ts : ANY — Type struct (from Type by-atom)

Returns: ANY — The IO group

(Type cvt ts)

Navigate to a type’s conversion group: (from (to)).

Parameters:

• ts : ANY — Type struct

Returns: ANY — The CVT group

(Type proc ts)

Navigate to a type’s PROC group: (call-stack eval-stack).

Parameters:

• ts : ANY — Type struct

Returns: ANY — The PROC group

(Type write-cell ts)

The write-handler stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell (%set-first! to mutate)

(Type display-cell ts)

The display-handler stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type analyse-cell ts)

The analyse-handler (tokenizer scoring) stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type from-cell ts)

The from-conversion alist cell of a type (see the Convert class).

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type to-cell ts)

The to-conversion alist cell of a type (see the Convert class).

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type call-cell ts)

The call-handler stack cell of a type (how (obj …) dispatches).

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type call-top ts)

The current (top) call handler – capture before pushing to delegate to it.

Parameters:

• ts : ANY — Type struct

Returns: CALLABLE — The handler

(Type delimit-cell ts)

The delimit-handler stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type read-cell ts)

The read-handler stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type iter-cell ts)

The iter-handler stack cell of a type (how (iter obj) builds an iterator).

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type ops-cell ts)

The generic-operator alist stack cell of a type: ((op-sym . handler) …).

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

(Type push-write ts f)

Push a write handler onto a type’s write stack (shadows the current one).

Parameters:

• ts : ANY — Type struct
• f : CALLABLE — Write handler (fn (_ obj) …)

Returns: ANY — nil

(Type pop-write ts)

Pop the top write handler from a type’s write stack.

Parameters:

• ts : ANY — Type struct

Returns: ANY — nil

(Type push-display ts f)

Push a display handler onto a type’s display stack.

Parameters:

• ts : ANY — Type struct
• f : CALLABLE — Display handler

Returns: ANY — nil

(Type push-call ts f)

Push a call handler onto a type’s call stack (overrides how (obj …) dispatches).

Parameters:

• ts : ANY — Type struct
• f : CALLABLE — Call handler (fn (_ obj . args) …)

Returns: ANY — nil

(Type push-analyse ts f)

Push an analyse (tokenizer scoring) handler onto a type’s analyse stack.

Parameters:

• ts : ANY — Type struct
• f : CALLABLE — Analyse handler (fn (_ buffer score chr) …)

Returns: ANY — nil

(Type push-delimit ts f)

Push a delimit handler onto a type’s delimit stack.

Parameters:

• ts : ANY — Type struct
• f : CALLABLE — Delimit handler

Returns: ANY — nil

(Type push-read ts f)

Push a read handler onto a type’s read stack.

Parameters:

• ts : ANY — Type struct
• f : CALLABLE — Read handler (fn (_ buffer) …)

Returns: ANY — nil

(Type push-iter ts f)

Push an iter handler onto a type’s iter stack – sets how (iter obj) builds an iterator.

Parameters:

• ts : ANY — Type struct
• f : CALLABLE — Iter handler (fn (_ obj) -> iterator)

Returns: ANY — nil

(Type push-op ts op f)

Register a binary generic-operator handler on a type; the C operators (+ - * / % = <) dispatch here. A re-registration shadows the older handler.

Parameters:

• ts : ANY — Type struct
• op : ATOM — Operator symbol, e.g. ‘+
• f : CALLABLE — Binary handler (fn (_ a b) …); owns coercing a plain operand

Returns: ANY — nil

(Type refuse-arithmetic! ts tname)

Make a type refuse the arithmetic operators (+ - * / % <) with an err:type naming the operator and TNAME, where the C prims would otherwise fall through to integer arithmetic on the object’s pointer.

Parameters:

• ts : ANY — Type struct (from Type by-atom)
• tname : STRING — The type’s name, as the error message spells it

Returns: ANY — nil

(Type cast! obj src)

LOW-LEVEL: overwrite OBJ’s type tag with SRC’s (raw pointer write).

Parameters:

• obj : ANY — Object to retag
• src : ANY — Object whose type tag to copy

Returns: ANY — OBJ, retagged