File I/O

The tables below are generated from the interpreter's own builtin dispatch table (the fn call_builtin match statement in engine/crates/qu-interp/src/lib.rs), not written speculatively ahead of the implementation — every function listed here runs today.

> Note — WASM has no filesystem at all. Qu's browser target > (wasm32-unknown-unknown) has no native filesystem access — that's an > Emscripten-target feature, not this one. Every builtin on this page that > touches a PATH (fopen, read_csv, write_csv, ...) is native-only; a > browser build can only reach files through JS-mediated mechanisms like the > File System Access API or a plain <input type=file> read. See Book 3, "A > hard platform boundary," for the full reasoning. The "Data-Format > Conversion" builtins below (jsonify/csvify/xmlify/parse_json/ > parse_csv/parse_xml and the pairwise converters) are the one exception > on this page: they only ever touch in-memory strings, no path/file > involved, so this platform boundary doesn't apply to them.

Opening & Closing Files

fopen/close are a general-purpose text/binary file-handling pair, returning/consuming an opaque Value::File handle. mode follows MATLAB's own fopen convention. Text and binary modes are treated identically at the byte level — the b suffix is accepted for MATLAB-familiar scripts, but "r" and "rb" behave the same way internally.

> Note — "r" mode reads are a real stream, not a whole-file buffer. > Opening a file for reading no longer loads its entire contents into memory > up front — fopen(path, "r") opens a real buffered stream > (std::io::BufReader) and only reads as many bytes as read_line/ > read_all/read_char/seek/etc. actually ask for. This matters for large > files: a multi-hundred-MB (or larger) file can be opened and processed > line-by-line or byte-by-byte without ever holding the whole thing in > memory at once. Every read builtin's return values are unaffected — this > is purely an internal memory-use improvement, not a behavior change > (write/append modes were never eager-loading anything and are > untouched).

> Note — a different close exists for plotting. The bare command > close (no parentheses, used as a plot-window verb alongside pan/zoom/ > colorbar) is a separate, unrelated no-op accepted for GUI-script > compatibility in headless static exports. It lives in a completely > different match statement (the plot-command dispatch) from the > close(f) file-handle builtin documented here.

Text I/O

Every read returns Nothing — Qu's "absent" marker (composes with ??, e.g. read_line(f) ?? "done") — once nothing is left to read, except read_all, where an empty string is itself a legitimate non-exceptional result.

Interactive input

Not a file handle at all — reads one line typed by whoever is running the script right now, the way MATLAB's input/Python's input() do. Added in v0.3.0.

Writing to a handle opened in "r" mode errors clearly rather than silently no-op'ing or panicking; the same holds for every write builtin below.

Position Control & Non-Advancing Peeks

seek/tell/rewind/eof control a readable handle's read cursor directly; peek_line/peek_char/peek_byte (§ 2026-09-01) read the next unit exactly the way read_line/read_char/read_byte would, WITHOUT moving that cursor — a second peek_* call, or the very next real read_* call, sees the identical data again. Implemented as a real save-position/read/restore-position round trip around the same buffered reader seek/tell already control (not a hand-rolled one-item lookahead buffer), so it composes correctly with everything else that touches the cursor.

All of these are restricted to readable handles (the same restriction seek/tell/rewind already have) — a write-only or append-mode handle has no tracked read cursor to save/restore or report.

Three distinct peek functions — matching read_line/read_char/ read_byte's own three existing granularities one-for-one — rather than a single generic peek(): this codebase already made that same naming choice on the read side (there is no bare read()), and a lone peek() would additionally collide with the unrelated fifo collection's own .peek() method (see Data Structures), which answers a completely different question.

Reach for peek_line whenever a parser needs to look at the next line before deciding whether to actually consume it — a "does this file start with a header row?" check, or a loop that groups lines until it sees one that doesn't belong. The example below opens a three-line log file and shows that peek_line and the following read_line see the identical first line, and only the read cursor moves once a real read_line call happens:

# The three-line file this reads is written here. It used to open a

# log.txt that the chapter does not create until 700 lines further down,

# so this block failed and was dropped from the page while the build

# reported success.

w = fopen("log.txt", "w")
write_line(w, "a")
write_line(w, "b")
write_line(w, "c")
close(w)

f = fopen("log.txt", "r")
first_line = peek_line(f)          # doesn't consume anything

same_line  = read_line(f)          # sees first_line again

next_line  = read_line(f)          # only NOW does this move on

print("{first_line} | {same_line} | {next_line}")
close(f)
# a | a | b

a | a | b

peek_char/peek_byte work the same way at their own granularity — a character peek for text decisions, a byte peek for binary ones — and both compose cleanly with read_until/read_chars/read_byte on the same handle, because every one of these calls shares the same underlying cursor. The example below writes "Hello,World" to a file with no newline, then walks it back with a mix of consuming reads and non-consuming peeks, printing every intermediate value so each call's effect (or lack of one) on the cursor is visible:

f = fopen("greeting.txt", "w")
write_char(f, "Hello,World")
close(f)

g = fopen("greeting.txt", "r")
first       = read_char(g)         # "H"

peeked      = peek_char(g)         # "e" -- cursor not moved

next        = read_char(g)         # "e" again, same char peeked returned

chunk       = read_chars(g, 3)     # "llo"

next_byte   = peek_byte(g)         # 44, the byte for ',' -- still not consumed

before_comma = read_until(g, ",")  # "" -- the comma was right there, now consumed

w_byte      = read_byte(g)         # 87, the byte for 'W'

rest        = read_all(g)          # "orld"

close(g)
print("{first}{next}{chunk} peeked={peeked} next_byte={next_byte} before_comma=\"{before_comma}\" w_byte={w_byte} rest={rest}")
# Hello peeked=e next_byte=44 before_comma="" w_byte=87 rest=orld

Hello peeked=e next_byte=44 before_comma="" w_byte=87 rest=orld

Binary I/O

Typed reads/writes accept an endian= keyword argument ("little" default, or "big"), implemented with Rust's own from_le_bytes/to_le_bytes (and their _be_ counterparts) — no hand-rolled byte shuffling. A typed read returns Nothing if fewer bytes remain than the type needs.

Reach for write_bit/read_bit when a format is defined at the bit level rather than the byte level — status-flag registers, packed boolean arrays, anything from an instrument or protocol spec that talks about individual bits rather than whole bytes. They pack individual bits into bytes MSB-first; close(f) flushes and zero-pads any partial byte left pending. The example below writes four bits (1,0,1,1), which is not a whole byte, closes the file to force that flush, then reads the same four bits back and confirms only one byte was actually written to disk:

f = fopen("flags.bin", "wb")
write_bit(f, 1)
write_bit(f, 0)
write_bit(f, 1)
write_bit(f, 1)
close(f)                       # only 4 bits written -- flushed as one padded byte


g = fopen("flags.bin", "rb")
b0 = read_bit(g)
b1 = read_bit(g)
b2 = read_bit(g)
b3 = read_bit(g)
close(g)
print("{b0}{b1}{b2}{b3}")      # 1011

print(file_size("flags.bin"))  # 1 -- one byte on disk for 4 bits

1011
1

The other fixed-width types round-trip the same way, each with its own read_*/write_* pair — this is the toolset for reading and writing a binary format with a known, fixed layout: a data-logger capture, a device's native save file, or any interchange format built around fixed-width integers and floats rather than text. The example below writes one value of each width (a signed 16-bit int, an unsigned 16-bit int, an unsigned 32-bit int, and a 64-bit double) back to back, then reads them back in the same order to show the round trip is exact:

f = fopen("sample.bin", "wb")
write_int16(f, -5)
write_uint16(f, 300)
write_uint32(f, 70000)
write_double(f, 3.14159)
close(f)

g = fopen("sample.bin", "rb")
a = read_int16(g)
b = read_uint16(g)
c = read_uint32(g)
d = read_double(g)
close(g)
print("{a} {b} {c} {d}")       # -5 300 70000 3.14159

-5 300 70000 3.14159

read_int64/write_int64 and their unsigned counterparts round-trip the same way, with one real caveat worth seeing rather than just stating: every Value here is an f64, exact only up to 2^53, so a 64-bit integer past that (about 9 quadrillion) comes back rounded, not exact. write_array/read_array are the block versions of the fixed-width functions above — a whole Vec or Mat written or read in one call instead of one element at a time; a Mat is written in its own column-major order, so reading it back needs a reshape/-> (r, c) to recover the original shape (a flat file has no shape of its own):

f = fopen("sample64.bin", "wb")
write_int64(f, -123456789012)
write_uint64(f, 9007199254740993)   # 1 past 2^53 -- the exact-precision edge

close(f)

g = fopen("sample64.bin", "rb")
a = read_int64(g)
b = read_uint64(g)
close(g)
print("{a} {b}")               # -123456789012 9007199254740992 -- rounded


M = [1, 2, 3; 4, 5, 6]
write_array("matrix.bin", M, type = "int32")
back = read_array("matrix.bin", type = "int32") -> (2, 3)
print(back)                    # [1, 2, 3; 4, 5, 6] -- shape recovered via reshape

-123456789012 9007199254740992
[1, 2, 3; 4, 5, 6]

Compression & Entropy Coding

Three from-scratch entropy coders — Huffman, adaptive range coding, and rANS — plus the zlib/DEFLATE decoder read_mat and load_image already carried internally, exposed as script-callable builtins rather than left as an implementation detail only those two readers could reach.

All four take their input the same way: a Str (its UTF-8 bytes) or a Vec of numbers in 0..=255. All four decoders hand bytes back the same way too — a Vec of 0-255 numbers by default, or the decoded text as a Str with as_str = true. An encoder returns a Record rather than a bare byte string because a decoder needs the model as well as the payload; pass the whole record straight back to the matching decoder.

