API

The modules, each a page: what it exposes, with its type and its documentation.

• array: Arrays: a fixed number of elements, each reached at once by its index (from 0).
• bench: Benchmarks, run by heff bench, as Go’s testing.B runs them.
• bits: Bits, the prelude’s: a bitstring of any length, not changed once made — a type of its own beside Bytes, which are whole bytes.
• boc: Behaviour-oriented concurrency (Cheeseman et al., OOPSLA 2023), on std.domain: a cown holds a value; when c body spawns a behaviour, which later, once, with every cown of c its own at once, is given what they hold and gives back what they are to hold after it.
• browser.dom: For the page’s DOM: its operations, each taking the evidence that the DOM is in the program’s effect (as state’s get does).
• browser.gpu: For work run on a GPU: a device held by a with, buffers on it held by withs of their own, written and read, a kernel loaded from its code, and a kernel dispatched over a grid of workgroups with buffers bound.
• browser.gpu.canvas: A <canvas> of the page shown a GPU buffer’s pixels: where the DOM’s effect and the GPU’s meet.
• browser.gpu.kernel: A GPU kernel written in heff, by combinators: an expression of the kernel is an Exp a, of a Float32, an Int32, a UInt32 or a Bool, built by the prelude’s operators (x + y, x * y, -x, x /. y of floats, x / y and x % y of integers) and this module’s functions (lit, lessThan, both, either, negation, convert, load, length); a statement is an operation of the effect stmt, so that a kernel’s body is a Co stmt Unit written with do: define, store, when, ifElse, forRange, globalId.
• browser.gpu.run: A kernel of browser.gpu.kernel run on a GPU: printed as WGSL (browser.gpu.wgsl), loaded, and dispatched over as many workgroups as n invocations take, its buffers bound in order.
• browser.gpu.wgsl: A kernel of browser.gpu.kernel printed as WGSL, WebGPU’s: its buffers bound at @group(0), in order, then the entry point, its body printed by a handler of stmt (co’s Handler) whose state is the next fresh name and the lines printed.
• browser.http: For a page’s HTTP requests: a request sent by the browser’s fetch, its body and its response’s bytes, and the response, or why none came.
• browser.js: JavaScript’s strings: JSString, text as JavaScript has it, UTF-16, beside a String, which is bytes (UTF-8 as a literal writes it, but any byte may be in one).
• browser.remote: An API over HTTP, a page’s side: a client’s transport by the browser’s fetch (browser.http), each call a POST of its frame to the server, std.remote’s (C), the answer the response’s body.
• builtin: The types the language answers with itself: every other module imports this one without writing it.
• bytes: Bytes: bytes, not changed once made — a body, what a socket reads, a file’s content where it is no text — a type of its own beside String, which is text (though any bytes may be in one).
• check: Tests: unit tests, properties and models, run by heff test.
• cml: Concurrent ML (Reppy), on std.domain: threads that meet at channels, and events, their synchronous operations, composed before one of them is committed.
• co: Computations with higher-order effects, and their handlers.
• custodian: Custodians, as Racket has them: a custodian has things in its custody — what a with holds — what ends a thing given to it, and the custodians made under it, and shutdown ends all of it at once.
• exception: For failing and recovering: throw abandons the rest of the computation with a word of why (an err: a message, a diagnostic), and recover hears it.
• ffi: C’s types as values, and an effect’s operations that C functions do: a description, which the compiler reads where it compiles the program for C, and makes the provider’s side of — how an operation’s fields are given to the function, what its result is made into, and the dispatch — in place of the same written by hand in the module’s M.provider.c.
• float32: Float32: IEEE 754’s single precision, 24 bits of precision, from about 1.4e-45 to 3.4e38 — each operation’s result rounded to one, as C’s float and JavaScript’s Math.fround round.
• generator: Generators of random values, for properties, after Hedgehog: a generator makes a value together with every smaller value to try instead of it, a rose tree, so that each generator shrinks, and a generator made of others shrinks by theirs — there is no shrink to write apart, and none to get out of step with the generator.
• int: Int’s bits: an integer’s, as two’s complement has them, its sign extended for ever (as Python’s are) — the and, or and xor of two, and shifts.
• int16: Int16: the integers from -32768 to 32767, wrapping around as the machine’s do (two’s complement): fromInt 32768 is -32768.
• int32: Int32: the integers from -2147483648 to 2147483647, wrapping around as the machine’s do (two’s complement): fromInt 2147483648 is -2147483648.
• int64: Int64: the integers from -9223372036854775808 to 9223372036854775807, wrapping around as the machine’s do (two’s complement): fromInt 9223372036854775808 is -9223372036854775808.
• int8: Int8: the integers from -128 to 127, wrapping around as the machine’s do (two’s complement): fromInt 128 is -128.
• json: JSON (RFC 8259), written in heff: a value, read from its text (parse), written back (stringify, as JavaScript’s JSON.stringify writes it), read into (field, at, str, …) and built (obj, kv, num, jstr).
• list: The operations of lists, which every module has by the name List without importing it: List.map, List.foldl, List.length.
• manifest: What a project’s package.hf says, as types: package : Package; and what an app/X/build.hf says, build : Build.
• parallel: For two computations run in parallel: Parallel l r k runs l and r in parallel, and goes on with k of their answers.
• prelude: The basic types and what is done with them: Nat, Empty, pairs, Maybe, Either, Bytes (bytes has its operations); Bool, Unit and lists (builtin has them), lists’ :: and ++ (their other operations are List’s); numbers and strings, by the primitives, with their operators.
• regex: Regular expressions, of RE2’s (Go’s) syntax, matched as Go’s regexp matches: leftmost first, each | and repetition preferring what it is written to prefer, in time linear in the string (no backtracking: the threads of an NFA run side by side, as RE2’s do).
• remote: An effect whose operations another program does: an API, shared by a client and a server, each of them a handler of the same effect.
• resource: A host’s thing held by a with, the same for every effect: an open file, a socket, a process, a canvas — what must be let go of.
• rune: Rune: a code point of Unicode, a 32-bit value, as Go’s rune is.
• state: For a state: one value, got and put.
• std.adler32: Adler-32, the checksum of RFC 1950 that zlib keeps: two sums of the bytes, each modulo 65521, the largest prime below 65536 — a, 1 and each byte, and b, each a so far — as b times 65536 and a, Go’s adler32.Checksum.
• std.base32: Base32 (RFC 4648): bytes written as text, each five of them as eight digits of 32, the text padded with = to a multiple of eight.
• std.base64: Base64 (RFC 4648): bytes written as text, each three of them as four digits of 64, A-Z, a-z, 0-9 and two more, the text padded with = to a multiple of four.
• std.cli: A command line, described once: what each command takes is a term of Args, and the words given are read by it, the usage and each command’s help written from it, and what the word being written completes to said by it (the shells’ scripts ask the program).
• std.cli.interactive: A program’s commands, as std.cli says them, learned by using them: a list of the commands with what each does, filtered by what is typed; a command picked is a form of its positionals and its flags — each with what it is, its values, whether it is wanted — and the command line the form makes, shown as it is filled in, with what is wrong with it yet.
• std.crc32: CRC-32, the checksum of IEEE 802.3 that zlib, gzip, zip and PNG keep: the bytes’ remainder by the polynomial 0x04c11db7, its bits reflected (0xedb88320), begun at and inverted by 0xffffffff — Go’s crc32.ChecksumIEEE.
• std.csv: CSV (RFC 4180), read and written as Go’s encoding/csv reads and writes it with its settings left as they are: a record a line, ended by a line feed or a carriage return and a line feed, its fields between commas.
• std.datetimezone: Time zones: which offset from UTC (std.offset) the clocks of a place are at when — +08:00 in Taipei all year round, -05:00 in New York in winter and -04:00 in summer — and so which instant a date and time on its clocks (std.localdatetime) is.
• std.deque: Double-ended queues: a sequence pushed onto and popped from at either end, persistent.
• std.doc: Pretty-printing documents: Wadler’s algorithm as Haskell’s prettyprinter has it (layoutPretty, ribbon 1.0), so that the formatter, and any other code that lays text out, can be written in heff.
• std.domain: For domains, as OCaml 5’s: computations run truly at once, each on a thread of the system of its own, and what synchronises them — cells every domain reads and writes (Atomic), mutexes and conditions.
• std.duration: Durations: fixed lengths of time, exact to the nanosecond, of any size, as an Int is.
• std.file: Files open, read and written a piece at a time: a file opened by open and closed by close, or held by a with that closes it when its body ends (with f := File.open path do ...); read a chunk or a line at a time, written, sought in; what the system says of it (stat); and the standard streams, as open files.
• std.filesystem: For files by path: reading one, writing one, listing a directory, removing one, making one read-only, copying one, moving one, putting one in place of another; what a path is, its status and its mode; a temporary directory or file.
• std.flate: DEFLATE (RFC 1951), decompressed: the compressed data of zlib, gzip, zip and PNG, as Go’s compress/flate reads it — its blocks stored, of the fixed Huffman codes or of codes of their own, until the one marked last.
• std.fuel: Fuel: a computation run on so much of it, stopped where it runs out — a watchdog, killing a runaway computation, not a time slice.
• std.glob: Glob patterns, as a shell writes them: src/**/*.hf, read once (compile), then matched against a path (matches) or expanded from a directory into the paths there that match (glob).
• std.gzip: gzip (RFC 1952), decompressed: members, one after another, each DEFLATE data between a header and the CRC-32 and the length of what it holds, as Go’s compress/gzip reads them — the bytes of all the members, one after another.
• std.hashmap: Maps from keys to values by the keys’ hashes: a hash array mapped trie (HAMT), as Clojure’s, Scala’s and Haskell’s unordered-containers’ maps are.
• std.hashtable: Maps from keys to values by the keys’ hashes, in flat arrays: open addressing, as Rust’s, Go’s and Python’s tables are.
• std.heap: Heaps, by an order of their elements: a priority queue, its least element always at hand.
• std.hex: Hexadecimal (RFC 4648’s base16): bytes written as text, each as two digits of 16, 0-9 and a-f, the high four bits first, as Go’s encoding/hex writes them.
• std.hmac: HMAC, the message authentication code of RFC 2104: a hash of a message and a secret key, which only one who has the key can make, so that a message whose code is right was not made or changed by anyone else.
• std.html: HTML’s escapes of text: escape writes the five characters that would be read as markup, &, <, >, ' and ", as references, and unescape reads every reference back, as Go’s html package does (EscapeString, UnescapeString): the numeric ones, é and é, and the named ones, all of HTML5’s.
• std.http: For HTTP requests: a request sent, and its response, or why none came.
• std.http.bocserver: For an HTTP/1.1 server on boc’s behaviours: a listener’s connections served at once, as many as come, each a cown of its own, each step of each a behaviour — a request parsed and handed to the handler, a response written, the next request read — and every wait (an accept, a read, a write) an act awaited (BOC.await), so no domain and no cown is held while a client is slow.
• std.http.cmlserver: An HTTP/1.1 server of many connections at once, on cml’s threads: a listener’s connections each served by a thread of its own, by std.http.server’s serveConnection, the others served meanwhile.
• std.http.server: An HTTP/1.1 server, written over std.net’s sockets: a listener’s connections accepted one at a time, each one’s requests read in turn — the request line, the headers, and a body of the length its Content-Length says — each given to a handler, and its response written with its length, the connection kept for the next request unless it is to be closed (HTTP/1.0, or Connection: close), and closed by the with holding it when it is done.
• std.instant: Instants: points on the time line, the same everywhere, to the nanosecond — what std.time’s clock tells, and what no calendar or clock on the wall does alone.
• std.io: For the standard streams, stdio: what a program writes, to its output (write, print, a line) and to its error stream (writeErr, printErr), and all of its input (readStdin).
• std.localdate: Dates of the ISO calendar — the proleptic Gregorian one, of today, taken back before it was made and on without end — with no time of day and no zone: a date on a calendar on the wall, the 29th of February 2024, which is no instant, as it begins at a different one in each place.
• std.localdatetime: A date and a time of day together, with no zone: 2024-02-29T15:04:05 on a calendar and a clock on the wall, which is still no instant, as it comes at a different one in each place — an offset from UTC (std.offset) makes it one, a std.offsetdatetime.
• std.localtime: Times of day, to the nanosecond, with no date and no zone: a time on a clock on the wall, 15:04:05, which is no instant, as it comes every day, at a different one in each place.
• std.map: Maps of keys to values, whichever they are: a theory of what std.ordmap, std.hashmap and std.hashtable each do, so that a definition written once works on any of them, and a program picks one by its type.
• std.math: The functions of a float: the trigonometric ones (of an angle in radians), the exponential and the logarithm, powers, rounding, and the constants pi and e (sqrt and floor are the prelude’s), and the float a decimal is, correctly rounded (fromDecimal; a Float32’s is float32’s).
• std.md5: MD5, the hash of RFC 1321: any bytes to 16 bytes.
• std.mime: Media types (MIME types, RFC 2045 and RFC 6838): the type of a file by its extension (typeByExtension), the extensions of a type (extensionsByType), and a type with its parameters read from its text (parseMediaType, RFC 2045 §5.1 and RFC 2231’s continuations and encodings) and written back (renderMediaType).
• std.multipart: Multipart bodies (RFC 2046 §5.1), and forms sent as one, form-data (RFC 7578): a body read into its parts (parse) and written of them (render), each part its headers and its body.
• std.net: For TCP sockets: a connection made to a host and a port, or a port listened on and its connections accepted; bytes read from a connection and written to it; a connection’s ends and where they are.
• std.offset: Offsets from UTC: how far a clock on the wall is ahead of UTC, or behind it, fixed — +08:00 in Taipei all year round, -05:00 in New York in winter — in whole seconds, within 18 hours either way.
• std.offsetdatetime: A date and time of day at an offset from UTC: 2024-02-29T15:04:05+08:00, what a clock on the wall said where the clock was 8 hours ahead of UTC — an instant (std.instant), and how it was read there.
• std.ordmap: Maps from keys to values, by an order of the keys: a balanced (AVL) tree, so a lookup, an insertion or a deletion takes as many steps as the log of the size.
• std.path: Paths, a type of their own: where a file is, read from a string in a style — Posix (/a/b) or Windows (C:\a\b, \\server\share\a, either slash read) — and written back in one.
• std.period: Periods: amounts of time a calendar counts — a year, a month, a week, a day, an hour — not fixed lengths: a month after January 31 is 29 days on in 2024 and 28 in 2023, so a period has no length until it is laid on a date, and is no std.duration.
• std.process: For the process: its arguments, its environment, where its program is and where it runs, the commands it runs — to their end, or started beside it, held by a with, spoken to and waited for — and how it ends.
• std.progress: For saying what a program is doing: its tasks, a tree of them, each with how many of its items are done, of how many — as zig’s std.Progress has them.
• std.random: Random numbers, pure: a generator is a value, Random, and each draw gives what it drew and the generator to draw the next from — the same generator always draws the same.
• std.rational: Rationals: exact fractions of integers, as Racket’s exact numbers are, of any size, as an Int is.
• std.reactor: For outside operations begun now and finished later: what lets a scheduler’s threads go on while one of them waits on a socket, a name being resolved or an HTTP request.
• std.reference: For a cell of the world: made with its first value, read, written.
• std.remote: An API over HTTP, the C backend’s side: a server’s requests answered by the API’s real handler, over std.http.server, and a client’s transport by std.http.
• std.set: Sets, by an order of their elements: a map whose values are nothing.
• std.sha1: SHA-1, the hash of FIPS 180-4: any bytes to 20 bytes.
• std.sha256: SHA-256, the hash of FIPS 180-4: any bytes to 32 bytes, so that bytes that are not the same are, as far as anyone can find, not hashed to the same 32.
• std.signal: For signals: the ones a program is sent — Ctrl-C, a kill, its terminal closed or resized — waited for, each a thing that happens outside it, as a read of a socket is.
• std.terminal: For the terminal the program runs on, console: whether it has one (interactive), its size (measure), the keys typed at it one at a time (readInput; not a line at a time, nor shown as they are typed: raw, begin to finish), and a screen drawn on it (draw).
• std.terminal.widget: What a program shows on a terminal, and what is typed at it, as values: the keys a terminal’s input is read as (decode), the rows a screen is drawn as (Frame) and the text that draws them (paint), and a few widgets, each a value and what a key makes of it.
• std.thread: For OS threads: work run truly at once, on std.domain’s domains — a pool of them mapping a function over a list (parMap), a computation run on n of them, each given its index (spread), and Parallel handled by them, each side a domain (inThreads).
• std.time: For time: waiting, and two clocks.
• std.tzdb: The tz database the system keeps: its zones read from their files, as NodaTime’s DateTimeZoneProviders.Tzdb gives them, and the zone the system is set to.
• std.url: URLs (RFC 3986), written in heff: a URL read from its text into its parts (parse), written back (render), a reference resolved against the URL it is in (resolve, RFC 3986 §5.2), and the escapes of its parts and of a query’s keys and values.
• std.zlib: zlib (RFC 1950), decompressed: DEFLATE data between a header of two bytes and the Adler-32 of what it holds, as Go’s compress/zlib reads it.
• std.zoneddatetime: A date and time of day in a time zone: 2024-03-10T03:00:00-04:00 in America/New_York, what the clocks there said, at the offset they were at — an instant (std.instant), and how it was read there.
• string: More of strings than the prelude’s: what is replaced in one, what is cut from either end, cases, padding, and integers and floats written in other ways than debug writes them (another base, a fixed number of places).
• uint16: UInt16: the integers from 0 to 65535, wrapping around as the machine’s do: fromInt 65536 is 0, fromInt (-1) is 65535.
• uint32: UInt32: the integers from 0 to 4294967295, wrapping around as the machine’s do: fromInt 4294967296 is 0, fromInt (-1) is 4294967295.
• uint64: UInt64: the integers from 0 to 18446744073709551615, wrapping around as the machine’s do: fromInt 18446744073709551616 is 0, fromInt (-1) is 18446744073709551615.
• uint8: UInt8: the integers from 0 to 255, wrapping around as the machine’s do: fromInt 256 is 0, fromInt (-1) is 255.
• wire: Values as bytes, and bytes as values again: what two programs say to each other, a C program and a page’s script among them (remote sends an effect’s operations so).