Overview
The standard library is the set of modules shipped with tape. Import one by its bare name:
tape
import io from "io";
import collections from "collections";tape finds them in stdlib/ next to the tape binary (or in ./stdlib, or
any -I path). They’re ordinary tape modules: you can read their source.
Modules
| Module | What it’s for |
|---|---|
arena | Bump allocation over memory you own, for t0 and up: over, alloc, mark, release |
io | Console output and input, streams, buffering, IoError: println, read_line, BufWriter |
fs | Files and directories: read_file, write_file, open, read_dir, mkdir_all, metadata |
bits | Bit counting, rotation, byte swapping, little- and big-endian loads and stores |
ascii | Byte classification (is_digit, is_space, …), case mapping, digit values |
bytes | Byte views without allocating: copy, fill, eq, index_of, trim, split, lines, cut |
cstr | NUL-terminated C strings at the C boundary: as_view, from_view, free |
str | Building strings: join, repeat, replace, case, padding, Builder |
fmt | Number formatting beyond "{x}": hex, binary, fixed decimals, byte sizes |
path | File paths as text: join, dirname, basename, ext, normalize |
math | Integer helpers and floating-point functions for f64 and f32: rounding, roots, trigonometry, exp/log, pow |
affine | 2D transforms (CSS’s matrix(a, b, c, d, e, f)): translate, scale, rotate, skew, compose, invert, apply |
words | Word lookup tables: a fixed list of words becomes an enum and a lookup built at compile time (gen_lookup) |
conv | Numbers to text and back, exactly: parse_i64, parse_f64, parse_f32, fmt_i64, fmt_f64, fmt_f32 |
mem | Heap memory: alloc (*u8 or MemError), alloc_or_trap, realloc, free, heap arenas, raw byte operations; live_allocs to check for leaks |
utf8 | UTF-8 text: decode, encode, validate, count, chars |
hash | Non-cryptographic hashes: fnv1a_64, wyhash, crc32, hash_i64 |
crypto | Cryptography in constant time: SHA-256/384/512, HMAC, HKDF, ChaCha20-Poly1305, AES-GCM, X25519, P-256, signature checks, a CSPRNG |
x509 | X.509 certificates for TLS: a strict DER reader, parse, host name matching, a trust store, verify_chain |
ca_roots | tape’s bundled root certificates (Mozilla’s CA set), the same on every platform: load, certs, COUNT |
tls | A TLS 1.3 client as a sans-I/O engine: you move the bytes, it does the protocol; certificate checks through x509, ALPN, KeyUpdate, leaf pinning |
collections | Containers for any element type: Vec, Map and Set (integer, string or custom keys), Deque, Heap, BitSet; Vec_i64, Map_string_i64 and others ready to use |
sort | Sorting and binary search for slices of any type: sort_i64, sort_string, binary_search_i64, generators for your own types and orders |
rand | Seedable random numbers: xoshiro256, pcg32, range_i64, next_f64, shuffle and choice |
os | Arguments, environment, exit, working directory, platform, entropy: args, env, PLATFORM |
json | JSON: parse to a Value tree, accessors, stringify compact or indented, errors with line and column, a streaming Tokenizer, gen_codec for your structs |
serial | Mark a struct once for every serialization format: @serial.skip, @serial.rename, @serial.explicit |
hot | Hot reload’s safe point: hot.poll() swaps edited components in during a tape run --hot |
vm | Scripts inside your program: contexts that decide what a script may use, host modules it calls, instances run a time slice at a time, errors as data |
regex | Regular expressions in linear time: compile, find, captures, matches, split, replace_all |
encoding | base64, base64url, hex and percent-encoding, both ways, as strings or into your buffer |
mime | Email: parse a message into parts, headers, addresses, attachments and text; compose one with draft |
charset | Text in other encodings as UTF-8: windows-1252, ISO-8859, KOI8, Shift_JIS, GBK, Big5, EUC-KR, UTF-16, UTF-7, IMAP mailbox names: lookup, decode |
time | Measuring and sleeping, dates, the user’s time zone, ISO 8601 and mail dates: now, sleep, utc_now, local_now, parse_rfc5322, format, relative, brief |
process | Starting programs with exact arguments, output to files, a pipe into stdin, timeouts, kill, exit status: command, spawn, wait_timeout |
pipe | Byte streams between programs on one machine: listen, accept and connect with timeouts, read_line |
desktop | Other programs’ windows and the screens: find, wait_for, place, set_topmost, close, screens (Windows) |
net | TCP and UDP sockets, name resolution, connect_host with Happy Eyeballs, poll, TCP streams as io streams, TLS connections and trust sets |
http | An HTTP client over http and https: get, request, headers, opt-in redirects, timeouts and limits, parse_url; a Client that keeps connections and runs many requests at once (get_all, start, wait), over HTTP/2 where the server offers it |
h2, hpack | HTTP/2 underneath http: the client side of a connection as a state machine over bytes, and its header compression |
cli | Command lines from a declarative spec: parse, flag, value, positional, usage, message |
log | Leveled log lines with timestamps: info, warn, set_level, TAPE_LOG, sinks |
color | Building and mixing colors: rgb, channels, lighten, darken, lerp, brightness |
gfx | Drawing on a pixel surface: rectangles, shapes, text, blits, clipping, pixels and checksums |
image | PNG, JPEG, WebP, BMP, HV3 and HV4 bytes to surfaces (WebP decoded only) and back: decode, encode |
text, font, fill | TrueType text on pixels: font.open, text.draw, text.measure; the outline filler underneath |
audio | Sound output: clips played once (play, load), streams written as you make samples (open, write_i16, drain), decode_wav |
wav | WAV files read without allocating: info, decode_into your buffer |
ui | Component trees in a window (run) or offscreen (headless): layout, painting, input, testing |
widgets | Ready-made components: Label, Button, TextInput, Checkbox, Slider, Image, … |
theme | The look of the widgets: light, dark, set at run time; the palette as #style constants |
tween, easing | Values over time: tweens through points with a curve per leg (from_f64, to, step, retarget), the easing curves, animating a component (ui.animated, ui.animate) |
gpu | The GPU on every platform (Metal on macOS, OpenGL 4.3 on Windows and Linux): a window or offscreen device, buffers, textures, render and compute pipelines from #shader stages, passes, reading results back |
gl | OpenGL: a window with a GL context (open, poll, present), shaders and programs with the driver’s log as an error (program, compute), check, debug messages, the GL functions under their Khronos names |
locale | The active locale for @t strings: set, get, from LANG/LC_ALL, available |
Pure and capability modules
A pure module only computes: it has no effect besides its return values and the memory you hand it (allocating memory is allowed). A capability module touches the outside world: the console, the clock, files, processes, the network, windows.
| Pure | Capability |
|---|---|
bits, ascii, cstr, str, fmt, path, mem, math, affine, words, collections, sort, rand, color, arena, utf8, hash, crypto, x509, ca_roots, tls, hpack, h2, conv, bytes, cli, json, serial, regex, encoding, charset, mime, gfx, image, font, fill, text, theme, easing, tween, wav | io, fs, os, time, process, pipe, desktop, net, http, log, ui, widgets, locale, audio, gl, gpu, hot, vm |
A pure module never imports a capability module, so code that uses only pure modules can’t do I/O. A host that embeds tape can rely on that.
Conventions
- Text is passed as
[]const u8. Astringor a literal is accepted wherever a[]const u8is expected (see Strings as byte views). A C string goes throughcstr.as_view(p)first. - Errors are enum values returned as
T or SomeError, each with a description, so"{err}"reads well. A module that passes on other modules’ errors wraps them in a tagged union (http.HttpError,net.SecureError), whosedesc()reads the same way. - Generated containers come from
@tapegenerators: the common ones are ready (collections.Vec_i64,collections.Map_string_i64); for others callcollections.gen_vec(Person)once and useVec_Person. You don’t import the modules the generated code uses. A container owns copies of its elements and is itself a managed value: it is freed when its variable goes out of scope and copied by assignment (see collections and Ownership).
Testing
Modules carry their tests in a #test region. tape test stdlib/cstr.tape
runs them in the VM and as native code and checks that both agree; see
tape test.