lib/lisp.x

The Lisp runtime: reader, session, and evaluator.

Primary API

Functions

lisp_address

Var lisp_address(Var cell, Symbol tag)

Retags a raw evaluator cell as the typed pointer named by tag.

Source: lib/lisp.x:1046

lisp_car

Var lisp_car(Var value)

Returns the first element of value, or void when it is nil. A nonlist operand raises <bad-types>.

Source: lib/lisp.x:780

lisp_cdr

Var lisp_cdr(Var value)

Returns the tail of value, or nil when it is nil. A nonlist operand raises <bad-types>.

Source: lib/lisp.x:789

lisp_cell

Var lisp_cell(Var value)

Allocates one evaluator-owned raw Var slot initialized to value.

Source: lib/lisp.x:1040

lisp_load

Var lisp_load(Var cell)

Returns the raw value currently held in an evaluator cell.

Source: lib/lisp.x:1048

lisp_match_replace

Var lisp_match_replace(List input, Var pat, Var template)

Returns the instantiated template when input matches pat. List.match_replace returns a List, so a template that is a bare binder loses a scalar result. Lisp sees the replacement itself. A miss, malformed pattern, cache pressure, or machine error returns input unchanged.

Source: lib/lisp.x:1001

lisp_store

Var lisp_store(Var cell, Var value)

Stores value in an evaluator cell and returns it.

Source: lib/lisp.x:1050

lisp_string_lstrip

String lisp_string_lstrip(String string, Var chars)

Trims leading bytes, accepting the same charset values as strip.

Source: lib/lisp.x:989

lisp_string_rstrip

String lisp_string_rstrip(String string, Var chars)

Trims trailing bytes, accepting the same charset values as strip.

Source: lib/lisp.x:993

lisp_string_strip

String lisp_string_strip(String string, Var chars)

Trims the bytes in chars, using whitespace for an empty String.

Source: lib/lisp.x:985

lisp_truth

Var lisp_truth(Var value)

Returns Lisp true for every value except nil and void.

Source: lib/lisp.x:766

lisp_void

Var lisp_void(void)

Returns the void sentinel to the evaluator.

Source: lib/lisp.x:1038

Lisp

Lisp.adopt

void Lisp.adopt(Lisp lisp, Lisp parent)

Makes lisp read parent’s definitions for names it does not bind.

A name the child defines shadows the parent’s, and a write always lands in the child, so one child never observes another’s definitions. The child also takes the parent’s special forms rather than its own, because _auto_bindings_ok compares a binding’s identity and a program the parent compiled has to keep guarding correctly under a child.

The caller keeps parent alive for as long as any child names it, and freezes it with Lisp.freeze before the first child runs: a child’s values belong to a narrower Context than the parent’s, so nothing a child produces may become reachable from the parent.

Source: lib/lisp.x:714

Lisp.apply

Var Lisp.apply(Lisp lisp, Var callable, List values)

Applies callable to already evaluated values. Macros and evaluator special forms other than the built-in apply are not procedures and are rejected. The built-in accepts a callable and a List and recursively applies those already evaluated values. The Lisp session owns Scope allocations made by the call; returned canonical or caller-supplied values keep their existing owners. The caller retains responsibility for callable, values, and their referents.

Raises: <bad-arg> for a null session, <not-call> for a non-procedure or evaluator-only callable, <bad-arity> or <bad-types> at the call boundary, or a cause raised by the called procedure.

Source: lib/lisp.x:2834

Lisp.auto_prepare

int Lisp.auto_prepare(Lisp lisp)

Word-compiles every lambda this session’s globals name, in place.

Call it while the Context that owns lisp is current and before any child session runs, so each program’s frozen constants belong to that Context. Returns the number of lambdas that gained a program.

A lambda a global holds indirectly, inside a List or a Map value, is not reached: the globals a library defines are the callables a child resolves by name, and those are what a shared program guards against.

Source: lib/lisp.x:2697

Lisp.bind

void Lisp.bind(Lisp lisp, String name, Func function)

Installs function as name and transfers its storage to lisp. Invalid arguments raise <bad-arg> without transferring ownership. Once validation succeeds, the Func moves before the global insertion. The caller relinquishes ownership even if name canonicalization or Map growth then raises <alloc-fail>, <size-limit>, or <bad-enc>, but may borrow the pointer while the session lives. Values inside the Func, including its signature graph, retain their existing owners.

