API reference

rate: Int
samples: List[Int]

Rendered sound: sample rate plus 16-bit signed samples (mono).

fn render(source: Text) -> Result[Sound, Text]

Synthesizes .pta source text into a Sound (formats/pta-audio.md). This is the MONO mixdown: a v4 `pan` places voices only in `render_stereo`; here every voice plays at full on the one channel (echo and everything else apply identically).

fn silence(ms: Int) -> Sound

Silence of the given length in milliseconds (at 44100 Hz).

fn tone(note: Text, ms: Int, wave: Text, volume: Int) -> Result[Sound, Text]

A single synthesized note, e.g. tone("c4", 500, "sine", 80).

fn append(a: Sound, b: Sound) -> Sound

b played after a.

fn mix(a: Sound, b: Sound) -> Sound

a and b played together (summed, clamped); length is the longer one.

fn gain(s: Sound, percent: Int) -> Sound

The sound scaled to `percent` loudness (0–200), clamped.

fn repeat(s: Sound, times: Int) -> Sound

The sound repeated `times` times.

fn adsr(s: Sound, attack_ms: Int, decay_ms: Int, sustain: Int, release_ms: Int) -> Sound

The classic ADSR envelope applied over the sound's full length: linear attack and decay to `sustain` percent, then a linear release over the final `release_ms`.

fn to_wav_bytes(sound: Sound) -> Bytes

The single export bridge for playback: RIFF/WAVE PCM bytes.

rate: Int
left: List[Int]
right: List[Int]

A stereo sound: two channels at the same rate. A v4 score places voices with `pan`; `render` stays the mono mixdown.

fn render_stereo(source: Text) -> Result[Stereo, Text]

Renders .pta source text in stereo: `pan` (version 4) attenuates the far channel per voice, so a centered score's channels both equal the mono render exactly. Accepts every version 1–4.

fn to_wav_bytes_stereo(s: Stereo) -> Bytes

The stereo export bridge: RIFF/WAVE PCM, 16-bit, two interleaved channels — `to_wav_bytes`' twin. A shorter channel is padded with silence so the encode is total.

fn encode(bytes: Bytes) -> Text

Encodes bytes as Base64 with `=` padding.

fn decode(text: Text) -> Result[Bytes, Text]

Decodes standard Base64 (with `=` padding). A character outside the alphabet, a length that is not a multiple of four, or `=` padding anywhere but as a suffix of the final group is an error. Non-canonical trailing bits (the unused low bits of the last significant character) are accepted rather than rejected — RFC 4648 §3.5 leaves this to the decoder, and `encode` always emits the canonical form, so round-trips are unaffected.

fn sha256(msg: Bytes) -> Bytes

SHA-256 of the given bytes, as a 32-byte digest.

fn sha256_hex(msg: Bytes) -> Text

SHA-256 as a lowercase hex string.

fn hmac_sha256(key: Bytes, msg: Bytes) -> Bytes

HMAC-SHA-256 (RFC 2104) of `msg` under `key`, as a 32-byte tag.

fn hmac_sha256_hex(key: Bytes, msg: Bytes) -> Text

HMAC-SHA-256 as a lowercase hex string.

fn crc32(msg: Bytes) -> Int

CRC-32 (IEEE 802.3, the zip/png checksum), computed bit by bit.

fn parse(text: Text) -> Result[List[List[Text]], Text]

Parses CSV text into rows of fields. An unterminated quoted field, or content after a field's closing quote (`"ab"c`), is an error.

fn serialize(rows: List[List[Text]]) -> Text

Serializes rows of fields into CSV text (LF line endings, trailing newline per row). A CSV line cannot distinguish an empty row `[]` from a row holding one empty field `[""]` — both write a bare newline and `parse` reads them back as a single empty field.

fn encode(bytes: Bytes) -> Text

Lowercase hex, two digits per byte (the builtin `Bytes.to_hex`).

fn decode(text: Text) -> Result[Bytes, Text]

