Docs

Modules & Standard Library

Module System

Eta organises code into modules. Every top-level source file must contain one or more (module …) forms. The module system supports exports, imports with filtering, and incremental REPL execution.

Key sources: module_linker.h · expander.h · driver.h

Module Syntax

(module <name>
  (export <id> ...)           ;; names visible to importers
  (import <module-name>)      ;; import all exported names
  (import (only <mod> <id> ...))
  (import (except <mod> <id> ...))
  (import (rename <mod> (<old> <new>) ...))
  (begin
    (define ...)
    (defun ...)
    ...))

Example:

(module geometry
  (export area circumference)
  (import std.math)
  (begin
    (defun area (r) (* pi (* r r)))
    (defun circumference (r) (* 2 pi r))))

Module Linker Phases

The ModuleLinker resolves inter-module dependencies in two passes:

flowchart LR subgraph "Pass 1: Index" SCAN["Scan all (module …) forms"] SCAN --> DEF["Collect define names"] SCAN --> EXP["Collect export names"] SCAN --> IMP["Queue import specs"] end subgraph "Pass 2: Link" RES["Resolve imports"] RES --> FILT["Apply only / except / rename"] FILT --> VIS["Populate visible set\n(defined ∪ imported)"] end SCAN --> RES

Pass 1 — `index_modules()`

For each (module name ...) form:

Create a ModuleTable entry with the module name
Scan the body for define / defun forms ? populate defined
Scan (export …) ? populate exports
Queue (import …) clauses as PendingImports

Errors detected: DuplicateModule

Pass 2 — `link()`

For each queued PendingImport:

Look up the source module’s exports set
Apply the import filter:

Filter	Effect
`(import mod)`	Import all exported names
`(import (only mod a b))`	Import only `a` and `b`
`(import (except mod x))`	Import all except `x`
`(import (rename mod (old new)))`	Import `old` as `new`

Check for conflicts with already-visible names
Add resolved names to the target module’s visible set
Record provenance in import_origins for diagnostics

Errors detected: UnknownModule, CircularDependency, ConflictingImport, NameNotExported, ExportOfUnknownName

Incremental Execution (REPL)

The Driver supports incremental execution for the REPL:

sequenceDiagram participant User participant Driver participant Linker participant SA as SemanticAnalyzer participant VM User->>Driver: run_source("(module a ...)") Driver->>Driver: Lex + Parse + Expand Driver->>Driver: Append to accumulated_forms_ Driver->>Linker: index_modules(ALL accumulated forms) Driver->>Linker: link() Driver->>SA: analyze_all(ALL forms) Driver->>VM: Execute only NEW modules Driver-->>User: result User->>Driver: run_source("(module b (import a) ...)") Driver->>Driver: Lex + Parse + Expand Driver->>Driver: Append to accumulated_forms_ Driver->>Linker: index_modules(ALL accumulated forms) Note over Linker: Re-indexes everything<br/>(linker is non-incremental) Driver->>Linker: link() Driver->>SA: analyze_all(ALL forms) Driver->>VM: Execute only module b (a already executed) Driver-->>User: result

Key properties:

All accumulated forms are re-fed to the linker each time (it is stateless between calls)
The executed_modules_ set tracks which modules have already run, so they are not re-executed
VM globals_ persist across calls, so definitions from module a are visible when module b runs
Builtins are re-installed each cycle (their heap objects may have been GC’d)

Stdlib Loading

Eta does not auto-load a prelude module. Import stdlib modules explicitly in each module or REPL submission.

Standard Library Reference

All standard library modules are defined in the stdlib/std/ directory. Use explicit imports for each module you depend on:

(import std.core)
(import std.math)
(import std.io)

`std.core` — Core Combinators & Predicates

(import std.core)

Function	Signature	Description
`atom?`	`(x) ? bool`	True if `x` is not a pair
`void`	`() ? '()`	Returns the empty list
`identity`	`(x) ? x`	Identity function
`compose`	`(f g) ? (λ (x) (f (g x)))`	Function composition
`flip`	`(f) ? (λ (a b) (f b a))`	Swap arguments
`constantly`	`(v) ? (λ args v)`	Always returns `v`
`negate`	`(pred) ? (λ (x) (not (pred x)))`	Negate a predicate
`cadr`	`(xs) ? element`	Second element
`caddr`	`(xs) ? element`	Third element
`caar`, `cdar`, `caddar`	`(xs) ? element`	Nested accessors
`last`	`(xs) ? element`	Last element of a list
`list?`	`(x) ? bool`	True if `x` is a proper list
`iota`	`(count [start [step]]) ? list`	Generate a sequence
`assoc-ref`	`(key alist) ? value \| #f`	Association list lookup