Source: lib/lisp.x:2934

Lisp.call_budget

void Lisp.call_budget(Lisp lisp, long budget)

Sets how many calls one evaluation of lisp may make before it is stopped. lisp must be a live session and budget must be positive. The default is LISP_CALL_STEP_MAX, which is large enough that only a computation that does not end reaches it; a test sets a small one to reach it quickly.

The budget belongs to the public entry. Lisp.eval, Lisp.apply, and Lisp.eval_string each open one, and a call that runs it out does not renew it, so one entry reports a runaway once however many calls follow.

Source: lib/lisp.x:2672

Lisp.eval

Var Lisp.eval(Lisp lisp, Var expression)

Evaluates one Lisp form in lisp. Evaluation is synchronous and may retain the expression or values it reaches in session globals, Lambdas, or captures as described by the module ownership rule. Effects completed before a later failure are not rolled back. Raises: <bad-arg> for a null session, or any evaluator, imported operation, or called-procedure cause.

Source: lib/lisp.x:2816

Lisp.eval_file

Var Lisp.eval_file(Lisp lisp, File source)

Reads and evaluates every form from file. Reading starts at the current stream position, consumes through EOF, and leaves the borrowed stream open. Forms run in order, so effects from forms completed before a later read or evaluation failure are not rolled back. A null Lisp session is rejected by Lisp.eval_string only after the stream has been consumed.

Raises: <bad-arg> for a null stream or embedded NUL, <io-fail>, <size-limit>, or <alloc-fail> while reading, or any cause from Lisp.eval_string.

Source: lib/lisp.x:2874

Lisp.eval_string

Var Lisp.eval_string(Lisp lisp, String source)

Reads and evaluates every form in source. Forms run in source order and the return value is the last result, or Lisp nil for a null, empty, or comment-only source. Globals and other effects completed before a later reader or evaluator failure remain installed.

Raises: <bad-arg> for a null session, <incomplete> or <malformed> while reading, or any cause from Lisp.eval.

Source: lib/lisp.x:2847

Lisp.freeze

void Lisp.freeze(Lisp lisp)

Marks lisp complete, so nothing produced later may reach it.

Word compilation is what this guards: a program’s frozen constants do not own their pointees, so one compiled while a unit’s Context is current would leave a frozen session holding values that die with that unit. After this, Lisp.auto_prepare is the only way a lambda this session owns gains a program.

Source: lib/lisp.x:730

Lisp.kernel

Lisp Lisp.kernel(void)

Creates an isolated embedded Lisp session with only evaluator primitives. The caller owns a successful session and must pass it to Lisp.destroy. Returns NULL if a long shared name cannot be owned by the active pool chain. Failure of native once initialization writes a diagnostic and aborts the process.

Raises: <alloc-fail> or <size-limit> while creating session storage, or <bad-enc> while interning shared or special-form names.

Source: lib/lisp.x:658

Lisp.new

Lisp Lisp.new(void)

Creates an isolated session with the standard Lisp environment loaded. The caller owns the result and must pass it to Lisp.destroy. If standard-source evaluation transfers, no handle is returned and the constructed session remains allocated. Raises any cause from Lisp.kernel or Lisp.eval_string.

Source: lib/lisp.x:687

Lisp.reslot

void Lisp.reslot(void *storage, List params, int count)

Renames the live slots of the current shared-machine frame. params names every slot the frame holds: the Lambda’s parameters first, then the bindings a lowered binding scope opened, in slot order. count is how many of those slots are live. The evaluator resolves a free name through this list, so a form that leaves the machine from inside a lowered binding scope still reads that scope’s bindings.

Source: lib/lisp.x:161

Lisp.step

int Lisp.step(void *storage)

Counts one call made by the running machine and reports whether the evaluation in progress has made too many. An exhausted budget stays exhausted until the entry that opened it returns.

Source: lib/lisp.x:146

Lisp.try_get

int Lisp.try_get(Lisp lisp, String name, Var *out)

Writes the global binding for name to out when present. Returns 1 only after writing the borrowed value. A null session, name, or output, or an absent name returns 0 and leaves out unchanged. Raises <alloc-fail> or <bad-enc> when a nonempty lookup name cannot be canonicalized.

Source: lib/lisp.x:2896

Advanced and interop API

Lisp

Lisp.apply_values

Var Lisp.apply_values( void *storage, Var callable, const Var *values, int count)