Decodes a hex string (upper- or lowercase) to bytes. An odd length or a non-hex character is an error.

Method.Get
Method.Post
Method.Put
Method.Delete
Method.Patch
Method.Head
Method.Options

An HTTP request method.

code: Int
Status.ok(self) -> Bool — Whether the request succeeded (2xx).
Status.client_error(self) -> Bool — Whether the caller made a mistake (4xx).
Status.server_error(self) -> Bool — Whether the server failed (5xx).

An HTTP status code (200, 404, 500, …).

method: Method
url: Text
headers: Map[Text, Text]
body: Option[Bytes]
Request.with_header(self, name: Text, value: Text) -> Request — The same request carrying one more header.

An HTTP request: a method, a URL, headers, and an optional body.

status: Status
headers: Map[Text, Text]
body: Bytes
Response.ok(self) -> Bool — Whether the response succeeded (2xx).
Response.text(self) -> Option[Text] — The body decoded as UTF-8 text, if it is valid.
Response.header(self, name: Text) -> Option[Text] — The value of a header, if the response carries it.

An HTTP response: a status, headers, and a body.

fn get(url: Text) -> Request

A GET request for a URL, no headers or body — the common case.

fn post(url: Text, body: Bytes) -> Request

A POST request carrying a body.

fn request(method: Method, url: Text, headers: Map[Text, Text], body: Option[Bytes]) -> Request

A request with every field given explicitly.

fn is_success(status: Status) -> Bool

Whether a status is a success (200–299).

fn is_client_error(status: Status) -> Bool

Whether a status is a client error (400–499).

fn is_server_error(status: Status) -> Bool

Whether a status is a server error (500–599).

width: Int
height: Int
pixels: List[Int]

A rendered image: dimensions plus a flat RGB pixel list (3 ints per pixel, row-major, values 0–255).

fn canvas(width: Int, height: Int, r: Int, g: Int, b: Int) -> Image

A solid-color canvas of width x height pixels (each 1-4096), filled with the RGB color (each channel 0-255).

fn set_pixel(img: Image, x: Int, y: Int, r: Int, g: Int, b: Int) -> Image

The image with one pixel set (ignores out-of-canvas coordinates).

fn get_pixel(img: Image, x: Int, y: Int) -> Option[Tuple[Int, Int, Int]]

The (r, g, b) triple at (x, y), or None outside the canvas. A tuple since Sprint 210 `[LLM-first decision]`: two independent benchmark models both guessed `case Some((r, g, b))` — the destructuring form IS the prior; a List needed index reads.

fn draw_rect(img: Image, x: Int, y: Int, w: Int, h: Int, r: Int, g: Int, b: Int) -> Image

The image with a filled rectangle drawn on it (clipped to the canvas).

fn draw_line(img: Image, x1: Int, y1: Int, x2: Int, y2: Int, r: Int, g: Int, b: Int) -> Image

The image with a straight line drawn on it (Bresenham, clipped).

fn draw_circle(img: Image, cx: Int, cy: Int, radius: Int, r: Int, g: Int, b: Int) -> Image

The image with a filled circle drawn on it (clipped).

fn draw_ellipse(img: Image, cx: Int, cy: Int, rx: Int, ry: Int, r: Int, g: Int, b: Int) -> Image

The image with a filled ellipse drawn on it (clipped) — since v5.

fn draw_ellipse_outline(img: Image, cx: Int, cy: Int, rx: Int, ry: Int, r: Int, g: Int, b: Int) -> Image

The image with a one-pixel ellipse ring drawn on it — since v5.

fn draw_circle_outline(img: Image, cx: Int, cy: Int, radius: Int, r: Int, g: Int, b: Int) -> Image

The image with a one-pixel circle ring drawn on it — since v5.

fn draw_rect_outline(img: Image, x: Int, y: Int, w: Int, h: Int, r: Int, g: Int, b: Int) -> Image

The image with a one-pixel rectangle outline drawn on it — since v5.