`std.math` — Mathematical Functions

(import std.math)

Binding	Type	Description
`pi`	constant	3.141592653589793
`e`	constant	2.718281828459045
`square`	`(x) ? x→`	Square
`cube`	`(x) ? x→`	Cube
`even?`	`(n) ? bool`	Even predicate
`odd?`	`(n) ? bool`	Odd predicate
`sign`	`(x) ? -1 \| 0 \| 1`	Sign function
`clamp`	`(x lo hi) ? number`	Clamp to range
`quotient`	`(a b) ? number`	Integer quotient
`gcd`	`(a b) ? number`	Greatest common divisor
`lcm`	`(a b) ? number`	Least common multiple
`expt`	`(base exp) ? number`	Exponentiation (fast power)
`sum`	`(xs) ? number`	Sum of a list
`product`	`(xs) ? number`	Product of a list

`std.aad` — AD Helpers and Gradient Checks

(import std.aad)

Function	Signature	Description
`grad`	`(f vals) ? (list primal grad-vector)`	Run tape-based reverse-mode AD on scalar `f`
`ad-abs`	`(x) ? number`	Policy-aware absolute value
`ad-max` / `ad-min`	`(a b ...) ? number`	Policy-aware piecewise max/min
`ad-relu`	`(x) ? number`	`max(0, x)` built on AD-safe primitives
`ad-clamp`	`(x lo hi) ? number`	Policy-aware clamp
`softplus`	`(x beta) ? number`	Smooth approximation to `max(0, x)`
`smooth-abs`	`(x epsilon) ? number`	Smooth absolute value (`epsilon` required)
`smooth-clamp`	`(x lo hi beta) ? number`	Smooth clamp approximation
`check-grad`	`(f vals [rtol [atol [step-scale]]]) ? bool`	Compare AAD gradient vs finite differences
`check-grad-report`	`(f vals [rtol [atol [step-scale]]]) ? vector`	Detailed gradient-check report
`with-checkpoint`	`(thunk) ? result`	Checkpoint API surface for AD blocks

`std.io` — Input/Output Utilities

(import std.io)

Function	Signature	Description
`print`	`(x)`	Display `x`
`println`	`(x)`	Display `x` followed by newline
`eprintln`	`(x)`	Print to stderr
`display-to-string`	`(x) ? string`	Render value to string via string port
`read-line`	`([port]) ? string \| #f`	Read a line (returns `#f` at EOF)
`with-output-to-port`	`(port thunk) ? result`	Redirect stdout for `thunk`
`with-input-from-port`	`(port thunk) ? result`	Redirect stdin for `thunk`
`with-error-to-port`	`(port thunk) ? result`	Redirect stderr for `thunk`

`std.collections` — Higher-Order List & Vector Operations

(import std.collections)

Function	Signature	Description
`map*`	`(f xs) ? list`	Map (single-list)
`map2`	`(f xs ys) ? list`	Pairwise map over two lists (truncates to shorter list)
`zip-with`	`(f xs ys) ? list`	Alias for `map2`
`map-indexed`	`(f xs) ? list`	Map with zero-based index (calls `f` with `i` and `x`)
`filter`	`(pred xs) ? list`	Keep elements matching `pred`
`foldl`	`(f acc xs) ? value`	Left fold
`foldr`	`(f init xs) ? value`	Right fold
`reduce`	`(f xs) ? value`	Fold without initial accumulator
`any?`	`(pred xs) ? bool`	True if any element matches
`every?`	`(pred xs) ? bool`	True if all elements match
`count`	`(pred xs) ? number`	Count matching elements
`sum-by`	`(f xs) ? number`	Sum transformed elements
`zip`	`(xs ys) ? list`	Zip two lists into pairs
`pairwise`	`(xs) ? list`	Adjacent element pairs as dotted pairs
`take`	`(n xs) ? list`	First `n` elements
`drop`	`(n xs) ? list`	Skip first `n` elements
`flatten`	`(xss) ? list`	Flatten one level of nesting
`range`	`(start end) ? list`	Integer range `[start, end)`
`sort`	`(less? xs) ? list`	Merge sort with custom comparator
`vector-map`	`(f v) ? vector`	Map over a vector
`vector-for-each`	`(f v)`	Side-effecting vector traversal
`vector-foldl`	`(f acc v) ? value`	Left fold over a vector
`vector-foldr`	`(f init v) ? value`	Right fold over a vector
`vector->list`	`(v) ? list`	Convert vector to list
`list->vector`	`(xs) ? vector`	Convert list to vector

