← 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 catalogue 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.

Field: data carried by a Type instance.

raw

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

Field: 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

Examples:

(same? (first ((Type wrap (Type of 0)) fields)) (first (Type fields))) => #t

(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

Examples:

((Type wrap (Type of 0)) %repr) => "#<type:INTEGER>"

(Type %layout-entry fname paths)

The contract row for fname, or nil.

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

Examples:

(first (rest (Type %layout-entry 'type-write-stack %base-paths))) => 'type
(null? (Type %layout-entry 'no-such-field %base-paths)) => #t

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type %layout-cell ts 'type-write-stack 'type) (first (Type write-cell ts)))) => #t

(Type %layout-fields root)

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

Returns: LIST — Name symbols

Examples:

(first (Type %layout-fields 'type)) => 'type-name-stack

(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 fields hold both forms

Examples:

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

(Type %unit-label k)

The engine’s numeric code for a unit label.

Parameters:

• k : SYMBOL — A unit label

Returns: INTEGER — 0..3

Examples:

(Type %unit-label 'ref) => 0
(Type %unit-label 'word) => 1

(Type %unit-label-mask labels)

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

Parameters:

• labels : LIST — Unit labels, unit 0 first

Returns: INTEGER — The mask

Examples:

(Type %unit-label-mask '(word ref)) => 1

(Type set-unit-labels! ts n labels)

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 label of the slot-0-counted payload that follows, so (Type set-unit-labels! ts -1 ‘(word ref)) is the vector.

Parameters:

• ts : ANY — Type struct (from Type by-atom)
• n : INTEGER — Unit count – fixed, or -k for the slot-0-counted convention
• labels : LIST — One label 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-unit-labels! 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

Examples:

(first (Type fields)) => 'type-name-stack

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type cell ts 'type-io) (Type io ts))) => #t

(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

Examples:

(Type ? 7 (Type of 0)) => #t
(Type ? "7" (Type of 0)) => #f

(Type of v)

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

Parameters:

• v : ANY — Value

Returns: ATOM — The type’s handle atom

Examples:

(same? (Type of 1) (Type of 2)) => #t
(null? (Type of ())) => #t

(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

Examples:

(Type name (Type of "s")) => "STRING"
(Type name (Type of (list 1))) => "LIST"

(Type alist)

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

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

Examples:

(let ((row (first (Type alist)))) (same? (rest row) (Type by-atom (first row)))) => #t

(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

Examples:

((Type wrap (Type by-atom (Type of 0))) name) => "INTEGER"
(null? (Type by-atom 'no-such-type)) => #t

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type io ts) (Type cell ts 'type-io))) => #t

(Type cvt ts)

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

Parameters:

• ts : ANY — Type struct

Returns: ANY — The CVT group

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type cvt ts) (Type cell ts 'type-cvt))) => #t

(Type proc ts)

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

Parameters:

• ts : ANY — Type struct

Returns: ANY — The PROC group

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type proc ts) (Type cell ts 'type-proc))) => #t

(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)

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (first (Type write-cell ts)) (Type cell ts 'type-write-stack))) => #t

(Type display-cell ts)

The display-handler stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (first (Type display-cell ts)) (Type cell ts 'type-display-stack))) => #t

(Type analyse-cell ts)

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

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (first (Type analyse-cell ts)) (Type cell ts 'type-analyse-stack))) => #t

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type from-cell ts) (Type cell ts 'type-from-stack))) => #t

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type to-cell ts) (Type cell ts 'type-to-stack))) => #t

(Type call-cell ts)

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

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (first (Type call-cell ts)) (Type cell ts 'type-call-stack))) => #t

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type call-top ts) (first (first (Type call-cell ts))))) => #t

(Type delimit-cell ts)

The delimit-handler stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (first (Type delimit-cell ts)) (Type cell ts 'type-delimit-stack))) => #t

(Type read-cell ts)

The read-handler stack cell of a type.

Parameters:

• ts : ANY — Type struct

Returns: ANY — The cell

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (first (Type read-cell ts)) (Type cell ts 'type-read-stack))) => #t

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (first (Type iter-cell ts)) (Type cell ts 'type-iter-stack))) => #t

(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

Examples:

(let ((ts (Type by-atom (Type of 0)))) (same? (Type ops-cell ts) (Type cell ts 'type-ops-stack))) => #t

(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 label with SRC’s (raw pointer write).

Parameters:

• obj : ANY — Object to relabel
• src : ANY — Object whose type label to copy

Returns: ANY — OBJ, relabelled

Type/named

Look up a type handle by its registered name: nil when no registered type has that name. NAME is a bare symbol or a string as written; any other form is evaluated and must answer one.

Parameters:

• name : ANY — The registered name: a symbol or a string as written, or a form that answers one

Returns: ATOM — The type’s handle atom, or nil

Examples:

(Type name (Type named INTEGER)) => "INTEGER"