There is no compressor to pair with zlib_decompress yet. That is a real gap, named here rather than implied away.

A round trip through any of the three coders returns exactly what went in:

s = "hello hello hello compression world"
enc = rans_encode(s)
print(numel(enc.bytes))                    # coded length, in bytes

print(rans_decode(enc, as_str = true) == s)  # true

18
true

Directories & Paths

A script that reads a file usually has to find it first. These are the builtins that answer "where am I", "what is in here" and "which of these files do I actually want" — the last of which is list_files, and it is the one worth reading about.

list_dir and list_files divide the work between them. list_dir gives the bare names inside one directory, files and subdirectories alike, and stops there. list_files takes a whole-path pattern, walks as deep as the pattern tells it to, returns paths you can open, and never returns a directory. The second is what you want for "every HTML page under website/"; the first is what you want when you are about to look at each entry and decide.

All six above are disabled in sandboxed execution (see sandbox_mode), the same as touch and write_csv — each is capable of destroying or overwriting a file the script did not create, recycle_bin=true or not.

The wildcards list_files understands

* deliberately stops at a separator. If it did not, website/*.html would also match website/fn/add.html and the ordinary case would be wrong — which is why ** has to be spelled differently, in every shell and every language that ships a glob.

Both / and \ separate segments in a pattern, so a Windows path can be written either way, and the paths that come back use the platform's own separator.

Reading list_files's arguments

One argument is a pattern if it has a wildcard in it and a directory if it does not, so neither spelling needs a keyword to say which was meant:

list_files()                          every file in the current directory
list_files("C:/users/pc")             every file in that directory
list_files("*.html")                  by pattern, here
list_files("C:/users/pc", "*.html")   directory and pattern, given apart
list_files("website/**/*.html")       the whole subtree

filter= is the keyword spelling of the pattern. Passing both a positional pattern and filter= is an error rather than a silent choice between them.

Narrowing by size and by content

KB/MB/GB are 1024-based here, the way a file manager reports a size rather than the 1000-based SI reading. KiB/MiB/GiB are accepted as explicit spellings of those same values. A unit that is not one of these errors, rather than being read as bytes: ">2Mb" is a typo worth hearing about, and answering it as "2 bytes" would give a wrong answer that looks like a right one.

The filters run in the order that reads the fewest bytes — the name pattern first, which opens nothing; then size=, one metadata call; then contains=, which has to read the file. Pairing contains= with a pattern or a size bound is what keeps a search over a large tree cheap.

The example below makes its own files first, so it finds the same thing wherever it is run — and note what it does not do: print cur_dir(). That would put this machine's absolute path into the page, since the documentation build runs every example and keeps what it printed.

mkdir("list_demo")
write_text("list_demo/report.qu", "print(1)")
write_text("list_demo/plot.qu", "print(2)")
write_text("list_demo/notes.txt", "the needle is here")
make_file("list_demo/empty.log")

qu_files = list_files("list_demo", "*.qu")
print("{length(qu_files)} Qu files")

carrying = list_files("list_demo/*", contains = "needle")
for f in carrying
    print("carries the needle: {f}")
end for

blank = list_files("list_demo/*", size = "0")
print("{length(blank)} empty file")

2 Qu files
carries the needle: list_demo\notes.txt
1 empty file

Running Other Programs

Qu could already run *code* in another language — python_exec, js_exec, matlab_exec — but not a *program*. That is a strange hole for a language whose own build tooling is written in itself: the shell scripts under tools/ exist largely because the Qu program inside each one could not ask git a question.

Two builtins, because there are two different jobs and one call does not do both well.

A program that fails is not a Qu error. A non-zero exit comes back as success = false, not as an exception — exec("git", ("diff", "--quiet")) uses the exit code as its answer, and a language that raised on it would make that unwritable. What *does* error is being unable to start the program at all, which is a genuinely different thing.

shell's process id is not always the program's own. "minimized" and "maximized" have no API reachable from Rust's Command, so they go through cmd /C start /MIN|/MAX, and the id that comes back belongs to that launcher — which exits as soon as it has started the program. "normal" and "hidden" spawn directly and give a real, live id. Worth knowing before you store one.

On anything other than Windows, "normal" and "hidden" behave (there is no window to hide, so hidden simply means no terminal is borrowed), and "minimized"/"maximized" error rather than being quietly ignored. They are window-manager instructions with no meaning to sh, and accepting them in silence would mean a script that looks portable and is not.

Both are refused under qu run --sandbox, alongside python_exec, js_exec and matlab_exec. Starting a process is the most capability-bearing thing a script can do, and a sandbox that let one through would not be one.

r = exec("echo hello from a program", shell = true)
print("said: {trim(r.stdout)}")
print("success {r.success}, exit code {r.exit_code}")

failed = exec("exit 3", shell = true)
print("a failure is data, not an error: success {failed.success}, code {failed.exit_code}")

