Reference
Exact rules and APIs to come back to. The language pages describe syntax and semantics; the API reference has one page for each of its 741 types, functions, methods, macros and keywords, generated from the documentation comments in the compiler and coil-stdlib sources. Press / to search by name.
Language
| Page | Contents |
|---|---|
| Command line | Every coil command and the flags you will use. |
| Syntax | Grammar overview: declarations, statements, expressions. |
| Type system | Inference, generics, traits, aliases, aggregates. |
| Operators | Precedence table and operand rules. |
| Arrays & Vec | Fixed [T; N] and growable Vec<T>. |
| Casts | expr as T between primitives. |
| Modules | use, mod, roots and how a path finds its file. |
| Macros | Derives, attribute macros, name!(…) macros, quote. |
| Compile-time code | Computed consts, comptime and IO grants. |
| Effects | pure fn, uses {…} and inferred effects. |
| Contracts | requires, ensures, invariants and --contracts levels. |
| Permissions | --allow-read, --allow-net and the reachability check. |
| Panics | panic and what aborts a program. |
| done | Has a coroutine finished? |
| Tests | test("…") { … } cases run by coil test. |
| coil.toml | Project manifest: roots, entry, package metadata. |
| Error codes | Stable E#### diagnostics. |
| Host embedder API | Rust closures callable from bytecode. |
| What is not built in | Where the compiler stops and userland starts. |
Prelude & primitives
In scope in every file, no use needed.
| Module | Contents | Items |
|---|---|---|
prelude | Option, Result, Vec, ranges and iteration: in scope in every file. | 10 |
prelude::ops | Operator traits (Add, Eq, Ord, Show, …): implement them to use operators on your types. | 24 |
prelude::math | Float math (sqrt, sin, ln, …) and small linear algebra (dot, cross, matmul, Matrix). Auto-imported. | 25 |
Primitive types | int, float, bool, byte, string and unit: the built-in value types. | 6 |
Keywords | Every keyword and contextual keyword, with what it does and an example. | 59 |
Compiler modules
Shipped with the compiler; import what you use.
| Module | Contents | Items |
|---|---|---|
arbitrary | Random values for property tests: Gen, the Arbitrary trait and any. | 3 |
clock | Wall-clock and monotonic time in nanoseconds, and sleeping. | 3 |
env | Command-line arguments, environment variables, working directory, exit and exec. | 9 |
ffi | Call C libraries at run time: dload, declare, invoke. | 6 |
ffi::types | Type tags that describe C argument and return types to ffi::declare. | 17 |
gc | Garbage-collector handles: Root pins, Weak references, heap size and manual collection. | 9 |
io | Files, standard streams, TCP and UDP as non-blocking streams of bytes. | 23 |
io::fs | Paths and the file system: metadata, directories, rename, copy, symlinks. | 16 |
io::net | TCP and UDP sockets. | |
io::net::tcp | TCP clients and servers: connect, listen, accept. | 8 |
io::net::udp | UDP sockets: bind, send_to, recv_from. | 5 |
macro | What a macro receives and returns: Code, Expr, TypeDecl, FnDecl and helpers. | 21 |
string | format, UTF-8 conversion and byte-offset helpers for string. | 8 |
task | Structured concurrency on one thread: scopes, tasks, timeouts and channels. | 14 |
thread | OS threads, channels, mutexes and read-write locks. | 25 |
Standard library
coil-stdlib: collections, text, numbers, blocking IO.
| Module | Contents | Items |
|---|---|---|
arith | Overflow-aware integer arithmetic: checked, wrapping, saturating and overflowing operations. | 6 |
ascii | Classify and convert single ASCII bytes: digits, letters, whitespace, case. | 13 |
bytes | Helpers for Vec<byte> buffers: search, slice, replace, pad, hex. | 20 |
cell | Ref<T>: a shared mutable cell for state that closures and tasks must see change. | 1 |
collections | Sorting and other helpers over Vec, plus the collection types in its submodules. | 5 |
collections::bitset | BitSet: a compact set of small non-negative integers. | 3 |
collections::deque | VecDeque: a double-ended queue with fast push and pop at both ends. | 1 |
collections::list | List: a singly-linked list. | 3 |
collections::map | HashMap: a hash map from keys to values. | 3 |
collections::set | HashSet: a set of unique values. | 1 |
collections::tree | TreeMap: a map that keeps its keys in sorted order. | 3 |
collections::vec | Functional helpers for Vec: map, filter, fold, chunks, windows, partition, search. | 15 |
conv | Parse numbers from text and format integers in decimal, hex or binary. | 6 |
encoding | Base64 encoding and decoding. | 2 |
fmt | Buf: a string builder for text assembled piece by piece. | 1 |
io::file | Read and write whole files in one call. | 6 |
io::sync | Blocking IO helpers: println, read_line, write_all, read_to_end. | 11 |
num | Numeric helpers: abs, min, max, clamp, round, gcd and the constants PI, E, TAU. | 19 |
path | Path: build, take apart and use file-system paths. | 1 |
random | Rng: a seeded pseudo-random number generator. | 1 |
tests | assert! and the other macros used in tests and examples. | 6 |
text | String helpers: trim, split, find, replace, join, pad, case. | 19 |