Quoin reference

Core

• ANSIA String carrying color markup, e.g. #ANSI'a [#ff6961]red[/] word'. A [...] tag
• ActAsUserListMarker mixin for classes constructible from a tagged list literal:
• ActAsUserStringMarker mixin for classes constructible from a tagged string literal:
• AmbiguousMethodErrorA multimethod send where two variants are equally specific for the arguments and
• AnsiTestReporterThe built-in terminal reporter: aligned [Suite] tags, one line per test
• ArgumentErrorA method or block invoked with the wrong number of arguments.
• ArithmeticErrorAn impossible arithmetic operation — division or modulo by zero.
• ArrayA typed, contiguous numeric column: every element is the same dtype (#float64 or #int64), held in one packed buffer rather than exploded into per-element values. The layout is Apache Arrow's non-nullable primitive format, so extensions (numpy, databases) read the same bytes with zero conversion.
• AsyncStructured concurrency over the task scheduler: run blocks as concurrent tasks whose I/O overlaps (gather:), park without blocking other tasks (sleep:), and put a deadline on anything (timeout:do:). See docs/internal/ASYNC_ARCH.md.
• Base64Base64 encoding between Bytes and text — the standard alphabet, with = padding.
• BigDecimalAn exact base-10 decimal number with up to 28 significant digits -- for money and other quantities where binary floating point drifts. Construct with BigDecimal.of: (a String or an Integer; deliberately not a Double, which would already carry rounding error). Arithmetic never mixes silently: a non-BigDecimal operand is 'message not understood'.
• BigIntegerAn arbitrary-precision integer. Construct explicitly with BigInteger.of: (a decimal String or an Integer); arithmetic never mixes silently -- a plain Integer operand is 'message not understood', so convert both sides first. Division truncates toward zero, like Integer.
• BlockA closure: code plus its captured environment. Written as a literal { ... }, with parameters as { |x y| ... }. Run one with value / value: / valueWithArgs:, loop with whileDo:, handle errors with catch:. Inside a block, ^ returns from the block itself and ^^ returns from the enclosing method.
• BooleanThe two truth values, written as the literals true and false. Control flow in Quoin is messaging a Boolean: if:/else: take blocks and run the matching one, so there is no statement-level if.
• BuiltinAssertionsThe assertion vocabulary test methods write against (isTrue:,
• ByteStreamA buffered binary stream — the one reading/writing surface over every conduit: files ([IO]File.byteStream / create: / append:), sockets (TcpSocket#byteStream or ByteStream.over:), and stdin ([IO]Stdin.byteStream).
• BytesImmutable binary data — a contiguous run of raw octets. Text crosses the boundary explicitly: '…'.asBytes encodes, asString decodes (UTF-8). Build from integers with Bytes.of:, slice with from:to:, concatenate with +. An opaque blob (an image, a gzip stream) belongs here; a typed numeric column belongs in Array.
• CSVParse and generate CSV, RFC 4180 tabular text.
• CaseA case/switch expression: match a subject against a series of conditions
• ChannelA CSP-style channel for passing values between tasks. Channel.new is an unbuffered rendezvous -- a send parks until a receiver takes the value; Channel.buffered:n queues up to n values before sends park. close ends the conversation: further sends raise, receives drain the buffer then answer nil, and each: ends.
• ClassThe class of classes: Integer, List, and every user-defined class are instances of Class. Define one with Name <- { ... } (a subclass with Parent <- Name <- { ... }), reopen one with Name <-- { ... }, and reflect with name / parent / class. Note that on classes == is the SUBTYPE test, and Pattern ~ x is instance-of.
• ClassErrorA class-structural violation: extending a sealed! class, instantiating an
• DNSName resolution — the system resolver (getaddrinfo, the same one TcpSocket.connect: uses), exposed. Lookups run on the blocking pool and park the task, not the scheduler.
• DateA civil calendar date — year, month, day; no time of day, no time zone. The type for birthdays, deadlines, and schedules, where "March 3rd" means March 3rd regardless of zone.
• DateTimeA zone-aware date and time: an instant plus its time zone, so calendar components, DST, and offsets all come out right.
• DoubleA 64-bit IEEE-754 floating-point number -- the type of literals like 3.14. Arithmetic with either an Integer or a Double operand happens in floating point and yields a Double. Whole values print without a decimal point (4.0.s is '4').
• DurationA signed, fixed length of time, with nanosecond precision.
• ErrorThe root of every throwable error: a human-readable message plus an optional
• ExtensionA connected out-of-process extension: a subprocess speaking the Quoin extension wire, providing classes and operations to the host program. Extension.loadPackage: is the managed entry point (spawn per the package's extension.toml, install its classes under the package namespace, run its init.qn glue) -- use name:* does this for you. The handle's call:with: family is the raw op surface that package glue builds on. See docs/internal/EXT_PACKAGING.md.
• FiberA coroutine: a block that can suspend itself with Fiber.yield: -- or the ^> value sugar -- and be resumed by its caller, exchanging values both ways. Cooperative and in-task; for concurrent tasks whose I/O overlaps, use Task / Async instead.
• FiberErrorA Fiber misused: resuming a finished or failed Fiber, a Fiber resuming itself, or
• GeneratorAn iterable made from a yielding block: each ^> in the block becomes an
• HexHexadecimal encoding between Bytes and text: two hex digits per byte, lower-case on encode, either case accepted on decode.
• HttpErrorHttpError — throw a status (and optional body) from anywhere under a
• IndexErrorRaised by an out-of-bounds index (e.g. List.at:put:, Bytes.at:). The VM
• InstantA point on the monotonic clock, for measuring elapsed time.
• IntegerA 64-bit signed whole number -- the type of integer literals like 42.
• IoErrorRaised by socket/stream/file operations. kind is a symbol categorizing the
• IterateEvery collection combinator, derived from a single method: each:.
• IterateAssertionsCollection assertions layered on BuiltinAssertions; mixed into Test
• IteratorAn external, pull-style iterator (hasNext?/next) over any each:-able.
• JSONParse and generate JSON text.
• KeyValuePairOne key/value entry — what a Map yields when iterated: each: hands its block a KeyValuePair per entry, read with key and value. Build one directly with KeyValuePair.new:{ var key = …; var value = … }.
• ListThe ordered, growable sequence — Quoin's workhorse collection, written #(10 20 30).
• Log
• MapThe insertion-ordered dictionary, written #{'a': 1 'b': 2}. Any value can be a key, and iteration, printing, and serialization keep the order entries were added — a parse → generate round-trip doesn't reshuffle a document.
• MatchOne resolved regex match — what Regex.match: answers. s is the matched text, at: reads a capture group by index (1-based; 0 is the whole match) or by name, captures lists them all, and bind: destructures them into a block's parameters.
• MathA namespace of mathematical constants and free functions -- Math.sin: x where a method hung off the number would read awkwardly. Number-centric operations (abs, floor, sqrt, pow:, min:, max:) live on Integer/Double; sqrt: and pow:to: are mirrored here in free-function style. Every function accepts an Integer or a Double and returns a Double; angles are in radians.
• MessageNotUnderstoodA message sent to a receiver that has no matching method.
• MessagePackCompact binary serialization: pack: a value to Bytes, unpack: it back.
• MethodA method as an object: the reflective handle behind a selector in a class's method table. Method objects are created by the VM when classes define or extend methods; there is no public constructor.
• MixinThe base class for mixins — method bundles a class pulls in with .mix:. Define
• NameErrorReading a name bound to nothing (typo). Assigning to an undeclared local is a
• NilThe class of nil, the single 'no value' value -- what a missing Map key or a search that finds nothing returns. nil is not a Boolean and does not answer if:else:; test for it with == nil or defined? (which is false only for nil).
• NotImplementedErrorRaised by the ... placeholder statement: the code path exists but its body
• NumberRangeA numeric interval from start toward end - end-EXCLUSIVE - iterating in
• ObjectThe universal root: every value is an Object, and every class inherits from it. It carries the protocol everything shares -- identity and equality (==: / !=: / ~:), rendering (s / pp / print), reflection (class / can?: / doc / docFor: / perform:args:), and raising a value as an error (throw).
• ParallelPool machinery behind the parallel List combinators (parallelCollect: /
• ParseErrorA parse/decode failure of input data (invalid UTF-8, a malformed HTTP response
• PlanPlan — the join graph (docs/internal/CONCURRENCY_ARCH.md §13.5).
• ProcessErrorA subprocess failed its check: nonzero exit (or death by signal) where success was
• RandomAccessFilePositioned reads over a file — pread-style, no cursor: every readAt:count: names its own offset, so reads are independent and there is no hidden position state. This is the substrate for random-access FORMATS (zip's central directory lives at the end of the file), where a sequential ByteStream is the wrong shape. Read-only. Together with size, this is the informal random-access read protocol — Bytes speaks it too (core/17-zip.qn), so code written against it reads a file or a byte buffer alike.
• RegexA compiled regular expression -- the type of #/pattern/ literals. Match with ~, split with split:, substitute via String.replace:with:. Patterns use Rust's regex syntax.
• RuntimeThe running program's own runtime: command-line arguments, process exit:, and the eval: family for compiling and running Quoin source at runtime.
• SetThe insertion-ordered collection of unique values, written #<1 2 3>. Adding an element that is already present is a no-op.
• SpanA mixed-unit, calendar-aware duration: years, months, weeks, days, and time units held as SEPARATE fields — "1 month" stays 1 month until it meets a date, where Date/DateTime arithmetic applies it correctly (end-of-month clamping, DST). Contrast Duration, which is a fixed length of time.
• StackErrorA recursion the VM refused before it could overflow the machine stack: a block that
• StopIterationRaised by an exhausted iterator's next (see core/02-iterate.qn).
• StringImmutable UTF-8 text -- the type of 'single-quoted' literals (a double quote starts a comment in Quoin, so strings are single-quoted). Position-based operations (length, index:, insert:at:) count characters, not bytes. Strings concatenate with +, format with %, and interpolate with .mod; every operation returns a new String.
• StringStreamA text stream: the UTF-8 view of a byte conduit, usually obtained from [IO]File#stringStream, a socket's stringStream, or [IO]Stdin.
• SymbolAn interned identifier -- the type of #name literals (#'quoted form' for names with spaces or punctuation). Two symbols with the same name are the same object, so comparing them is a cheap identity check. Symbols name things -- selectors, classes, keys -- where a String would carry text.
• TOMLParse and generate TOML, the config-file format.
• TaskA detached concurrent task -- the fire-and-forget primitive beneath the structured Async.gather:. Task.spawn: starts one and answers a handle for observing and controlling it: join for the result, cancel for cooperative cancellation, status / done? to poll. Tasks interleave on one scheduler and their I/O overlaps. See docs/internal/ASYNC_ARCH.md.
• TcpListenerThe server side of TCP: a socket bound to a local address, accepting incoming connections.
• TcpServerA minimal concurrent TCP server. start: accepts connections in the background, handling
• TcpSocketA plaintext TCP connection.
• TermTerminal facts and markup rendering. color? answers whether styled output is on — the same detection the standard-stream writers use (a terminal, NO_COLOR unset, CLICOLOR_FORCE honored) — and width/height the console size. render: turns color markup into escape codes unconditionally (for output that bypasses the std streams); strip: turns it into plain text.
• TestOne test: a named method (declared with TestSuite#test:) that runs with
• TestAssertionResultThe record of one assertion: the verdict, the #( expected comparison
• TestReporterAbstract lifecycle interface for test output. TestRunner announces the
• TestResultImmutable summary of one Test's run: its assertion results plus
• TestRunnerDrives suites against a reporter, firing the lifecycle hooks in order;
• TestSuiteA named group of tests — the unit a test file declares. Constructing one
• TimeA wall-clock time of day — no date, no zone: the type for "the shop opens at 9:40". Arithmetic with a Duration WRAPS around midnight (a zoneless clock has nowhere else to go); until: answers the signed Duration between two clock readings within one day. It meets dates through Date#atTime:zone: and DateTime#time.
• TimeZoneAn IANA time zone (America/New_York, Asia/Tokyo, …) or UTC — the zone component of a DateTime.
• TimeoutErrorRaised by the Async.timeout:ms do:{…} deadline combinator (the bare form, no
• TimerA one-selector stopwatch: run a block, get its elapsed time.
• TimestampAn absolute instant in time: UTC wall-clock, nanosecond precision.
• TlsSocketA TLS-encrypted TCP connection, with the same read/write surface as TcpSocket.
• TypeErrorA value of the wrong type where another was required (e.g. writing a non-String
• ULIDA 128-bit sortable identifier: a 48-bit millisecond timestamp plus 80 random bits, rendered as 26 characters of Crockford base32. String order equals creation order, so ULIDs make good keys where insertion order matters. Generate with ULID.generate, parse with ULID.parse:.
• UUIDA 128-bit universally unique identifier. Generate with UUID.generateV4 (random) or UUID.generateV7 (time-ordered, so fresh IDs sort by creation time), or parse the standard hyphenated form with UUID.parse:. Renders via s as the 36-character hyphenated lowercase form.
• UnreachableErrorRaised by the !!! placeholder statement: a code path the author asserts can
• UsageErrorA command line that doesn't fit its [CLI]Spec — unknown option, missing value,
• VMThe VM's self-introspection surface: stats (counters by section), aotRefusals (which members stayed interpreted and why), and ps / psTree (a live snapshot of tasks and workers as plain data).
• ValueErrorA value of the right type but invalid content (e.g. a non-hex string to
• WebSocket
• WorkerAn isolate: a fresh VM on its own OS thread (or child process) with message lanes to its parent. Parent side: Worker.spawn:'unit.qn' answers a handle -- send: / receive exchange values, join parks until the unit finishes. Worker side, inside the spawned unit: class-side Worker.receive / Worker.send: are the mirror lanes, and Worker.worker? says which side you are on. Messages deep-copy plain data (numbers, strings, booleans, nil, Bytes, Lists, Maps); symbols, instances, and resources refuse -- and blocks cross only as a whole thread-backed message. See docs/internal/CONCURRENCY_ARCH.md.
• WorkerServiceHost a class in a dedicated worker isolate and get a PROXY whose ordinary method sends become RPC over the worker lanes: sticky state with serialized access -- an actor, effectively. Arguments and returns follow the worker data taxonomy (plain data crosses; blocks and instances refuse), errors in the hosted method raise catchably at the call site, and one call runs at a time (concurrent callers queue fairly).
• YAMLParse and generate YAML documents.

[Archive]

• [Archive]TarThe streaming reader. each: (and the whole Iterate vocabulary over it)
• [Archive]TarEntryOne archive member: metadata is plain fields; bytes pulls the content from the
• [Archive]TarWriterThe streaming writer, from [Archive]Tar.writeTo:. Members are written in call
• [Archive]ZipThe reader. Construction parses the end-of-central-directory record and the
• [Archive]ZipEntryOne archive member, from the central directory. Metadata is plain fields;
• [Archive]ZipWriterThe writer, from [Archive]Zip.writeTo:. Writing streams naturally — each

[CLI]

• [CLI]ParsedThe parse result: at: reads any declared name (option, positional, rest — a name
• [CLI]SpecThe declarative spec. Builder methods return self, so a whole tool declares in one

[Crypto]

• [Crypto]DigestOne-shot cryptographic digests (and MD5, kept with the hashes despite being broken for security use). Each method hashes a String's UTF-8 bytes or a Bytes value and answers the raw digest as Bytes — toHex for the usual text form, Base64.encode: for wire formats.
• [Crypto]HmacKeyed message authentication (HMAC) over the SHA family. Message and key are each a String (UTF-8) or Bytes; the MAC comes back as Bytes. To CHECK a received MAC use verifySha256:message:key: — it compares in constant time, where == on the recomputed Bytes would leak timing.
• [Crypto]RandomBytes from the operating system's CSPRNG — for keys, tokens, and salts. The seedable Random class is for simulations and tests; this one is for secrets (and is deliberately not seedable).

[HTTP]

• [HTTP]BodyA request or response body — two backings, one interface. A *chunk* is just a
• [HTTP]BodyTooLargeThrown while draining a body that exceeds a caller-imposed byte ceiling — the
• [HTTP]ClientThe convenience facade: class-side helpers for the common verbs. Kept thin so a
• [HTTP]HeadTooLargeThrown while reading a request head that exceeds maxHeadBytes; the connection
• [HTTP]ParserInternal: the native HTTP/1.1 head parser under [HTTP]Client and [HTTP]Server (use std:net/http) — a thin wrapper over httparse. Programs normally use those classes, not this one.
• [HTTP]RequestThe request Builder. Convenience methods on [HTTP]Client cover the common cases;
• [HTTP]ResponseAn HTTP response: status line, headers (a list of #(name value) pairs, order- and
• [HTTP]ServerThe server: bind in init (so port works before start, including after an
• [HTTP]ServerRequestAn inbound request: the parsed head plus the body as an [HTTP]Body —
• [HTTP]ServerResponseAn outbound response under construction: status, #(name value) header pairs,

[IO]

• [IO]FileA file on the local filesystem.
• [IO]FolderA directory on the local filesystem, listed entry by entry.
• [IO]HandleOne of the process's three standard streams: stdout, stderr, or stdin.
• [IO]StdinThe process's standard input.

[Lang]

• [Lang]NodeOne node of a parsed program — every node, one class: kind answers WHICH (a Symbol: #send, #classDefinition, #stringLiteral, …), children the structural children in source order, and at:#field the kind-specific parts (#selector/#receiver/#arguments on a #send; #name/#parent/#body on a #classDefinition; #value on literals; nil for a field the kind doesn't have). Source fidelity is total: file, span (#( start end line column )), and text (the exact source slice) — which is what makes the span-based [Lang]Rewrite (qnlib/lang/ast.qn) safe. Trees are immutable views; transform by rewriting source, then parse again.
• [Lang]ParserThe Quoin parser, exposed: parse: answers the program's [Lang]Node tree — the same AST the compiler consumes, wrapped, never copied. Unparseable source throws the same catchable ParseError Runtime.eval: throws. parse:named: labels the unit, and the name rides every node's file (diagnostics built from the tree point somewhere real). See [Lang]Node, and qnlib/lang/ast.qn for the traversal vocabulary and the span-based [Lang]Rewrite.
• [Lang]RewriteAn edit list over one unit's source: collect replacements by node span,

[OS]

• [OS]EnvREAD-ONLY access to the process environment. Mutation is deliberately absent: the C environment is process-global state that other threads (workers, the blocking I/O pool) may be reading concurrently, so setting variables would be a soundness hazard. Listings are sorted by name, and entries that are not valid UTF-8 are skipped rather than mangled.
• [OS]PathPurely LEXICAL path manipulation over Strings. Nothing here touches the filesystem -- no stat, no symlink resolution, no requirement that a path exist -- which is what makes it safe on a path you are about to create. Filesystem access lives on [IO]File / [IO]Folder.
• [OS]ProcessSubprocesses, on the scheduler: run: parks the calling task (other tasks keep running) until the child exits, answering a ProcessResult; start: spawns for streaming and answers this handle — read stdout/stderr like a socket, write with writeStdin:/closeStdin, wait/kill/terminate it. The command is a List (program + arguments) — there is NO shell, so nothing splits, globs, or injects. An undetached child dies with its handle (and a cancelled run: kills its child); detach opts out.
• [OS]ProcessResultWhat a one-shot [OS]Process.run: answers: the child's complete output and how it

[Test]

• [Test]MainEntry point for qn test. The runner synthesizes use test, a glob of the caller's

[Web]

• [Web]AppThe framework core: routing DSL, middleware onion, render conventions, and error
• [Web]PoolMulti-core request execution over worker isolates — the pool behind
• [Web]Response[Web]Response — the response handlers build: an [HTTP]ServerResponse with the
• [Web]RouteOne compiled path pattern: static segments, ':name' (captures exactly one segment,
• [Web]RouterPer-verb route tables with most-specific-wins dispatch. The router is pure
• [Web]UrlThe URL percent codec: component encoding/decoding plus query- and form-string