Recoil

Built-ins reference

This page covers the language-level built-ins and compiler-recognized forms: operators, constructors, actions, datatype actions, and diagnostics. Two major built-ins have their own pages — the PARSE dialect and state machines (FSM/FST).

Operators

Arithmetic + - * / //, comparisons = == <> < > <= >=, and logical and or. Precedence (higher binds tighter):

a: 10 + 5 * 2           ; 20 — multiplication binds tighter
b: (10 + 5) * 2         ; 30
f: as f32! a             ; explicit cast with `as`

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 a bitset! for parse.
• size-of <abi-type> — lowers to C sizeof(...).
• offset-of <c-struct> <field> — lowers to C offsetof(...).
• static-assert <cond> <message> — compile-time assertion (lowers to _Static_assert); cond must 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 value none (NULL)?
• error? — is an error currently set (or is this value an error)?
• 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 — returns a mutable, non-growable series.
• flex series — returns a mutable, growable series.

Size-changing ops (#flexible only)

• append — grows a #flexible string! / array! T / vector! T, or appends a tagged slot to a #flexible block!.
• insert — prepends at position 0.
• remove/last — pops the last element.

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 [b [MyBuf!] return: [i64!]] [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:

Ownership & resource forms

• defer [body] — run on function exit (LIFO).
• defer/error [body] — run only when an error is set.
• unused name — declare an intentionally unused binding.

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: Cannot assign void return value to variable 'x'
BORROW CHECKER ERROR: 's1' used after move
CLI ERROR: Unknown option: --bogus

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.

The authoritative list lives in lib/runtime.rcl. See the error-handling section of the guide for usage.