Built-ins reference
This page covers the language-level built-ins and compiler-recognized forms: operators, constructors, control flow, binding forms, actions, datatype actions, ownership and atomics, and diagnostics. Two major built-ins have their own pages — the PARSE dialect and state machines (FSM/FST).
Operators
Arithmetic + - * / % (modulo is %; there is no
//), integer bitwise and shift << >> & | xor,
comparisons = == <> < > <= >=, and logical
and or. Precedence (higher binds tighter):
| Level | Operators |
|---|---|
| 20 | * / % |
| 10 | + - << >> & | xor |
| 5 | = == <> < > <= >= |
| 3 | and or |
a: 10 + 5 * 2 ; 20 — multiplication binds tighter
b: (10 + 5) * 2 ; 30
f: as f32! a ; explicit cast with `as`
The shift and bitwise operators share one precedence band with
+ and - and evaluate left to right, so
parenthesise every term: (tag & 255) | (x << 8).
Bitwise operators accept integers only.
Constructors & conversions
make <type> <value>— the standard typed construction form, also used for typed bindings (x: make i32! 1).as <type> <value>— explicit cast / coercion.charset <chars>— builds abitset!forparse.size-of <abi-type>— lowers to Csizeof(...).offset-of <c-struct> <field>— lowers to Coffsetof(...).static-assert <cond> <message>— compile-time assertion (lowers to_Static_assert);condmust be constant.addr-of <binding>— address-of for addressable values.
bytes: size-of c-pointer!
ptr: addr-of x
static-assert (size-of i32!) = 4 "i32! must be 4 bytes"
Predicates & general helpers
none?— is a nullable valuenone(NULL)?errored?— is an error currently set in the global state? (zero-arity, consuming read)error?— is this specific value an error? (takes one operand)length?— datatype-driven length query.print— type-directed printing.form,mold— value-to-text conversions.load,load-as— data conversion forms.
ptr: none
if none? ptr [print "null"]
n: length? nums
Series, string, dict & block actions
Resolved through parser/type/runtime support, not as plain functions.
Native series state
freeze series— returns an immutable native series.thaw series— unlocks an owned series in place to mutable, non-growable.flex series— unlocks an owned series in place to mutable, growable.copy series— a fresh owned, writable duplicate;thaw/flexreject a string literal or a:nameborrow withB3006, so writeflex copy s.
Size-changing ops (#flexible only)
append— grows a#flexiblestring!/array! T/vector! T, or appends a tagged slot to a#flexible block!.insert— prepends at position 0.remove/last— pops the last element.
append, insert, and remove are valid
only on #flexible series. Non-flex
block!/string!/vector! are
static-size — no reallocation is allowed.
Dict / map style
pick— lookup;contains?— membership.get-or-put— lookup with insertion;update-or-insert— update helper.remove/key— removal;clear— clear where supported.take— supported on selected sequence/port APIs.
counts: make [#mutable dict! [string! i32!]] [string! i32!]
get-or-put counts "ok" 1
print pick counts "ok" ; 1
Extending types with extend
A user struct can implement built-in actions by mapping an action name to a Recoil function:
MyBuf!: make struct! [data: c-pointer! len: i64!]
mybuf-length: func [
"Return the length of a MyBuf."
b [MyBuf!] "The buffer to measure."
return: [i64!] "The number of bytes in the buffer, read from its len field."
] [return b/len]
extend MyBuf! [
length? mybuf-length
]
n: length? mybuf ; lowers to mybuf_length(mybuf)
Rules: the action must be a known built-in (length?,
open?, query, …); the function must be defined before
the extend; its return type must match the action contract.
Diagnostics: T4200 (not a struct), T4201 (function
not defined), T4202 (return type mismatch).
Datatype actions
Built-in action coverage by type:
| Type | Actions |
|---|---|
file! | open? |
port! | open?, query, length? |
vector!, array!, block!, dict!, string!, slice!, c-string!, url! | length? |
fsm! | send |
Control flow & expressions
These are compiler-recognized forms, not library calls.
if, either, match, all
and any are expressions; the loop forms are expressions too, yielding
the final body value.
if cond [body],either cond [then] [else]— both branches of aneithermust have the same type.unless cond [body]— runs whencondis false (statement only).switch subject [cases…]— value dispatch over literal branches.match subject [branches…]—sum!pattern dispatch that binds variant payloads.all [expr …]/any [expr …]— short-circuit AND / OR.while [cond] [body],repeat word count [body],foreach [word] vector [body],foreach [key value] dict [body],break,continue,return expr.
Binding & declaration forms
name: value— an inferred-type binding. Reach formakeonly when inference cannot resolve the type.name: mutable value— a binding that may be reassigned.mutableis accepted only as the direct initializer of a binding (P1725); the old statement-formmutis removed (P1022).Name!: constrain base! [predicate…]— a constrained alias of a scalar numeric type, e.g.PositiveI32!: constrain i32! [(> 0)].comptime [body],compfunc [spec] [body]— compile-time evaluation. A compfunc can take its arguments unparsed (#raw), receive their resolved types (#typed), and return AST withmacro-expr; see the repository'scomptimedoc.
Colour literals: a three- or four-part tuple! such as
229.224.212 or 229.224.212.255 is packed at parse time into
a 0xRRGGBBAA u32! (alpha defaults to 255). It is a
syntax desugar, not a runtime type.
Ownership & resource forms
string!, block!, vector! and
array! are shared and reference-counted by default; assignment adds a reference and
the source stays valid, and so do typed dict! values. Ports, maps, errors, binary! and
pointers are move-only, and so is any series declared #unique.
See Ownership & borrowing.
| Attribute | Meaning |
|---|---|
#mutable | slot, field and path updates are allowed |
#flexible | the series can grow and shrink (implies mutable slots) |
#unique | opt a series out of sharing: an owned transfer moves it |
#atomic | scalar storage with indivisible loads, stores and read-modify-write |
#stack / #heap | fixed vector! storage: inline and move-only, or managed (the default) |
:name— a borrowed parameter, in both the spec and the call site.defer [body]— run on function exit (LIFO).defer/error [body]— run only when an error is set.unused name— declare an intentionally unused binding.
Atomics
Loads and stores on an #atomic binding are implicit and
sequentially consistent. Read-modify-write is spelled with named forms: #atomic needs C11, so it is rejected under --c-profile c99 (P1757) and on the wasm32-emscripten and esp32 targets (P1765).
atomic-add target value,atomic-sub target value— return the previous value; integer and pointer targets only (P1760).atomic-exchange target value— returns the previous value.atomic-compare-exchange target expected desired— returns alogic!success flag.
counter: make [#atomic i32!] 0
atomic-add counter 5
old: atomic-exchange counter 7 ; 5
ok: atomic-compare-exchange counter 7 9 ; true
Tasks & channels
go [body],go/after ms [body]— spawn a cooperative task (statement form, inside a function).sleep ms— park the current task, or drive the scheduler from the main flow.make channel! [T n]— a typed bounded channel;nof 0 is a rendezvous channel.send ch value,receive ch,close ch—sendmoves heap values into the channel.
run: func [
"Send two values through a channel from a spawned task and print them as they are received."
return: [none!] "Nothing."
] [
ch: make channel! [i32! 4]
go [
send ch 1
send ch 2
]
print receive ch ; 1
print receive ch ; 2
]
run
Diagnostics
Compile-time failures are reported both as a human-readable string and as a structured object attached to the raised error.
Message format
TYPE ERROR T4000: Cannot assign void return value to variable 'x'
BORROW CHECKER ERROR B3000: 's1' used after move
CLI ERROR R6001: Unknown option: --bogus
The shape is <PREFIX> <CODE>: <message>; a diagnostic without a code omits it.
Prefixes include SYNTAX ERROR, TYPE ERROR,
BORROW CHECKER ERROR, MODULE ERROR,
STRUCT ERROR, COMPTIME ERROR,
FUNCTION HEADER ERROR, MODULE HEADER ERROR,
CLI ERROR, BUILD ERROR,
INTERNAL ERROR.
Structured shape
Each diagnostic carries stage (one of parser,
module, borrow-checker, ir,
codegen, cli, build), a
kind, a stable code such as P1000, a
message, and optional context / location.
The authoritative code list lives in the repository's
diagnostics doc.
Runtime error codes
Runtime errors carry a category type and a numeric code. Any value whose
type is >= ERR_TYPE_MATH (1) is treated as an error.
| Code | Category | Constant |
|---|---|---|
| 300 | Math — divide by zero | ERR_MATH_ZERO_DIVIDE |
| 301 | Math — integer overflow | ERR_MATH_OVERFLOW |
| 302 | Math — underflow | ERR_MATH_UNDERFLOW |
| 500 | FFI — null pointer | ERR_FFI_NULL_POINTER |
| 700 | Series — out of bounds | ERR_SERIES_OUT_OF_BOUNDS |
| 701 | Series — past end | ERR_SERIES_PAST_END |
| 800–841 | Port (TCP/TLS/HTTP/DNS) | ERR_PORT_* — see Ports |
| 850–853 | Parse / FST | ERR_PARSE_* |
| 860 | Channel — closed | ERR_CHANNEL_CLOSED |
| 900+ | User | via make error! |
The authoritative list lives in lib/runtime.rcl. See the
error-handling section of the guide for usage.
Known limits
Things Recoil deliberately does not do yet, so you can tell a gap from a bug. Sources: deferred-scope-0.12.md and current-map-block-json-limitations.md in docs/user/.
Concurrency and atomics
- Infix read-modify-write on an
#atomicbinding (counter: counter + 1) is rejected withB3012. Useatomic-add,atomic-sub,atomic-exchangeoratomic-compare-exchange. - esp-idf and browser-wasm keep a run-to-completion task queue: no yielding,
go/afterdelays ignored,sleepblocks the process. See Concurrency. #atomiccovers scalar storage only. Sharing a managed series across OS threads is unsupported; the docs say reference counts stay non-atomic and this is a compile-time error.
Macros
- A
macro-exprmacro is expression-only: statement AST such as a declaration is rejected withP1301. A compfunc that returns a block returns source, parsed where the call stands, so it can expand to declarations and statements. Custom macro diagnostics, reflection APIs and generic struct expansion exist. - Still deferred to 0.13: automatic hygiene (
gensymis the manual tool), AST re-entry, declaring a type or callback wrapper from an expansion inside a function body (P1788), and inline lambda arguments tomap,filterandfold.
map!, array!, JSON and typeset!
- Schema
map!declarations are closed, struct-backed object types; anonymous structuralmap!types do not exist. Baremap!is the open, string-keyed container ofvalue!cells. - Schema dynamic field paths (
obj/:field) work only with statically resolvable selectors; runtime string-to-field dispatch is out of scope. - Optional fields use
#optional, recognised only insidemake map! [...]field blocks. Absent-field reads are errors, so guard withpresent?; optionality does not extend to locals, params, returns or elements. - Typed JSON decode ignores unknown keys, and array-of-union decoding is not implemented.
load-jsonreturns avalue!: arrays as heterogeneousblock!, objects asmap!. Malformed input and excessive nesting are runtime errors. typeset!has syntax and normalization but incomplete runtime support;matchstayssum!-only. There are nojson!ortable!types.
Not re-checked against the compiler: the exact wording of the cross-thread sharing error, the per-item milestone assignments, and the typeset! and predicate-narrowing statements. Treat them as the docs' claims.