fn draw_thick_line(img: Image, x1: Int, y1: Int, x2: Int, y2: Int, width: Int, r: Int, g: Int, b: Int) -> Image

The image with a line of the given stroke width (a square stamp per Bresenham step, clipped) — since v5. Width 1 is draw_line.

fn draw_polyline(img: Image, points: List[Int], r: Int, g: Int, b: Int) -> Image

The image with connected segments through the points (flat x y pairs) — since v5: a brush stroke is one op, not one line per segment.

fn to_ppm_bytes(img: Image) -> Bytes

The single export bridge for viewing: binary PPM (P6) bytes.

fn from_ppm_bytes(raw: Bytes) -> Result[Image, Text]

The inverse bridge (since Sprint 27): parses the P6 bytes to_ppm_bytes writes — and any binary PPM with maxval 255 — back into an Image, so existing pictures can enter the toolkit.

fn draw_gradient(img: Image, x: Int, y: Int, w: Int, h: Int, r1: Int, g1: Int, b1: Int, r2: Int, g2: Int, b2: Int, direction: Text) -> Image

A linear (`"vertical"`/`"horizontal"`) or `"radial"` gradient fill over the clipped region — any other direction behaves as vertical (v2 toolkit, Sprint 35).

fn draw_polygon(img: Image, points: List[Int], r: Int, g: Int, b: Int) -> Image

A filled polygon from flat x/y pairs (even-odd scanline fill, clipped). Fewer than three points paints nothing (v2 toolkit).

fn flood_fill(img: Image, x: Int, y: Int, r: Int, g: Int, b: Int) -> Image

Four-connected flood fill from (x, y) — the v3 toolkit twin.

fn draw_ops(img: Image, ops: Text) -> Result[Image, Text]

Applies a draw-section's operations (the full v4 op set, hex colors) onto an existing image — the primitive that makes layers and imported pictures composable (Sprint 38): each op line is exactly a .pti draw: line without its indentation.

fn draw_text(img: Image, x: Int, y: Int, size: Int, r: Int, g: Int, b: Int, content: Text) -> Image

Draws text in the built-in 5×7 pixel font at (x, y), scaled by whole pixels (v4 toolkit, Sprint 40). Unknown characters draw nothing; letters are case-insensitive; spaces advance the pen.

fn crop(img: Image, x: Int, y: Int, w: Int, h: Int) -> Image

The w×h region of the image starting at (x, y); out-of-canvas parts read as black.

fn flip_x(img: Image) -> Image

The image mirrored left–right.

fn flip_y(img: Image) -> Image

The image mirrored top–bottom.

fn scale(img: Image, factor: Int) -> Image

The image scaled up by a whole factor (nearest neighbor).

fn blit(dst: Image, src: Image, x: Int, y: Int) -> Image

The destination with `src` painted onto it at (x, y), clipped.

fn map_pixels(img: Image, f: fn(Int, Int, Int) -> List[Int]) -> Image

A new image with `f` applied to every pixel's r/g/b triple; results are clamped to 0–255.

fn invert(img: Image) -> Image

Every channel inverted.

fn grayscale(img: Image) -> Image

Luma grayscale (Rec. 601 weights).

fn brighten(img: Image, amount: Int) -> Image

Every channel shifted by `amount` (negative darkens), clamped.

fn render(source: Text) -> Result[Image, Text]

Renders .pti source text into an Image (formats/pti-image.md).

fn min(a: Int, b: Int) -> Int

The smaller of two integers.

fn max(a: Int, b: Int) -> Int

The larger of two integers.

fn clamp(x: Int, lo: Int, hi: Int) -> Int

Clamps x into the inclusive range [lo, hi].

fn sign(x: Int) -> Int

-1 for negative numbers, 0 for zero, 1 for positive numbers.

fn is_even(n: Int) -> Bool

Whether n is divisible by two — zero and negatives included (is_even(0) and is_even(-2) are true).

fn pow(base: Int, exp: Int) -> Int

base raised to a non-negative exponent (asserts exp >= 0).

