← Index

x/type/base

Base: execution-context / sandbox objects, via the Base class.

(Base make) -> a Base instance wrapping a fresh execution-context; (b eval expr) / (Base eval b expr) evaluates expr inside it, isolated from the outer env.

CONTRACT: a fresh base is the bare C ISA – no display/write, no catalogue protocol. Reach in with parent closures or (b bind …); see core/sandbox specs.

Field reflection: (b cell ‘line) walks the layout contract; (Base fields) lists the names. The raw C base rides the raw field; statics and tokenizer seams accept either form.

Class Base

Execution-context / sandbox objects: each base is a whole, isolated interpreter – its own environment, type registry, and reader state – wrapped as a Base instance.

CONTRACT: a fresh base is the bare C ISA – no display/write, no reader macros, no catalogue protocol. Reach in with parent closures or (b bind …); see core/sandbox specs.

An instance renders as #; the raw C base it wraps (the `raw` field) renders as the opaque #.

Field access walks the layout contract: (b cell ‘line), names from (Base fields).

raw

The raw C base object this instance wraps – what the C prims and tokenizer doors consume. Read it to hand the base to raw plumbing; (Base wrap r) re-clothes one.

Field: data carried by a Base instance.

(eval expr)

Evaluate expr inside this base, isolated from the outer env. An error raised inside propagates to the caller’s guard; the base’s env is restored to its pre-eval structure on the way out.

Instance method: called on a Base instance.

Parameters:

• expr : ANY — The form to evaluate (quote it – it is a value here)

Returns: ANY — The result of the evaluation

Examples:

(let ((b (Base make))) (b eval '(+ 1 2))) => 3

(bind name val)

Define name as val in this base’s environment, visible to subsequent evals – the door for handing a child selected capabilities.

Instance method: called on a Base instance.

Parameters:

• name : SYMBOL — The name to define
• val : ANY — The value to bind

Returns: ANY — val

Examples:

(let ((b (Base make))) (b bind 'x 5) (b eval 'x)) => 5

(make-type name h)

Register a custom type on this base – cross-base make-type. Handler closures are built in the CALLING base and travel with instances; this base is marked shared so the caller’s GC never sweeps them.

Instance method: called on a Base instance.

Parameters:

• name : STRING — The new type’s name
• h : LIST — Handler alist: (verb . handler) pairs, e.g. ‘write

Returns: ANY — The type handle, for use inside this base

(cell fname)

The object the layout contract’s path addresses for fname, walked from this base. A cell-label field’s value sits in the cell’s first slot; refuses non-base-rooted names.

What it hands back is raw engine structure. Some of it is a C-built spine – the type-alist field is one – whose nodes answer #f to pair?; walk those with the bare first/rest/null? accessors, never the List or Iter walkers, which refuse them.

Instance method: called on a Base instance.

Parameters:

• fname : SYMBOL — A base field name – see (Base fields)

Returns: ANY — The addressed cell/object

Examples:

(let ((b (Base make))) (%cell-int (first (b cell 'line)))) => 1

(fields)

Every base field name from the layout contract.

Instance method: called on a Base instance.

Returns: LIST — Field name symbols, contract order

Examples:

(List includes? 'line ((Base make) fields)) => #t

(%repr)

Inspection form: # (N = the base's live allocation count).

Instance method: called on a Base instance.

Returns: STRING — The repr string

(Base make)

Create a fully initialized, isolated interpreter base, wrapped as a Base instance: the built-in types, the C prims, and a read buffer – no lib is loaded.

Returns: OBJECT — A Base instance; its raw field is the C base object

Examples:

(let ((b (Base make))) (b eval '(* 6 7))) => 42

(Base make-tok)

Create a minimal tokenizer base, wrapped as a Base instance: no types, no prims – only the boolean singletons are inherited. For custom tokenizer type registration on an isolated base.

Returns: OBJECT — A Base instance

Examples:

(Base base? (Base make-tok)) => #t

(Base wrap r)

Clothe a raw base object as a Base instance.

Parameters:

• r : ANY — A raw base object (from the C prims or plumbing)

Returns: OBJECT — The instance

Examples:

((Base wrap ((Base make) raw)) eval '(+ 1 2)) => 3

(Base base? v)

Test whether v is a Base instance.

Parameters:

• v : ANY — Any value

Returns: BOOL — #t for Base instances only

Examples:

(Base base? 5) => #f

(Base raw-of v)

The raw base object of either form – instances unwrap, anything else passes through. The seam the statics and tokenizer doors use.

Parameters:

• v : ANY — A Base instance or raw base

Returns: ANY — The raw base object

Examples:

(let ((b (Base make))) (eq? (Base raw-of b) (b raw))) => #t
(let ((r ((Base make) raw))) (eq? (Base raw-of r) r)) => #t

(Base eval target expr)

Evaluate expr inside target, isolated from the outer env. An error raised in target propagates to the caller’s guard; target’s env is restored to its pre-eval structure on the way out.

Parameters:

• target : ANY — The base to evaluate in (instance or raw)
• expr : ANY — The form to evaluate (quote it – it is a value here)

Returns: ANY — The result of evaluating expr in target

Examples:

(let ((b (Base make))) (Base eval b '(+ 1 2))) => 3

(Base bind target name val)

Define name as val in target’s environment, visible to subsequent (Base eval target …) forms.

Parameters:

• target : ANY — The base to bind in (instance or raw)
• name : SYMBOL — The name to define
• val : ANY — The value to bind

Returns: ANY — val

Examples:

(let ((b (Base make))) (Base bind b 'x 5) (Base eval b 'x)) => 5

(Base make-type target name h)

Register a custom type on target – cross-base make-type. Handler closures are built in the CALLING base and travel with instances; target is marked shared so the caller’s GC never sweeps them.

Parameters:

• target : ANY — The base to register the type on (instance or raw)
• name : STRING — The new type’s name
• h : LIST — Handler alist: (verb . handler) pairs, e.g. ‘write

Returns: ANY — The type handle, for use inside target

(Base cell target fname)

The layout-contract cell for fname, walked from target. Refuses non-base-rooted names.

What it hands back is raw engine structure. Some of it is a C-built spine – the type-alist field is one – whose nodes answer #f to pair?; walk those with the bare first/rest/null? accessors, never the List or Iter walkers, which refuse them.

Parameters:

• target : ANY — The base to walk (instance or raw)
• fname : SYMBOL — A base field name – see (Base fields)

Returns: ANY — The addressed cell/object

Examples:

(%cell-int (first (Base cell (Base make) 'line))) => 1

(Base fields)

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

Returns: LIST — Field name symbols, contract order

Examples:

(List includes? 'line (Base fields)) => #t

(Base slots)

The positions in a base’s slot vector, from the engine’s contract (engine/tools/contract/base-slots.x): one row a slot, (position name (argument…) (type…)). A routine in a slot has the engine’s one signature, (base args), where args is a run of words, one an argument, each an object, an integer or a string as the row gives it.

Returns: LIST — The contract rows, position order

Examples:

(List includes? 'env-lookup (List map (fn (_ row) (first (rest row))) (Base slots))) => #t

(Base %slot-position name)

The contract position of slot name; refuses a name the contract does not list.

Returns: INTEGER — The position

Examples:

(Base %slot-position (first (rest (first (Base slots))))) => 0
(guard (e (Err label e)) (Base %slot-position 'no-such-slot)) => 'value

(Base slot target name)

The address of the routine in target’s slot name: the function pointer the engine calls through that position, as an integer.

Parameters:

• target : ANY — The base whose slot vector to read (instance or raw)
• name : SYMBOL — A slot name – see (Base slots)

Returns: INTEGER — The routine’s address

Examples:

(= (Base slot (Base make) 'env-lookup) (Base slot (%base) 'env-lookup)) => #t

(Base slot! target name routine)

Store routine in target’s slot name, so the engine calls it through that position from its next call on, in target alone. A callable’s function pointer is what is stored, and the caller keeps the callable alive for as long as the slot holds it. Storing back the address this answers restores the routine it replaced.

Parameters:

• target : ANY — The base whose slot vector to write (instance or raw)
• name : SYMBOL — A slot name – see (Base slots)
• routine : ANY — A callable, or a routine’s address as an integer

Returns: INTEGER — The address the slot held

Examples:

(let ((b (Base make))) (Base slot! b 'env-lookup (Base slot b 'env-lookup)) (b eval '(+ 1 2))) => 3