said: hello from a program
success true, exit code 0
a failure is data, not an error: success false, code 3

Memory-Mapped Files

Read-only, random-access mapping of a file's bytes via the memmap2 crate, without loading the file into a Vec up front — useful for jumping around inside a large file (a header at a known offset, a fixed-width record at an arbitrary index) without either an eager full read or a chain of seek calls on a fopen handle. Distinct from Value::File: an mmap handle has no read cursor to advance — every mmap_read call takes an explicit byte range. Writable mapping is out of scope; use fopen/the write builtins above for writing.

Reach for mmap_open/mmap_read instead of fopen/seek/read_bin when a program needs to jump around inside a large file at arbitrary offsets — a header at a known position, or one record out of a huge array of fixed-width records — without either reading the whole file up front or issuing a seek call for every access. The example below maps a binary file, reads its first 16 bytes as a "header," then reads 64 bytes starting at byte offset 5 * 64 as if the file were a flat array of 64-byte records, and prints both to show a single mapping serves any number of independent, arbitrary-offset reads:

# The file is written here first. Mapping one the repository does not

# carry would make this block fail, and a block that fails is dropped

# from the page while the build still reports success.

write_array("big_dataset.bin", 0 to 511, type = "u8")

m = mmap_open("big_dataset.bin")
n = mmap_len(m)
header = mmap_read(m, 0, 16)          # first 16 bytes, wherever they live

record5 = mmap_read(m, 5 * 64, 64)    # the 6th fixed-width 64-byte record

print(n)
print(header)
print(record5)

512
[0, 1, 2, 3, 4, 5, 6, 7, ... (16 elements)]
[255, 255, 255, 255, 255, 255, 255, 255, ... (64 elements)]

Polymorphic Streams: StreamFile / StreamURL

StreamFile(path, [mode]) and StreamURL(url) (§ StreamFile/StreamURL polymorphic streams, 2026-08-31) are two constructors that produce values exposing the same method names — read_line/read_all/eof/close — so code written against "a stream" doesn't need to know or check which concrete kind it was handed:

StreamURL is fetch-then-wrap, not incremental network streaming — a deliberate, investigated choice, not a shortcut. ureq's response body IS a real Read-implementing stream, but reusing fopen's exact streaming-reader plumbing against it would require widening FileHandleState's reader field to a boxed trait object AND handling HTTP responses that have no Content- Length at all (chunked transfer encoding) — a real FileHandleState redesign, not a reasonable extension of it. So StreamURL fetches the whole body up front (exactly what http_get already does) and serves it back through the same method names as a read-only in-memory stream — every method above behaves identically to the file side, just without the "hasn't downloaded yet" state a genuinely incremental reader would have.

The whole point: one function, written once against the shared method names, works unmodified against either kind. The example below defines a drain function once, using only eof/read_line/close, and calls it against a local file opened with StreamFile and a remote resource opened with StreamURL — neither the function body nor the caller needs to know which kind of stream it was handed:

n = fopen("notes.txt", "w")
write_line(n, "line one")
write_line(n, "line two")
close(n)

function drain(s)
    total = ""
    while not eof(s)
        total = total + read_line(s) + "|"
    end while
    close(s)
    return total
end function

a = drain(StreamFile("notes.txt"))
print(a)                                    # line one|line two|


b = drain(StreamURL("https://example.com/"))
print(length(b) > 0)                        # true -- some HTML came back

line one|line two|
true

CSV

read_csv/write_csv operate directly on a path — no fopen handle involved; they open/read/write the file internally in one call.