fn gcd(a: Int, b: Int) -> Int

The greatest common divisor of two integers (always non-negative).

Json.Null
Json.Bool(value: Bool)
Json.Int(value: Int)
Json.Float(value: Float)
Json.Str(value: Text)
Json.Arr(items: List[Json])
Json.Obj(entries: Map[Text, Json])

A parsed JSON value. Match on it to read a document; absence of a key is `Map.get -> None`, never null-the-language-feature.

fn parse(text: Text) -> Result[Json, Text]

Parses a JSON document into a Json value; trailing content after the value (other than whitespace) is an error.

fn to_text(json: Json) -> Text

Serializes a Json value to canonical JSON text — compact (no spaces), objects in insertion order, output always literal UTF-8.

fn sum(xs: List[Int]) -> Int

The sum of all elements (0 for the empty list).

fn product(xs: List[Int]) -> Int

The product of all elements (1 for the empty list).

fn range(from: Int, to: Int) -> List[Int]

The integers from `from` (inclusive) to `to` (exclusive).

fn largest(xs: List[Int]) -> Option[Int]

The largest element, or None for the empty list.

fn smallest(xs: List[Int]) -> Option[Int]

The smallest element, or None for the empty list.

fn count_where(xs: List[Int], pred: fn(Int) -> Bool) -> Int

How many elements satisfy the predicate.

fn index_of[T](xs: List[T], x: T) -> Int

The index of the first element equal to `x`, or -1 (since Sprint 32 — the first generic functions in the stdlib).

fn reversed[T](xs: List[T]) -> List[T]

The list in reverse order.

fn take[T](xs: List[T], n: Int) -> List[T]

The first `n` elements (fewer when the list is shorter).

fn drop[T](xs: List[T], n: Int) -> List[T]

Everything after the first `n` elements.

fn zip[A, B](xs: List[A], ys: List[B]) -> List[Tuple[A, B]]

Pairs elements up to the shorter length (since Sprint 33 — the first generic function returning tuples of two parameters).

fn enumerate[T](xs: List[T]) -> List[Tuple[Int, T]]

Pairs each element with its zero-based index (`(0, x0), (1, x1), …`).

fn zip_with[A, B, C](xs: List[A], ys: List[B], f: fn(A, B) -> C) -> List[C]

Combines two lists element-wise with `f`, to the shorter length.

fn unzip[A, B](pairs: List[Tuple[A, B]]) -> Tuple[List[A], List[B]]

Splits a list of pairs into a pair of lists — the inverse of `zip`.

fn any[T](xs: List[T], pred: fn(T) -> Bool) -> Bool

True if any element satisfies the predicate (false for the empty list).

fn all[T](xs: List[T], pred: fn(T) -> Bool) -> Bool

True if every element satisfies the predicate (true for the empty list).

fn find[T](xs: List[T], pred: fn(T) -> Bool) -> Option[T]

The first element satisfying the predicate, or None.

fn unique[T](xs: List[T]) -> List[T]

The distinct elements, in first-seen order. O(n²) — a linear `contains` scan per element, since element types need only equality, not hashing or ordering.

fn flatten[T](xss: List[List[T]]) -> List[T]

One flat list from a list of lists, preserving order.

fn chunk[T](xs: List[T], size: Int) -> List[List[T]]

The list split into consecutive chunks of at most `size` (which must be positive; a non-positive size yields the whole list as one chunk).

fn min_by[T](xs: List[T], key: fn(T) -> Int) -> Option[T]

The element with the smallest key, or None for the empty list.

fn max_by[T](xs: List[T], key: fn(T) -> Int) -> Option[T]

The element with the largest key, or None for the empty list.

fn sort_by[T](xs: List[T], key: fn(T) -> Int) -> List[T]

The list ordered by an integer key (stable insertion sort — the generic companion to the builtin `sorted`, which handles Int/Float/ Text directly). O(n²): for a large list ordered by an Int/Float/Text key, prefer the builtin `sorted`.