Applies a Lisp callable to already evaluated shared-machine values. storage names the running context; values may be null only when count is zero, count must not be negative, and the array is borrowed for the call. The active Lisp session owns new Scope allocations; other returned Vars keep their ordinary owners. Raises any cause from argument materialization or the callable.

Source: lib/lisp.x:175

Lisp.auto_disable

void Lisp.auto_disable(Lisp lisp, int disabled)

Forces calls through the recursive evaluator when disabled is nonzero. lisp must be a live session. Re-enabling AUTO preserves published programs, thresholds, statistics, and the instrumentation pointer.

Source: lib/lisp.x:2683

Lisp.auto_instrument

void Lisp.auto_instrument(Lisp lisp, MachineStats *stats)

Selects optional detailed machine statistics for later AUTO executions. lisp must be a live session. stats is borrowed, retained without initialization, and updated in place; it must outlive every evaluation until replaced or cleared with NULL.

Source: lib/lisp.x:2658

Lisp.auto_stats

LispAutoStats Lisp.auto_stats(Lisp lisp)

Returns the current cumulative automatic-evaluator statistics for lisp. lisp must be a live session. The returned structure is a value snapshot and does not reset any counter.

Source: lib/lisp.x:2651

Lisp.cleanup

void Lisp.cleanup(Lisp value)

Ends the owned lifetime when a managed local leaves its block.

Source: lib/lisp.x:2942

Lisp.destroy

void Lisp.destroy(Lisp lisp)

Releases a Lisp session and invalidates all session-owned state. This includes its global and reserved Maps, Lambdas, transferred Funcs, prepared programs, and machine slots. Borrowed values are not released. A null session does nothing; no evaluation or machine call may remain active. Destroying its still-active Scope raises <bad-state>.

Source: lib/lisp.x:699

Lisp.enter

void Lisp.enter(void *storage, Var callable, const Var *values, int count)

Pushes one prepared-Lambda environment for the shared machine. storage names a running LispMachine context, callable is a prepared Lambda, and values supplies the Lambda’s count borrowed arguments. The array and its values must remain live until the matching Lisp.leave.

Source: lib/lisp.x:103

Lisp.leave

void Lisp.leave(void *storage)

Pops the innermost environment installed by Lisp.enter. Calls must balance in last-in, first-out order; the borrowed argument array is no longer retained afterward.

Source: lib/lisp.x:121

Lisp.precall

int Lisp.precall(void *storage, Var callable, List raw, Var *value)

Handles a callable that cannot continue through prepared machine dispatch. Returns 0 and leaves value unchanged when the machine may proceed. Otherwise it applies the callable to borrowed raw forms, writes value, and returns 1. storage and value must be nonnull and belong to the running LispMachine invocation.

Source: lib/lisp.x:198

Lisp.program

int Lisp.program(Var callable, MachineView *view, int *nparam, Var *body)

Returns the prepared AUTO program for an eligible Lisp Lambda. On success, writes all three nonnull outputs and returns 1. Otherwise it returns 0 and leaves them unchanged. The view and body are borrowed from the Lambda and remain valid only while its owning Lisp session lives.

Source: lib/lisp.x:67

Lisp.read

Symbol Lisp.read(Lisp lisp, String source, unsigned *cursor, Var *out)

Reads one Lisp form and returns <value> or <eof>. A nonnull out receives the form only for <value>; it is otherwise unchanged. New result storage uses the caller’s active Scope and canonical pools, not the temporary token Scope, and remains valid until those owners are released. On success cursor advances past the form, at EOF it becomes the source length, and on a reader error it identifies the failing form’s first token. A null source or cursor returns <eof> without raising. A nonnull cursor must initially hold a byte offset no greater than the source length. A successful session construction must first initialize the shared reader names; afterward lisp is not consulted and may be null.

Raises: <incomplete> for a truncated form, <malformed> for invalid reader syntax, or <alloc-fail>, <size-limit>, or <bad-enc> while tokenizing, constructing, interning, or boxing the form.

Source: lib/lisp.x:748

Lisp.resolve

int Lisp.resolve(void *storage, Var name, Var *value)

Resolves one global Lisp name for the running shared machine. storage must be the context of a running LispMachine and value must be nonnull. Returns 1 and writes the borrowed binding, or returns 0 and leaves the output unchanged.