`std.hashmap` — Hash Map Helpers

(import std.hashmap)

Runtime primitives:

Function	Signature	Description
`hash-map`	`(k1 v1 k2 v2 ...) -> map`	Construct a map from key/value pairs
`make-hash-map`	`() -> map`	Empty hash map
`hash-map?`	`(x) -> bool`	Hash map predicate
`hash-map-ref`	`(m k [default]) -> value`	Lookup with optional default
`hash-map-assoc`	`(m k v) -> map`	Return a map with `k` bound to `v`
`hash-map-dissoc`	`(m k) -> map`	Return a map without `k`
`hash-map-keys`	`(m) -> list`	Keys as a list
`hash-map-values`	`(m) -> list`	Values as a list
`hash-map-size`	`(m) -> int`	Number of entries
`hash-map->list`	`(m) -> list`	Association-list form `((k . v) ...)`
`list->hash-map`	`(xs) -> map`	Build from alist or flat key/value list
`hash-map-fold`	`(f init m) -> value`	Fold with `(f acc k v)`
`hash`	`(x) -> int`	Generic hash function

Convenience wrappers:

hash-map-empty?, hash-map-contains?, hash-map-update, hash-map-update-with-default, hash-map-merge, hash-map-merge-with, hash-map-map, hash-map-filter, hash-map->alist, alist->hash-map.

`std.hashset` — Hash Set Helpers

(import std.hashset)

Runtime primitives:

Function	Signature	Description
`make-hash-set`	`() -> set`	Empty hash set
`hash-set`	`(x1 x2 ...) -> set`	Construct a set from values
`hash-set?`	`(x) -> bool`	Hash set predicate
`hash-set-add`	`(s x) -> set`	Add an element
`hash-set-remove`	`(s x) -> set`	Remove an element
`hash-set-contains?`	`(s x) -> bool`	Membership check
`hash-set-union`	`(a b) -> set`	Union
`hash-set-intersect`	`(a b) -> set`	Intersection
`hash-set-diff`	`(a b) -> set`	Difference `a \ b`
`hash-set->list`	`(s) -> list`	Set elements as a list
`list->hash-set`	`(xs) -> set`	Build from list

Convenience wrappers:

hash-set-empty?, hash-set-size, hash-set-subset?, hash-set-equal?.

`std.atom` - Atomic Mutable References (opt-in)

(import std.atom)

Provides single-cell mutable references with CAS semantics.

Function	Signature	Description
`atom:new`	`(value) -> atom`	Create a new atom.
`atom:atom?`	`(x) -> bool`	Atom predicate.
`atom:deref`	`(a) -> value`	Read current value.
`atom:reset!`	`(a value) -> value`	Replace current value and return it.
`atom:swap!`	`(a fn arg ...) -> value`	Compute and install a new value via CAS retry.
`atom:compare-and-set!`	`(a old new) -> bool`	CAS from `old` to `new` using raw `LispVal` equality.

Alias exports are also provided for explicit opt-in imports: atom, atom?, deref, reset!, swap!, compare-and-set!.

For full details and collision guidance with std.core:atom?, see Atom.

`std.regex` — Regular Expressions

(import std.regex)

Regex helpers backed by C++ std::regex (ECMAScript syntax). The API accepts either compiled regex handles or string patterns.