fn group_by[T](xs: List[T], key: fn(T) -> Int) -> Map[Int, List[T]]

Groups elements by an integer key, preserving first-seen key order and per-group element order.

fn get_or[K, V](m: Map[K, V], key: K, default: V) -> V

The value for `key`, or `default` when the key is absent.

fn merge[K, V](a: Map[K, V], b: Map[K, V]) -> Map[K, V]

`a` and `b` merged into one map; on a shared key, `b` wins.

fn map_values[K, V, W](m: Map[K, V], f: fn(V) -> W) -> Map[K, W]

The map with `f` applied to every value; keys are unchanged.

fn from_lists[K, V](keys: List[K], values: List[V]) -> Map[K, V]

A map from parallel key and value lists, paired to the shorter length; a later duplicate key overwrites an earlier one.

fn invert[K, V](m: Map[K, V]) -> Map[V, K]

The map with keys and values swapped. When several keys share a value, the last one (in insertion order) wins.

fn filter[K, V](m: Map[K, V], pred: fn(K, V) -> Bool) -> Map[K, V]

The entries whose `(key, value)` satisfy the predicate.

fn pi() -> Float

The ratio of a circle's circumference to its diameter.

fn tau() -> Float

Two pi — a full turn in radians.

fn e() -> Float

Euler's number, the base of the natural logarithm.

fn min(a: Float, b: Float) -> Float

The smaller of two floats.

fn max(a: Float, b: Float) -> Float

The larger of two floats.

fn clamp(x: Float, lo: Float, hi: Float) -> Float

Clamps x into the inclusive range [lo, hi].

fn sign(x: Float) -> Float

-1.0 for negatives, 0.0 for zero, 1.0 for positives.

fn pow(base: Float, exp: Int) -> Float

base raised to an integer exponent (negative exponents invert).

fn hypot(x: Float, y: Float) -> Float

The length of the hypotenuse — sqrt(x*x + y*y).

fn tan(x: Float) -> Float

The tangent of an angle in radians.

fn to_degrees(radians: Float) -> Float

Converts radians to degrees.

fn to_radians(degrees: Float) -> Float

Converts degrees to radians.

fn lerp(a: Float, b: Float, t: Float) -> Float

Linear interpolation from a to b by t (t = 0 gives a, t = 1 gives b).

fn round_to(x: Float, places: Int) -> Float

Rounds x to a number of decimal places (asserts places >= 0).

vertices: List[Float]
faces: List[Int]
colors: List[Int]

A triangle mesh: flat vertex coordinates (3 floats per vertex), flat face indices (3 zero-based vertex indices per triangle), and flat RGB colors (3 ints 0–255 per triangle, version 2).

fn add_box(m: Mesh, w: Float, h: Float, d: Float, x: Float, y: Float, z: Float) -> Mesh

A mesh with a cuboid appended: w×h×d, centered on x/z, base at y.

fn add_plane(m: Mesh, w: Float, d: Float, x: Float, y: Float, z: Float) -> Mesh

A mesh with a flat ground rectangle appended (w×d, centered).

fn add_sphere(m: Mesh, r: Float, segments: Int, x: Float, y: Float, z: Float) -> Mesh

A mesh with a UV sphere appended (radius r, `segments` around the equator, segments / 2 rings).

fn add_cylinder(m: Mesh, r: Float, h: Float, segments: Int, x: Float, y: Float, z: Float) -> Mesh

A cylinder: two rings of `segments` points, wall quads, capped — v3.

fn add_cone(m: Mesh, r: Float, h: Float, segments: Int, x: Float, y: Float, z: Float) -> Mesh

A cone: a base ring, an apex, wall triangles and a base fan — v3.

fn add_torus(m: Mesh, big_r: Float, small_r: Float, segments: Int, x: Float, y: Float, z: Float) -> Mesh

A torus: a segments x segments grid of quads around the ring — v3.

fn render(source: Text) -> Result[Mesh, Text]

