Glossary¶

Terms used throughout the Kaappi documentation.

Alist¶

Association list. A list of pairs where each pair maps a key to a value. Used throughout Kaappi's ecosystem for JSON objects, HTTP headers, query parameters, and configuration.

'(("name" . "Alice") ("age" . 30))

Look up values with assoc:

(cdr (assoc "name" '(("name" . "Alice"))))  ;=> "Alice"

Bignum¶

An arbitrary-precision integer. When a fixnum operation would overflow 63 bits, the result is automatically promoted to a bignum. Bignums can represent any integer, limited only by available memory.

(expt 2 100)  ;=> 1267650600228229401496703205376

Bytecode¶

The intermediate representation produced by the compiler. Kaappi uses a register-based bytecode format. Bytecode is executed by the VM or compiled to native code by the LLVM native backend.

Call/cc¶

Short for call-with-current-continuation. Captures the current continuation and passes it to a procedure. The most powerful control flow primitive in Scheme — enables coroutines, exceptions, backtracking, and more. See also call/ec.

Call/ec¶

Short for call-with-escape-continuation. Like call/cc but the continuation can only be used during the dynamic extent of the call. Much cheaper than call/cc because it doesn't copy the stack. Use call/ec for non-local exits (early return, loop break).

(call/ec (lambda (exit)
  (for-each (lambda (x) (when (< x 0) (exit x)))
            '(1 2 -3 4))))
;=> -3

Channel¶

A communication primitive for fibers: first-in-first-out message passing between green threads — and, when handed through a thread thunk, between OS threads. Channels may be bounded to a capacity (sends then block while full) and closed to signal end-of-stream.

(define ch (make-channel))
(spawn (lambda () (channel-send ch 42)))
(channel-receive ch)  ;=> 42

Compiler¶

The stage that transforms expanded S-expressions into bytecode. Kaappi's compiler handles lexical scoping, closure capture, tail call optimization, and pattern matching for syntax forms.

Continuation¶

The "rest of the computation" at any point in a program. When you call call/cc, the current continuation is packaged as a procedure that, when invoked, resumes execution from that point. Continuations are a fundamental concept in Scheme that enable advanced control flow.

Diagnostic code¶

The stable KP identifier attached to every diagnostic Kaappi reports — KP1xxx read, KP2xxx compile, KP3xxx runtime, KP4xxx lint, KP9xxx internal. A code never changes meaning between releases, so tooling and guard clauses can dispatch on it (via error-object-code) where message text would be unstable. kaappi explain KP3001 describes any code from the command line; the Diagnostic Reference lists them all.

Expander¶

The macro expansion stage. Transforms syntax-rules macros into core forms before compilation. Kaappi uses hygienic macro expansion, which prevents accidental variable capture.

Fiber¶

A lightweight, cooperatively scheduled green thread. Fibers run within a single OS thread and communicate via channels. Much cheaper to create than OS threads.

(import (kaappi fibers))
(define ch (make-channel))
(spawn (lambda () (channel-send ch "hello")))
(channel-receive ch)  ;=> "hello"

Fixnum¶

A 63-bit signed integer stored directly in a tagged value word (no heap allocation). Fixnums are the fastest numeric type. Arithmetic that overflows is automatically promoted to a bignum.

Flonum¶

An IEEE 754 double-precision floating-point number. Since v0.6.0, flonums are packed directly into the value word via NaN-boxing, eliminating heap allocation.

3.14159        ;; flonum
(inexact 1/3)  ;=> 0.3333333333333333

GC¶

Garbage collector. Kaappi uses a mark-and-sweep collector that traces live objects from roots (stack, globals) and frees unreachable memory.

Hygienic macros¶

Macro expansion that preserves lexical scoping — variables introduced by a macro don't accidentally capture or shadow user variables. Kaappi implements this via syntax-rules as specified in R7RS.

LLVM native backend¶

Ahead-of-time native compiler. Compiles Scheme programs to native executables via LLVM IR using kaappi compile. Handles closures, tail calls, continuations, and the full R7RS feature set. Operations not yet covered fall back to the bytecode interpreter automatically.

NaN-boxing¶

A value representation technique that packs flonums directly into the 64-bit value word by exploiting the structure of IEEE 754 NaN values. Eliminates heap allocation for floating-point numbers.

Pair¶

The fundamental compound data type in Scheme. A pair holds two values: the car (first element) and the cdr (second element). Lists are built from chains of pairs terminated by the empty list '().

(cons 1 2)       ;=> (1 . 2)     — a dotted pair
(cons 1 '(2 3))  ;=> (1 2 3)     — a proper list

Port¶

An abstraction for I/O streams. Input ports read data, output ports write data. Files, strings, stdin, and stdout are all accessed through ports.

(call-with-input-file "data.txt" read-line)

Proper list¶

A chain of pairs where the final cdr is the empty list '(). Most list operations require proper lists.

'(1 2 3)         ;; proper list: (1 . (2 . (3 . ())))
'(1 2 . 3)       ;; improper list (dotted pair at the end)

R7RS¶

Revised^7 Report on the Algorithmic Language Scheme. The language standard that Kaappi implements. "R7RS-small" is the core language; there is also an R7RS-large effort (which Kaappi does not target).

Reactor¶

The per-OS-thread event loop behind non-blocking I/O for fibers. When a read, write, sleep, or channel wait would block, the fiber parks on the reactor — kqueue on macOS/BSD, epoll on Linux, poll_oneoff under WASI — which wakes it when the file descriptor is ready or the timer expires. The OS thread keeps running other fibers meanwhile. See Concurrency.

Reader¶

The stage that converts source text into S-expressions (Scheme data structures). Handles parentheses, quoting, numbers, strings, characters, booleans, vectors, and bytevectors.

REPL¶

Read-Eval-Print Loop. The interactive prompt (kaappi>). Type expressions, see results immediately. Kaappi's REPL supports line editing, history, tab completion, and comma commands.

SRFI¶

Scheme Requests for Implementation. Community-authored library specifications with reference implementations. Kaappi supports 85 SRFIs (11 built-in, 73 portable, plus the SRFI 261 naming convention). See SRFI Support for the full list.

Example: SRFI-1 provides extended list operations (fold, filter, partition, etc.).

Syntax-rules¶

The R7RS pattern-based macro system. Defines macros by specifying patterns and their expansions. Hygienic by design.

(define-syntax when
  (syntax-rules ()
    ((when test body ...)
     (if test (begin body ...)))))

Tagged value¶

Kaappi's internal representation of Scheme values. Each value is a 64-bit word with tag bits that encode the type (fixnum, pointer, immediate boolean/char/nil, or NaN-boxed flonum). This allows type checking without dereferencing a pointer.

Tail call¶

A function call in tail position — the last thing a function does before returning. Kaappi optimizes tail calls to reuse the current stack frame, enabling unbounded recursion without stack overflow.

(define (loop n) (loop (+ n 1)))  ;; runs forever, O(1) stack

Thottam¶

Kaappi's package manager. Installs, updates, and removes ecosystem libraries. Named after the Tamil word for "garden." See thottam docs.

Thunk¶

A zero-argument procedure. Used to delay evaluation:

(define my-thunk (lambda () (+ 1 2)))
(my-thunk)  ;=> 3

Common in error testing (test-error "name" thunk), lazy evaluation, and dynamic-wind.

VM¶

Virtual machine. Kaappi's register-based bytecode interpreter. Executes bytecode instructions, manages the call stack, and coordinates with the GC. Programs can also be compiled to native binaries via the LLVM native backend.