Lowering emits this read only for a name that is none of the frame’s slots and none of the Lambda’s captures. A free name is lexical, so the only place left to look is the session and its parents, and the frame is not consulted.

Source: lib/lisp.x:89

Lisp.retarget

void Lisp.retarget(void *storage, Var callable, const Var *values, int count)

Replaces the current shared-machine environment for a tail call. The callee may be any prepared Lambda, not only the running one, because a free name is lexical and the callee never reads the frame it lands in. The parent environment is preserved. callable must be its prepared Lambda, count must match its parameters, and the borrowed values remain live until another retarget or the environment is left.

Source: lib/lisp.x:135

Lisp.set_global

void Lisp.set_global(Lisp lisp, String name, Var value)

Binds name to value in the embedded Lisp global environment. The session stores the value in a raw slot, so void remains distinct from Lisp nil. The binding does not take ownership of value referents; their canonical graphs or other owners must outlive the binding or session. Binding an x2c. name protects that namespace from later Lisp def forms, but direct calls to this function may replace such a binding.

Raises: <bad-arg> for a null session or name, or <alloc-fail>, <size-limit>, or <bad-enc> while canonicalizing or storing the binding.

Source: lib/lisp.x:2909

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Functions

lisp_add

Var lisp_add(Var a, Var b)

Concatenates when either operand is String, otherwise adds dynamically.

Source: lib/lisp.x:866

lisp_atom

Var lisp_atom(Var value)

Returns Lisp true unless value is a nonempty List.

Source: lib/lisp.x:771

lisp_compare

Var lisp_compare(Var a, Var b)

Compares Lisp numbers by value and returns a boxed negative, zero, or positive. Integer and floating encodings of one number compare equal. A nonnumeric operand raises <bad-types>.

Source: lib/lisp.x:854

lisp_divide

Var lisp_divide(List values)

Divides the first value by each later one; one value reciprocates it. An empty input raises <bad-arity>.

Source: lib/lisp.x:908

lisp_eq

Var lisp_eq(Var a, Var b)

Returns Lisp true when a and b are equal by Var.equal.

Source: lib/lisp.x:796

lisp_eq_chain

Var lisp_eq_chain(List values)

Reports whether every neighbouring pair of numbers compares equal. Fewer than two values raise <bad-arity>; a nonnumber raises <bad-types>.

Source: lib/lisp.x:938

lisp_ge_chain

Var lisp_ge_chain(List values)

Reports whether two or more numbers never increase. Fewer than two values raise <bad-arity>; a nonnumber raises <bad-types>.

Source: lib/lisp.x:962

lisp_gt_chain

Var lisp_gt_chain(List values)

Reports whether two or more numbers strictly decrease. Fewer than two values raise <bad-arity>; a nonnumber raises <bad-types>.

Source: lib/lisp.x:956

lisp_le_chain

Var lisp_le_chain(List values)

Reports whether two or more numbers never decrease. Fewer than two values raise <bad-arity>; a nonnumber raises <bad-types>.

Source: lib/lisp.x:950

lisp_list

Var lisp_list(Var value)

Returns Lisp true when value is List-typed, including nil.

Source: lib/lisp.x:802

lisp_lt_chain

Var lisp_lt_chain(List values)

Reports whether two or more numbers strictly increase. Fewer than two values raise <bad-arity>; a nonnumber raises <bad-types>.

Source: lib/lisp.x:944

lisp_minus

Var lisp_minus(List values)

Subtracts each later value from the first; one value negates it. An empty input raises <bad-arity>.

Source: lib/lisp.x:887

lisp_number

Var lisp_number(Var value)

Returns Lisp true when value has an integer or floating kind.

Source: lib/lisp.x:810

lisp_pair

Var lisp_pair(Var value)

Returns Lisp true when value is a nonempty List.

Source: lib/lisp.x:799

lisp_plus

Var lisp_plus(List values)

Adds or concatenates every value left to right; no values gives 0.

Source: lib/lisp.x:877

lisp_procedure

Var lisp_procedure(Var value)

Returns Lisp true when value is a native function or Lambda.

Source: lib/lisp.x:819

lisp_read_file

Var lisp_read_file(String path)

Reads path completely, closes it, and returns its boxed String contents. Raises the open, read, size, or allocation cause reported by File. An opened stream is still closed on transfer.

Source: lib/lisp.x:1012

lisp_repr

Var lisp_repr(Var value)

Boxes the readable representation of value.

Source: lib/lisp.x:968