Function	Signature	Description
`regex:compile`	`(pattern . flags) -> regex`	Compile a reusable regex object
`regex:match?`	`(regex-or-pattern input) -> bool`	Full-string match
`regex:search`	`(regex-or-pattern input [start]) -> match-or-#f`	First match with offsets/captures
`regex:find-all`	`(regex-or-pattern input) -> list`	All matches
`regex:replace`	`(regex-or-pattern input replacement) -> string`	Replacement string form (`$1`, `$<name>`, etc.)
`regex:replace-fn`	`(regex-or-pattern input fn) -> string`	Callback replacement form
`regex:split`	`(regex-or-pattern input) -> vector`	Regex delimiter split
`regex:quote`	`(s) -> string`	Escape regex metacharacters
`regex:match-groups-hash`	`(match) -> hash-map`	Named capture groups as a hash map of `name -> (start . end)`

For the full reference and performance notes, see Regex.

`std.test` — Lightweight Test Framework

(import std.test)

Uses define-record-type for test-case, test-group, test-result, group-result, and test-summary.

Function	Description
`make-test`	`(name thunk)` — create a test case
`make-group`	`(name children)` — create a test group
`run`	`(node) ? result` — run a test or group
`summary`	`(result) ? test-summary` — count pass/fail
`print-summary`	`(summary)` — display totals
`assert-true`	`(x [msg])` — assert truthy
`assert-false`	`(x [msg])` — assert falsy
`assert-equal`	`(expected actual [msg])` — assert equality
`assert-not-equal`	`(a b [msg])` — assert inequality
`assert-approx-equal`	`(expected actual tol [msg])` → assert numeric closeness within `tol`
`print-tap`	`(result)` — emit TAP-formatted output for CI consumers
`print-junit`	`(result [port])` — emit JUnit XML for CI consumers

Example:

(module my-tests
  (import std.test)
  (import std.math)
  (import std.io)
  (begin
    (define suite
      (make-group "math"
        (list
          (make-test "square"
            (lambda () (assert-equal 25 (square 5))))
          (make-test "gcd"
            (lambda () (assert-equal 6 (gcd 12 18)))))))

    (let ((result (run suite)))
      (print-summary (summary result)))))

Output:

2 tests, 2 passed, 0 failed

`std.logic` — Relational / miniKanren-style Programming

(import std.logic)

Provides logic variables, unification, search combinators, and a miniKanren-flavoured surface (fresh, conde, conj, disj, run*, run-n, run1, ==, ==o, succeedo, failo, copy-term*, naf, succeeds?, findall, membero, condu, conda, onceo, logic-throw, logic-catch).

Full documentation: Logic Programming

`std.clp` — Constraint Logic Programming over Integers / Finite Domains

(import std.clp)

Domain constructors ((z lo hi), (fd v1 v2 ...)), constraint posting (clp:= clp:+ clp:plus-offset clp:abs clp:* clp:sum clp:scalar-product clp:element clp:<= clp:>= clp:<>), clp:all-different, search (clp:solve, clp:labeling), and optimisation (clp:minimize, clp:maximize). Shares the unified trail and the 'clp.prop async propagation queue with std.clpb and std.clpr.

Full documentation: Constraint Logic Programming (Z/FD)

`std.clpb` — Boolean Constraint Logic (opt-in)

(import std.clpb)

Boolean variables and constraints (clp:boolean, clp:and, clp:or, clp:xor, clp:imp, clp:eq, clp:not, clp:card) plus search and queries (clp:labeling-b, clp:sat?, clp:taut?). Requires explicit import.

Full documentation: Boolean Constraints (CLP(B))

`std.clpr` — Real-Interval Constraint Logic (opt-in)

(import std.clpr)

Real-domain constructors and accessors, linear arithmetic (clp:r+, clp:r-, clp:r*scalar), constraint posting (clp:r=, clp:r<=, clp:r<, clp:r>=, clp:r>), simplex/QP optimisation (clp:r-minimize, clp:r-maximize, clp:rq-minimize, clp:rq-maximize), and queries (clp:r-bounds, clp:r-feasible?). Requires explicit import.

`std.db` — Procedural Datalog over Fact Tables

(import std.db)

Defines persistent relations as defrel, asserts/retracts ground facts (assert, retract, retract-all), queries via call-rel / call-rel?, builds per-argument indexes (index-rel!), and tabulates recursive rules (tabled).

Full documentation: Datalog Database

`std.causal` — DAGs, Do-Calculus, and Causal Estimation

(import std.causal)