Tessellates .ptm source text into a Mesh (formats/ptm-model.md).

fn to_obj_bytes(m: Mesh) -> Bytes

The single export bridge for viewing: Wavefront OBJ text as bytes.

fn render_view(m: Mesh, width: Int, height: Int, yaw: Float, pitch: Float) -> images.Image

A rendered orbit view of the mesh (Sprint 45): the camera is auto-framed on the model's bounding sphere (2.2 radii away), yaw orbits around y and pitch tilts the camera up (both in degrees), occlusion is decided per pixel by a 1/z depth buffer (Sprint 234) with two-sided shading against a fixed world-space key light.

fn render_view_from(m: Mesh, width: Int, height: Int, yaw: Float, pitch: Float, zoom: Float) -> images.Image

The orbit view at a chosen camera distance (Sprint 178): `zoom` is a factor on the automatic framing distance — `1.0` frames the whole model exactly like `render_view`, `0.5` moves twice as close, `2.0` twice as far. Values are clamped to `0.2`–`8.0`, so a wild factor degrades gracefully instead of clipping through the model.

fn render_view_fine(m: Mesh, width: Int, height: Int, yaw: Float, pitch: Float, zoom: Float, bg_r: Int, bg_g: Int, bg_b: Int) -> images.Image

The fine orbit view (Sprint 179): the same rasterizer rendered at twice the size and box-averaged down (2×2 supersampling — crisp edges from the identical geometry), a soft fill light so undersides read instead of falling to black, and a chosen background (RGB 0–255, clamped). Costs four times the pixels of [`render_view_from`]; the fast path stays exactly as it was.

fn render_view_showcase(m: Mesh, width: Int, height: Int, yaw: Float, pitch: Float, zoom: Float) -> images.Image

The showcase view (Sprint 218, M35): the fine render under a sky — a vertical gradient background and soft ground shadows cast along the key light onto the model's base plane, 2×2 supersampled like [`render_view_fine`]. The scene look the workshop opens with; existing entries are untouched (this is additive).

fn matches_glob(pattern: Text, text: Text) -> Bool

Whether `text` matches a shell glob `pattern` in full. `*` matches any run of characters (including none), `?` exactly one, `[a-z]` / `[!a-z]` a character class; everything else is literal.

fn matches(pattern: Text, text: Text) -> Result[Bool, Text]

Whether `text` matches the regex `pattern` in full (anchored at both ends). Returns a teaching error for a malformed pattern rather than a silent mismatch. Supports literals, `.`, `[classes]`, the shorthands `\d \w \s` (and `\D \W \S`), alternation `a|b`, groups `(...)`, and the quantifiers `* + ? {n} {n,} {n,m}`.

fn captures(pattern: Text, text: Text) -> Result[Option[List[Text]], Text]

The whole match plus each group's captured substring (group order), when `pattern` matches `text` in full (anchored); `Ok(None)` when it does not; a teaching error for a malformed pattern. A group that did not participate captures `""`; a repeated group captures its last iteration. Consistent with `matches` on whether the text matches, and polynomial (no catastrophic backtracking).

name: Text
min_version: Text

One dependency: a package name and the minimum version that works.

name: Text
pkg_version: Text
summary: Text
deps: List[Dep]
modules: List[Text]

A parsed package manifest.

fn render(source: Text) -> Result[Package, Text]

Parses polytone.pkg source text (formats/pkg-manifest.md).

name: Text
pkg_version: Text
summary: Text

One package listed by a registry index.

title: Text
packages: List[PackageRef]

A parsed registry index (formats/registry-index.md).

fn render_index(source: Text) -> Result[Registry, Text]

Parses index.ptr source text (formats/registry-index.md).

fn union[T](a: Set[T], b: Set[T]) -> Set[T]

Every element of `a` and `b` (union). `b`'s elements are added to a copy of `a`'s.

fn intersection[T](a: Set[T], b: Set[T]) -> Set[T]

The elements in both `a` and `b` (intersection).

