← Index

x/doc/doc-prims

Retroactive documentation for C primitives, boot forms, and type system functions.

Core forms

lit

Return the argument unevaluated (quote).

Parameters:

• form : ANY — Any expression

Returns: ANY — The expression itself

Examples:

(lit x) => 'x
(lit (1 2 3)) => (1 2 3)

def

Bind a name to a value in the current environment.

Value is evaluated before the name is bound. Use the self parameter (first arg to fn) for recursion.

Parameters:

• name : SYMBOL — Name to bind
• value : ANY — Expression to evaluate and bind

Examples:

(def x 42) => 42

See also: set!

set!

Mutate an existing binding.

Signals an error if name is not already bound.

Parameters:

• name : SYMBOL — Bound name to update
• value : ANY — New value

Examples:

(do (def x 1) (set! x 2) x) => 2

See also: def

fn

Create a closure (applicative: arguments are evaluated before the body runs).

Parameters:

• params : LIST — Parameter list: (a b), (a . rest), or args for variadic
• body : ANY — Body expression(s)

Returns: PROCEDURE — A new closure

Examples:

(def add (fn (_ a b) (+ a b))) => 
((fn (_ x) (* x x)) 5) => 25

See also: op

op

Create an operative (fexpr: arguments are NOT evaluated).

Use eval with the env parameter to evaluate arguments selectively.

Parameters:

• params : LIST — Formal parameters for unevaluated args
• env-param : SYMBOL — Name bound to caller’s environment
• body : ANY — Body expression(s)

Returns: OPERATIVE — A new operative

Examples:

(def my-if (op (test then else) e (if (eval test e) (eval then e) (eval else e)))) => 

See also: fn

eval

Evaluate an expression, optionally in a given environment.

With one arg: uses TCO (tail-call safe). With env arg: saves/restores env after.

An environment is one pair, (bindings . parent), not an alist. The engine does not check its shape: a hand-built one, such as (list (pair ‘x 5)), crashes the process.

Parameters:

• expr : ANY — Expression to evaluate
• env : PAIR — Environment to evaluate in (optional): one an operative receives as its environment parameter, or one (Env current) or (Fn env f) answers

Returns: ANY — Result of evaluation

Examples:

(eval '(+ 1 2)) => 3
(let ((k 7)) ((op () e (eval '(+ k 1) e)))) => 8

See also: eval! Env

eval!

Evaluate in current environment, returning the result immediately.

No TCO, no env save/restore. Use for non-tail evaluation of computed forms.

Parameters:

• expr : ANY — Expression to evaluate

Returns: ANY — Result of evaluation

Examples:

(eval! '(* 6 7)) => 42

See also: eval

match

Pattern matching: evaluate clauses until a test succeeds.

Similar to cond but a C primitive. Tests are evaluated in order.

Parameters:

• clauses : LIST — ((test result) …) pairs — first truthy test wins

Examples:

(match ((= x 0) "zero") ((< x 0) "neg") (#t "pos")) => 

guard

Error handler: evaluate body with an error guard.

Parameters:

• var : SYMBOL — Name bound to the error value
• handler : ANY — Expression evaluated if error occurs (var is bound)
• body : ANY — Expression to evaluate

Examples:

(guard (e (list 'caught e)) (error "boom")) => ('caught "boom")

error

Signal an error with a message.

Parameters:

• message : STRING — Error message
• value : ANY — Associated value (optional)

Examples:

(guard (e e) (error "bad input")) => "bad input"

wrap

Create an applicative from a combiner (evaluates args before calling).

Parameters:

• combiner : CALLABLE — An operative or procedure

Returns: CALLABLE — An applicative

Examples:

((wrap (op (a) e a)) (+ 1 2)) => 3

unwrap

Extract the underlying combiner from an applicative.

Parameters:

• applicative : CALLABLE — A wrapped combiner

Returns: CALLABLE — The underlying combiner

Examples:

((unwrap (wrap (op (a) e a))) (+ 1 2)) => ('+ 1 2)

Pair operations

pair

Create a new pair (cons cell) from two values.

Parameters:

• a : ANY — First element (head)
• d : ANY — Second element (tail)

Returns: PAIR — A new pair

Examples:

(pair 1 2) => (1 . 2)
(pair 1 (pair 2 ())) => (1 2)

See also: first rest

first

Return the first element (head) of a pair.

Parameters:

• p : PAIR — A pair

Returns: ANY — The first element

Examples:

(first '(1 2 3)) => 1

See also: rest pair

rest

Return the second element (tail) of a pair.

Parameters:

• p : PAIR — A pair

Returns: ANY — The second element

Examples:

(rest '(1 2 3)) => (2 3)

See also: first pair

Arithmetic

+

Variadic addition. Returns the sum of all arguments.

Parameters:

• args : NUMBER — Zero or more numbers

Returns: NUMBER — Sum of all arguments, or 0 with no arguments

Examples:

(+ 1 2 3) => 6
(+) => 0

-

Variadic subtraction. With one argument, negates. With multiple, folds left.

Parameters:

• args : NUMBER — One or more numbers

Returns: NUMBER — Difference, or negation with one argument

Examples:

(- 10 3 2) => 5
(- 5) => -5

*

Variadic multiplication. Returns the product of all arguments.

Parameters:

• args : NUMBER — Zero or more numbers

Returns: NUMBER — Product of all arguments, or 1 with no arguments

Examples:

(* 2 3 4) => 24
(*) => 1

/

Variadic integer division. Folds left.

Parameters:

• args : NUMBER — One or more numbers

Returns: NUMBER — Quotient from left fold

Examples:

(/ 100 5 2) => 10

%

Variadic modulo. Folds left.

Parameters:

• args : NUMBER — Two or more numbers

Returns: NUMBER — Remainder from left fold

Examples:

(% 10 3) => 1

~

Bitwise NOT.

Parameters:

• n : INTEGER — Integer

Returns: INTEGER — Bitwise complement

Examples:

(~ 0) => -1
(~ 5) => -6

&

Bitwise AND.

Parameters:

• a : INTEGER — First operand
• b : INTEGER — Second operand

Returns: INTEGER — Bitwise AND

Examples:

(& 12 10) => 8

|

Bitwise OR.

Parameters:

• a : INTEGER — First operand
• b : INTEGER — Second operand

Returns: INTEGER — Bitwise OR

Examples:

(| 12 10) => 14

^

Bitwise XOR.

Parameters:

• a : INTEGER — First operand
• b : INTEGER — Second operand

Returns: INTEGER — Bitwise XOR

Examples:

(^ 12 10) => 6

<<

Left shift.

Parameters:

• n : INTEGER — Value to shift
• count : INTEGER — Number of bits

Returns: INTEGER — Shifted value

Examples:

(<< 1 4) => 16

>>

Arithmetic right shift.

Parameters:

• n : INTEGER — Value to shift
• count : INTEGER — Number of bits

Returns: INTEGER — Shifted value

Examples:

(>> 16 2) => 4
(>> -16 2) => -4

Predicates

eq?

Compare the value words of a and b: #t when the two hold the same word. An integer, a character or a symbol compares by its value; any other object by its first data word, so two distinct pairs whose first elements are the same object answer #t, as do an integer and the character with that code. Use same? for object identity.

Parameters:

• a : ANY — First value
• b : ANY — Second value

Returns: BOOL — #t when the value words are the same

Examples:

(eq? 'x 'x) => #t
(eq? (pair 'x 1) (pair 'x 9)) => #t
(same? (pair 'x 1) (pair 'x 9)) => #f

See also: same?

same?

Test object identity: #t when a and b are the same object. Values that are equal but made separately are not: two integer literals with one value, or two strings with one text, answer #f. nil, #t and #f are each a single object.

Parameters:

• a : ANY — First value
• b : ANY — Second value

Returns: BOOL — #t when a and b are the same object

Examples:

(let ((p (pair 'x 1))) (same? p p)) => #t
(same? (pair 'x 1) (pair 'x 9)) => #f
(same? 7 7) => #f
(same? () ()) => #t

See also: eq?

=

Test numeric equality.

Parameters:

• a : INTEGER — First number
• b : INTEGER — Second number

Returns: BOOL — t if equal

Examples:

(= 3 3) => #t
(= 3 4) => #f

<

Test numeric less-than.

Parameters:

• a : INTEGER — First number
• b : INTEGER — Second number

Returns: BOOL — t if a < b

Examples:

(< 1 2) => #t
(< 2 1) => #f

Strings

symbol->str

Convert a symbol to a string.

Parameters:

• sym : SYMBOL — A symbol

Returns: STRING — The symbol’s name

Examples:

(symbol->str 'abc) => "abc"

bytes->str

Pack a list of characters into a string, one low byte per char.

Parameters:

• bytes : LIST — List of byte-valued characters

Returns: STRING — A string of those bytes

Examples:

(bytes->str (list #\h #\i)) => "hi"

I/O

write

Write a value in machine-readable form.

Strings are quoted, characters show read syntax. Use for serialization.

Parameters:

• val : ANY — Value to write

See also: display

display

Display a value in human-readable form.

Strings are unquoted, characters are bare. Use for user output.

Parameters:

• val : ANY — Value to display

See also: write

Memory management

alloc-limit!

Set the allocation ceiling (runaway-memory guard): the process stops rather than allocate past n objects. 0 disables.

Parameters:

• n : INTEGER — Object-count ceiling; 0 = unlimited

Foreign function interface

Continuations

call/cc

Call a function with the current continuation.

Parameters:

• f : CALLABLE — Function receiving the continuation

Returns: ANY — Result of f, or value passed to continuation

Examples:

(+ 1 (call/cc (fn (_ k) (k 41)))) => 42
(+ 1 (call/cc (fn (_ k) 2))) => 3

x-core operatives

null?

Test if a value is nil (the empty list).

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if nil

Examples:

(null? ()) => #t
(null? '(1)) => #f

pair?

Test if a value is a pair (cons cell).

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if pair

Examples:

(pair? '(1)) => #t
(pair? ()) => #f

atom?

Test if a value is an atom (not a pair).

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if not a pair

Examples:

(atom? 5) => #t
(atom? '(1)) => #f

number?

Test if a value is an integer.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if integer

Examples:

(number? 42) => #t
(number? "42") => #f

real?

Test if a value is a real number: a number that is not complex. The number modules extend it in place as they load.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if real

Examples:

(real? 42) => #t
(real? 'a) => #f

str?

Test if a value is a string.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if string

Examples:

(str? "a") => #t
(str? 'a) => #f

symbol?

Test if a value is a symbol.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if symbol

Examples:

(symbol? 'a) => #t
(symbol? "a") => #f

char?

Test if a value is a character.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if character

Examples:

(char? #\a) => #t
(char? "a") => #f

procedure?

Test if a value is callable (procedure or primitive).

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if procedure or primitive

Examples:

(procedure? list) => #t
(procedure? 'list) => #f

if

Conditional: evaluate test, then branch.

Parameters:

• test : ANY — Condition expression
• then : ANY — True branch
• else : ANY — False branch (optional)

Examples:

(if (> 3 2) "yes" "no") => "yes"

See also: match cond

let

Bind local variables and evaluate body.

Named let: (let name ((var init) …) body) creates a loop.

Parameters:

• bindings : LIST — ((name value) …) binding pairs
• body : ANY — Body expression

Examples:

(let ((x 1) (y 2)) (+ x y)) => 3
(let loop ((n 5) (acc 1)) (if (= n 0) acc (loop (- n 1) (* acc n)))) => 120

See also: letrec

do

Evaluate expressions sequentially, return last result.

Parameters:

• exprs : ANY — One or more expressions

Examples:

(do (def x 1) (+ x 1)) => 2

begin

Alias for do.

Examples:

(begin 1 2) => 2

See also: do

not

Logical negation.

Parameters:

• x : ANY — Value to negate

Returns: BOOL — t if x is falsy

Examples:

(not #f) => #t
(not 0) => #f

list

Create a list from arguments.

Parameters:

• args : ANY — Zero or more values

Returns: LIST — A new list

Examples:

(list 1 2 3) => (1 2 3)

and

Short-circuit logical AND.

Parameters:

• args : ANY — Zero or more expressions

Returns: ANY — Last truthy value, or #f

Examples:

(and 1 2 3) => 3

or

Short-circuit logical OR.

Parameters:

• args : ANY — Zero or more expressions

Returns: ANY — First truthy value, or nil

Examples:

(or #f 42) => 42

newline

Display a newline character.

quasi

Quasiquote: template with unquote and splicing.

Use , to unquote a single expression, ,@ to splice a list.

Parameters:

• template : ANY — Template expression with , and ,@ escapes

Examples:

(let ((x 42)) (quasi (a ,x b))) => ('a 42 'b)

repl

Start the read-eval-print loop.

Customizable: %repl-prompt and %repl-print control display.

include-once

Load and evaluate a file, skipping if already loaded.

Parameters:

• path : STRING — File path to include

provide

Register a module’s exported symbols.

Parameters:

• name : SYMBOL — Module name, e.g. x/list
• exports : SYMBOL — Exported symbol names (variadic)

import

Import a module (include its file if not yet loaded).

Parameters:

• name : SYMBOL — Module name to import

str=?

Test string equality.

Parameters:

• a : STRING — First string
• b : STRING — Second string

Returns: BOOL — t if equal

Examples:

(str=? "abc" "abc") => #t
(str=? "abc" "abd") => #f

require-once

Include a file only if it has not been loaded before. Alias for include-once.

Parameters:

• path : STRING — File path to include

See also: include-once

doc

Attach documentation metadata to a definition, provide, or bare symbol.

Three forms: (doc (def name val) meta… desc), (doc (provide name syms) meta… desc), (doc name meta… desc)

Meta forms: (param name TYPE desc), (returns TYPE desc), (example expr result), (see name), (note text)

note

Section marker for documentation grouping. No-op at runtime.

Parameters:

• text : STRING — Section description

help

Look up documentation in the REPL.

(help) shows overview. (help name) shows function, class or module docs; (help Class member) shows one member. (help modules) lists all modules.

A name is a bare symbol as written, or an expression that evaluates to one, such as ‘name. Anything else answers “No documentation”. A class listing leaves out members whose names begin with %; (help Class %member) still answers for one by name.

apropos

Search documentation by name substring, printing each match with its description.

Parameters:

• str : STRING — Substring to search for: a string, a bare symbol, or an expression that evaluates to one

Returns: LIST — The matching names, as symbols, sorted by name; () when nothing matches

modules

List all known modules with load status and descriptions.

Primitives catalogue

prims

The primitives catalogue: an alist of (ns . ((method . impl) …)) domains.

The registry of stable implementation identities; modules fetch dependencies

from it at load instead of assuming ambient global names.

Returns: LIST — The live catalogue alist

Examples:

(pair? (prims)) => #t

See also: prim-ref

prim-domain

The method alist filed under a catalogue namespace, or nil.

Parameters:

• ns : SYMBOL — Namespace symbol, e.g. ‘int

Returns: LIST — ((method . impl) …) for the namespace, or nil

Examples:

(pair? (prim-domain 'int)) => #t
(null? (prim-domain 'no-such-ns)) => #t

See also: prims

prim-ref

Fetch the implementation filed under ns/method, or nil.

The consumer half of the registry protocol. Fetch at module load and

cache in a lexical (hot paths) or call inline (cold paths).

Parameters:

• ns : SYMBOL — Namespace symbol, e.g. ‘iter
• method : SYMBOL — Method symbol, e.g. ‘next

Returns: ANY — The registered implementation, or nil if absent

Examples:

(prim-ref 'int '+) => #<prim>

See also: prim-reg!

prim-reg!

File an x-lang value into the catalogue under ns/method.

The producer half of the registry protocol: library implementations register

under the same stable identities as C prims. Registration prepends, so a

re-registration shadows the older entry on lookup. Returns nil.

Parameters:

• ns : SYMBOL — Namespace symbol, e.g. ‘float
• method : SYMBOL — Method symbol, e.g. ‘+
• value : ANY — The implementation to register (fn, op, or any value)

Examples:

(do (prim-reg! 'demo 'twice (fn (_ n) (* n 2))) ((prim-ref 'demo 'twice) 21)) => 42

See also: prim-ref

x/core/predicates

Type predicates (null?, pair?, number?, real?, str?, symbol?, char?, …) built from C primitives.

Examples:

(list (null? ()) (pair? ()) (symbol? 'a)) => (#t #f #t)

x/core/control

Core control flow: if and let, as operatives built on match.

Examples:

(let ((n 3)) (if (> n 2) 'big 'small)) => 'big