DAG utilities (dag:nodes, dag:parents, …), do-calculus identification (do:identify, do:identify-details, observed variants), and numeric estimators (do:estimate-effect, do:conditional-mean, do:marginal-prob).

Full documentation: Causal Inference

ADMG-specific helpers (districts and latent projection) are in a separate submodule:

(import std.causal.admg)

Generalized adjustment/front-door/IV helpers are available in:

(import std.causal.adjustment)

Estimation backends (g-formula, IPW, AIPW, TMLE, bootstrap CI, sensitivity metrics) are available in:

(import std.causal.estimate)

Graph rendering helpers (DOT, Mermaid, LaTeX, literal validation) are available in:

(import std.causal.render)

`std.stats` — Statistics & Linear Models

(import std.stats)

Descriptive statistics, distribution quantiles, bivariate measures, OLS (returns a %ols-result record with backward-compatible nine-element list accessors), multivariate regression, and column-wise operations over lists, vectors, or fact-table columns. Eigen-backed.

Full documentation: Statistics

`std.time` - Wall-Clock and Monotonic Time

(import std.time)

Time helpers for wall-clock timestamps, monotonic elapsed measurement, sleep/delay, UTC/local calendar breakdown, and ISO-8601 formatting.

Function	Signature	Description
`time:now-ms`	`() -> int`	Current Unix epoch in milliseconds
`time:now-us`	`() -> int`	Current Unix epoch in microseconds
`time:now-ns`	`() -> int`	Current Unix epoch in nanoseconds
`time:monotonic-ms`	`() -> int`	Monotonic milliseconds (origin unspecified)
`time:sleep-ms`	`(ms) -> '()`	Sleep current thread for `ms` milliseconds
`time:utc-parts`	`(epoch-ms) -> alist`	Date/time parts with `offset-minutes = 0`
`time:local-parts`	`(epoch-ms) -> alist`	Local date/time parts with timezone offset
`time:format-iso8601-utc`	`(epoch-ms) -> string`	`YYYY-MM-DDTHH:MM:SSZ`
`time:format-iso8601-local`	`(epoch-ms) -> string`	`YYYY-MM-DDTHH:MM:SS+/-HH:MM`
`time:elapsed-ms`	`(start end) -> int`	Non-negative monotonic delta

Example:

(let ((t0 (time:monotonic-ms)))
  (time:sleep-ms 25)
  (println (time:elapsed-ms t0 (time:monotonic-ms))))

`std.fs` — Filesystem and Path Primitives

(import std.fs)

Path manipulation, directory enumeration, file metadata, and temp-file allocation backed by std::filesystem. Requires explicit import.

Function	Signature	Description
`fs:file-exists?`	`(path) -> bool`	Path resolves on disk
`fs:directory?`	`(path) -> bool`	Path is a directory
`fs:delete-file`	`(path) -> '()`	Remove a regular file
`fs:make-directory`	`(path) -> '()`	Create a directory (idempotent)
`fs:list-directory`	`(path) -> list`	Sorted entry names
`fs:path-join`	`(seg ...) -> string`	Variadic path build
`fs:path-split`	`(path) -> list`	Inverse of `fs:path-join`
`fs:path-normalize`	`(path) -> string`	Lexical canonicalisation
`fs:temp-file`	`() -> string`	Allocate a unique temp-file path
`fs:temp-directory`	`() -> string`	Allocate a unique temp dir
`fs:file-modification-time`	`(path) -> int`	mtime in epoch ms
`fs:file-size`	`(path) -> int`	Size in bytes

Full documentation: Filesystem

`std.os` — Process / Environment Primitives

(import std.os)

Environment variables, command-line arguments, current working directory, and process exit. Requires explicit import.

Function	Signature	Description
`os:getenv`	`(name) -> string \| #f`	Lookup, `#f` if unset
`os:setenv!`	`(name value) -> '()`	Mutate process environment
`os:unsetenv!`	`(name) -> '()`	Idempotent unset
`os:environment-variables`	`() -> alist`	Sorted `("KEY" . "value")` pairs
`os:command-line-arguments`	`() -> list`	Strings passed after the script
`os:exit`	`([code]) -> never`	Terminate the process
`os:current-directory`	`() -> string`	Working directory
`os:change-directory!`	`(path) -> '()`	`chdir` equivalent

Full documentation: OS Primitives

`std.process` - Subprocess Execution (opt-in)