fn difference[T](a: Set[T], b: Set[T]) -> Set[T]

The elements of `a` that are not in `b` (difference, `a - b`).

fn symmetric_difference[T](a: Set[T], b: Set[T]) -> Set[T]

The elements in exactly one of `a` or `b` (symmetric difference).

fn is_subset[T](a: Set[T], b: Set[T]) -> Bool

True if every element of `a` is in `b`.

fn is_superset[T](a: Set[T], b: Set[T]) -> Bool

True if every element of `b` is in `a`.

fn is_disjoint[T](a: Set[T], b: Set[T]) -> Bool

True if `a` and `b` share no elements.

fn all[T](ts: List[Task[T]]) -> List[T]

Drives every task in list order and collects the results.

fn repeat(s: Text, times: Int) -> Text

s repeated `times` times ("" for zero or negative counts).

fn pad_left(s: Text, width: Int, fill: Text) -> Text

Pads s on the left with `fill` (one character) until it is `width` long. An empty `fill` cannot add width, so s is returned unchanged.

fn pad_right(s: Text, width: Int, fill: Text) -> Text

Pads s on the right with `fill` (one character) until it is `width` long. An empty `fill` cannot add width, so s is returned unchanged.

fn is_blank(s: Text) -> Bool

Whether s is empty or whitespace-only.

epoch_second: Int
Instant.civil(self) -> Civil — This instant as broken-down UTC calendar fields.
Instant.iso(self) -> Text — This instant in RFC 3339 form, e.g. "2026-08-06T12:00:00Z".
Instant.plus(self, d: Duration) -> Instant — This instant moved forward by `d`.
Instant.minus(self, d: Duration) -> Instant — This instant moved back by `d`.
Instant.until(self, other: Instant) -> Duration — The span from this instant to `other` (negative when `other` is earlier).
Instant.is_before(self, other: Instant) -> Bool — Whether this instant is strictly before `other`.
Instant.is_after(self, other: Instant) -> Bool — Whether this instant is strictly after `other`.

A point on the UTC timeline: seconds since the Unix epoch (1970-01-01T00:00:00Z). Negative values are before the epoch.

seconds: Int
Duration.in_minutes(self) -> Int — This span in whole minutes, truncated toward zero.
Duration.in_hours(self) -> Int — This span in whole hours, truncated toward zero.
Duration.in_days(self) -> Int — This span in whole days, truncated toward zero.
Duration.abs(self) -> Duration — The same span without a sign.

A signed span of time, in whole seconds.

year: Int
month: Int
day: Int
hour: Int
minute: Int
second: Int
weekday: Int

Broken-down UTC calendar fields. `weekday` is 0=Sunday .. 6=Saturday.

fn is_leap(year: Int) -> Bool

Whether a year is a leap year in the proleptic Gregorian calendar.

fn days_in_month(year: Int, month: Int) -> Int

The number of days in a month (1-12); asserts the month is in range.

fn of_civil(year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int) -> Result[Instant, Text]

Builds an Instant from UTC calendar fields, validating every field; returns a teaching error (never a silently wrong date) on any range violation, February 30th included.

fn to_civil(instant: Instant) -> Civil

Breaks an Instant down into UTC calendar fields.

fn add(instant: Instant, d: Duration) -> Instant

The instant `d` after the given one.

fn sub(instant: Instant, d: Duration) -> Instant

The instant `d` before the given one.

fn between(a: Instant, b: Instant) -> Duration

The span from `a` to `b` (positive when b is later than a).

fn before(a: Instant, b: Instant) -> Bool

Whether `a` is strictly before `b`.

fn after(a: Instant, b: Instant) -> Bool

Whether `a` is strictly after `b`.

fn seconds(n: Int) -> Duration

A duration of n seconds.

fn minutes(n: Int) -> Duration

A duration of n minutes.

fn hours(n: Int) -> Duration

A duration of n hours.

fn days(n: Int) -> Duration

A duration of n days.

fn weeks(n: Int) -> Duration

A duration of n weeks.