lisp_str

Var lisp_str(Var value)

Boxes the display String of value.

Source: lib/lisp.x:965

lisp_string

Var lisp_string(Var value)

Returns Lisp true when value is a String.

Source: lib/lisp.x:813

lisp_string_append

Var lisp_string_append(String left, String right)

Returns the boxed concatenation of left and right.

Source: lib/lisp.x:971

lisp_string_downcase

Var lisp_string_downcase(String string)

Returns a boxed lower-case copy of string.

Source: lib/lisp.x:978

lisp_substring

Var lisp_substring(String string, int start, int stop)

Returns the boxed unit-step slice string[start:stop].

Source: lib/lisp.x:974

lisp_symbol

Var lisp_symbol(Var value)

Returns Lisp true when value has Symbol kind.

Source: lib/lisp.x:816

lisp_times

Var lisp_times(List values)

Multiplies every value; no values gives 1.

Source: lib/lisp.x:899

lisp_type

Symbol lisp_type(Var value)

Returns the runtime tag of value.

Source: lib/lisp.x:862

lisp_write_file

Var lisp_write_file(String path, String text)

Replaces path with text and reports Lisp success. The file is opened with truncation and always closed. A write or close failure returns nil after any accepted bytes; this operation is not atomic. An open failure transfers its File cause. Null text writes an empty file.

Source: lib/lisp.x:1021

Lisp

Lisp.evaluate

Var Lisp.evaluate(void *storage, Var form)

Evaluates one borrowed form in the running machine’s environment. storage must name a running LispMachine context. The form is interpreted by the ordinary evaluator with the machine frame’s parameters and captures visible, so a form the lowering does not cover behaves exactly as it does outside a prepared program. Results keep their ordinary session or value owners. Raises any cause the form raises.

Source: lib/lisp.x:240

Lisp.expanded

int Lisp.expanded(void *storage, List site, Var *out)

Checks a lowered form after preceding effects have run. Returns 0 when its dependencies match. Otherwise evaluates the original call into out and returns 1. storage must name the running context, site must contain the original form and dependency pairs, and out must be nonnull. Results retain their ordinary session or value owners.

Source: lib/lisp.x:251

Lisp.immediate

Var Lisp.immediate(void *storage, Var callable)

Resolves a prepared immediate lambda in the running machine context. Returns callable while the lambda constructor is unchanged; otherwise evaluates its original literal. The caller environment stays live and is borrowed by the prepared body. storage must name the running context, and callable must be its prepared immediate Lambda.

Source: lib/lisp.x:220

Public types

Lisp

typedef struct Lisp *Lisp

Represents one isolated embedded Lisp session. Create it with Lisp.new or Lisp.kernel and end it with Lisp.destroy. The module header describes its owned and borrowed state. A session is mutable and requires caller serialization.

Source: lib/lisp.x:42

LispAutoStats

typedef struct LispAutoStats { long invocations, machine_entries, machine_errors; long analyses, published, ineligible; long guard_failures, remembered_fallbacks; long inlined_scopes; long inline_declines; long program_bytes; } LispAutoStats

Reports cumulative automatic-evaluator activity for one Lisp session. Counter values are snapshots since session creation. program_bytes counts published programs still owned by the session; detailed machine counters are collected separately through Lisp.auto_instrument.

Source: lib/lisp.x:53

Design notes

Each Lisp session owns a Scope holding its global environment. Evaluation uses eager left-to-right arguments for lambdas and natives, raw arguments for macros and special forms, macro expansion evaluated once in the caller’s environment, globals able to shadow reserved forms, nil as the only false value, and by-value capture of free locals through body flattening.

Identifiers use canonical Atoms: compact x2c Symbols when their spelling round-trips exactly, with direct canonical-String <lsym> Vars as the arbitrary-length, case-sensitive fallback. The reader converts shared Tokenizer output into Var and List forms.

The session Scope owns the Lisp record, Maps, Lambdas, bound Func storage, prepared programs, and reusable machine slots. The internal lisp-machine.x decoder executes eligible prepared programs. Maps, Lambda bodies, and captures retain Vars by value without cloning their referents. Canonical graphs and identity-bearing values therefore keep their pool or caller ownership and must outlive every session entry that refers to them. A session is not synchronized; its caller serializes evaluation and mutation and destroys it only after every call has returned.

Tests and examples

make verify (unittest/test-lisp.x) and make examples.