(import std.process)

Blocking and non-blocking subprocess support with captured stdio and pipe-backed ports that integrate with existing read-u8, write-u8, and close-port workflows.

Function	Signature	Description
`process:run`	`(program args [opts]) -> (status stdout stderr)`	Blocking run with capture/inherit/null stream options
`process:spawn`	`(program args [opts]) -> handle`	Non-blocking spawn returning a process handle
`process:wait`	`(handle [timeout-ms]) -> int or #f`	Wait for completion (`#f` on timeout)
`process:kill` / `process:terminate`	`(handle) -> bool`	Hard/soft termination
`process:pid` / `process:alive?` / `process:exit-code`	`(handle) -> ...`	Lifecycle state accessors
`process:stdin-port` / `process:stdout-port` / `process:stderr-port`	`(handle) -> port or #f`	Child stdio port access
`process:run-string`	`(program args [opts]) -> stdout`	Convenience accessor for captured stdout

Full documentation: Subprocesses

`std.freeze` - Coroutine-Style Goal Suspension (opt-in)

(import std.freeze)

Adds freeze (suspend a goal until a logic variable is bound) and dif (disequality between terms) on top of the attributed-variable substrate. Requires explicit import.

Full documentation: Freeze & Dif

`std.supervisor` — Actor Supervisor Compatibility Shim (opt-in)

(import std.supervisor)

Compatibility module that re-exports std.actor.supervisor. New actor code should import std.actor.supervisor directly for one-for-one, one-for-all, rest-for-one, child specs, and restart-intensity controls. Requires explicit import.

Full documentation: Supervisors

`std.fact_table` — Columnar Fact Tables

(import std.fact_table)

An in-memory, column-oriented store of fixed-arity rows with optional per-column hash indexes for O(1) equality lookups.

Category	Key Functions
Construction	`make-fact-table`, `fact-table?`
Mutation	`fact-table-insert!`, `fact-table-build-index!`
Query	`fact-table-query`, `fact-table-ref`, `fact-table-row-count`, `fact-table-row`
Iteration	`fact-table-for-each`, `fact-table-filter`, `fact-table-fold`
Aggregation	`fact-table-group-count`, `fact-table-group-sum`, `fact-table-group-by`, `fact-table-partition`
CSV Bridge	`fact-table-load-csv`, `fact-table-save-csv`

Full documentation: Fact Tables

`std.csv` — Native CSV Reader/Writer

(import std.csv)

Native CSV API backed by vincentlaucsb/csv-parser.

Category	Key Functions
Reader	`csv:open-reader`, `csv:reader-from-string`, `csv:columns`, `csv:read-row`, `csv:read-record`, `csv:read-typed-row`, `csv:close`
Writer	`csv:open-writer`, `csv:write-row`, `csv:write-record`, `csv:flush`, `csv:save-file`
Streaming	`csv:fold`, `csv:for-each`, `csv:collect`, `csv:load-file`

Full documentation: CSV

`std.json` — Native JSON Reader/Writer

(import std.json)