fn to_iso(instant: Instant) -> Text

Formats an Instant as ISO 8601 UTC — "YYYY-MM-DDTHH:MM:SSZ".

Value.Str(s: Text)
Value.Int(n: Int)
Value.Bool(b: Bool)
Value.Arr(items: List[Value])

A TOML scalar or array value.

name: Text
pairs: List[Tuple[Text, Value]]
Table.get(self, key: Text) -> Option[Value] — The value stored under `key`, if the table has one.
Table.has(self, key: Text) -> Bool — Whether the table carries `key`.
Table.text(self, key: Text) -> Option[Text] — The Text under `key`, if it is present and is a string.
Table.int(self, key: Text) -> Option[Int] — The Int under `key`, if it is present and is a number.
Table.keys(self) -> List[Text] — The keys in declaration order.

One table: its header name ("" for the root) and its ordered pairs.

fn parse(text: Text) -> Result[List[Table], Text]

Parses TOML text into an ordered list of tables. The root table (keys before any `[header]`) comes first with name "". A malformed line is a typed error.

fn serialize(tables: List[Table]) -> Text

Serializes tables back to TOML text (the inverse of parse).

fn encode(text: Text) -> Text

Percent-encodes text: unreserved characters pass through, every other UTF-8 byte becomes %XX.

fn decode(text: Text) -> Result[Text, Text]

Decodes a percent-encoded string. A truncated or non-hex escape, or bytes that are not valid UTF-8, is an error.

fn v4(gen: Rng) -> Text

A fresh random UUID (version 4). Draws sixteen bytes from `gen`, sets the version nibble to 4 and the variant bits to 10 (RFC 4122 §4.4), and renders `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`.

width: Int
height: Int
fps: Int
frames: List[Int]
audio: Text

Rendered video: dimensions, frame rate, flat RGB frame data (width × height × 3 ints per frame, frames in order) — and since v2 the soundtrack (`""` = none): a relative `.pta` address — or, since v3's embedded `audio:` block, the full `.pta` source itself (embedded source contains newlines; a reference never does). Hosts render it through the audio codec; the video codec stays pure.

fn render(source: Text) -> Result[Video, Text]

Renders .ptv source text into a Video (formats/ptv-video.md).

fn to_y4m_bytes(v: Video) -> Bytes

The single export bridge for playback: an uncompressed YUV4MPEG2 (C444) stream — `ffplay out.y4m` / `mpv out.y4m` play it directly.

Block.Heading(level: Int, text: Text)
Block.Paragraph(text: Text)
Block.Code(text: Text)
Block.Bullets(items: List[Text])
Block.Link(url: Text, label: Text)
Block.Image(source: Text, alt: Text)
Block.Film(source: Text, alt: Text)
Block.Sound(source: Text, alt: Text)
Block.Input(name: Text, label: Text)
Block.Button(target: Text, label: Text)
Block.Quote(text: Text)
Block.Note(text: Text)
Block.Table(head: List[Text], rows: List[List[Text]])
Block.Nav(links: List[Tuple[Text, Text]])
Block.Rule

One typed document block — markup never exists as strings. Image/Film/Sound reference native documents by relative address (since v2, Sprint 34).

title: Text
blocks: List[Block]

A parsed document: title plus blocks in order.

fn render(source: Text) -> Result[Document, Text]

Parses .ptw source text into a Document (formats/ptw-web.md).

fn form_value(submitted: List[Text], name: Text) -> Option[Text]

Reads a form field from program arguments (v3, Sprint 41): the viewer submits each input as one `name=value` argument with spaces encoded as '+'. Missing fields are None; empty submissions are Some("").

fn to_html_bytes(doc: Document, assets: Map[Text, images.Image]) -> Bytes

The single export bridge: a standalone HTML page as bytes. `assets` maps image-block sources to rendered images — supplied ones embed as BMP data URIs, so the page stays self-contained; missing ones (and film/sound blocks) render as addressed links (v2, Sprint 34).