table.load/table.write are part of a small, closed table./timer. "namespace-dot" alias set (§ ergonomic API layer, 2026-08-31): the parser recognizes exactly the token sequence table . load ( / table . write ( and rewrites it, at parse time, straight to read_csv(...)/write_csv(...) — evaluation is byte-identical, since it's literally the same call. table is not a real namespace value; it still works as an ordinary variable name (table = 5) and the existing table(...) table-constructor call is completely unaffected (that's a different token shape — no . involved).

Native Modules: xlsx and codec

These are not builtins, and builtins() does not list them. They are modules compiled into the engine, and a program reaches them through import, which opens their names and leaves the qualified path available at the same time:

import xlsx
names = sheets("book.xlsx")        # opened by the import

names = xlsx.sheets("book.xlsx")   # qualified, always available

Where the bare name would be ambiguous it is refused rather than guessed at. xlsx offers a read and so does the language, so a bare read after import xlsx is an error naming the fix — write xlsx.read(...) for the module's, or drop the import to get the builtin back. import nope names the modules a build actually has, which is the reliable way to find out.

Spreadsheets: xlsx

A round trip, which is also the way to see what headers=false does — the header row comes back as data under positional column names:

import xlsx

t = table(city = ("Aachen", "Bonn", "Cologne"), pop = (249, 331, 1087))
xlsx.write("cities.xlsx", t, sheet = "Cities")

print(xlsx.sheets("cities.xlsx"))          # ("Cities")

print(xlsx.read("cities.xlsx"))            # a Table, city/pop

print(xlsx.read("cities.xlsx", headers = false))

("Cities")
city      pop
-------  ----
Aachen    249
Bonn      331
Cologne  1087
A        B   
-------  ----
city     pop 
Aachen   249 
Bonn     331 
Cologne  1087

Audio: codec

The readers take src as either a path (string) or the file's bytes as a Vec of whole numbers 0-255 — a script that already has the bytes, from a socket or an archive, should not have to write a temporary file to use them, and the two can never be confused because a FLAC stream starts with the bytes fLaC.

The WAV writer is split in two for the same reason, pointed the other way: codec.write_wav writes a file, and codec.encode_wav hands back the bytes for a script that is going to send them somewhere rather than store them. Only WAV is written — see the note below the table for what is not.

flac_info needs no split — a header is a header. The three decoders differ only in which format they read: they return the same shapes, scale to the same range, and a script that handles one handles all three.

Bit depth and dither are named, never defaulted

depth has no default because the depth is what decides how much of the signal survives the write, and a default would be the library quietly choosing that for you.

dither is required at depth=16 specifically, and leaving it out is an error rather than a silent truncation:

import codec

codec.write_wav("out.wav", x, depth = 16)
# error -- depth = 16 quantises 64-bit samples down to 16 bits, and doing

# that without saying how is an error: silent truncation of audio is

# audible. Name dither = "tpdf" or dither = "none".

Samples are 64-bit floats inside a Signal, so 16-bit is always a reduction, and it is the depth where the difference is plainly audible — rounding alone leaves harmonic distortion on fades and quiet passages. "tpdf" adds ±1 LSB of triangular noise, which trades that distortion for a flat noise floor uncorrelated with the signal; "none" is plain rounding, which is a legitimate choice as long as it is a *choice*. The dither is drawn from the interpreter's own generator, so seed(n) makes a dithered write reproducible.

depth=24 does not require the argument (it accepts it), and depth=32 refuses it: 32-bit float has no quantisation step, so there would be nothing for a dither to do.

import codec

a = codec.decode_wav("take.wav")            # a stereo file

codec.write_wav("take24.wav", a.channels, depth = 24)
codec.write_wav("take16.wav", a.channels, depth = 16, dither = "tpdf")

A round trip at a file's own depth is exact, not approximate: the scale is 2^(depth-1) in both directions, a power of two, so the integers come back as the integers they were. The one asymmetry is the format's — two's complement has no +2^(depth-1), so a sample of exactly +1.0 clips to one step below full scale, while -1.0 is exact.

Not written, and not silently implied covered: RF64 (the >4GB WAV variant), and FLAC/OGG/MP3/AIFF/CAF encoding. hound has no RF64 support in either direction and claxon is a FLAC *decoder* only, so each of these means a from-scratch container implementation — exactly what IMPL.md §7 exists to prevent. Reading FLAC, MP3 and WAV is unaffected; it is only the write direction that stops at WAV.

None of the codec examples here are run by the build: they need an audio file, and the repository carries none.

import codec

info = codec.flac_info("take.flac")
print("{info.fs} Hz, {info.channels} ch, {info.bits} bit")

Overloads: codec.decode_flac

What comes back depends on how many series the call produces, because there is no one type that fits both without lying about one of them.

Case: one series — mono, or channel=

src is a mono file; channel, when given, picks one channel out of any file, numbered from 0. Returns a Signal: the sample rate travels with the samples, so spectrogram/welch/sosfilt need no second argument. That is the whole reason Signal exists, and it is the common case.

import codec

x = codec.decode_flac("take.flac", channel = 0)
spectrogram(x)

Case: several series — multi-channel

src is a file with more than one channel; channel is absent, so no single series is picked out. Returns a Record with fields: fs (Num, the sample rate in Hz), bits (Num, bits per sample), frames (Num, samples per channel), channels (List of Signal, one per channel, each already carrying the rate — so a.channels[0] goes straight into anything that takes a signal, with no reassembly needed). A Signal is one series and a Mat has nowhere to put the sample rate, which is why this form cannot hand back either of them.

import codec

a = codec.decode_flac("stereo.flac")
print("{a.fs} Hz, {len(a.channels)} channels, {a.frames} frames")
welch(a.channels[0])

Data-Format Conversion (JSON / CSV / XML)

read_csv/write_csv above and save/save_all/load (see Collections, Strings & Data Frames for the json_to_value/"type"-tag shape save/load use) all read/write a FILE. The builtins below (§ data-format conversion builtins, 2026-09-01) are the same conversions as plain in-memory STRINGS instead — for building a request body, embedding data in another format's document, or converting between formats without ever touching disk. Two primitives per format (xify(value) -> str / parse_x(str) -> value), plus six pairwise converters. Four of the six are one-line compositions of those primitives — e.g. json2csv(s) is exactly csvify(parse_json(s)) — not four independent implementations. The other two, csv2json and xml2json, deliberately do not go through jsonify: they produce a plain JSON array of row objects (the shape most external JSON consumers expect) rather than jsonify's own {"type":"table", ...} envelope — see their table entries below for the exact contract. A conversion that doesn't make sense for the input's shape (a bare number has no CSV shape; a live handle like a worker or mutex has no meaning in any of these formats) is a clear, named error, not a panic or a silently wrong result.

Overloads: parse_json

Case: a jsonify/save envelope

str carries a top-level "type" string field — the tag jsonify/save attach. Returns the exact typed Value that tag names, reconstructed in full, not a generic guess from the JSON's own shape.

env = jsonify(3 + 4j)
back = parse_json(env)
print(env)          # {"type":"complex","re":3.0,"im":4.0}

print(type(back))   # complex

print(back)         # 3 + 4j

{"type":"complex","re":3.0,"im":4.0}
complex
3 + 4j

Case: ordinary JSON, no envelope

str is plain JSON from anywhere else — an HTTP API response, hand-written JSON, or the same envelope with its "type" tag stripped off. Mapped in generically instead: a bare object becomes a record field-for-field, so the identical re/im pair that named a Complex above comes back as a plain record once the tag naming it is gone.

env = jsonify(3 + 4j)
plain = replace(env, "\"type\":\"complex\",", "")
v = parse_json(plain)
print(plain)         # {"re":3.0,"im":4.0}

print(type(v))       # record

{"re":3.0,"im":4.0}
record

The Value<->XML mapping

XML had no support anywhere in Qu before this (via the quick-xml crate — see engine/crates/qu-interp/Cargo.toml's own comment for why). Every value serializes to one XML element named after its type (<num>, <vec>, <table>, ...) — the direct analogue of jsonify's own "type" tag, just moved from a JSON object key to the thing XML tags things with (an element name). A few shapes get a genuinely XML-native structure instead of a mechanical port of the JSON one:

• Table is row-oriented, not JSON's column-major arrays: one <row> per table row, with one child element per column inside it, named after the column. A <columns> list up front declares column order and each column's kind ("num"/"str") — necessary, not decorative: without it, a text column that happens to hold only numeral-looking values ("007") would be indistinguishable from a numeric column on the way back in.
• Model/Record/Dict fields become child elements NAMED after the field (<coef>...</coef>), each wrapping that field's own self-describing node — the XML analogue of jsonify's "object key -> recursively-serialized value" choice for these.
• A Table column name or Record/Dict/Model field name that isn't a legal XML element name ([A-Za-z_][A-Za-z0-9_]*) is a clear xmlify error naming the offending name — the practical way to hit this is a read_csv/CSV-text header with a space in it (csv2xml), since every name that originates from real Qu source already satisfies the check.

See engine/crates/qu-interp/src/xml_ops.rs's own module doc comment for the complete variant-by-variant mapping table.

The example below builds a small two-row Table from CSV text, converts it to XML with xmlify to show the <columns>/<row> shape described above, parses it back with parse_xml to confirm the round trip preserves the data, and then runs the same CSV text through csv2json — printed here to make the point from the table above concrete: the result is a plain array of row objects, not jsonify's type-tagged envelope:

t = parse_csv("name,age\nAlice,30\nBob,25\n")
print(xmlify(t))
# <table>

#   <columns>

#     <column kind="str">name</column>

#     <column kind="num">age</column>

#   </columns>

#   <row>

#     <name>Alice</name>

#     <age>30</age>

#   </row>

#   <row>

#     <name>Bob</name>

#     <age>25</age>

#   </row>

# </table>


back = parse_xml(xmlify(t))
print(back.name[0])   # Alice


j = csv2json("product,price\nWidget,9.99\n")
print(j)               # [{"product":"Widget","price":9.99}]

<table>
  <columns>
    <column kind="str">name</column>
    <column kind="num">age</column>
  </columns>
  <row>
    <name>Alice</name>
    <age>30</age>
  </row>
  <row>
    <name>Bob</name>
    <age>25</age>
  </row>
</table>
    ... 2 more lines

jsonify/parse_json are the JSON side of the same pair csvify/parse_csv and xmlify/parse_xml already show above. Of the pairwise converters not shown elsewhere on this page, json2xml, xml2csv, and csv2xml are each exactly the one-line composition their own table entry says they are; xml2json is the row-object conversion csv2json just demonstrated, applied to XML input instead of CSV:

The next example chains every converter on this page against the same two-row table, in both directions, to demonstrate that the whole set forms a connected graph — CSV to JSON, JSON back to CSV, CSV to XML and back, JSON to XML and back — and that parse_json at the very end can still recover a real Table even though the JSON it's reading came from xml2json's row-object shape rather than jsonify's own envelope:

t = parse_csv("product,price\nWidget,9.99\nGadget,4.50\n")

csv_text = csvify(t)
json_text = jsonify(t)

back_from_json = json2csv(json_text)   # csvify(parse_json(json_text))

print(back_from_json)

xml_from_csv = csv2xml(csv_text)       # xmlify(parse_csv(csv_text))

csv_from_xml = xml2csv(xml_from_csv)   # csvify(parse_xml(xml_from_csv))

print(csv_from_xml)

xml_from_json = json2xml(json_text)    # xmlify(parse_json(json_text))

json_from_xml = xml2json(xml_from_json) # the row-object array, not jsonify(parse_xml(...))

parsed = parse_json(json_from_xml)      # parse_json accepts that shape too -- back to a real Table

print(nrow(parsed))                     # 2

product,price
Widget,9.99
Gadget,4.5

product,price
Widget,9.99
Gadget,4.5

2

See catalog/qu_format_conversion.qu for a fuller worked demo (JSON/CSV/XML round trips plus two pairwise converters on real sample data, with printed output proving correctness field-by-field).

Worked examples

The most basic file-writing pattern in Qu: open a handle in "w" mode (truncate-or-create), write one line at a time with write_line, and close the handle when done to flush it to disk. This is the shape almost every logging or report-writing script starts from. The example prints file_size afterward just to make the write's effect on disk visible:

f = fopen("log.txt", "w")
write_line(f, "run started")
write_line(f, "value = " + str(42))
close(f)
print(file_size("log.txt"))    # 23 -- "run started\n" + "value = 42\n"

23

Reading it back: read_line returns Nothing at EOF, but Qu today has neither a source-level nothing literal nor ==/!= support for two Str operands (compare's catch-all falls back to as_num(), which errors on a string — the same pre-existing gap noted next to contains/indexof in Collections, Strings & Data Frames), so an EOF-sentinel-comparison loop isn't expressible yet. For a known number of lines, a bounded loop works cleanly; for an unknown number, read_all is the more honest tool today:

f = fopen("log.txt", "r")
for i = 0 to 1
    print(read_line(f))
end for
close(f)

g = fopen("log.txt", "r")
print(read_all(g))
close(g)

run started
value = 42
run started
value = 42

Reading a whole CSV straight into a Table (no fopen needed) and working with it using the Data Frame builtins from Collections, Strings & Data Frames, then writing a filtered subset back out to a second CSV file:

The file is written here before it is read, so the example runs anywhere — including a fresh clone. It used to open a measurements.csv that no part of the repository created, which meant the block could not run, and a block that cannot run is dropped from the rendered page without the build reporting anything: the page shipped with the example missing and the build said it succeeded.

measurements = table(
    x = [-1.5, 0.5, 2.0, -0.25, 3.75],
    sensor = ["a", "b", "a", "c", "b"]
)
write_csv(measurements, "measurements.csv")

df = read_csv("measurements.csv")
print(nrow(df))
print(describe(df))
write_csv(filter(df, df.x > 0), "positive_only.csv")
print(read_all_text("positive_only.csv"))

5
stat         x
-----  -------
count        5
mean       0.9
std    2.03562
min       -1.5
25%      -0.25
50%        0.5
75%          2
max       3.75
x,sensor
0.5,b
2,a
    ... 1 more lines

A minimal binary I/O round trip: open a handle in "wb" mode, write a 32-bit integer followed by a 32-bit float, close it, then reopen the same file in "rb" mode and read the two values back in the same order they were written. This is the pattern every other binary example on this page builds on — the typed read_*/write_* pairs only work correctly when the read order matches the write order, since there's no type tag on disk to check against:

f = fopen("record.bin", "wb")
write_int32(f, 12345)
write_float(f, 3.5)
close(f)

g = fopen("record.bin", "rb")
n = read_int32(g)
x = read_float(g)
close(g)
print("n = {n}, x = {x}")

n = 12345, x = 3.5

read_all_text(path) is the one-call shortcut for "give me this whole file as a string" — no fopen/close pair needed when a script only ever wants to read a file once, in full, such as loading a small config or notes file at startup. The example below writes a two-line file the normal way, then reads the whole thing back in one call:

n = fopen("notes.txt", "w")
write_line(n, "line one")
write_line(n, "line two")
close(n)
print(read_all_text("notes.txt"))
# line one

# line two

line one
line two

When a file holds a run of same-typed numbers rather than one fixed-width record, read_values/read_array read all of them in a single call instead of looping over read_double/read_int32/etc. one value at a time. read_values(f, type, n) reads n values of the given type from an already-open handle (useful mid-stream, alongside other reads on the same file); read_array(path, type=) skips fopen entirely and reads a whole file as one typed array in one call. The example below writes three 64-bit doubles, checks the file's size with file_size before opening anything, then reads the same three numbers back both ways to show they agree:

f = fopen("temps.bin", "wb")
write_double(f, 20.5)
write_double(f, 21.0)
write_double(f, 19.8)
close(f)

print(file_size("temps.bin"))            # 24 -- 3 doubles, 8 bytes each


g = fopen("temps.bin", "rb")
vals = read_values(g, "f64", 3)
close(g)
print(vals)                              # [20.5, 21, 19.8]


whole = read_array("temps.bin", type="f64")
print(whole)                             # [20.5, 21, 19.8]

24
[20.5, 21, 19.8]
[20.5, 21, 19.8]

A file of fixed-size records — logger output, an instrument's native save format, anything with a repeating struct layout — is read with read_struct/read_structs instead of unpacking each field by hand. fields is a list of (name, type) pairs describing one record's layout, in byte order; read_struct(f, fields) reads exactly one record and returns it as a record value with one field per name, while read_structs(f, fields, n) reads n of them into a Table, one column per field, which is the more useful shape once there are enough records to want to work on them column-wise. The example below writes two (f64, u16) records back to back, then reads first one and then both, column-wise:

f = fopen("records.bin", "wb")
write_double(f, 0.0)
write_uint16(f, 12)
write_double(f, 0.5)
write_uint16(f, 15)
close(f)

fields = [["t", "f64"], ["ch", "u16"]]

g = fopen("records.bin", "rb")
one = read_struct(g, fields)
close(g)
print(one.t)                             # 0

print(one.ch)                            # 12


h = fopen("records.bin", "rb")
tbl = read_structs(h, fields, 2)
close(h)
print(nrow(tbl))                         # 2

print(tbl.ch)                            # [12, 15]

0
12
2
[12, 15]

Interop with MATLAB doesn't require a MATLAB installation just to read data it produced: read_mat(path) reads a .mat file directly (via the matfile crate) and hands back every saved variable as a field on one record, named after the variable, so .mat files from a lab instrument or an existing MATLAB pipeline can be consumed without leaving Qu. The example below reads a .mat file containing a single saved variable named temperature and prints its values:

Not run by the build, and it cannot be: Qu reads MATLAB files but has no writer for them, so this example cannot create its own input the way the CSV one above does. It needs a .mat produced by MATLAB or SciPy.

vars = read_mat("measurements.mat")
print(vars.temperature)                  # [20.5, 21, 19.8]

argv() and getenv(name) are how a Qu script reads its own invocation context — command-line arguments and environment variables — the same information a shell script would get from $1/$2 and $MY_VAR. Every argument after a literal -- on the command line becomes one element of argv()'s list; getenv reads one named environment variable, coming back as none (Qu's absent-value marker, composing with ??) if it isn't set. The example below assumes the script was invoked as qu run analyse.qu -- data.csv 1000:

args = argv()
print(length(args))                      # 2 -- "data.csv" and "1000"

print(args)                              # ("data.csv", "1000")


level = getenv("QU_LOG") ?? "info"
print(level)

0
()
info

write_report(path) bundles everything a script has printed and plotted so far — printed output, tables, and any figures produced up to that point in execution — into one standalone HTML file with nothing linked from outside it, suitable for emailing or archiving without also shipping a folder of image files. The example below computes a small sum, prints it, then writes and confirms the report file:

x = 1:10
print("sum = " + str(sum(x)))
write_report("summary.html")
print(file_exists("summary.html"))       # true

sum = 55
true

Running another language inline is for the case where a library or routine simply has no Qu equivalent yet: python_exec/js_exec/matlab_exec all share one contract. code (string) is the guest-language source to run. vars= (optional, a Record/Dict) arrives as ordinary variables in the guest — built with Qu's {name=value, ...} record syntax, not JSON-style {"name": value}. An injected output-path variable (_qu_output_path for Python and JavaScript, qu_output_path for MATLAB — see the note above on why that one can't take a leading underscore) is where the guest writes a JSON result, and the call always returns a record of {stdout, stderr, success, exit_code, result}. The example below runs a one-line Python snippet with no injected variables, then a second Python snippet that receives x via vars= and returns a computed result, then the same pattern once in JavaScript:

py = python_exec("result = 1 + 1\nimport json\njson.dump(result, open(_qu_output_path, 'w'))")
print(py.result)                         # 2


py2 = python_exec("import json\nresult = x * 2\njson.dump(result, open(_qu_output_path, 'w'))", vars={x=21})
print(py2.result)                        # 42


js = js_exec("const fs = require('fs'); fs.writeFileSync(_qu_output_path, JSON.stringify(1 + 1));")
print(js.result)                         # 2

2
42
2

matlab_exec follows the exact same contract — matlab_exec(code, [vars=]), same {stdout, stderr, success, exit_code, result} return shape, code writing its result to the injected qu_output_path variable — but actually running it requires a working local MATLAB installation with a valid license, which this environment does not currently have (the license here has expired), so no runnable example is included for it. A failed run does not panic: success comes back false and stderr carries MATLAB's own error text (a license error, in this environment's case), the same "describe the failure, don't crash" contract every other guest-language failure follows.

More functions