RFC 8259 JSON codec implemented in-tree (eta/core/src/eta/util/json.h, no third-party dependency). Objects decode to hash maps, arrays to vectors, numbers default to flonums (with an opt-in 'keep-integers-exact? flag for integer fidelity). Requires explicit import.

Function	Signature	Description
`json:read`	`(port [opts ...]) -> value`	Read one JSON document from an input port
`json:read-string`	`(string [opts ...]) -> value`	Parse a JSON string
`json:write`	`(value [port]) -> '()`	Write JSON to a port (default: current-output-port)
`json:write-string`	`(value) -> string`	Serialise to a string

Full documentation: JSON

Prelude Status

std.prelude is not part of the standard library contract. Import modules explicitly.

`std.torch` — libtorch Neural Network Bindings

(import std.torch)

Category	Key Functions
Tensor creation	`tensor`, `ones`, `zeros`, `randn`, `manual-seed`, `arange`, `linspace`, `from-list`
Arithmetic	`t+`, `t-`, `t*`, `t/`, `matmul`, `dot`
Linear algebra/sampling	`cholesky`, `mvnormal`
Unary ops	`neg`, `tabs`, `texp`, `tlog`, `tsqrt`, `relu`, `sigmoid`, `ttanh`, `softmax`
Shape	`shape`, `reshape`, `transpose`, `squeeze`, `unsqueeze`, `cat`
Reductions	`tsum`, `mean`, `tmax`, `tmin`, `argmax`, `argmin`
Conversion	`item`, `to-list`, `numel`
Autograd	`requires-grad!`, `requires-grad?`, `detach`, `backward`, `grad`, `zero-grad!`
NN layers	`linear`, `sequential`, `relu-layer`, `sigmoid-layer`, `dropout`, `forward`, `parameters`, `train!`, `eval!`
Loss functions	`mse-loss`, `l1-loss`, `cross-entropy-loss`
Optimizers	`sgd`, `adam`, `step!`, `optim-zero-grad!`
Device	`gpu-available?`, `gpu-count`, `device`, `to-device`, `to-gpu`, `to-cpu`, `nn-to-device`
Helpers	`train-step!` — one-call training step (zero-grad ? forward ? loss ? backward ? step)

Full documentation: Neural Networks with libtorch

`std.actor` — PID-based Actors

(import std.actor)

std.actor is the primary local concurrency API.

Function	Signature	Description
`self`	`(self)`	Return current actor PID
`spawn`	`(spawn thunk)`	Spawn one local actor
`send`	`(send pid payload)`	Send one message to PID or registered name
`receive`	`(receive cases [timeout-ms [timeout-thunk]])`	Selective receive with optional timeout
`receive-after`	`(receive-after timeout-ms)`	Receive one message or `#f` on timeout
`monitor`	`(monitor pid)`	Register process monitor and return monitor ref
`demonitor`	`(demonitor ref [flush?])`	Remove monitor; optional flush removes queued `DOWN`
`link` / `unlink`	`(link pid)` / `(unlink pid)`	Link or unlink actor exits
`trap-exit!`	`(trap-exit! enabled?)`	Toggle trapped linked exits as mailbox messages
`register` / `whereis`	`(register name pid)` / `(whereis name)`	Local name registry
`process-info`	`(process-info pid [key])`	Process metadata/introspection

Related modules: std.actor.supervisor, std.actor.gen_server, and std.actor.node.

`std.net` — Networking Transport

(import std.net)

std.net is the explicit NNG transport layer. Use it for socket-level communication patterns and endpoint management.

High-level helpers

Function	Signature	Description
`with-socket`	`(with-socket type thunk)`	Create a socket, run `(thunk sock)`, close via `dynamic-wind` — safe even on exceptions
`request-reply`	`(request-reply endpoint message)`	Open a REQ socket, dial, send, receive exactly one reply, close
`worker-pool`	`(worker-pool module-path tasks)`	Compatibility helper over socket-based child workers
`pub-sub`	`(pub-sub endpoint topics handler)`	Connect a SUB socket, subscribe to `topics`, call `handler` on each message
`survey`	`(survey endpoint question timeout-ms)`	Open a SURVEYOR socket, broadcast `question`, collect all responses before deadline

Low-level nng builtins (globally available)

Primitive	Signature	Description
`nng-socket`	`(nng-socket type-sym)`	Create a socket → `'pair`, `'req`, `'rep`, `'pub`, `'sub`, `'push`, `'pull`, `'surveyor`, `'respondent`, `'bus`
`nng-listen`	`(nng-listen sock endpoint)`	Bind and listen on an endpoint
`nng-dial`	`(nng-dial sock endpoint)`	Connect to an endpoint (auto-reconnects)
`nng-close`	`(nng-close sock)`	Close the socket (idempotent; also called by GC)
`nng-socket?`	`(nng-socket? x)`	Socket predicate
`send!`	`(send! sock value [flag])`	Serialize and send; flags: `'text`, `'noblock`, `'wait`
`recv!`	`(recv! sock [flag])`	Receive and deserialize; returns `#f` on timeout; flags: `'noblock`, `'wait`
`nng-poll`	`(nng-poll items timeout-ms)`	Poll multiple sockets; returns list of ready sockets
`nng-subscribe`	`(nng-subscribe sock topic)`	Set SUB topic filter (byte prefix)
`nng-set-option`	`(nng-set-option sock option value)`	Set socket option (`'recv-timeout`, `'send-timeout`, `'survey-time`, …)

Legacy process-spawn socket helpers (compatibility)

Primitive	Signature	Description
`spawn`	`(spawn module-path [endpoint])`	Spawn a child `etai` process; returns parent-side PAIR socket
`spawn-wait`	`(spawn-wait sock)`	Block until the child process exits; return exit code
`spawn-kill`	`(spawn-kill sock)`	Forcibly terminate the child process
`spawn-thread`	`(spawn-thread thunk)`	Run a 0-arg closure (with captured upvalues) in a fresh in-process VM thread; returns the parent-side PAIR socket
`spawn-thread-with`	`(spawn-thread-with proc args)`	In-process variant for a named procedure plus argument list
`thread-join`	`(thread-join sock)`	Wait for an in-process actor thread to finish
`thread-alive?`	`(thread-alive? sock)`	Non-blocking thread liveness check
`monitor`	`(monitor sock)`	Receive a `(down ...)` message when the peer (process or thread) exits
`current-mailbox`	`(current-mailbox)`	Child-side PAIR socket for legacy socket-mailbox workflows

Transport usage examples

;; Safe socket management
(with-socket 'req
  (lambda (sock)
    (nng-dial sock "tcp://localhost:5555")
    (send! sock '(compute 42))
    (recv! sock 'wait)))

;; One-shot synchronous RPC
(request-reply "tcp://localhost:5555" '(compute 42))

;; Subscribe to a topic stream
(pub-sub "tcp://localhost:5556"
         '("prices" "alerts")
         (lambda (msg) (println msg)))

;; Scatter-gather query
(survey "tcp://*:5557" '(status?) 1000)

Full documentation: std.actor · std.actor.node · std.net

Builtin Primitives vs. Standard Library

There are two layers of “standard” functionality:

Layer	Defined in	Mechanism
Builtins	C++ (`core_primitives.h`, `io_primitives.h`, `port_primitives.h`)	Registered as `Primitive` heap objects in fixed global slots
Standard Library	Eta (`std/*.eta`)	Regular Eta functions defined in modules

Builtins like +, cons, display are always available (they occupy global slots 0..N−1). The standard library modules build on top of builtins to provide higher-level abstractions like foldl, sort, and read-line.

LSP Integration

File: lsp_server.h

The eta_lsp executable implements the Language Server Protocol over JSON-RPC (stdio). It creates a Driver internally and runs the compilation pipeline on each textDocument/didOpen and didChange event, publishing diagnostics back to the editor.

Supported LSP features:

textDocument/publishDiagnostics — real-time error reporting
Document synchronization (full content sync)

VS Code Extension

The editors/vscode/ directory contains a VS Code extension that provides:

TextMate grammar for syntax highlighting (eta.tmLanguage.json)
Language configuration (bracket matching, comment toggling)
LSP client that launches eta_lsp as a child process

Install via the build script or manually with vsce package.

Modules & Standard Library

Module System

Module Syntax

Module Linker Phases

Pass 1 — index_modules()

Pass 2 — link()

Incremental Execution (REPL)

Stdlib Loading

Standard Library Reference

std.core — Core Combinators & Predicates

std.math — Mathematical Functions

std.aad — AD Helpers and Gradient Checks

std.io — Input/Output Utilities

std.collections — Higher-Order List & Vector Operations

std.hashmap — Hash Map Helpers

std.hashset — Hash Set Helpers

std.atom - Atomic Mutable References (opt-in)

std.regex — Regular Expressions

std.test — Lightweight Test Framework

std.logic — Relational / miniKanren-style Programming

std.clp — Constraint Logic Programming over Integers / Finite Domains

std.clpb — Boolean Constraint Logic (opt-in)

std.clpr — Real-Interval Constraint Logic (opt-in)

std.db — Procedural Datalog over Fact Tables

std.causal — DAGs, Do-Calculus, and Causal Estimation

std.stats — Statistics & Linear Models

std.time - Wall-Clock and Monotonic Time

std.fs — Filesystem and Path Primitives

std.os — Process / Environment Primitives

std.process - Subprocess Execution (opt-in)

std.freeze - Coroutine-Style Goal Suspension (opt-in)

std.supervisor — Actor Supervisor Compatibility Shim (opt-in)

std.fact_table — Columnar Fact Tables

std.csv — Native CSV Reader/Writer

std.json — Native JSON Reader/Writer