Primitives
Core
| Function | Description | Example |
|---|---|---|
(import spec) | Import a module by specifier. Resolves via search paths (CWD, --path, --home) with extension probing (.lisp, native plugins). Binary files that fail UTF-8 reading are automatically tried as plugins. (alias: import-file, module/import) | (import "std/http") |
Math
| Function | Description | Example |
|---|---|---|
(math/-inf) | Negative infinity (IEEE 754). (alias: -inf) | (math/-inf) |
(math/acos x) | Returns the arccosine of a number (in radians). (alias: acos) | (math/acos 1) |
(math/asin x) | Returns the arcsine of a number (in radians). (alias: asin) | (math/asin 1) |
(math/atan x) | Returns the arctangent of a number (in radians). (alias: atan) | (math/atan 1) |
(math/atan2 y x) | Returns the arctangent of y/x (in radians), using the signs of both arguments to determine the quadrant. (alias: atan2) | (math/atan2 1 1) |
(math/cbrt x) | Returns the cube root of a number. (alias: cbrt) | (math/cbrt 27) |
(math/cos x) | Returns the cosine of a number (in radians). (alias: cos) | (math/cos 0) |
(math/cosh x) | Returns the hyperbolic cosine of a number. (alias: cosh) | (math/cosh 1) |
(math/e) | The mathematical constant e (Euler's number). (alias: e) | (math/e) |
(math/exp x) | Returns e raised to the power of x. (alias: exp) | (math/exp 1) |
(math/exp2 x) | Returns 2 raised to the power of x. (alias: exp2) | (math/exp2 3) |
(math/f32-bits x) | Return the IEEE 754 f32 bit pattern of a number as an integer. | (math/f32-bits 1.0) |
(math/f32-from-bits bits) | Reinterpret an integer as an IEEE 754 f32 bit pattern. | (math/f32-from-bits 1065353216) |
(math/fmod a b) | Floating-point remainder. Returns a - floor(a/b) * b. (alias: fmod) | (math/fmod 5.5 2.0) #=> 1.5 |
(math/inf) | Positive infinity (IEEE 754). (alias: +inf, inf) | (math/inf) |
(math/log x base) | Returns the natural logarithm of x, or logarithm with specified base. (alias: log) | (math/log 2.718281828) |
(math/log10 x) | Returns the base-10 logarithm of a number. (alias: log10) | (math/log10 100) |
(math/log2 x) | Returns the base-2 logarithm of a number. (alias: log2) | (math/log2 8) |
(math/nan) | Not-a-number (IEEE 754 NaN). (alias: nan) | (math/nan) |
(math/pi) | The mathematical constant pi (π). (alias: pi) | (math/pi) |
(math/pow x y) | Returns x raised to the power of y. (alias: pow) | (math/pow 2 8) |
(math/sin x) | Returns the sine of a number (in radians). (alias: sin) | (math/sin 0) |
(math/sinh x) | Returns the hyperbolic sine of a number. (alias: sinh) | (math/sinh 1) |
(math/sqrt x) | Returns the square root of a number. (alias: sqrt) | (math/sqrt 16) |
(math/tan x) | Returns the tangent of a number (in radians). (alias: tan) | (math/tan 0) |
(math/tanh x) | Returns the hyperbolic tangent of a number. (alias: tanh) | (math/tanh 1) |
(math/trunc x) | Returns the integer part of a number, truncating toward zero. (alias: trunc) | (math/trunc 3.7) |
String Operations
| Function | Description | Example |
|---|---|---|
(@string) | Create a mutable string from byte arguments. | (@string 72 101 108 108 111) |
(string/contains? s substr) | Check if string contains substring. | (string/contains? "hello" "ell") #=> true |
(string/ends-with? s suffix) | Check if string ends with suffix. (alias: string-ends-with?) | (string/ends-with? "hello" "lo") #=> true |
(string/find haystack needle offset) | Find the grapheme index of a substring, with optional start offset. Returns the index (integer) or nil if not found. (alias: string-index, string/index, string-find, string/index-of) | (string/find "hello" "ll") #=> 2 |
(string/format template args) | Format a template string with positional or named arguments. | (string/format "{} + {} = {}" 1 2 3) #=> "1 + 2 = 3" |
(string/join lst sep) | Join list of strings with separator. (alias: string-join) | (string/join (list "a" "b" "c") ",") #=> "a,b,c" |
(string/lowercase s) | Convert string to lowercase. (alias: string/downcase, string-downcase) | (string/lowercase "HELLO") #=> "hello" |
(string/repeat s n) | Repeat a string N times. (alias: string-repeat) | (string/repeat "ab" 3) #=> "ababab" |
(string/replace s old new) | Replace all occurrences of old substring with new. (alias: string-replace) | (string/replace "hello" "l" "L") #=> "heLLo" |
(string/size-of s) | Return the UTF-8 byte length of a string. | (string/size-of "café") #=> 5 |
(string/split s delim) | Split string by delimiter. Returns an array of substrings (empty strings between consecutive delimiters). Delimiter cannot be empty. (alias: string-split) | (string/split "a,b,c" ",") #=> ["a" "b" "c"] |
(string/starts-with? s prefix) | Check if string starts with prefix. (alias: string-starts-with?) | (string/starts-with? "hello" "he") #=> true |
(string/trim s) | Remove leading and trailing whitespace. (alias: string-trim) | (string/trim " hello ") #=> "hello" |
(string/uppercase s) | Convert string to uppercase. (alias: string/upcase, string-upcase) | (string/uppercase "hello") #=> "HELLO" |
(uri-encode str) | Percent-encode a string per RFC 3986. | (uri-encode "hello world") ;=> "hello%20world" |
Arrays
| Function | Description | Example |
|---|---|---|
(@array) | Create a mutable array from arguments. | (@array 1 2 3) #=> @[1 2 3] |
(array) | Create an immutable array from arguments. | (array 1 2 3) #=> [1 2 3] |
(array/new n fill) | Create array of n elements, all set to fill value. | (array/new 3 0) #=> [0 0 0] |
(insert arr idx val) | Insert element at index in array. Mutates in place, returns the same array. | (insert @[1 3] 1 2) #=> @[1 2 3] |
(popn arr n) | Remove and return last n elements from array as a new array. Mutates original. | (popn @[1 2 3 4] 2) #=> @[3 4] |
(remove arr idx count) | Remove element(s) at index from array. Mutates in place, returns the same array. | (remove @[1 2 3] 1) #=> @[1 3] |
Structs
| Function | Description | Example |
|---|---|---|
(@struct) | Create a mutable struct from key-value pairs | (@struct :a 1 :b 2) |
(deep-freeze value) | Recursively freeze a value and all its contents. Converts mutable collections to immutable and recurses into elements. Atoms and non-collection types are returned as-is. | (deep-freeze @[@[1 2] @{:a 3}]) |
(freeze collection) | Convert a mutable collection to its immutable equivalent. Handles @array, @struct, @set, @string (requires valid UTF-8), @bytes. Returns immutable values as-is. | (freeze @{:a 1 :b 2}) |
(get collection key default) | Get a value from a collection (tuple, array, string, struct, subprocess) by index or key, with optional default | (get [1 2 3] 0) |
(has? collection key-or-value) | Check if a collection has a key, element, or substring. Works on structs and subprocesses (key lookup), sets (membership), and strings (substring check). (alias: has-key?, contains?) | (has? {:a 1} :a) #=> true
(has? |1 2 3| 2) #=> true
(has? "hello" "ell") #=> true |
(keys collection) | Get all keys from a struct, or a subprocess's closed key set, as a list | (keys (@struct :a 1 :b 2)) |
(pairs struct) | Iterate over struct key-value pairs as [key value] arrays. | (pairs {:a 1 :b 2}) |
(struct) | Create an immutable struct from key-value pairs | (struct :a 1 :b 2) |
(thaw collection) | Convert an immutable collection to its mutable equivalent. Handles array, struct, set, string, bytes. Returns mutable values as-is. | (thaw {:a 1 :b 2}) |
(values collection) | Get all values from a struct, or a subprocess's, as a list | (values (@struct :a 1 :b 2)) |
JSON
| Function | Description | Example |
|---|---|---|
(json/parse json-string :keys :keyword) | Parse a JSON string into an immutable Elle value: a JSON array becomes an immutable array and a JSON object an immutable struct. Accepts optional :keys :keyword to use keyword keys in parsed structs instead of string keys. (alias: json-parse) | (json/parse "{\"name\": \"Alice\", \"age\": 30}" :keys :keyword) |
(json/pretty value) | Serialize an Elle value to pretty-printed JSON with 2-space indentation (alias: json-serialize-pretty) | (json/pretty (list 1 2 3)) |
(json/serialize value) | Serialize an Elle value to compact JSON (alias: json-serialize) | (json/serialize (@struct :name "Bob" :age 25)) |
File I/O
| Function | Description | Example |
|---|---|---|
(file/append path content) | Append string content to a file (alias: append-file) | (file/append "log.txt" "new line") |
(file/copy src dst) | Copy a file (alias: copy-file) | (file/copy "source.txt" "dest.txt") |
(file/delete path) | Delete a file (alias: delete-file) | (file/delete "temp.txt") |
(file/delete-dir path) | Delete a directory (must be empty) (alias: delete-directory) | (file/delete-dir "empty-dir") |
(file/delete-dir-all path) | Delete a directory and everything under it (need not be empty) (alias: delete-directory-all) | (file/delete-dir-all "scratch") |
(file/lines path) | Read lines from a file and return as a list of strings (alias: read-lines) | (file/lines "data.txt") |
(file/ls path) | List directory contents (alias: list-directory) | (file/ls ".") |
(file/lstat path) | Get filesystem metadata as a struct (does not follow symlinks) | (file/lstat "link.txt") |
(file/mkdir path) | Create a directory (alias: create-directory) | (file/mkdir "new-dir") |
(file/mkdir-all path) | Create a directory and all parent directories (alias: create-directory-all) | (file/mkdir-all "a/b/c") |
(file/mktempdir) | Create a uniquely-named directory under the platform temp root (TMPDIR on Unix, %TEMP% on Windows) and return its path (alias: make-temp-directory) | (file/mktempdir) |
(file/read path) | Read entire file as a string (alias: slurp) | (file/read "data.txt") |
(file/rename old-path new-path) | Rename a file (alias: rename-file) | (file/rename "old.txt" "new.txt") |
(file/size path) | Get file size in bytes (alias: file-size) | (file/size "data.txt") |
(file/stat path) | Get filesystem metadata as a struct (follows symlinks) | (file/stat "data.txt") |
(file/write path content) | Write string content to a file (overwrites if exists) (alias: spit) | (file/write "output.txt" "hello") |
Function Introspection
| Function | Description | Example |
|---|---|---|
(attune signals closure) | Return a new closure that permits ONLY the specified signals — all others are intercepted and converted to :error. Dual of squelch: squelch blocks specific signals, attune allows only specific signals. Mask-first argument order. | (attune |:yield :error| (fn () (yield 1))) |
(disgit f) | Return the cached SPIR-V bytes from a GIT'd closure. Errors if the closure has not been GIT'd. (alias: fn/disgit) | (disgit (git (fn [a b] (+ a b)))) |
(fn/arity value) | Returns closure arity as int, pair, or nil (alias: arity) | (fn/arity (fn (x y) x)) |
(fn/bytecode-size value) | Returns size of bytecode in bytes, or nil (alias: bytecode-size) | (fn/bytecode-size (fn (x) x)) |
(fn/captures value) | Returns number of captured variables, or nil (alias: captures) | (fn/captures (let [x 1] (fn () x))) |
(fn/disasm closure) | Disassemble a closure's bytecode into a list of instruction strings. (alias: disbit, fn/disbit) | (fn/disasm (fn (x) x)) |
(fn/disasm-jit closure) | Render the Cranelift IR the JIT emits for a closure, or nil if it has none. (alias: disjit, fn/disjit) | (fn/disasm-jit (fn (x) x)) |
(fn/errors? value) | Returns true if closure may error | (fn/errors? (fn (x) (/ 1 x))) |
(fn/flow closure-or-fiber) | Return the LIR control flow graph of a closure or fiber as structured data. | (fn/flow (fn (x y) (+ x y))) |
(fn/git? f) | Returns true if the closure has cached SPIR-V bytes (has been GIT'd). | (fn/git? (fn [a b] (+ a b))) |
(fn/gpu-eligible? value) | Returns true if closure passes signal and structural checks for GPU compilation | (fn/gpu-eligible? (fn [a b] (+ a b))) |
(fn/mutates-params? value) | Returns true if closure mutates any parameters (alias: mutates-params?) | (fn/mutates-params? (fn (x) (assign x 1))) |
(fn/signature f) | Return the declared shape of a function: {:name :required :optional :rest :named-keys :signals :doc :origin}. Errors on a non-function. | (fn/signature (fn [a &opt b] a)) |
(git f workgroup-size) | Eagerly compile a GPU-eligible closure to SPIR-V and cache on its template. Returns the closure. All closures sharing the same template see the cached SPIR-V. Optional second argument is workgroup size (default 256). | (git (fn [a b] (+ a b))) |
(squelch closure signals) | Return a new closure that intercepts and converts the specified signals to :error at runtime. The second argument can be a keyword, set, array, list, or integer of signal bits. | (squelch (fn () (yield 1)) |:yield|) |
Fibers
| Function | Description | Example |
|---|---|---|
(fiber/abort fiber error?) | Gracefully terminate a fiber by injecting an error and resuming it. Defer/protect blocks run. (alias: abort) | (fiber/abort f)
(fiber/abort f :reason) |
(fiber/bits fiber) | Get the signal bits from the fiber's last signal | (fiber/bits f) |
(fiber/cancel fiber error?) | Hard-kill a fiber. Sets it to :error without unwinding. No defer/protect runs. Supports self-cancel. (alias: cancel) | (fiber/cancel f)
(fiber/cancel f :reason) |
(fiber/caps fiber?) | Get the fiber's active capabilities as a keyword set | (fiber/caps)
(fiber/caps f) |
(fiber/child fiber) | Get the most recently resumed child fiber, or nil if none | (fiber/child f) |
(fiber/clear-fuel fiber) | Remove the instruction budget, restoring unlimited execution. | (fiber/clear-fuel f) |
(fiber/emit bits value) | Emit a signal from the current fiber (alias: emit) | (emit 2 42) |
(fiber/fuel fiber) | Read remaining fuel. Returns integer or nil if unlimited. | (fiber/fuel f) |
(fiber/mask fiber) | Get the fiber's signal mask | (fiber/mask f) |
(fiber/new closure mask) | Create a fiber with a signal mask. Optional :deny withholds capabilities. (alias: fiber) | (fiber/new (fn [] 42) |:error| :deny |:io|) |
(fiber/parent fiber) | Get the parent fiber, or nil if this is a top-level fiber | (fiber/parent f) |
(fiber/propagate fiber) | Propagate a caught signal from a child fiber, preserving the child chain | |
(fiber/refuse fiber error?) | Refuse the call a paused fiber is suspended on: raise the error at the fiber's own call site, where its protect catches it. The fiber stays alive and runs on. | (fiber/refuse f)
(fiber/refuse f :not-permitted) |
(fiber/resume fiber value) | Resume a fiber, optionally delivering a value (alias: resume) | (fiber/resume f) |
(fiber/set-fuel fiber n) | Set the instruction budget on a fiber. n is a non-negative integer. | (fiber/set-fuel f 10000) |
(fiber/status fiber) | Get the fiber's lifecycle status (:new, :alive, :paused, :dead, :error) | (fiber/status f) |
(fiber/value fiber) | Get the signal payload from the fiber's last signal | (fiber/value f) |
Clock
| Function | Description | Example |
|---|---|---|
(clock/cpu) | Return thread CPU time in seconds | (clock/cpu) |
(clock/monotonic) | Return seconds elapsed since process start (monotonic clock) | (clock/monotonic) |
(clock/realtime) | Return seconds since Unix epoch (wall clock) | (clock/realtime) |
Time
| Function | Description | Example |
|---|---|---|
(time/sleep seconds) | Sleep for the specified number of seconds (blocks the thread) | (time/sleep 1.5) |
Metaprogramming
| Function | Description | Example |
|---|---|---|
(backend? tier) | True iff the given tier keyword is the currently executing tier. Runtime predicate, since one closure runs on every tier under compile/run-on. Used by the test runner's gate! and divergence fixtures. | (backend? :jit) |
(jit/rejections) | List closures rejected from JIT compilation. Returns list of {:name :reason :calls} structs sorted by call count ascending. | (jit/rejections) |
(lir/closure-value-const-count) | Number of closure-valued ValueConst instructions converted to ClosureRef by the LIR cross-thread serializer. Used by regression tests to assert the ClosureRef LIR-transfer fix fires. | (lir/closure-value-const-count) |
(meta/datum->syntax context datum) | Create a syntax object with lexical context from another syntax object (alias: datum->syntax) | (meta/datum->syntax stx 'x) |
(meta/gensym prefix) | Generate a unique symbol with optional prefix (alias: gensym) | (meta/gensym "tmp") |
(meta/origin f) | Return the source location of a closure as {:file :line :col}, or nil if unavailable. | (defn foo () 42) (meta/origin foo) |
(meta/syntax->datum stx) | Strip scope information from a syntax object, returning the plain value (alias: syntax->datum) | (meta/syntax->datum stx) |
(meta/syntax->list stx) | Convert a syntax list to an immutable array of syntax objects (alias: syntax->list) | (meta/syntax->list stx) |
(meta/syntax-e stx) | Shallow-unwrap a syntax object: returns atoms as plain values, compounds unchanged (alias: syntax-e) | (meta/syntax-e stx) |
(meta/syntax-first stx) | Return the first element of a syntax list as a syntax object (alias: syntax-first) | (meta/syntax-first stx) |
(meta/syntax-keyword? stx) | Return true if stx is a syntax object wrapping a keyword (alias: syntax-keyword?) | (meta/syntax-keyword? stx) |
(meta/syntax-list? stx) | Return true if stx is a syntax object wrapping a list (including empty) (alias: syntax-list?) | (meta/syntax-list? stx) |
(meta/syntax-nil? stx) | Return true if stx is a syntax object wrapping nil (alias: syntax-nil?) | (meta/syntax-nil? stx) |
(meta/syntax-pair? stx) | Return true if stx is a syntax object wrapping a non-empty list (alias: syntax-pair?) | (meta/syntax-pair? stx) |
(meta/syntax-rest stx) | Return a syntax list of all but the first element (alias: syntax-rest) | (meta/syntax-rest stx) |
(meta/syntax-symbol? stx) | Return true if stx is a syntax object wrapping a symbol (alias: syntax-symbol?) | (meta/syntax-symbol? stx) |
(read str) | Parse the first form from a string, returning a value | (read "(+ 1 2)") #=> (+ 1 2) |
(read-all str) | Parse all forms from a string, returning a list of values | (read-all "1 2 3") #=> (1 2 3) |
(signals) | Return the signal registry as a struct mapping keywords to bit positions. | (signals) |
(vm/config key?) | Read runtime configuration. No args returns the full config struct. Pass a keyword (:trace, :jit, :wasm, :stats) to read a specific field. | (vm/config :jit) |
(vm/config-set key value) | Set a runtime configuration field. Use (put (vm/config) :key value) instead. | (vm/config-set :jit :eager) |
(vm/list-primitives category?) | List registered names as a sorted list of symbols. Optional category filter. (alias: list-primitives) | (vm/list-primitives)
(vm/list-primitives :math)
(vm/list-primitives :"special form") |
(vm/primitive-meta name) | Get structured metadata for a primitive as a struct. (alias: primitive-meta) | (struct-get (vm/primitive-meta "pair") "doc") #=> "Construct a pair..." |
(vm/query op arg) | Query VM state (call-count, doc, global?, fiber/self) | (vm/query "call-count" some-fn) |
(vm/tier) | The backend tier currently executing, as a keyword (:bytecode, :jit, :wasm, :mlir-cpu). Reflects the tier forced by compile/run-on; :bytecode otherwise. | (vm/tier) #=> :bytecode |
Debugging
| Function | Description | Example |
|---|---|---|
(debug/arena-allocs thunk) | Run thunk, return (result . net-allocs). (alias: arena/allocs) | (debug/arena-allocs (fn [] (pair 1 2))) |
(debug/arena-bytes) | Return bytes consumed by the current FiberHeap. (alias: arena/bytes) | (debug/arena-bytes) |
(debug/arena-count) | Return current heap object count. (alias: arena/count, arena-count) | (debug/arena-count) |
(debug/arena-dump) | Print every live mortal region (id, rc, object count, object tags) to stderr. Returns nil. (alias: arena/dump) | (arena/dump) |
(debug/arena-object-limit) | Get current object limit. Returns int or nil (unlimited). (alias: arena/object-limit) | (debug/arena-object-limit) |
(debug/arena-over-frees) | Return direct double-releases seen (monotonic): a DecrefRegion of an absent or already-zeroed region. (alias: arena/over-frees) | (debug/arena-over-frees) |
(debug/arena-page-claims) | Return pages claimed from the heap's page pool (monotonic, never decremented on release). (alias: arena/page-claims) | (debug/arena-page-claims) |
(debug/arena-peak) | Return peak object count (high-water mark). (alias: arena/peak) | (debug/arena-peak) |
(debug/arena-region-count) | Return number of active regions. (alias: arena/region-count) | (debug/arena-region-count) |
(debug/arena-region-ids) | Return physical region ids issued (one past the largest id ever minted from scratch). (alias: arena/region-ids) | (debug/arena-region-ids) |
(debug/arena-region-info) | Return array of {:id N :rc N :objects N} per active region. (alias: arena/region-info) | (debug/arena-region-info) |
(debug/arena-region-of value) | Return region ID for a heap value (0 for non-heap). (alias: arena/region-of) | (debug/arena-region-of (pair 1 2)) |
(debug/arena-region-table) | Return entries in the region table (one past the largest physical region id ever made live). (alias: arena/region-table) | (debug/arena-region-table) |
(debug/arena-reset-peak) | Reset peak to current count. Returns previous peak. (alias: arena/reset-peak) | (debug/arena-reset-peak) |
(debug/arena-set-object-limit n) | Set max heap object count. Pass nil to remove limit. Returns previous limit or nil. (alias: arena/set-object-limit) | (debug/arena-set-object-limit 10000) |
(debug/arena-stats fiber?) | Return heap arena statistics. (alias: arena/stats, vm/arena, arena-stats) | (debug/arena-stats) |
(debug/arena-total-allocs) | Return cumulative objects ever minted (monotonic, never decremented on free). (alias: arena/total-allocs) | (debug/arena-total-allocs) |
(debug/memory) | Returns memory usage statistics as (rss-bytes virtual-bytes) (alias: memory-usage) | (debug/memory) |
(debug/print value) | Prints a value with debug information to stderr (alias: debug-print) | (debug/print 42) |
(debug/symbol-count) | Returns the number of interned symbols in the symbol table | (debug/symbol-count) |
(debug/trace label value) | Traces execution with a label, prints to stderr, returns value (alias: trace) | (debug/trace "x" 42) |
Bitwise Operations
| Function | Description | Example |
|---|---|---|
(bit/and xs) | Bitwise AND of all arguments | (bit/and 12 10) #=> 8 |
(bit/not x) | Bitwise NOT of argument | (bit/not 0) #=> -1 |
(bit/or xs) | Bitwise OR of all arguments | (bit/or 12 10) #=> 14 |
(bit/shl x n) | Left shift first argument by second argument (clamped to 0-63). (alias: bit/shift-left) | (bit/shl 1 3) #=> 8 |
(bit/shr x n) | Arithmetic right shift first argument by second argument (clamped to 0-63). (alias: bit/shift-right) | (bit/shr 8 2) #=> 2 |
(bit/xor xs) | Bitwise XOR of all arguments | (bit/xor 12 10) #=> 6 |
FFI (Foreign Function Interface)
| Function | Description | Example |
|---|---|---|
(ffi/align type) | Get the alignment of a C type in bytes. | (ffi/align :double) #=> 8 |
(ffi/array elem-type count) | Create an array type descriptor from element type and count. | (ffi/array :i32 10) |
(ffi/call fn-ptr sig) | Call a C function through libffi. | (ffi/call sqrt-ptr sig 2.0) |
(ffi/callback sig closure) | Create a C function pointer from an Elle closure. Returns a pointer. | (ffi/callback (ffi/signature :int [:ptr :ptr]) (fn (a b) 0)) |
(ffi/callback-free ptr) | Free a callback created by ffi/callback. | (ffi/callback-free cb-ptr) |
(ffi/free ptr) | Free C memory. | (ffi/free ptr) |
(ffi/lookup lib name) | Look up a symbol in a loaded library. | (ffi/lookup lib "strlen") |
(ffi/malloc size) | Allocate C memory. | (ffi/malloc 100) |
(ffi/native path) | Load a shared library by Linux-style name (resolved to the host's .dylib/.dll). Pass nil for the current process. | (ffi/native "libm.so.6") |
(ffi/on-unload lib symbol) | Register a teardown C symbol (zero-arg) to run for a library at an explicit (ffi/run-teardowns). The library mapping is never unloaded, so this is optional graceful cleanup — never required to avoid a crash, never run automatically. | (ffi/on-unload git-lib "git_libgit2_shutdown") |
(ffi/read ptr type) | Read a typed value from C memory. | (ffi/read ptr :i32) |
(ffi/run-teardowns) | Run all registered FFI library teardowns (ffi/on-unload), in reverse load order. Explicit-only; never unloads the libraries. Call only when workers that used the libraries have quiesced. | (ffi/run-teardowns) |
(ffi/signature return-type arg-types fixed-args) | Create a reified function signature. Optional third arg for variadic functions. | (ffi/signature :int [:ptr :size :ptr :int] 3) |
(ffi/size type) | Get the size of a C type in bytes. | (ffi/size :i32) #=> 4 |
(ffi/string ptr max-len) | Read a null-terminated C string from a pointer. | (ffi/string ptr) |
(ffi/struct fields) | Create a struct type descriptor from field types. | (ffi/struct [:i32 :double :ptr]) |
(ffi/write ptr type value) | Write a typed value to C memory. | (ffi/write ptr :i32 42) |
allocator
| Function | Description | Example |
|---|---|---|
(allocator/install allocator) | Install a custom allocator on the current fiber's heap. INTERNAL: use via with-allocator macro only. | |
(allocator/uninstall) | Uninstall the current custom allocator, freeing remaining custom objects. INTERNAL: use via with-allocator macro only. | |
box
| Function | Description | Example |
|---|---|---|
(box value) | Create a mutable box containing a value. | (box 42) #=> #<box> |
(rebox box value) | Modify the value in a box and return the new value. | (let [c (box 1)] (rebox c 2) (unbox c)) #=> 2 |
(unbox box) | Extract the value from a box. | (unbox (box 42)) #=> 42 |
bytes
| Function | Description | Example |
|---|---|---|
(@bytes) | Create mutable bytes. Accepts integers (0-255), or a single string/keyword. | (@bytes 72 101 108 108 111)
(@bytes "hello") |
(bytes) | Create immutable bytes. Accepts integers (0-255), or a single string/keyword. | (bytes 72 101 108 108 111)
(bytes "hello") |
(seq->hex x) | Convert bytes, @bytes, array, @array, list, or integer to a lowercase hex string. Mutable input (@bytes, @array) produces @string; all other input produces string. Integer input uses big-endian minimal-byte encoding (0 → "00"). Aliases: bytes->hex, bytes->hex-string. | (seq->hex (bytes 72 101 108)) ;=> "48656c"
(seq->hex [72 101 108]) ;=> "48656c"
(seq->hex 255) ;=> "ff" |
(slice coll start end?) | Slice a sequence from start to end index. If end is omitted, slice to end of sequence. Returns same type as input. | (slice [1 2 3 4 5] 1 3)
(slice "hello" 1) |
chan
| Function | Description | Example |
|---|---|---|
(chan &opt capacity) | Create a channel. Returns [sender receiver]. Optional capacity for bounded channel. | (chan) |
(chan/clone sender) | Clone a sender. Multiple senders can feed the same channel. | (chan/clone sender) |
(chan/close sender) | Close a sender. Receivers will get :disconnected after buffered messages drain. | (chan/close sender) |
(chan/close-recv receiver) | Close a receiver. Senders will get :disconnected on next send. | (chan/close-recv receiver) |
(chan/recv receiver) | Non-blocking receive. Returns [:ok msg], [:empty], or [:disconnected]. | (chan/recv receiver) |
(chan/send sender msg) | Non-blocking send. Returns [:ok], [:full], or [:disconnected]. | (chan/send sender 42) |
(chan/try-select receivers) | Non-blocking poll over receivers. Returns [index msg], [:empty], or [:disconnected]. | (chan/try-select @[r1 r2]) |
(chan/wait-ready receivers &opt timeout-ms) | Park the current fiber until a receiver is ready, a sender closes, or timeout-ms elapses. Returns nil; caller re-checks with chan/try-select. | (chan/wait-ready @[r1 r2] 1000) |
collection
| Function | Description | Example |
|---|---|---|
(sort coll) | Sort a collection in ascending order using the built-in value ordering. Type-preserving: @arrays mutated in place, arrays and lists return new sorted values. | (sort @[3 1 2]) #=> @[1 2 3]
(sort ["b" "a" "c"]) #=> ["a" "b" "c"] |
comparison
| Function | Description | Example |
|---|---|---|
(= a b) | Test equality of values. Numeric-aware at every depth: (= 1 1.0) and (= [1] [1.0]) are true; IEEE NaN is never equal, even inside collections. Chained: (= a b c) means all are equal. | (= 1 1) #=> true
(= 1 1.0) #=> true
(= 1 2 1) #=> false |
(hash value) | Hash any value to an integer. Equal values produce equal hashes. | (hash 42) #=> <integer>
(= (hash :foo) (hash :foo)) #=> true |
(identical? a b) | Test equality with no coercion. Values of the same type with equal contents are identical, even two separate allocations; floats compare by bit pattern, so NaN is identical to NaN. (identical? 1 1.0) is false. For pointer identity use %identical?. | (identical? 1 1) #=> true
(identical? 1 1.0) #=> false
(identical? @[1] @[1]) #=> true |
compile
| Function | Description | Example |
|---|---|---|
(compile/add-handler analysis fn-name signal-kind) | Wrap call sites of a function with signal handling. | (compile/add-handler analysis :fetch-page :error) |
(compile/analyze source opts) | Analyze Elle source text. Returns an opaque analysis handle for queries. | (compile/analyze "(defn f [x] (+ x 1))") |
(compile/apply-rules source rules) | Apply rename/replace/report migration rules, supplied as data, to SOURCE text via the rewrite edit engine, reapplied to a fixpoint. Returns {:source :count :reports}. The consumer-migration engine of `elle semver`. | (compile/apply-rules "(old 1)" [{:kind :rename :from "old" :to "new"}]) |
(compile/barrier-module source name) | Compile a file (SOURCE, NAME) in the per-form fault-barrier test mode: whole-module analysis (epoch + shared bindings), then return a mutable array of [index thunk] pairs — one 0-arg thunk per test (expression) form, each capturing the file's shared bindings. def/var forms run eagerly as setup. Signals on a compile failure or a def-initializer fault. Powers `elle test` (src/test). | (compile/barrier-module "(assert (= 1 1) \"ok\")" "<eval>") |
(compile/binding analysis name) | Return detailed info about a specific binding. | (compile/binding analysis :x) |
(compile/bindings analysis) | Return all bindings from an analysis with metadata. | (compile/bindings (compile/analyze src)) |
(compile/call-graph analysis) | Return the full call graph with nodes, roots, and leaves. | (compile/call-graph (compile/analyze src)) |
(compile/callees analysis name) | Return functions called by the named function. | (compile/callees analysis :main) |
(compile/callers analysis name) | Return functions that call the named function. | (compile/callers analysis :fetch-page) |
(compile/captured-by analysis name) | Return functions that capture the named binding. | (compile/captured-by analysis :config) |
(compile/captures analysis name) | Return what a function captures and how (value, lbox, transitive). | (compile/captures analysis :make-handler) |
(compile/diagnostics analysis) | Return diagnostics (warnings, errors) from an analysis. | (compile/diagnostics (compile/analyze src)) |
(compile/dumps source name) | Compile a module (SOURCE, NAME) once through the file front-end and return a struct of rendered --dump artifacts keyed by kind: :ast :fhir :defuse :regions :hir :lir :cfg :dfa :jit :escape. The in-process form of `elle --dump=KIND` (returns the text instead of printing and exiting). Stages that fail to compile or yield nothing are omitted. Powers CAS asset capture in `elle test` (src/test). | (compile/dumps "(+ 1 2)" "<eval>") |
(compile/exports analysis) | Return the module surface of an analysis: {:constructor :exports}, or nil when the file's return expression is not an export struct. | (compile/exports (compile/analyze src)) |
(compile/extract analysis opts) | Extract a line range into a new function. Returns new source, captures, and signal. | (compile/extract analysis {:from :fn :lines [5 10] :name :new-fn}) |
(compile/parallelize analysis fn-names) | Check if functions can safely run in parallel. Verifies no shared mutable captures. | (compile/parallelize analysis [:fetch-a :fetch-b]) |
(compile/primitives) | Return metadata for all Rust-defined primitives as an array of structs. | (compile/primitives) |
(compile/query-signal analysis query) | Find functions matching a signal query (:silent, :io, :yields, :jit-eligible, or signal name). | (compile/query-signal analysis :silent) |
(compile/read-forms source name) | Parse SOURCE (NAME for error spans) into a list of syntax values, without expanding or compiling. Companion to compile/whole-module-syntax: read a legacy multi-form file once in the main VM, then ship the syntax (sendable across os/spawn) to a worker that compiles + runs it with its own stdlib. Powers `elle test` (src/test). | (compile/read-forms "(def x 1)\n(+ x 2)" "<eval>") |
(compile/rename analysis old-name new-name) | Binding-aware rename. Returns new source with all references updated. | (compile/rename analysis :old-name :new-name) |
(compile/run-on tier f) | Force-dispatch a closure on a specific tier (:bytecode, :jit, :mlir-cpu). Used by lib/differential.lisp to verify tier agreement. Returns the result, or signals :tier-rejected if the tier doesn't accept the closure. | (compile/run-on :bytecode (fn [a b] (+ a b)) 3 4) |
(compile/signal analysis name) | Return the inferred signal of a named function. | (compile/signal analysis :my-fn) |
(compile/symbols analysis) | Return all symbol definitions from an analysis. | (compile/symbols (compile/analyze src)) |
(compile/whole-module source name) | Compile a file (SOURCE, NAME) as ONE whole-file thunk (legacy multi-form test mode): whole-module analysis (epoch + letrec bindings), then return a mutable array with a single [0 thunk] pair whose 0-arg thunk runs every top-level form (def/var and expressions alike) in source order. Unlike compile/barrier-module it does not hoist def/var eagerly or slice expressions per form — so an imperative script runs in order, once per tier, in isolation, matching a direct file run. Signals on a compile failure. Powers `elle test` for multi-form files (src/test). | (compile/whole-module "(def x 1)\n(assert (= x 1) \"ok\")" "<eval>") |
(compile/whole-module-syntax forms name) | Like compile/whole-module, but from a list of already-parsed syntax values (FORMS, from compile/read-forms) plus NAME, instead of a source string. Returns a mutable array with one [0 thunk] pair. Lets the runner parse a multi-form file in the main VM and compile it in a worker against the worker's own stdlib. Powers `elle test` (src/test). | (compile/whole-module-syntax (compile/read-forms "(+ 1 2)" "<eval>") "<eval>") |
conversion
| Function | Description | Example |
|---|---|---|
(float x) | Convert number to float. Accepts int (→ f64) or float (identity). Use parse-float for string→float. | (float 42) #=> 42.0
(float 3.14) #=> 3.14 |
(integer x) | Convert number to integer (i64). Accepts int (identity) or float (truncation). Use parse-int for string→int. | (integer 3.7) #=> 3
(integer 42) #=> 42 |
(keyword str) | Convert a string to a keyword. | (keyword "foo") |
(number->string n radix?) | Convert a number to string. With an optional radix (2–36), converts an integer to the given base (lowercase, no prefix). | (number->string 42) #=> "42"
(number->string 255 16) #=> "ff"
(number->string -255 16) #=> "-ff" |
(parse-float s) | Parse string or keyword to float. | (parse-float "3.14") #=> 3.14 |
(parse-int s radix?) | Parse string or keyword to integer. Optional radix (2–36) for base conversion. | (parse-int "42") #=> 42
(parse-int "ff" 16) #=> 255
(parse-int "1010" 2) #=> 10 |
(string values) | Convert values to string. Multiple arguments are concatenated. | (string "count: " 42) #=> "count: 42" |
elle
| Function | Description | Example |
|---|---|---|
(elle/boot-fingerprint) | Return this binary's boot fingerprint — a 64-bit hash over the running executable, which carries the sources it boots from — or nil when the OS will not name it. | (elle/boot-fingerprint) |
(elle/build-profile) | Return the cargo profile this binary was compiled under: "debug" or "release". | (elle/build-profile) |
(elle/epoch n) | Return the current language epoch. With 1 arg, returns the arg (compile-time declaration form). | (int? (elle/epoch)) # => true |
(elle/executable) | Return the path of the running elle binary, or nil when the OS will not say. | (elle/executable) |
(elle/info) | Get package information (name, version, description) | (elle/info) |
(elle/version) | Get the current package version | (elle/version) |
intrinsic
| Function | Description | Example |
|---|---|---|
(%add a b) | Add two numbers | |
(%add-set set value) | Add to an immutable set, returning a fresh set (monomorphic immutable set add) | |
(%add-set-mut set value) | Add to a mutable @set in place, returning it (monomorphic @set add) | |
(%array-push arr val) | Append element | |
(%array? x) | Is array? | |
(%bit-and a b) | Bitwise AND | |
(%bit-not x) | Bitwise complement | |
(%bit-or a b) | Bitwise OR | |
(%bit-xor a b) | Bitwise XOR | |
(%bool? x) | Is boolean? | |
(%box? x) | Is box? | |
(%bytes-push b val) | Append a byte (integer) or all bytes of a bytes value to bytes/@bytes | |
(%bytes? x) | Is bytes? | |
(%closure? x) | Is closure? | |
(%del coll key) | Dissoc/delete key | |
(%del-set coll value) | Delete an element from an immutable set, returning a fresh set (monomorphic immutable set del) | |
(%del-set-mut coll value) | Delete an element from a mutable @set in place, returning it (monomorphic @set del) | |
(%del-struct coll key) | Delete a key from an immutable struct, returning a fresh struct (monomorphic immutable struct del) | |
(%del-struct-mut coll key) | Delete a key from a mutable @struct in place, returning it (monomorphic @struct del) | |
(%div a b) | Divide two numbers | |
(%empty? x) | Is empty list? | |
(%eq a b) | Equality | |
(%fiber? x) | Is fiber? | |
(%first p) | First of pair | |
(%float x) | Convert to float | |
(%float? x) | Is float? | |
(%freeze x) | Mutable to immutable | |
(%ge a b) | Greater than or equal | |
(%get coll key) | Indexed/keyed access | |
(%gt a b) | Greater than | |
(%has? coll key) | Key/element exists? | |
(%identical? a b) | Pointer identity | |
(%int x) | Convert to integer | |
(%int? x) | Is integer? | |
(%keyword? x) | Is keyword? | |
(%le a b) | Less than or equal | |
(%length x) | Polymorphic length | |
(%lt a b) | Less than | |
(%mod a b) | Floored modulus (sign follows divisor) | |
(%mul a b) | Multiply two numbers | |
(%ne a b) | Not equal | |
(%nil? x) | Is nil? | |
(%not x) | Logical not | |
(%pair a b) | Construct a pair | |
(%pair? x) | Is pair? | |
(%pop arr) | Remove/return last element | |
(%pop-bytes b) | Remove and return the last byte (as an int) from a mutable @bytes in place (monomorphic @bytes pop) | |
(%pop-string s) | Remove and return the last grapheme from a mutable @string in place (monomorphic @string pop) | |
(%push-array arr val) | Append to an immutable array, returning a fresh array (monomorphic immutable array-push) | |
(%push-array-mut arr val) | Append to a mutable @array in place, returning it (monomorphic @array push) | |
(%put coll key val) | Assoc/set element | |
(%put-array coll key val) | Set an index in an immutable array, returning a fresh array (monomorphic immutable array put) | |
(%put-array-mut coll key val) | Set an index in a mutable @array in place, returning it (monomorphic @array put) | |
(%put-struct coll key val) | Assoc into an immutable struct, returning a fresh struct (monomorphic immutable struct put) | |
(%put-struct-mut coll key val) | Assoc into a mutable @struct in place, returning it (monomorphic @struct put) | |
(%rem a b) | Remainder (sign follows dividend) | |
(%rest p) | Rest of pair | |
(%set? x) | Is set? | |
(%shl a b) | Shift left | |
(%shr a b) | Shift right | |
(%string-push s val) | Append string to string/@string | |
(%string-push-mut s val) | Append a string to a mutable @string in place, returning it (monomorphic @string push) | |
(%string? x) | Is string? | |
(%struct? x) | Is struct? | |
(%sub a b?) | Subtract or negate | |
(%symbol? x) | Is symbol? | |
(%thaw x) | Immutable to mutable | |
(%type-of x) | Type as keyword | |
io
| Function | Description | Example |
|---|---|---|
(describe value) | Return a string describing a value's type and content. | (describe (list 1 2 3)) #=> "<list (3 elements)>" |
(io/backend kind keepalive) | Create an I/O backend. :async for asynchronous, :mock for testing. Optional second arg is the worker keepalive in seconds (nil for the default): how long an idle I/O worker thread waits for another operation before it retires. | (io/backend :async) |
(io/cancel backend id) | Cancel a pending async I/O operation by submission ID. Returns nil. | (io/cancel backend id) |
(io/reap backend) | Non-blocking poll for async I/O completions. Returns array of completion structs. | (io/reap backend) |
(io/submit backend request fiber?) | Submit an I/O request to an async backend. Optional third arg is the fiber the result is for, which the backend asks about before it assembles a completion. Returns submission ID. | (io/submit backend request) |
(io/wait backend timeout-ms) | Wait for async I/O completions. timeout-ms: negative=forever, 0=poll, positive=ms. Returns array of completion structs. | (io/wait backend 1000) |
(io/workers backend) | Background worker operations this backend has submitted but not yet reaped. Zero for a backend that runs its operations in the kernel (io_uring) rather than on threads. | (io/workers backend) |
(pp value) | Pretty-print a value with indentation. Returns the value. | (pp (list 1 2 (list 3 4))) |
list
| Function | Description | Example |
|---|---|---|
(->array coll) | Convert any sequence to an immutable array. Lists, @arrays, sets, strings (graphemes), and bytes (integers) are supported. | (->array (list 1 2 3)) #=> [1 2 3]
(->array @[1 2]) #=> [1 2]
(->array |3 1 2|) #=> [1 2 3] |
(->list coll) | Convert any sequence to a list. Arrays, @arrays, sets, strings (graphemes), and bytes (integers) are supported. | (->list [1 2 3]) #=> (1 2 3)
(->list @[1 2]) #=> (1 2)
(->list |3 1 2|) #=> (1 2 3) |
(first sequence) | Get the first element of a sequence (list, array, string). Returns nil for empty. | (first (list 1 2 3)) |
(length collection) | Get the length of a collection (list, string, array, table, struct, symbol, or keyword) | (length (list 1 2 3)) |
(list elements) | Create a list from arguments | (list 1 2 3) |
(rest sequence) | Get the rest of a sequence. Returns type-preserving empty for empty input. | (rest (list 1 2 3)) |
(second sequence) | Get the second element of a sequence. Returns nil if fewer than 2 elements. | (second (list 1 2 3)) |
parameter
| Function | Description | Example |
|---|---|---|
(parameter default) | Create a new dynamic parameter with a default value. | (def p (parameter 42))
(p) #=> 42 |
path
| Function | Description | Example |
|---|---|---|
(path/absolute path) | Compute absolute path (does not require path to exist) | (path/absolute "src") |
(path/absolute? path) | True if path is absolute | (path/absolute? "/foo") |
(path/canonicalize path) | Resolve path through filesystem (symlinks resolved, must exist) | (path/canonicalize ".") |
(path/components path) | Split path into list of components | (path/components "/a/b/c") |
(path/cwd) | Get current working directory | (path/cwd) |
(path/dir? path) | Check if path is a directory | (path/dir? "/home") |
(path/exists? path) | Check if path exists | (path/exists? "data.txt") |
(path/extension path) | Get file extension without dot (nil if none) | (path/extension "data.txt") |
(path/file? path) | Check if path is a regular file | (path/file? "data.txt") |
(path/filename path) | Get file name (last component, nil if none) | (path/filename "/home/user/data.txt") |
(path/join components) | Join path components | (path/join "a" "b" "c") |
(path/normalize path) | Lexical path normalization (resolve . and ..) | (path/normalize "./a/../b") |
(path/parent path) | Get parent directory (nil if none) | (path/parent "/home/user/data.txt") |
(path/relative target base) | Compute relative path from base to target (nil if impossible) | (path/relative "/foo/bar/baz" "/foo/bar") |
(path/relative? path) | True if path is relative | (path/relative? "foo") |
(path/stem path) | Get file stem (filename without extension, nil if none) | (path/stem "archive.tar.gz") |
(path/with-extension path ext) | Replace file extension (empty string removes it) | (path/with-extension "foo.txt" "rs") |
port
| Function | Description | Example |
|---|---|---|
(port/close port) | Close a port. Idempotent. Yields to cancel pending I/O before closing the fd. | (port/close p) |
(port/encoding port) | Return the port's encoding as a keyword: :text or :binary. :text ports return strings and grapheme-count read-exact; :binary ports return bytes and byte-count. | (port/encoding (tcp/connect "127.0.0.1" 6379)) #=> :binary |
(port/flush port) | Flush port's write buffer. | (port/flush (port/stdout)) |
(port/open path mode) | Open a file as a text (UTF-8) port. Accepts optional :timeout ms keyword. | (port/open "data.txt" :read)
(port/open "fifo" :read :timeout 5000) |
(port/open-bytes path mode) | Open a file as a binary port. Accepts optional :timeout ms keyword. | (port/open-bytes "data.bin" :read)
(port/open-bytes "fifo" :read :timeout 5000) |
(port/open? port) | Check if a port is open. Signals :type-error on non-port. | (port/open? (port/stdout)) #=> true |
(port/path port) | Return the path or address the port was opened on, or nil for stdio ports. | (port/path (tcp/listen "127.0.0.1" 0)) |
(port/read port n) | Read up to n bytes from port. Returns bytes or nil (EOF). | (port/read (port/open "file.txt" :read) 1024) |
(port/read-all port) | Read everything remaining from port. | (port/read-all (port/open "file.txt" :read)) |
(port/read-exact port n) | Read exactly n bytes from port, looping over short reads. Returns bytes/string of length n, or nil if EOF arrived first. Unlike port/read (which is 'up to n' per POSIX), this resubmits short reads on stream sockets too — use it for length-prefixed binary framing (RESP, gRPC, h2 DATA, etc.). | (port/read-exact tcp-sock 1024) |
(port/read-line port) | Read one line from port. Returns bytes or nil (EOF). | (port/read-line (port/open "file.txt" :read)) |
(port/seek port offset) | Seek to a byte offset in a file port. Returns new absolute position. Syntax: (port/seek port offset [:from :start|:current|:end]) Default :from is :start (SEEK_SET). Discards the read buffer on seek. | (port/seek p 0)
(port/seek p 0 :from :start)
(port/seek p -1 :from :end) |
(port/set-options port) | Set port options. Currently: :timeout ms (nil clears). | (port/set-options p :timeout 5000) |
(port/stderr) | Return a port for standard error. | (port/stderr) |
(port/stdin) | Return a port for standard input. | (port/stdin) |
(port/stdout) | Return a port for standard output. | (port/stdout) |
(port/tell port) | Return current logical byte position in a file port. Accounts for per-fd read buffering: position = kernel_offset - buffer.len(). | (port/tell p) |
(port/write port data) | Write all of data to port, looping over short writes. Returns the number of bytes written, which equals the length of data — a caller never loops on the count. Errors if the fd fails part-way, since an unknown prefix reached the peer. | (port/write (port/stdout) "hello") |
posix
| Function | Description | Example |
|---|---|---|
(os/sig-close receiver) | Close a signal receiver. Decrements the watched-set refcount; the signal is unblocked process-wide when the last watcher releases it. Idempotent. | (os/sig-close r) |
(os/sig-mask) | Return a set of keywords for signals currently blocked on the calling thread (pthread_sigmask). | (os/sig-mask) |
(os/sig-name signum) | Name a signal number as its keyword (:sigterm, :sigsegv, ...), or nil when this build knows no name for it. Covers the fatal signals os/sig-send refuses, because a terminating status has to read as something. | (os/sig-name 11) |
(os/sig-next receiver) | Wait for the next batch of signal deliveries on a receiver. Yields to the scheduler. Resumes with an array of [{:signal :sigterm :sender-pid n :sender-uid n :code n :count n} ...]. | (os/sig-next r) |
(os/sig-pending) | Return a set of keywords for signals currently pending delivery on the calling thread (sigpending(2)). | (os/sig-pending) |
(os/sig-raise signum) | Send a POSIX signal to the current process. Capability: :os-signal. | (os/sig-raise :sigusr1) |
(os/sig-send pid signum) | Send a POSIX signal to a pid. signum is a keyword (:sigterm, :sigkill, etc.) or a named integer. Capability: :os-signal. | (os/sig-send 4242 :sigterm) |
(os/sig-watch signal-set) | Open a signal receiver that watches a set of POSIX signals. Blocks the signals on the calling thread and queues deliveries onto a kernel fd. Returns a SignalReceiver. See docs/posix-signals.md for mask policy. | (os/sig-watch |:sigterm :sigint|) |
(os/sig-watching) | Return a set of keywords for signals currently being watched by at least one live receiver. | (os/sig-watching) |
predicate
| Function | Description | Example |
|---|---|---|
(empty? collection) | Check if a collection is empty | (empty? (list)) |
(fiber? value) | Returns true if value is a fiber | (fiber? (fiber/new (fn () 42) |:yield|)) |
(io-backend? value) | Check if value is an I/O backend. | (io-backend? 42) #=> false |
(io-request? value) | Check if value is an I/O request. | (io-request? 42) #=> false |
(jit? value) | Returns true if closure has JIT-compiled code | (jit? (fn (x) x)) |
(port? value) | Check if value is a port. | (port? (port/stdin)) #=> true |
(ptr? value) | Check if value is a raw C pointer. | (ptr? ptr) #=> true
(ptr? 42) #=> false |
(silent? value) | Returns true if closure is silent (does not suspend: no yield, debug, or polymorphic signal). False for non-closures. | (silent? (fn (x) x)) |
(subprocess? value) | Check if value is a subprocess. | (subprocess? 42) #=> false |
(sys/ip? value) | True if the argument is a string holding an IPv4 or IPv6 address literal (e.g. "127.0.0.1", "::1"). Hostnames, bracketed or port-suffixed addresses, and non-strings are false. Synchronous — does no resolution; tcp/connect uses it to skip sys/resolve for IP literals. | (sys/ip? "127.0.0.1") #=> true |
(type-of value) | Get the type of a value as a keyword. | (type-of 42) #=> :integer
(type-of "hello") #=> :string |
ptr
| Function | Description | Example |
|---|---|---|
(ptr/add pointer offset) | Offset a pointer by a byte count. Returns a raw pointer. Offset may be negative. | (ptr/add buf 16) |
(ptr/diff pointer-a pointer-b) | Compute the signed byte distance between two pointers (a - b). | (ptr/diff p2 p1) |
(ptr/from-int integer) | Construct a raw C pointer from an integer address. Returns nil if address is 0. | (ptr/from-int addr) |
(ptr/to-int pointer) | Extract the raw address of a pointer as an integer. | (ptr/to-int buf) |
scheduler
| Function | Description | Example |
|---|---|---|
(ev/poll-fd fd mode timeout?) | Poll a raw fd for readiness — yields to the scheduler. mode: :read, :write, :read-write. Optional timeout in seconds. | (ev/poll-fd 5 :read 1.0) |
(ev/sleep seconds) | Async sleep — yields to the scheduler for the specified duration in seconds | (ev/sleep 0.5) |
set
| Function | Description | Example |
|---|---|---|
(@set) | Create a mutable set from elements (deduplicates, freezes mutable values) | (@set 1 2 3) |
(difference set1 set2) | Compute the difference of two sets (both must be the same type) | (difference (set 1 2 3) (set 2)) #=> |1 3| |
(intersection set1 set2) | Compute the intersection of two sets (both must be the same type) | (intersection (set 1 2) (set 2 3)) #=> |2| |
(seq->set seq) | Convert any sequence to a set. Immutable inputs (list, tuple, string, bytes, set) → immutable set. Mutable inputs (array, buffer, blob, @set) → mutable set. Freezes mutable values on insertion. | (seq->set [1 2 3]) #=> |1 2 3| |
(set) | Create an immutable set from elements (deduplicates, freezes mutable values) | (set 1 2 3) |
(string-contains? string substring) | Deprecated: use has? instead. Check if a string contains a substring. | (string-contains? "hello world" "world") #=> true |
(union set1 set2) | Compute the union of two sets (both must be the same type) | (union (set 1 2) (set 2 3)) #=> |1 2 3| |
special form
| Function | Description | Example |
|---|---|---|
(and expr...) | Short-circuit logical AND. Returns the first falsy value, or the last value if all truthy. | (and (> x 0) (< x 100)) |
(assign name value) | Mutate a mutable binding: one defined with var, or bound with an @ name. | (var x 0) (assign x 42) |
(attune! :signal or |signals|) | Declare, inside a function body, the most the function may emit: a body whose inferred signal exceeds the given signals is a compile error. | (defn add [x y] (attune! :error) (+ x y)) |
(begin expr...) | Sequence expressions. Does NOT create a scope — bindings leak into the enclosing scope. | (begin (def x 1) (def y 2) (+ x y)) |
(block :name? body...) | Sequence expressions in a new lexical scope. Supports optional keyword name for break targeting. | (block :outer (each x in [1 2 3] (when (= x 2) (break :outer x))) nil) # => 2 |
(break :name? value) | Exit a named block with a value. Must be inside a block; cannot cross function boundaries. | (block :loop (break :loop 42)) |
(cond test body...) | Multi-branch conditional. Tests clauses in order, evaluating the body of the first true test. | (cond (< x 0) "negative" (= x 0) "zero" "positive") |
(def pattern value) | Bind a value to an immutable name. Supports destructuring patterns including lists, arrays, and tables. | (def x 42)
(def {:name n :age a} {:name "Alice" :age 30}) |
(defmacro name (params...) body...) | Define a macro. The expander calls it with the unevaluated argument forms as syntax objects, and compiles the form it returns in their place. | (defmacro unless-zero (n & body)
`(if (= ,n 0) nil (begin ,;body)))
(unless-zero 3 :nonzero) # => :nonzero |
(doc name) | Display documentation for a named function or special form. Accepts a symbol or string. A symbol that names a closure passes the closure through; the analyzer rewrites any other symbol to its name. | (doc map)
(doc "map") |
(emit :signal value?) | Emit a signal with a value. The fiber suspends; the parent decides what happens next. Recognized as a special form only with a keyword or signal-set argument. | (emit :yield 1) |
(environment) | Reify the current lexical scope as a struct. Returns a struct mapping quoted symbols to their values for all lexical bindings a reference at this site would resolve. Primitives, compiler temporaries, and macro-introduced (scope-stamped) bindings are excluded. Useful with eval to pass the current environment. | (def x 42)
(environment) # => {'x 42}
(eval '(+ x 1) (environment)) # => 43 |
(eval expr env?) | Compile and execute an expression at runtime. The expression is a quoted datum that goes through the full compilation pipeline (expand, analyze, lower, emit, execute). It compiles against the primitives and the prelude only: the enclosing program's own bindings are not visible. An optional second argument provides an environment struct — its symbol-keyed entries become immutable bindings visible to the expression; pass (environment) to hand over the caller's lexical scope. A name that resolves against none of these is an undefined-variable error, surfaced as an :eval-error. | (eval '(+ 1 2))
(eval '(+ x y) {'x 10 'y 20}) |
(fn (params...) body...) | Create an anonymous function (lambda). Supports destructuring in parameters. | (fn (x y) (+ x y)) |
(if condition then else?) | Conditional expression. Evaluates condition, then either the then-branch or the else-branch. | (if (> x 0) "positive" "non-positive") |
(immutable! name) | Assert, inside a function body, that the named binding is never assigned there; an assignment is a compile error. | (defn f [] (immutable! x) x) |
(let [name value ...] body...) | Bind values to names in a new scope. Supports destructuring patterns. | (let [x 1 y 2] (+ x y)) |
(letrec [name value ...] body...) | Recursive let. Bindings can reference each other (for mutual recursion). | (letrec [even? (fn (n) (if (= n 0) true (odd? (- n 1)))) odd? (fn (n) (if (= n 0) false (even? (- n 1))))] (even? 10)) |
(match value pattern body...) | Pattern matching. Tests value against patterns in order, executing the first matching arm. | (match x 0 "zero" (a . b) (+ a b) _ "other") |
(muffle :signal or |signals|) | Declare, inside a function body, signals to remove from the function's inferred signal; beside a (silence) or attune! ceiling, widen the ceiling by them instead. Compile-time only: nothing stops a muffled signal at run time. | (defn f [x] (silence) (muffle :error) (+ x 1)) |
(numeric!) | Declare, inside a function body, that every parameter is a number, which proves the operands of % intrinsics, and assert that the function is GPU-eligible: no call, no closure, no heap value, no emit. A non-eligible body is a compile error. | (defn square [x] (numeric!) (%mul x x)) |
(or expr...) | Short-circuit logical OR. Returns the first truthy value, or the last value if all falsy. | (or default-value (compute-value)) |
(parameterize ((param value) ...) body...) | Dynamically bind parameters for the extent of the body. Each parameter is restored to its previous value on exit. | (def depth (make-parameter 0))
(parameterize ((depth 1)) (depth)) # => 1 |
(quote form) | Return the unevaluated form. Prevents evaluation of its argument. | (quote (+ 1 2)) # => (+ 1 2) |
(signal :keyword) | Declare a user signal at file scope. Produces the keyword value. | (signal :saturated) |
(silence param?) | Declare, inside a function body, that the function emits no signal at all, :error included; a body that may signal is a compile error. With a parameter name, bound that parameter instead: a closure passed for it must be silent, checked at function entry. | (defn pick [b x y] (silence) (if b x y))
(defn apply-silent [f x] (silence f) (f x)) |
(silent!) | Assert, inside a function body, that the function's inferred signal is empty, before any ceiling or muffle applies; otherwise a compile error. | (defn pick [b x y] (silent!) (if b x y)) |
(splice expr) | Mark a value for spreading into a function call or data constructor. The short form is `;expr`. Works on lists and arrays. Inside quasiquote, `,;expr` is unquote-splicing. | (defn f [a b c] (+ a b c))
(def args @[1 2 3])
(f ;args) # => 6 |
(unicode! major minor patch) | Declare the Unicode generation this source assumes; checked at compile time against the program's locked generation, evaluates to nil. With no arguments, fold to the selected version as [major minor patch]. | (unicode! 17) |
(var pattern value) | Bind a value to a mutable name. Supports destructuring. Use assign to mutate. | (var x 0)
(assign x (+ x 1)) |
(while condition body...) | Loop while condition is true. Returns nil, or the value a (break :while value) gives. | (var i 0) (while (< i 10) (assign i (+ i 1))) |
syntax sugar
| Function | Description | Example |
|---|---|---|
(-> value forms...) | Thread-first macro. Inserts value as first argument of each successive form. | (-> 5 (+ 3) (* 2)) # => (* (+ 5 3) 2) => 16 |
(->> value forms...) | Thread-last macro. Inserts value as last argument of each successive form. | (->> 5 (- 10) (* 2)) # => (* 2 (- 10 5)) => 10 |
(defer cleanup body...) | Run body in a fiber, then run cleanup whether the body completed or failed. Returns the body's value, or propagates its error after the cleanup. | (def log @[])
(defer (push log :cleanup)
(push log :body)
42) # => 42, and log is @[:body :cleanup] |
(defn name params body...) | Define a named function. Shorthand for (def name (fn params body...)). | (defn add [x y] (+ x y))
(add 1 2) # => 3 |
(each name in? collection body...) | Iterate over a sequence, binding each element to a name. Walks a list, an array, a string, bytes, a fiber's yields, a set, a struct's pairs, or a value whose traits carry :iter. The `in` is optional. | (each x in [1 2 3]
(println x)) |
(error value?) | Signal an error. The value can be anything; by convention a struct {:error :kind :message "msg"}. With no argument, signals nil. | (protect (error {:error :not-found :message "missing key"}))
# => [false {:error :not-found :message "missing key"}] |
(ffi/defbind name lib-handle "c-name" return-type [arg-types...]) | Define a named wrapper for a C function via FFI. Looks up the symbol, creates a signature, and defines a function that calls it. | (def libc (ffi/native nil))
(ffi/defbind abs libc "abs" :int [:int])
(abs -3) # => 3 |
(let* [name value ...] body...) | An alias of let, kept for Scheme readers: bindings are flat name-value pairs, and each sees the ones before it. | (let* [x 1 y (+ x 1)] (+ x y)) # => 3 |
(protect body...) | Run body in a fiber and return [ok? value]: [true result] when it completes, [false error] when it signals an error. The error does not propagate. | (protect (+ 1 2)) # => [true 3]
(protect (error {:error :boom})) # => [false {:error :boom}] |
(try body... (catch name handler...)) | Run body in a fiber. If it signals an error, run the handler with the error bound to the catch name and return the handler's value. | (try (error {:error :boom}) (catch e (get e :error))) # => :boom |
(unless condition body...) | Evaluate body when condition is false. Returns nil if true. | (unless (empty? [1 2]) (first [1 2])) # => 1 |
(when condition body...) | Evaluate body when condition is true. Returns nil if false. | (when (> 3 0) (println "positive")) |
(with name ctor dtor body...) | Bind name to the value of ctor, run body, then call dtor on that value, even when the body fails. Built on defer. | (def closed @[])
(with xs @[1 2] (fn [v] (push closed v))
(length xs)) # => 2, and closed holds xs |
(yield value?) | Suspend the current fiber, handing value (nil when omitted) to its resumer. Expands to (emit :yield value). | (def gen (fiber/new (fn () (yield 1) (yield 2)) |:yield|))
(fiber/resume gen) # => 1 |
(yield* fiber) | Resume a sub-fiber until it finishes, re-yielding each value it yields and passing each resume value back in. Returns the sub-fiber's final value. | (def inner (fiber/new (fn () (yield 1) 2) |:yield|))
(def outer (fiber/new (fn () (yield* inner)) |:yield|))
(fiber/resume outer) # => 1 |
sys
| Function | Description | Example |
|---|---|---|
(subprocess/exec program args opts) | Spawn a subprocess. Returns a subprocess: read :pid, :stdin, :stdout, :stderr and :exit from it with get. | (subprocess/exec "ls" ["-la"]) |
(subprocess/exit subprocess) | Return a subprocess's recorded exit status, or nil while nothing has reaped the child. Reads the record; it never waits and never reaps. | (subprocess/exit proc) |
(subprocess/kill subprocess signal) | Send a signal to a subprocess. signal is an integer or a keyword like :sigterm, :sigkill, :sighup, :sigint, :sigquit, :sigpipe, :sigalrm, :sigusr1, :sigusr2, :sigchld, :sigcont, :sigstop, :sigtstp, :sigttin, :sigttou, :sigwinch (default: :sigterm). Returns :signaled when kill(2) took the signal, :exited when the child's status is already recorded and nothing was sent, :missing when no process holds the pid. | (subprocess/kill proc :sigterm) |
(subprocess/pid subprocess) | Return the OS process ID of a subprocess, whether or not the child has been reaped. | (subprocess/pid proc) |
(subprocess/wait subprocess) | Wait for a subprocess to exit. Returns exit code (0 = success). A signalled child answers the negated signal number. | (subprocess/wait proc) |
(sys/args) | Return command-line arguments as a list (excluding interpreter and script path) | (sys/args) |
(sys/argv) | Return the full argv as a list: script name as element 0 followed by all user args. Element 0 is "-" for stdin or the script path for a file. Returns an empty list in REPL mode. | (sys/argv) |
(sys/env name) | Return the process environment as a struct with string keys and string values, or look up a single variable by name. Non-UTF-8 entries are silently skipped. | (sys/env) ; or (sys/env "HOME") |
(sys/exit code) | Exit the process with an optional exit code (0-255) | (sys/exit 0) |
(sys/halt value) | Halt the VM gracefully, returning a value to the host | (sys/halt 42) |
(sys/pid) | Return the current process's pid as an integer. | (sys/pid) |
(sys/resolve hostname) | Resolve a hostname to IP addresses via the system resolver (getaddrinfo). Returns an array of IP address strings. | (sys/resolve "localhost") |
(sys/spawn closure) | Spawn a thread running a deep-copied closure in a fresh VM with the standard library loaded (so eval/read in the worker resolve stdlib). Heavier than sys/spawn-vm (init_stdlib per spawn). | (sys/spawn (fn [] (+ 1 2))) |
(sys/spawn-vm closure) | Spawn a thread running a deep-copied closure in a fresh VM with primitives only (no stdlib). The cheap path; eval in the worker resolves primitives/intrinsics but not stdlib. | (sys/spawn-vm (fn [] (+ 1 2))) |
(sys/thread-id) | Return the ID of the current thread | (sys/thread-id) |
(sys/thread-state thread-handle) | Inspect a thread handle without blocking (a single check, never a loop): [:ready value], [:failed message], or [:pending receiver]. Building block for sys/join (which adds the scheduler-cooperative wait + timeout). | (sys/thread-state thread-handle) |
(sys/trap-exit! on) | Trap `exit` on this thread as a catchable {:error :exited :code N} signal (true) or restore process termination (false). Used by the test runner. | (sys/trap-exit! true) |
(sys/unique) | Return a fresh integer, unique across the whole process. A coordination key (futex key, correlation id) that, unlike a gensym, interns nothing. | (sys/unique) |
tcp
| Function | Description | Example |
|---|---|---|
(tcp/accept listener) | Accept a connection on a TCP listener. Returns a stream port. | (tcp/accept listener) |
(tcp/connect-ip ip port) | Connect to a TCP endpoint by IP literal (IPv4 or IPv6). Hostnames are rejected — the stdlib tcp/connect wrapper resolves names and calls this per address. Returns a stream port. | (tcp/connect-ip "127.0.0.1" 8080) |
(tcp/listen addr port) | Bind and listen on a TCP address. Returns a listener port. | (tcp/listen "127.0.0.1" 8080) |
(tcp/shutdown port how) | Shutdown a TCP stream. how: :read, :write, or :read-write. | (tcp/shutdown conn :write) |
traits
| Function | Description | Example |
|---|---|---|
(trait/iterable? value) | True when a value's elements come from an :iter trait method rather than from a builtin container. A list, array, string, bytes, or a plain set or struct answers false. | (trait/iterable? [1 2 3]) |
(trait/method value name) | Return a value's trait method by name, read from its :Sequence protocol and then its :Collection protocol. Returns nil when the value's own table carries neither the protocol nor the method. | (trait/method [1 2 3] :first) |
(trait/op value name) | Return the trait method that overrides a collection operator on a value, or nil. A list, array, string, bytes or syntax object answers nil — those carry their own traversal, so an operator never reads their trait table. | (trait/op (with-traits {:a 1} @{:Sequence {:map (fn [self f] :mapped)}}) :map) |
(traits value) | Return the trait table attached to a value, or nil if none. Usable as boolean: (if (traits v) ...) checks for presence. | (traits (with-traits [1 2 3] {:Seq {:first (fn (v) (get v 0))}})) |
(with-traits value table) | Attach a trait table to a value. Returns a new value with the same data and the given trait table. The table must be a struct (immutable or mutable). | (with-traits [1 2 3] {:Seq {:first (fn (v) (get v 0))}}) |
types
| Function | Description | Example |
|---|---|---|
(callable? x) | Returns true if value can be called: closures, native functions, parameters, structs, arrays, sets, strings, and bytes. | (callable? +) #=> true
(callable? {:a 1}) #=> true
(callable? |1 2|) #=> true
(callable? [1 2]) #=> true
(callable? 42) #=> false |
udp
| Function | Description | Example |
|---|---|---|
(udp/bind addr port) | Bind a UDP socket. Returns a UDP port. | (udp/bind "0.0.0.0" 9000) |
(udp/recv-from socket count) | Receive data from a UDP socket. Returns {:data :addr :port}. | (udp/recv-from sock 1024) |
(udp/send-to socket data addr port) | Send data to a remote address via UDP. Returns bytes sent. | (udp/send-to sock "hello" "127.0.0.1" 9000) |
unix
| Function | Description | Example |
|---|---|---|
(unix/accept listener) | Accept a connection on a Unix listener. Returns a stream port. | (unix/accept listener) |
(unix/connect path) | Connect to a Unix domain socket. Returns a stream port. | (unix/connect "./my.sock") |
(unix/listen path) | Listen on a Unix domain socket. Returns a listener port. | (unix/listen "./my.sock") |
(unix/shutdown port how) | Shutdown a Unix stream. how: :read, :write, or :read-write. | (unix/shutdown conn :write) |
watch
| Function | Description | Example |
|---|---|---|
(watch) | Create a filesystem watcher. Returns a watcher handle for use with watch-add, watch-next, watch-close. | (def w (watch)) |
(watch-add watcher path opts?) | Add a path to the watcher. Recursive by default. Optional third arg: {:recursive false}. | (watch-add w "src/") |
(watch-close watcher) | Close the watcher and release its resources. | (watch-close w) |
(watch-next watcher) | Wait for filesystem events. Yields to the scheduler; resumes with an array of event structs [{:kind :modify :path "..."}]. Event kinds: :create, :modify, :remove, :rename. On macOS (kqueue), :create is reported as :modify because kqueue does not distinguish them at the directory level. | (watch-next w) |
(watch-remove watcher path) | Remove a watched path from the watcher. | (watch-remove w "src/") |