← 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

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

apply

Apply a function to a list of arguments.

Parameters:

• f : CALLABLE — Function to apply
• args : LIST — Argument list

Returns: ANY — Result of application

Examples:

(apply + '(1 2)) => 3

eval

Evaluate an expression, optionally in a given environment.

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

Parameters:

• expr : ANY — Expression to evaluate
• env : LIST — Environment alist (optional)

Returns: ANY — Result of evaluation

See also: eval!

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

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

unwrap

Extract the underlying combiner from an applicative.

Parameters:

• applicative : CALLABLE — A wrapped combiner

Returns: CALLABLE — The underlying combiner

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

set-first!

Mutate the first element of a pair.

Parameters:

• p : PAIR — A pair
• val : ANY — New value

set-rest!

Mutate the second element of a pair.

Parameters:

• p : PAIR — A pair
• val : ANY — New value

first-int

Return the first element as a raw integer.

Parameters:

• p : PAIR — A pair

rest-int

Return the second element as a raw integer.

Parameters:

• p : PAIR — A pair

set-first-int!

Mutate the first element as a raw integer.

Parameters:

• p : PAIR — A pair
• val : INT — Integer value

set-rest-int!

Mutate the second element as a raw integer.

Parameters:

• p : PAIR — A pair
• val : INT — Integer value

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 : INT — Integer

Returns: INT — Bitwise complement

&

Bitwise AND.

Parameters:

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

Returns: INT — Bitwise AND

|

Bitwise OR.

Parameters:

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

Returns: INT — Bitwise OR

^

Bitwise XOR.

Parameters:

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

Returns: INT — Bitwise XOR

<<

Left shift.

Parameters:

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

Returns: INT — Shifted value

>>

Arithmetic right shift.

Parameters:

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

Returns: INT — Shifted value

Predicates

eq?

Test identity equality (pointer equality for objects, value for atoms).

Parameters:

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

Returns: BOOL — t if identical

=

Test numeric equality.

Parameters:

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

Returns: BOOL — t if equal

<

Test numeric less-than.

Parameters:

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

Returns: BOOL — t if a < b

Strings

symbol->str

Convert a symbol to a string.

Parameters:

• sym : SYMBOL — A symbol

Returns: STRING — The symbol’s name

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

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 : INT — 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

x-core operatives

null?

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

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if nil

pair?

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

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if pair

atom?

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

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if not a pair

number?

Test if a value is an integer.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if integer

str?

Test if a value is a string.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if string

symbol?

Test if a value is a symbol.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if symbol

char?

Test if a value is a character.

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if character

procedure?

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

Parameters:

• x : ANY — Value to test

Returns: BOOL — t if procedure or primitive

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.

See also: do

not

Logical negation.

Parameters:

• x : ANY — Value to negate

Returns: BOOL — t if x is falsy

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

number->str

Convert an integer to a string.

Parameters:

• n : INT — Integer to convert
• radix : INT — Base (optional, default 10)

Returns: STRING — String representation

str->number

Parse a string as an integer.

Parameters:

• s : STRING — String to parse

Returns: INT — Parsed integer, or nil on failure

str-ref

Return the character at an index in a string.

Parameters:

• s : STRING — A string
• i : INT — Zero-based index

Returns: CHAR — Character at index

str-length

Return the length of a string.

Parameters:

• s : STRING — A string

Returns: INT — Number of characters

substring

Extract a substring.

Parameters:

• s : STRING — Source string
• start : INT — Start index (inclusive)
• end : INT — End index (exclusive)

Returns: STRING — The substring

str=?

Test string equality.

Parameters:

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

Returns: BOOL — t if equal

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

peek-char

Return the next character from stdin without consuming it.

Returns: CHAR — The next character, or () at EOF

current-line

Return the current source line number.

Returns: INT — Line number in the current input

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 or module docs. (help modules) lists all modules.

apropos

Search documentation by name substring.

Parameters:

• str : STRING — Substring to search for

modules

List all known modules with load status and descriptions.

Primitives catalog

prims

The primitives catalog: 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 catalog alist

See also: prim-ref

prim-domain

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

Parameters:

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

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

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 catalog 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?, str?, symbol?, char?, …) built from C primitives.

x/core/control

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