SyncTERM v1.9a Manual

true false

Booleans.

null

The single null value.

123 0xFF 1.5e3

Numbers. All numeric values are 64-bit floats; 0x for hex; underscores 1_000_000 for digit grouping.

"hello"

String literal. Escapes: \\ \" \% \0 \a \b \e \f \n \r \t \v \xNN \uNNNN \UNNNNNNNN.

"got %(x)"

String interpolation: %(expr) evaluates expr and inserts its toString. A bare % not followed by ( is a lex error — see Strings and %.

[1, 2, 3]

List literal.

{"a": 1, "b": 2}

Map literal.

1..5

Half-open Range (1, 2, 3, 4 — excludes 5).

1...5

Closed Range (1, 2, 3, 4, 5 — includes 5).

System.print()

Print a blank line.

System.print(value)

Print value.toString followed by newline.

System.printAll(seq)

Print each item in seq, one per line.

System.write(value)

Print value.toString, no newline.

System.writeAll(seq)

Like printAll without newlines.

System.clock

Wall-clock time in seconds since process start, as Num.

obj == other

Identity by default; classes can override.

obj != other

Negation of ==.

obj.hash

Hash code, integer.

obj.is(class)

Type check; same as obj is class.

obj.toString

Default returns "instance of <Class>". Override for nicer output.

obj.type

Returns the object’s class.

!obj

Boolean negation. Falsy values are false and null only — every other value (including 0 and "") is truthy.

Cls.name

String name of the class.

Cls.supertype

Parent class, or Object for Object itself.

Cls.toString

The class name.

Num.pi

π.

Num.infinity

+∞.

Num.largest, Num.smallest

Max / min finite double.

Num.maxSafeInteger, Num.minSafeInteger

Range of exact-integer doubles (±2⁵³−1).

n.abs

Absolute value.

n.ceil, n.floor, n.round, n.truncate

Round-modes.

n.sqrt

Square root.

n.sin, n.cos, n.tan

Trig (radians).

n.asin, n.acos, n.atan

Inverse trig.

n.atan(x)

atan2(self, x).

n.log, n.log2, n.exp

Natural log, log base 2, eˣ.

n.pow(p)

nᵖ.

n.min(other), n.max(other)

Pairwise min / max.

n.clamp(lo, hi)

Clamp into [lo, hi].

n.fraction

Fractional part.

n.sign

-1 / 0 / +1.

n.isInteger, n.isInfinity, n.isNan

Predicates.

n.toString

Decimal string.

n & m, n | m, n ^ m, ~n

Bitwise (truncated to 32-bit).

n << k, n >> k

Bit shifts (also 32-bit).

s.count

Codepoint count.

s.isEmpty

True iff count == 0.

s.bytes

A Sequence view yielding each byte as a Num.

s.codePoints

A Sequence view yielding each codepoint as a Num.

s[i]

Codepoint substring starting at byte index i. If i is mid-codepoint, returns the raw byte.

s[a..b], s[a...b]

Byte-ranged substring. Negative indices count from the end.

s + other

Concatenation.

s * n

Repeat n times.

s.indexOf(needle)

Byte index of first match, or -1.

s.indexOf(needle, start)

Byte index of match at-or-after start.

s.contains(needle)

Substring presence.

s.startsWith(prefix)

Prefix check.

s.endsWith(suffix)

Suffix check.

s.replace(old, new)

All non-overlapping occurrences.

s.split(separator)

List of substrings, separator removed.

s.trim(), s.trimStart(), s.trimEnd()

Strip whitespace.

s.trim(chars), s.trimStart(chars), s.trimEnd(chars)

Strip any chars in the supplied string.

s.iterate(prev), s.iteratorValue(iter)

Sequence protocol: yields one codepoint substring per step.

s.toString

The string itself.

String.fromByte(n)

Single-byte string.

String.fromCodePoint(cp)

Encode a codepoint as UTF-8 string.

List.new()

Empty list.

List.filled(size, value)

Pre-fill size copies of value.

[a, b, c]

Literal.

list.count

Length.

list.isEmpty

True iff empty.

list[i], list[i] = v

Access / replace; negatives count from the end.

list[a..b], list[a...b]

Slice (returns a new List).

list.add(v)

Append.

list.addAll(seq)

Append every item of seq.

list.insert(i, v)

Insert v at index i.

list.remove(v)

Remove first occurrence; returns true if removed.

list.removeAt(i)

Remove and return element at i.

list.clear()

Empty the list.

list.indexOf(v)

Index of first match, or -1.

list.contains(v)

Membership.

list.sort()

In-place sort with <. Aborts on Strings (no < defined) — pass a comparator.

list.sort {|a, b| a < b }

In-place sort with a custom comparator.

list.swap(i, j)

In-place swap.

list.iterate(prev), list.iteratorValue(iter)

Sequence protocol.

list.toString

"[a, b, c]".

Map.new()

Empty map.

{"a": 1, "b": 2}

Literal.

m.count

Number of pairs.

m.isEmpty

Empty?

m[k], m[k] = v

Access / set. Missing key returns null.

m.containsKey(k)

Distinguishes "missing" from "value is null".

m.remove(k)

Remove and return the old value (or null).

m.clear()

Empty the map.

m.keys, m.values

Sequence views (lazy).

m.iterate(prev), m.iteratorValue(iter)

Sequence protocol; iterating yields keys.

m.toString

"{a: 1, b: 2}".

r.from

Lower bound.

r.to

Upper bound.

r.min, r.max

Bounds normalised regardless of direction.

r.isInclusive

True for ..., false for ...

r.count

Number of values.

for (i in r) {}

Iterate.

seq.all { fn }

True iff fn(item) is truthy for every item.

seq.any { fn }

True iff any item passes.

seq.contains(value)

Membership via ==.

seq.count

Eager count.

seq.count { fn }

Items where fn(item) is truthy.

seq.each { fn }

Apply fn for side-effects.

seq.isEmpty

True iff count == 0.

seq.join()

Concatenate all items' toString.

seq.join(sep)

…with sep between consecutive items.

seq.map { fn }

Lazy mapped sequence.

seq.where { fn }

Lazy filtered sequence.

seq.skip(n), seq.take(n)

Lazy.

seq.reduce { |a, b| …​ }

Fold from first item.

seq.reduce(seed) { |a, b| }

Fold from seed.

seq.toList

Materialise into a List.

Fiber.new { …​ }

Create a paused fiber whose body is the closure.

Fiber.current

The fiber currently running.

f.call(), f.call(value)

Resume f; the value is the return of the most recent Fiber.yield inside f.

f.transfer(), f.transfer(value)

Like call, but does not record this fiber as the resumer; cannot be returned to via Fiber.yield.

f.transferError(err)

Resume f with err raised inside it.

f.try(), f.try(value)

Like call, but if f aborts the abort is caught and f.error is set.

f.isDone

True after the body returns or aborts.

f.error

The abort message if try caught one, else null.

Fiber.yield()

Suspend; control returns to the most recent .call() caller.

Fiber.yield(value)

…passing value as the return of that .call().

Fiber.abort(err)

Raise err in the current fiber. Caller’s .try() catches it.

Fn.new { …​ }

Build from a closure literal.

f.call()

Invoke with no args.

f.call(a, b, …​)

Invoke with args (up to 16).

f.arity

Declared parameter count.

Linux / *BSD

$XDG_DATA_HOME/syncterm/scripts/
(default ~/.local/share/syncterm/scripts/)

macOS

~/Library/Application Support/SyncTERM/scripts/

Windows

%APPDATA%\SyncTERM\scripts\

Haiku

~/config/settings/SyncTERM/scripts/

scripts/<name>.wren

Pure library module. Loaded only when something imports it via import "<name>". Has no auto-run side effects. Where you put reusable code that other scripts pull in.

scripts/auto/<event>/<name>.wren

Auto-loaded entry script. Runs at the moment the framework fires <event>; typically registers hooks. Currently the only event is connected, fired once per BBS session, but the layout reserves room for startup / ssh / ui / etc. as new auto-load points are added.

syncterm

library

Foundational module: foreign-class declarations and Wren-side helpers (REPL, Key, Color, Codepage, …). Every other script imports from this one. Loads on first import.

console

auto / connected

Wren REPL. Triggered by Ctrl+`.

connected

auto / connected

Alt+L send-login handler. Sends username, password, and sysop password from the directory entry, with the right send-order rules per connection type.

Hook.onKey { |k| …​ }

k: 16-bit ciolib key code (see Key)

Bool — true to consume the keystroke

Hook.onKey(key, fn)

Filtered: fn(k) only fires when k == key. C-side filter — no Wren entry on misses.

Bool — true to consume

Hook.onInput { |b| …​ }

b: one byte received from the remote

Bool true drops the byte; String replaces it with the string’s bytes (up to 256 — larger replacements log a runtime error and the original byte passes through); anything else passes through.

Hook.onInput(byte, fn)

Filtered: fn(b) only fires when b == byte. C-side filter.

Same return contract as the unfiltered form.

Hook.onMatch(pattern, fn)

fn(m) fires when pattern matches the input stream. See "Streaming regex hooks" below.

Ignored — onMatch is passthrough-only. Use Hook.onInput (per- byte, drop / replace) when you need to remove bytes from the wire.

Hook.onMatchClean(pattern, fn)

Same as onMatch, but bytes are pre-filtered through SyncTERM’s shared ANSI parser so colour codes, cursor moves, and DCS / OSC strings never split a literal pattern. A pattern like "Welcome" matches even when the BBS sends "We" + ESC[1;33m + "lcome".

Ignored — passthrough-only, same contract as onMatch.

Hook.onMouse { |ev| …​ }

ev: 7-element list [event, bstate, modifiers, sx, sy, ex, ey]

Bool — true to consume

Hook.onMouse(event, fn)

Filtered: fn(ev) only fires when ev[0] == event. C-side filter.

Bool — true to consume

Hook.onStatus { |def| …​ }

def: SyncTERM’s default status string

String to replace the status, or non-string to fall through

Hook.every(ms, fn)

ms: milliseconds; fn: callable

(none — return value ignored)

remove()

Tombstone the hook. Future dispatches skip it. Safe to call from inside the hook’s own callback (the host removes by NULL-ing the callable; in-flight dispatch finishes on the still-allocated resources). Returns true on first call, false thereafter.

callCount

Number of times the host has invoked this hook. Counts every wrenCall, regardless of whether the callback returned truthy or errored.

totalRuntime

Cumulative wall-clock seconds spent inside wrenCall for this hook, measured with xp_timer() before and after each invocation.

minRuntime, maxRuntime

Smallest / largest single invocation time in seconds. Both read back as 0 for a never-fired hook; min is seeded on the first call.

/help, /?

Print commands, editing keys, history navigation, scrollback navigation, and exit keys.

/in <module>

Switch the eval target to <module>. Default is syncterm. Use this to inspect or mutate any other loaded module. /in with no argument prints the current target.

/mods

List every Wren module currently loaded into the VM, alphabetically sorted. Includes core (Wren’s built-in classes), every embedded module (syncterm, console, connected), every user script loaded from the scripts directory, and any module pulled in via import.

/quit, /q

Close the REPL and return to the BBS session.

Left / Right

Move the cursor within the current input line.

Home / End

Jump to start / end of the current input line.

Backspace

Delete the character before the cursor.

Delete

Delete the character at the cursor.

Up / Down (live mode)

Walk command history. If the line currently has typed text, that text becomes a prefix anchor — only history entries starting with it are visited.

PgUp / PgDn

Page through the scrollback log buffer. PgUp from live mode pins the current top of view; PgDn returns to live once you’ve scrolled past the tail.

Up / Down (scrollback mode)

Single-row scroll. Down past the tail rejoins live mode.

Enter (blank or whitespace-only)

Advance to a fresh prompt row without evaluating.

Ctrl+W

Backward kill-word, ending at the cursor (the tail past the cursor is preserved).

Ctrl+L

Clear the screen and the in-memory log. Returns to live mode.

Middle-click

Paste from system clipboard at the cursor. Multi-line text is split on LF and each line submitted as if Enter were pressed.

Alt+drag

Hand off to the existing select-and-copy gesture.

Ctrl+` / Esc / /quit

Close the REPL.

Screen.size

[width, height] of the entire screen.

Screen.save()

Save the entire screen contents. Returns an opaque handle.

Screen.restore(handle)

Restore a previously saved screen.

Screen.readRect(sx, sy, ex, ey)

Read a rectangle of cells (1-based, inclusive). Returns a Cells or null.

Screen.writeRect(sx, sy, ex, ey, cells)

Write a list of Cell objects into a rectangle.

Screen.moveRect(sx, sy, ex, ey, dx, dy)

Copy a rectangle to a new position.

Screen.attr=(a)

Set the active text attribute byte.

Screen.hyperlinkId, Screen.hyperlinkId=(id)

Hyperlink ID attached to subsequent window writes. 0 clears. Allocate IDs through Hyperlinks.add.

Input.next()

Block until the next event; return KeyEvent or MouseEvent.

Input.next(ms)

Wait up to ms milliseconds; return the event or null on timeout.

Input.poll()

Return immediately with the next pending event, or null if nothing is pending.

Input.unget(ev)

Push an event back to the front of the input queue. Routes by event type — KeyEvent → ungetch, MouseEvent → ungetmouse.

Input.mousedrag()

Hand off to SyncTERM’s drag-select gesture.

Input.mouseVisible=(b)

Show or hide the mouse cursor. Setter only — there is no ciolib query for visibility, and tracking it from Wren would drift if other code shows or hides the cursor.

Input.nextEvent(fiber)

Register fiber to receive the next key or mouse event. The caller yields to wait; resumes with KeyEvent or MouseEvent. Throws if another fiber is already registered. See Modal Input.

Input.wake(fiber, value)

Queue value to be delivered to fiber via the same result queue Input.nextEvent and Timer.trigger use. Safe to call from inside a hook body — only enqueues; the resume happens on the next main-loop drain. The canonical use case is a network-driven app where Hook.onInput wants to wake a UI fiber that’s parked on Input.nextEvent so the screen repaints when remote bytes change visible state. Multiple wakes queue up; each becomes one resumption. Do NOT call from inside another foreign method whose caller is about to re-enter wrenCall (same rule as wrenCall itself — see wren.md §7).

KeyEvent.new(code)

Construct from a raw 16-bit code.

code

Raw 16-bit ciolib code.

codepoint

Unicode value of the byte under the current Font.codepage for non-extended keys; null for extended keys (high byte non-zero).

text

UTF-8 form of codepoint, or "" for extended keys.

MouseEvent.new(event, modifiers, sx, sy, ex, ey)

Construct from raw fields.

event

Mouse event type code.

modifiers

Keyboard modifier mask.

startX, startY

Click-down coordinates (1-based).

endX, endY

Release coordinates (1-based).

Clipboard.text

Read the system clipboard as a string.

Clipboard.text=(s)

Write a string to the system clipboard.

cp437

0

IBM PC CP437 — original DOS character set, English plus box-drawing. The default for traditional ANSI BBSes.

cp1251

1

Windows-1251 — Cyrillic (Russian, Bulgarian, Ukrainian, etc.) in a "swiss" font variant.

cp1251_b

2

Windows-1251 with the broken-vertical glyph variant.

koi8r

3

KOI8-R — Russian Cyrillic. Common on 1990s Russian Linux/Unix systems.

iso8859_2

4

ISO-8859-2 (Latin-2) — Central European (Polish, Czech, Hungarian, …).

iso8859_4

5

ISO-8859-4 (Latin-4) — Northern European / older Baltic. 9-bit-mapped wide-glyph variant.

cp866m

6

CP866 — Russian DOS, "(c)" modified variant.

iso8859_9

7

ISO-8859-9 (Latin-5) — Turkish.

iso8859_8

8

ISO-8859-8 — Hebrew.

koi8u

9

KOI8-U — Ukrainian Cyrillic.

iso8859_15

10

ISO-8859-15 (Latin-9) — Western European with the Euro sign.

iso8859_5

11

ISO-8859-5 — Latin/Cyrillic.

cp850

12

CP850 — Multilingual Latin-1 (DOS Western European).

cp850_b

13

CP850 with the broken-vertical glyph variant.

cp865

14

CP865 — Nordic DOS (Danish, Norwegian).

cp865_b

15

CP865 with the broken-vertical glyph variant.

iso8859_7

16

ISO-8859-7 — Greek.

iso8859_1

17

ISO-8859-1 (Latin-1) — Western European, classic Unix default.

cp866m2

18

CP866 — Russian DOS, second modified variant.

cp866u

19

CP866-U — Ukrainian variant.

cp1131

20

CP1131 — Belarusian DOS.

armscii8

21

ARMSCII-8 — Armenian.

haik8

22

HAIK-8 — older Armenian set; used with the ARMSCII-8 screen map.

atascii

23

ATASCII — Atari 8-bit native character set.

petsciiUpper

24

PETSCII (uppercase/graphics mode) — Commodore 64/128 default.

petsciiLower

25

PETSCII (lowercase/shifted mode) — Commodore 64/128 after a Shift+Commodore key.

prestel

26

UK Prestel / Viewdata teletext — block mosaic graphics, double-height, conceal.

prestelSep

27

Prestel separated mosaics — block mosaics with gaps between cells.

atariSt

28

Atari ST GEM character set.

Cell.new()

Construct an empty cell.

ch, ch=(s)

Character as a Unicode string (one codepoint, round-tripped through CP437).

chByte, chByte=(n)

Character as a raw 8-bit byte.

font, font=(n)

Font slot.

legacyAttr, legacyAttr=(n)

Legacy attribute byte (foreground in low nibble, background in high nibble, plus bright/blink bits).

bright, bright=(b)

Bright bit.

blink, blink=(b)

Blink bit.

fgPalette, bgPalette

Foreground / background palette indices.

fgRgb, bgRgb

Foreground / background as 24-bit RGB. Setters preserve bits 24..30 of the existing field, so toggling between palette and RGB modes does not lose unrelated state.

hyperlinkId, hyperlinkId=(n)

Hyperlink ID attached to this cell.

Font.cp437English

0

Codepage 437 English (default).

1

Codepage 1251 Cyrillic, "swiss" variant.

2

Russian KOI8-R.

3

ISO-8859-2 Central European.

4

ISO-8859-4 Baltic wide (VGA 9-bit mapped).

5

Codepage 866 (c) Russian.

6

ISO-8859-9 Turkish.

7

HAIK-8 (used with the ARMSCII-8 screen map).

8

ISO-8859-8 Hebrew.

9

Ukrainian KOI8-U.

10

ISO-8859-15 West European, "thin" variant.

11

ISO-8859-4 Baltic (VGA 9-bit mapped).

12

Russian KOI8-R, alternate (b) variant.

13

ISO-8859-4 Baltic wide.

14

ISO-8859-5 Cyrillic.

15

ARMSCII-8 (Armenian).

16

ISO-8859-15 West European.

17

Codepage 850 Multilingual Latin I, "thin".

18

Codepage 850 Multilingual Latin I.

19

Codepage 865 Norwegian, "thin".

20

Codepage 1251 Cyrillic.

21

ISO-8859-7 Greek.

22

Russian KOI8-R, alternate (c) variant.

23

ISO-8859-4 Baltic.

24

ISO-8859-1 West European.

25

Codepage 866 Russian.

26

Codepage 437 English, "thin" variant.

27

Codepage 866 (b) Russian.

28

Codepage 865 Norwegian.

29

Ukrainian CP866-U.

30

ISO-8859-1 West European, "thin".

31

Codepage 1131 Belarusian, "swiss".

Font.commodore64Upper

32

Commodore 64 (uppercase / graphics).

Font.commodore64Lower

33

Commodore 64 (lowercase / shifted).

Font.commodore128Upper

34

Commodore 128 (uppercase / graphics).

Font.commodore128Lower

35

Commodore 128 (lowercase / shifted).

Font.atari

36

Atari 8-bit.

Font.potNoodle

37

P0T NOoDLE — Amiga BBS classic.

Font.mosOul

38

mO’sOul — Amiga BBS classic.

Font.microKnightPlus

39

MicroKnight Plus — Amiga.

Font.topazPlus

40

Topaz Plus — Amiga.

Font.microKnight

41

MicroKnight — Amiga.

Font.topaz

42

Topaz — Amiga (the original Workbench font).

Font.prestel

43

Prestel — UK Viewdata mosaic.

Font.atariSt

44

Atari ST GEM.

Font.ripterm

45

RIPterm — RIP graphics terminal font.

Font.name(i)

Human-readable font name for slot i, e.g. "Codepage 437 English". Returns the empty string for empty slots.

Font.count

Total number of populated font slots. Iteration bound — 0…​Font.count walks every available font.

Font.available(i)

true if slot i has actually been loaded (the user can configure SyncTERM to omit some built-ins).

Font.codepage

The Codepage value for slot 0 (whatever codepage the script’s strings should be transcoded into for display).

Font.codepageOf(i)

The codepage value for slot i. Several slots can share a codepage (the Amiga slots 37–42 are all iso8859_1, for example).

Hyperlinks[id]

URI string for id, or null.

Hyperlinks.containsKey(id)

true if id is present.

Hyperlinks.add(uri, idParam)

Allocate a new hyperlink ID for uri with optional id parameter string. Returns the new numeric ID.

Hyperlinks.params(id)

Parameter string for id, or null.

Console.count

Number of valid entries currently in the ring.

Console.total

Monotonic count of entries ever written. Survives clear().

Console[seq]

Entry with monotonic sequence seq, as a tuple [seq, ts, source, text]. source is one of the LogSource values. Out-of-range returns null.

Console.clear()

Drop all entries. total keeps incrementing.

Console.iterate, iteratorValue

Wren iteration protocol — works in for (e in Console) { …​ }.

REPL.eval(src)

Compile and run src in module syncterm. Returns null for statements; [value] (a one-element list) for expressions.

REPL.eval(module, src)

As above, in module.

REPL.hasModule(name)

true if name has been loaded.

REPL.modules

List of every module name currently loaded in the VM (including core). Order is implementation-defined; sort if you need stable output.

Conn.send(s)

Send bytes through the full path: telnet IAC escaping, then on-wire.

Conn.sendRaw(s)

Send bytes raw, bypassing IAC escaping.

Conn.close()

Close the connection.

Conn.connected

Bool — is the link up?

Conn.type

ConnType value.

Conn.pending

Bytes available to read right now (in the inbuf ring).

Conn.queued

Bytes queued to write that haven’t gone out yet.

Conn.peek(n)

Look at up to n bytes from the inbuf without consuming. Clamped to the actual ring size.

Conn.recv(n)

Read up to n bytes from the inbuf and consume them.

Cursor (1-based, on the terminal)

x, y

Origin (1-based, on the host screen)

originX, originY

Geometry

width, height, topMargin, bottomMargin, leftMargin, rightMargin

Color state

attr, fgColor, bgColor, hasPaletteOverride, paletteOverride

Fonts

fontSlot, altFonts

Scrollback

scrollbackLines, scrollbackWidth, scrollbackPos, scrollbackStart

Mode flags

emulation (Emulation), doorwayMode, music, started, skypix, logMode (LogMode), logPaused, statusDisplay (StatusDisplay)

Bitfield snapshots

extAttr (ExtAttr), lastColumnFlag (LastColumnFlag)

CTerm.write(s)

Send s to cterm_write — bypass the wire, render directly.

CTerm.suspended, CTerm.suspended = b

Read or write the wire-pump suspend flag. When set true, the main loop stops draining bytes from the conn buffer. Bytes pile up in the conn buffer; the TCP receive window eventually fills and the remote sees its send() calls block or EAGAIN. Use this to claim the screen for a modal dialog, transfer overlay, etc., without remote output painting underneath. Clear it again when you’re done. Registering a fiber via Input.nextEvent does not suspend on its own — scripts that want modal behavior must set this explicitly. When speed emulation is active and the flag transitions from true back to false, the byte pump is credited with all the bytes that would have processed at the emulated rate during the suspended interval; those bytes drain past the speed gate as fast as the pump can run, so the visible output catches up to where it would have been if the suspend had never happened.

Identity

name, addr, port, connType (ConnType), comment, type (BBSListType), id

Network

addressFamily (AddressFamily)

Auth

user, password, syspass, sftpPublicKey, sshFingerprint, sshFingerprintLen

Display

termName, screenMode (ScreenMode), bpsRate, font, noStatus, hidePopups, yellowIsYellow, forceLcf, palette, paletteSize

Modem / serial

stopBits, dataBits, parity (Parity), flowControl (FlowControl)

Telnet

telnetNoBinary, deferTelnetNegotiation, ghostProgram

RIP / music

rip (RipVersion), music (MusicMode)

File transfer

dlDir, ulDir, xferLogLevel (LogLevel), telnetLogLevel (LogLevel)

Logs

logFile, appendLogFile

Statistics

added, connected, fastConnected, calls, sortOrder

Directory.contains(name)

true if a file named name exists in the directory.

Directory.list

A Map keyed by entry name; values are File objects for regular files and Directory objects for subdirectories. Symlinks, device nodes, FIFOs, etc. are silently skipped. Names are filtered by the filename policy, so hidden / dotfiles / Windows-reserved names don’t appear. Each read enumerates the directory afresh; cache the value if you’ll touch it more than once. Use this to obtain handles to existing files, or to walk a tree.

Directory.create(name)

Atomically create a new zero-byte file named name in the directory and return a File object for it. Uses C11 exclusive- create mode (fopen(path, "wbx")) so a concurrent creator doesn’t silently truncate an existing file. Returns null if the file already exists, the name violates the filename policy, the path is too long, or the OS rejects the create for any other reason. The file is closed on return — call File.open() before reading or writing.

Directory.createDir(name)

Atomically create a new subdirectory named name and return a Directory object for it. Uses mkdir directly, which fails atomically if the path already exists — same race-free semantics as create() for files. Returns null on the same error conditions: existing entry, invalid name, path too long, or OS rejection (no permission, parent missing, …). Use list[name] to obtain a handle to a subdirectory that already exists.

Directory.delete(name)

Remove the entry named name from the directory. Handles regular files and empty subdirectories; refuses anything else (symlinks, device nodes, FIFOs, non-empty directories). Returns true on successful removal, false on any failure (no such entry, wrong type, non-empty directory, no permission, invalid name, …). On success, every live File / Directory handle whose path is at-or-below the removed entry is marked dead and pulled from the live-handle registry; a subsequent operation on any such handle aborts the calling fiber with a "handle is dead" error.

File.open()

Open the file (creating if necessary). Subsequent reads / writes start at offset 0.

File.close()

Close the file handle.

File.readBytes(count)

Read up to count bytes from the current offset; advance. Returns the bytes as a String.

File.readBytes(count, offset)

Read at an absolute offset; do not advance the current offset.

File.read()

Read the entire file from offset 0.

File.writeBytes(s), writeBytes(s, offset)

Write s at the current or given offset.

File.write(s)

Replace file contents with s.

File.readLine()

Read from the current offset to the first LF (0x0A) or EOF and return the bytes read with any trailing LF removed. Advances the offset past the LF on a hit, or to EOF if none was found. Returns null when the offset is already at EOF; a blank line returns the empty string.

File.writeLine(s)

Write s at the current offset, then append an LF (0x0A). The offset advances past the LF. No special handling if s already ends in LF — the trailing LF is appended unconditionally; use writeBytes for raw control over line termination.

File.offset, offset=(o)

Current read/write position.

File.size

Length of the file in bytes.

File.isOpen

true while the handle is valid.

File.sha1, File.md5

Hashes of the file’s full content; raw digest bytes (20 / 16 bytes) returned as a Wren String. Implementation memory-maps the file; zero-length files are hashed as the empty buffer. Returned as bytes rather than hex so they compare directly against SFTPEntry.hash from the sha1s@syncterm.net / md5s@syncterm.net SFTP extensions; format hex yourself if you need it for display.

Platform.name

OS identifier as a String. Returns "Windows" on Windows; the uname(2) sysname field on POSIX hosts (typically "FreeBSD", "Linux", "Darwin", etc.); "Unknown" on anything else. Win32 is checked before POSIX, so Cygwin / MSYS report the native OS.

Timer.trigger(fiber, ms)

Schedule fiber to be resumed with a TimerElapsed after ms milliseconds. Multiple pending entries per fiber are fine — each fires independently. Returns null. Throws on a non-numeric or negative ms, or when more than 32 timers are pending across the whole VM.

SFTP.available

true while the SSH connection has a usable SFTP subsystem.

SFTP.pubdir

The remote pubdir@syncterm.net path advertised by the server, or null if the extension wasn’t negotiated.

SFTP.realpath(fiber, path)

Resolve path to an absolute server path. Resumes with String or SFTPError.

SFTP.stat(fiber, path)

Stat a remote path. Resumes with SFTPStat or SFTPError.

SFTP.opendir(fiber, path)

Open a directory for iteration. Resumes with SFTPHandle or SFTPError.

SFTP.readdir(fiber, handle)

Read the next batch of entries from an open directory handle. Resumes with List<SFTPEntry> or null (EOF) or SFTPError. Loop until null, then call SFTP.close.

SFTP.open(fiber, path, flags)

Open a file. flags is a bitmask from FileFlag (see below). Resumes with SFTPHandle or SFTPError.

SFTP.read(fiber, handle, offset, count)

Read up to count bytes from handle at offset. Resumes with the bytes as a String, null at EOF, or SFTPError.

SFTP.write(fiber, handle, offset, bytes)

Write bytes to handle at offset. All-or-nothing: resumes with null on success or SFTPError.

SFTP.close(fiber, handle)

Close a handle returned by open / opendir. Resumes with null or SFTPError. After close, the handle is dead — further reads / writes / closes on it abort the calling fiber.

SFTP.mkdir(fiber, path), SFTP.rmdir(fiber, path), SFTP.remove(fiber, path), SFTP.rename(fiber, oldpath, newpath)

Mutation ops. Each resumes with null on success or SFTPError.

Null

null

Bool

true / false

Num

Num.toString form; NaN / Infinity have no Wren literal and are rejected

String

quoted with Wren-style escapes; % is always escaped to \% so output never starts an interpolation

List

[a, b, c]

Map

{key: value, …​} — keys must be hashable Wren types (Bool, Num, String, Range, null)

Range

coerced to List via .toList; serialisation is one-way (the deserialised value is a List)

Sequence

any other Sequence coerces to List via .toList

WOM.serialize(value)

Strict compact form. [1,2,3] / {"a":1,"b":2}. Aborts the fiber on unsupported types, NaN/Infinity, or cycles.

WOM.serialize(value, indent)

Strict pretty-printed form. indent is a String inserted once per nesting level (e.g. " " for two-space, "\t" for tab). Same error behaviour as the one-arg form.

WOM.serializeLossy(value)

Compact form that silently omits unsupported items from Lists and Maps; a top-level unsupported value becomes "null". Cycles still abort.

WOM.serializeLossy(value, indent)

Pretty-printed lossy form.

WOM.deserialize(text)

Parse text and return the reconstructed value. Aborts the fiber with a message containing the byte offset on syntax errors, premature end of input, trailing garbage, or a List / Map used as a Map key. Tolerates arbitrary whitespace and trailing commas inside […​] / {…​}. Accepts exactly the string-escape set the Wren compiler itself recognises.