Standard library
The standard library is a set of modules that ship with Mah. This page is a quick tour; the standard library reference has a page per module with a full guide, more examples, and every function.
You import them like any other file, with a std: path, either
namespaced or flat:
import math from "std:math" # math.sqrt(2), math.pi import "std:math" # sqrt(2), pi
print(sqrt(16), round(pi, 2)) # 4 3.14 std: names are reserved: they never refer to a file of yours, and an
unknown one (import "std:nope") is a compile error. An uncaught error
from inside a standard library function is reported at your call to it,
and in your editor, hover and go-to-definition work on its functions like
on your own (showing locations like std:math#20:9).
A module’s types are exported and reached like its functions: with a
namespaced import, json.JsonError, fs.FsError, process.Output, regex.Regex; the ones in a flat import (import "std:collections") are
written bare (Set). They are module-scoped, so your own struct Field or struct Match never clashes with a module’s.
So far there are std:math, std:path, std:json, std:csv, std:random, std:collections, std:regex, std:time, std:async, std:fs, std:process, std:bytes, std:socket, std:url, std:http, std:reflect and std:thread (and std:test, see Testing).
See the reference for each one. The rest of the plan (an HTTP
server, then a web framework) is in docs/STDLIB.md and docs/NEXT_PHASES.md in the repository.
std:math
Full guide: std:math.
import math from "std:math"
print(math.sqrt(2)) # 1.414213562373095048801688724
print(math.round(math.pi, 4), math.floor(0 - 2.5), math.ceil(2.1)) # 3.1416 -3 3
print(math.round(math.atan2(1, 1) * 180 / math.pi, 6)) # 45
print(math.log10(1000), math.min(3, 7), math.clamp(15, 0, 10)) # 3 3 10 | Function | |
|---|---|
pi, e | constants, to 28 digits |
sqrt(x), pow(x, y), abs(x) | exact on Numbers |
floor(x), ceil(x), round(x, digits = 0) | round rounds halves away from zero; negative digits round to tens, hundreds, … |
min(a, b), max(a, b), clamp(x, lo, hi) | |
sin, cos, tan, asin, acos, atan, atan2(y, x) | radians |
exp(x), log(x), log10(x) | log is the natural logarithm |
sqrt, pow and the rounding functions work on Mah’s own Numbers, so
they’re exact to 28 significant digits. The trigonometric, exponential
and logarithmic functions are computed in double precision (about 16
digits).
Bad input throws a RuntimeError.ArgumentError, which you can catch like
any error (see Errors):
import math from "std:math"
print(try math.log(0) else "log(0) is undefined")
print(try { math.sqrt(0 - 1) } catch { e: RuntimeError => { e.message } }) # sqrt: argument out of range sin(x) and cos(x) also work with no import at all, as they always have.
They’re ordinary names, though, so a function of your own called sin, or
a flat import "std:math", takes over.
std:path
Full guide: std:path.
Paths as Strings: nothing here touches the file system. Input may use / or \ and start with a drive (C:); normalize and relative always
answer with /.
import path from "std:path"
print(path.join("src", "main.mh"), path.join_all(["a", "b", "c"])) # src/main.mh a/b/c
print(path.dirname("a/b/c.txt"), path.basename("a/b/c.txt")) # a/b c.txt
print(path.extension("a.tar.gz"), path.stem("a.tar.gz")) # .gz a.tar
print(path.normalize("a/./b/../c//d/"), path.normalize("/../a")) # a/c/d /a
print(path.relative("/a/b", "/a/c/d"), path.is_absolute("C:\\x")) # ../c/d true | Function | |
|---|---|
join(a, b), join_all(parts) | an absolute b replaces a; no normalizing |
dirname(p), basename(p) | "." / "" when there’s nothing to give |
extension(p), stem(p) | from the last .; .bashrc has no extension |
normalize(p) | removes ., repeated separators and x/..; never climbs above a root |
is_absolute(p) | starts with a separator, or a drive and a separator |
relative(from, to) | the path from directory from to to |
std:json
Full guide: std:json.
import json from "std:json"
let config = try json.parse("{\"name\": \"mah\", \"tags\": [1, 2], \"debug\": null}") else [:]
print(config["name"], config["tags"][1], config["debug"]) # mah 2 none
print(try json.stringify(config) else "") # {"name":"mah","tags":[1,2],"debug":null}
print(try json.stringify(["a": [1]], indent: 2) else "")
# {
# "a": [
# 1
# ]
# } parse(text) turns objects into Maps (keys in document order), arrays
into Vectors, and null into none. It follows the JSON standard
strictly: no comments or trailing commas. stringify(value, indent = 0) writes compact JSON, or with indent spaces per level. It also writes
structs, as objects of their fields, and enum values: a unit variant is
its name ("Empty"), any other an object holding one key, the variant’s
name ({"Circle": {"r": 2}}). some(x) is written as x.
Both throw json.JsonError: json.JsonError.Syntax { message, line, column } when
the text isn’t JSON, and json.JsonError.Shape { message } for a value JSON
can’t hold (a function, or a Vector that contains itself).
import json from "std:json"
print(try { json.parse("[1, 2,]") } catch { e: json.JsonError => { e.message() } })
# expected a value, found ']' at line 1, column 7 To read JSON into your own types, implement json.FromJson. The helpers field(object, name), as_number, as_string, as_bool, as_vector and as_map check the shape as they go, throwing json.JsonError.Shape:
import json from "std:json"
struct Point { x: Number, y: Number }
impl json.FromJson for Point {
fn from_json(value) {
Point { x: json.as_number(json.field(value, "x"), "x"), y: json.as_number(json.field(value, "y"), "y") }
}
}
let p = try Point.from_json(json.parse("{\"x\": 1, \"y\": 2}")) else Point { x: 0, y: 0 }
print(p.x + p.y) # 3
print(try { Point.from_json(json.parse("{\"x\": 1}")) } catch { e: json.JsonError => { e.message() } })
# missing field 'y' Or let decode read it from the struct’s declaration. decode(T, value) (and parse_as(T, text), which is decode(T, parse(text))) checks a
parsed value against the annotations and builds the struct, through std:reflect (below). It handles Number, String, Bool, Vector<X>, Map<String, X>, Option<X> (a missing key is none), other
structs, and enums (the way stringify writes them). A field without an
annotation takes the value as it is, and a type that implements json.FromJson is read by its own from_json. Errors say where:
import json from "std:json"
struct User { name: String, age: Number, email: Option<String>, tags: Vector<String> }
let u = try json.parse_as(User, "{\"name\": \"ada\", \"age\": 36, \"tags\": [\"x\"]}") else none
print(u.name, u.age + 1, u.email, u.tags) # ada 37 none [x]
try {
json.parse_as(User, "{\"name\": \"a\", \"age\": \"old\", \"tags\": []}")
} catch {
e: json.JsonError => { print(e.message()) } # expected a Number for User.age, got String
}
print(try { json.parse_as(User, "{}") } catch { e: json.JsonError => { e.message() } })
# missing field 'name' for User The path in a message is the type’s name, then .field, [i] or ["key"]. json.decode(Vector, [1, "a"]) (no type arguments) passes the
items through untouched.
std:csv
Full guide: std:csv.
Comma-separated values, following RFC 4180: a field in double quotes can
hold the delimiter, line breaks, and "" for a quote.
import csv from "std:csv"
let rows = try csv.parse("name,city\nal,\"Paris, FR\"\n") else []
print(rows[1][1]) # Paris, FR
let people = try csv.parse_records("name,age\nal,3\nbo,4\n") else []
print(people[1]["name"], people.len()) # bo 2
print(try csv.stringify([["a", "b,c"], ["1", "say \"hi\""]]) else "")
# a,"b,c"
# 1,"say ""hi""" | Function | |
|---|---|
parse(text, delimiter = ",") | Vector<Vector<String>>, one Vector per row |
parse_records(text, delimiter = ",") | Vector<Map<String, String>>, keyed by the first row |
stringify(rows, delimiter = ",") | quotes only the fields that need it; none is an empty field |
stringify_records(records, delimiter = ",", columns = none) | a header row (columns, or the first record’s keys), then one row per Map |
column(row, name) | row[name], for csv.FromCsvRow impls |
Every field is read as a String (convert with to_number()). Lines end
with \n or \r\n, and blank lines are skipped. Errors are a csv.CsvError { message, line }, such as a quote that’s never closed or a record with
the wrong number of fields. csv.FromCsvRow works like json.FromJson, with from_csv_row(row) taking a record from parse_records.
std:random
Full guide: std:random.
import random from "std:random"
random.seed(42) # leave out for different numbers each run
print(random.random()) # 0.08386297105988216316063699196
print(random.randint(1, 6), random.choice(["heads", "tails"]))
let deck = ["A", "K", "Q", "J"]
random.shuffle(deck)
print(deck, random.sample(deck, 2)) | Function | |
|---|---|
random() | a Number in [0, 1) |
uniform(lo, hi) | a Number in [lo, hi) |
randint(lo, hi) | a whole Number from lo to hi, both included |
choice(v) | one item of a non-empty Vector |
shuffle(v), shuffled(v) | in place, or a shuffled copy |
sample(v, k) | k items from different positions |
seed(n) | makes everything after it repeatable |
Every VM uses the same generator (xoshiro256**), so a seeded program
prints the same numbers on the Python and the Rust runtime. Without a
seed, it starts from the operating system’s randomness. It isn’t meant
for cryptography. random.Rng.new(seed) makes an independent generator with the
same methods, which is handy when one part of a program needs repeatable
numbers and the rest doesn’t:
import random from "std:random"
let a = random.Rng.new(7)
let b = random.Rng.new(7)
print(a.randint(1, 100) == b.randint(1, 100)) # true Bad arguments, like choice([]) or randint(5, 1), throw a RuntimeError.ArgumentError.
std:collections
Full guide: std:collections.
Set, Deque and PriorityQueue, usually imported flat. Each works
with for and map/filter/reduce, and prints with its name.
import "std:collections"
let tags = Set.of(["red", "blue", "red"])
tags.add("green")
print(tags, tags.has("blue"), tags.len()) # Set[red, blue, green] true 3
print(tags.intersection(Set.of(["blue", "pink"]))) # Set[blue]
let line = Deque.of(["ana", "bo"])
line.push_front("vip")
print(line.pop_front(), line.pop_back(), line) # vip bo Deque[ana]
let tasks = PriorityQueue.new(fn(task) { task.len() })
for let t in ["write docs", "fix", "test it"] {
tasks.push(t)
}
print(tasks.pop(), tasks.pop(), tasks.pop()) # fix test it write docs Set: distinct values in the order they were first added. The values must be usable as Map keys (Strings, Numbers, Bools).add,remove,has,len,union,intersection,difference,is_subset, andequals(==on two Sets compares identity).Deque: push and pop at both ends in constant time:push_front,push_back,pop_front,pop_back,front,back,get(i). Popping an empty one givesnone, likeVector.pop.PriorityQueue:popgives the smallest item (bykey(item)if you pass a key function), and equal ones in the order they were pushed. For largest first, use a key that negates:fn(x) { 0 - x }.
std:regex
Full guide: std:regex.
import regex from "std:regex"
let date = regex.must_compile("(?<y>\\d{4})-(?<m>\\d\\d)")
let m = date.find("due 2026-09, paid 2026-10").unwrap()
print(m.text, m.start, m.group("y")) # 2026-09 4 2026
print(date.find_all("due 2026-09, paid 2026-10").len()) # 2
print(date.replace_all("2026-09 2027-01", "$m/$y")) # 09/2026 01/2027
print(regex.must_compile("\\s*,\\s*").split("a , b,c")) # [a, b, c]
print(regex.must_compile("cat", "i").replace_all("Cat CAT", fn(m) { m.text.to_lower() })) # cat cat Patterns use the familiar syntax, restricted to what every runtime matches identically:
. [abc] [^a-z] | any character but a newline / a class |
\d \w \s (and \D \W \S) | ASCII digit, word character ([0-9A-Za-z_]), whitespace |
^ $ \A \z \b \B | start, end, word boundary |
* + ? {n} {n,} {n,m} | repeats (add ? for lazy); counts up to 1000 |
(x) (?:x) (?<name>x) a\|b | groups and alternatives |
\. \\ \n \t | escapes: any punctuation after \ is literal |
Flags go in compile’s second argument: "i" (ASCII letters match
either case), "m" (^ and $ at every line), "s" (. matches a
newline too). $ without m is the very end of the text. Lookaround,
backreferences, and inline flags like (?i) aren’t supported, and a
pattern that uses them is an error rather than something that behaves
differently depending on where it runs. Remember that a Mah String has
its own escapes, so the pattern \d+ is written "\\d+".
A regex.Regex has is_match, find (an Option<regex.Match>), find_all, replace and replace_all (with $1, $name, ${name}, $$, or a
function of the Match), and split(text, limit = none). A regex.Match has text, start, end (positions count characters), and group(n) or group(name), which gives none for a group that didn’t take part. regex.escape(text) makes a pattern that matches text literally.
regex.compile throws a regex.RegexError saying what’s wrong and where, so
use it for patterns that come from outside the program. must_compile is for patterns written into the program: a mistake there is a bug, so
it throws a RuntimeError the checker doesn’t ask you to handle.
import regex from "std:regex"
let pattern = "(\\d+"
print(try { regex.compile(pattern) } catch { e: regex.RegexError => { e.message() } })
# missing ) at position 0 in "(\d+" std:time
Full guide: std:time.
import time from "std:time"
let d = time.utc(1790597925) # seconds since 1970, UTC
print(d) # 2026-09-28T12:18:45Z
print(time.format(d, "%A %d %B %Y, %H:%M")) # Monday 28 September 2026, 12:18
let later = time.utc(d.timestamp() + 36 * 3600) # times are Numbers of seconds
print(time.format(later, "%a %H:%M"), time.duration_text(later.timestamp() - d.timestamp())) # Wed 00:18 1d 12h 0m 0s
print(try time.parse("2026-02-30", "%Y-%m-%d") else "no such date") # no such date time.now() is the current time and time.monotonic() the seconds since
the program started (use it to measure how long something takes). Both,
and every duration, are Numbers of seconds with milliseconds, so ordinary
arithmetic works on them.
A time.DateTime has year, month, day, hour, minute, second and millisecond, plus timestamp(), weekday() (Monday is 1) and day_of_year(). Make one with time.utc(seconds) or time.date(year, month, day, hour = 0, ...). It prints in ISO 8601, which time.iso and time.parse_iso write and read.
| Code | Code | ||
|---|---|---|---|
%Y | year, 4 digits | %M | minute |
%m | month, 01–12 | %S | second |
%d | day, 01–31 | %f | millisecond, 000–999 |
%H | hour, 00–23 | %j | day of the year |
%B %b | month name, full / 3 letters | %A %a | weekday name, full / 3 letters |
parse and date throw time.TimeError for text that doesn’t match or an
impossible date (February 30). Everything is UTC for now: time zones
aren’t supported yet.
std:async
Full guide: std:async.
A Promise comes from detach. std:async combines them, and runs
timers:
import async from "std:async"
fn job(ms: Number, name: String) -> String {
sleep_async(ms)
name
}
print(async.all([detach job(30, "a"), detach job(10, "b")])) # [a, b]
print(async.race([detach job(30, "slow"), detach job(5, "fast")])) # fast
print(try { async.timeout(detach job(500, "x"), 20) } catch { e: async.TimeoutError => { e.message() } }) # timed out after 20 ms
let ticks = [0]
let ticker = async.set_interval(fn() { ticks[0] = ticks[0] + 1 }, 10)
async.set_timeout(fn() { async.clear_interval(ticker) }, 55) all(promises)gives every value, in order, once all are done, and throws as soon as any fails.race(promises)gives whichever settles first.timeout(promise, ms)gives the value if it comes in time and throwsasync.TimeoutErrorotherwise. The type checker knows each one’s result type and what it can throw.- These wait like any call;
detachthem to keep going meanwhile. set_timeout(f, ms)callsfonce, andset_interval(f, ms)calls it repeatedly untilclear_interval. An active interval keeps the program running; a cleared timer doesn’t. Callbacks can’t throw (their type isfn() throws never): handle errors inside them.
std:bytes
Full guide: std:bytes.
Making and decoding Bytes, Mah’s binary data
type. The methods on a Bytes value (to_hex(), to_base64(), to_text(), index_of, …) need no import; these are the constructors.
import bytes from "std:bytes"
fn decode(s: String) -> Bytes {
try {
return bytes.from_base64(s)
} catch {
e: bytes.BytesError => {
print(e.kind) # invalid_base64
return bytes.new()
}
}
}
print(decode("SGkh").to_text_lossy()) # Hi!
print(decode("not base64!").len()) # 0
print(bytes.new(3, 255), bytes.from_hex("CAFE")) # Bytes[ff ff ff] Bytes[ca fe] | Function | |
|---|---|
new(size = 0, fill = 0) | size bytes, each fill |
from_vector(items) | from a Vector of Numbers 0 to 255 |
concat(parts) | a Vector of Bytes joined into one new Bytes |
from_hex(text) | an even number of hex digits, either case |
from_base64(text) | standard alphabet, = padded, no whitespace |
from_hex and from_base64 throw bytes.BytesError { kind, description } (kind is "invalid_hex" or "invalid_base64"). A bad byte or size given
to new or from_vector is a runtime error, like b[i] = 300.
std:fs
Full guide: std:fs.
Files and directories. Every function waits like any call, but the work
happens off your program’s thread, so detach fs.read_text(path) lets
other tasks and timers run meanwhile.
import fs from "std:fs"
try {
let dir = fs.temp_dir() # a fresh temporary directory
defer fs.remove(dir, recursive: true)
fs.write_text(dir + "/todo.txt", "buy milk\nwalk dog\n")
fs.append_text(dir + "/todo.txt", "call mom\n")
let f = fs.open(dir + "/todo.txt")
defer f.close()
for let line, let i in f.lines() {
print(i + 1, line) # 1 buy milk, 2 walk dog, 3 call mom
}
print(fs.list_dir(dir), fs.info(dir + "/todo.txt").size) # [todo.txt] 27
fs.read_text(dir + "/missing.txt")
} catch {
e: fs.FsError => { print(e.kind, "-", e.message()) } # not_found - read_text: no such file ...
} | Function | |
|---|---|
read_text(path), write_text(path, text), append_text(path, text) | a whole file at once |
exists, is_file, is_dir(path) | Bools, never throwing |
info(path) | fs.FileInfo { kind, size, modified }: “file”, “dir” or “other”; bytes; seconds since 1970 |
list_dir(path) | the names in a directory, sorted |
mkdir(path, parents = false) | parents also makes missing directories above it |
remove(path, recursive = false) | a file or an empty directory, or with recursive a whole tree |
rename(from, to), copy(from, to) | replacing a file at to |
glob(pattern) | matching paths, sorted: *, ?, [abc] in a name, ** across directories |
temp_dir() | a new, empty temporary directory |
open(path, mode = "r") | a fs.File (mode “r”, “w” or “a”) with read_line() (none at the end), lines(), read_all(), write(text) and close() |
Errors are an fs.FsError whose kind is "not_found", "permission_denied", "already_exists", "is_a_directory", "not_a_directory", "directory_not_empty", "invalid_utf8", "closed" (using a closed File) or "other", plus the op, path, and
a description. Text is UTF-8, read and written exactly: no newline
conversion.
Binary files use Bytes instead of Strings: read_bytes(path), write_bytes(path, data), append_bytes(path, data),
and a File’s read_bytes(max = none) (up to max bytes, the rest of the
file without it; empty Bytes at the end) and write_bytes(data). Text and
binary reads can be mixed on one open file.
import bytes from "std:bytes"
import fs from "std:fs"
try {
let dir = fs.temp_dir()
defer fs.remove(dir, recursive: true)
let p = dir + "/data.bin"
fs.write_bytes(p, bytes.from_hex("89504e47"))
fs.append_bytes(p, bytes.new(4, 0))
let f = fs.open(p)
defer f.close()
print(f.read_bytes(max: 4).to_hex(), f.read_bytes().len()) # 89504e47 4
print(fs.read_bytes(p)) # Bytes[89 50 4e 47 00 00 00 00]
} catch {
e: fs.FsError => { print(e.kind) }
} A program importing std:fs needs bytecode 1.17.
std:process
Full guide: std:process.
The program’s arguments and environment, and running other programs. run waits for the program like any call, but the work happens off your
program’s thread, so detach process.run(...) lets other tasks and timers
run meanwhile.
import process from "std:process"
print(process.args()) # what follows `--`: mah run app.mh -- a "b c"
let port = process.env_get("PORT").unwrap_or("8080")
try {
let out = process.run("git", ["status", "--short"], cwd: some("."))
if out.ok() { print(out.stdout) } else { print("git said:", out.stderr) }
print(process.shell("ls | wc -l").stdout.trim())
process.run("no-such-program")
} catch {
e: process.ProcessError => { print(e.kind, "-", e.message()) } # not_found - no-such-program: no such file ...
} | Function | |
|---|---|
args() | the program’s arguments: everything after -- in mah run FILE -- ARGS... (also mah runc) |
exit(code = 0) | ends the program at once (0 to 255); output is flushed, but defers don’t run and no try/catch can stop it |
env_get(name) | some(value) or none |
env_set(name, value), env_remove(name) | change the program’s own copy of the environment |
env() | a Map of every variable, sorted by name |
cwd(), pid(), platform() | the current directory; the process id; “linux”, “macos” or “windows” |
run(program, args = [], cwd = none, env = none, stdin = "") | starts the program directly (no shell, found through PATH) and returns a process.Output { code, stdout, stderr } |
shell(command, cwd = none, env = none, stdin = "") | run of the command line through /bin/sh -c (cmd /C on Windows) |
process.Output.ok() is code == 0. A non-zero exit is not an error, and a
program killed by signal N has the code 128 + N. Output is decoded as
UTF-8, with invalid bytes replaced by U+FFFD. Only a program that can’t be
started throws a process.ProcessError whose kind is "not_found", "permission_denied" or "other", plus the command and a description.
The environment functions work on a copy taken when the program starts: env_set never changes the real environment, but the programs run starts get the copy (plus the call’s env entries). Names must be
non-empty and contain no =; names and values can’t contain a NUL
character.
std:socket
Full guide: std:socket.
TCP connections, plain or TLS. Every call waits like any async call; detach runs one in the background. Timeouts are in milliseconds.
import socket from "std:socket"
let server = socket.listen(0) # a free port on 127.0.0.1
let incoming = detach server.accept()
let client = socket.connect("127.0.0.1", server.port)
let conn = incoming.await
client.send_text("hello\n")
print(conn.read_line()) # hello
client.close()
conn.close()
server.close() socket.connect_tls(host, port) (or sock.start_tls(name) on a connected
socket) encrypts the connection, verifying the server’s certificate against
the system’s roots, or the PEM file the SSL_CERT_FILE environment variable
names. A server loads its certificate and key once with socket.tls_server_config(cert, key) and calls conn.start_tls_server(config) on each accepted socket. Failures throw socket.SocketError { kind, op, address, description }.
std:thread
Full guide: std:thread.
Run jobs on other threads. A thread is a queue of jobs; detach(t) expr and t.run(f, ...args) give Promises. A job works on a copy of every global
and of what it captures; shared let variables, changed in place inside atomic { } transactions, are shared by every thread, and so are semaphores
and channels.
import thread from "std:thread"
shared let total = 0
fn add(n) {
atomic { total = total + n }
}
let pool = thread.spawn(workers: 4)
let jobs = []
for let n in 1..=10 { jobs.push(pool.run(add, n)) }
for let j in jobs { j.await }
print(total) # 55
pool.join() Failures throw ThreadError { kind, message } ("closed", "deadlock", "stuck", "in_atomic", …).
std:url
Full guide: std:url.
Parse, build and resolve URLs, and percent-encode text and query strings.
import url from "std:url"
let u = url.parse("https://example.com:8443/docs/a?x=1#top")
print(u.host, u.port, u.path, u.query, u.fragment) # example.com 8443 /docs/a x=1 top
print(u.resolve("../b?y=2")) # https://example.com:8443/b?y=2
print(url.encode("a b/c"), url.encode_query(["q": "mah lang", "n": 2])) # a%20b%2Fc q=mah+lang&n=2
print(url.parse_query("a=1&b=x+y")) # [[a, 1], [b, x y]] std:http
Full guide: std:http.
An HTTP/1.1 client for http:// and https://, and a server, written in
Mah over std:socket. get, post, put, patch, delete, head and request(method, url, ...) take headers (a Map), timeout and max_redirects; the body-sending ones take body (String or Bytes), json or form.
import http from "std:http"
fn latest() throws http.HttpError {
let r = http.get("https://example.com/", headers: ["Accept": "text/html"])
print(r.status, r.header("content-type"), r.text().len())
let created = http.post("https://api.example.com/items", json: ["name": "mah"])
print(created.check_status().json())
} A 404 or 500 is still a Response (r.is_success(), r.check_status()); http.HttpError is for requests that couldn’t complete: refused or timed
out connections, untrusted certificates, bad URLs, too many redirects.
Redirects are followed, and the HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables are honored.
http.serve(port, handler) serves HTTP: a handler is a function from an http.Request to an http.Reply (Reply.text, json, html, bytes, redirect, empty, stream), and the server handles keep-alive, chunked
bodies, limits, concurrency (one task per connection), graceful shutdown
(server.close()) and, with tls: socket.tls_server_config(cert, key),
HTTPS.
import http from "std:http"
let server = http.serve(0, fn(req: http.Request) -> http.Reply { http.Reply.text("hi " + req.path) })
print(http.get(server.url("/there")).text()) # hi /there
server.close() std:reflect
Full guide: std:reflect.
What a program can find out about its own functions, types and values while
it runs. A bare type name is a value: Number, String, User, Vector (a Type; == compares them and print shows the name). A ## comment
directly above a fn, struct, enum, method, field, variant or parameter
is its documentation, and std:reflect reads it together with the
annotations, defaults and throws clause the source wrote (never what the
checker inferred, so an unannotated parameter’s type is reflect.TypeRef.Unknown).
import reflect from "std:reflect"
## Adds two numbers.
fn add(a: Number, b: Number = 1) -> Number { a + b }
## A user.
struct User {
## Their name.
name: String,
tags: Vector<String>
}
let sig = reflect.signature(add)
print(sig.name, sig.doc) # add Adds two numbers.
print(sig.params[1].has_default, sig.params[1].default) # true some(1)
match reflect.schema(User) {
some(reflect.Schema.Struct { type: t, doc: doc, type_params: tps, fields: fields, decorators: ds }) => {
print(doc, fields[0].name, fields[0].doc) # A user. name Their name.
}
_ => { }
}
let u = reflect.construct(User, ["name": "ada", "tags": []])
print(reflect.type_of(u) == User, reflect.type_of(3)) # true Number
print(reflect.call(add, [1], ["b": 5])) # 6 | Function | |
|---|---|
type_of(value) | the value’s type (type_of(none) is None) |
signature(f) | a reflect.Signature { name, doc, type_params, params, returns, throws, decorators, rest, kwrest }; each reflect.Param has name, type, doc, has_default and default (some(value) when it’s a literal). rest and kwrest are Options of the ... and ** parameters, which params doesn’t list. A function wrapped by a hook reports the original’s signature |
schema(T) | some(Schema.Struct { ... fields }) or some(Schema.Enum { ... variants }); none for Number, String and the other primitives |
methods(T) | the reflect.Method { name, function, is_method, trait_name } written in impls: inherent first, then trait methods by trait and name |
implements(T, "Trait") | whether the type has methods for that trait, native ones included |
call(f, args = [], kwargs = [:]) | f(...args, **kwargs) |
construct(T, fields), construct_variant(T, "Variant", fields) | a new struct or enum value from exactly its fields; a missing or unknown field throws reflect.ReflectError naming it |
find(decorators, target) | the first of a decorators Vector (see Decorators) whose type is target (a Type), that is the same function as target (a function, even if it was wrapped since), or that == it; none if there is none |
A type annotation comes back as a reflect.TypeRef: Unknown, Named { type, args }, Fn { params, returns, throws }, Param { name }, SelfType, Never or Trait { name, args }.
...xs and **m in a call’s argument list (a Vector into positional
arguments, a Map into keyword arguments: f(...args, k: 1, **more)) exist so call can be written in Mah; see Functions & closures.
The natives behind it read the .mahc file’s structure and run the
decorator hooks, so they need bytecode 1.16 (and so does any program that
imports std:json, whose decode is written over it, or has a decorator,
which imports std:reflect implicitly). std:reflect exports its types (TypeRef, Param, Signature, Field, Variant, Schema, Method, ReflectError) and the hook traits and their
info structs (WrapFn, WrapParam, WrapField, WrapStruct, FnInfo, ParamInfo, FieldInfo, TypeInfo, see Decorators),
reached as reflect.TypeRef and so on; like every module’s types they are module-scoped, so your own Field or Method struct never clashes with them.
How it’s built
Each module is a Mah file inside the mah package (mah/std/math.mh).
Most of std:math is plain Mah. The functions that need the machine,
such as tan and log, are declared with extern fn, which binds a Mah
function to a native the VM provides:
export extern fn tan(x: Number) -> Number = "math.tan" std:path and std:collections need no natives, and std:json and std:csv are Mah too, over a handful of natives for reading a value’s
type and fields and a String’s characters. std:random’s generator is a
small native, specified bit for bit so every runtime computes the same
numbers. std:fs and std:process’s run hand their work to a thread and settle
a Promise when it’s done; an open file is an id in a table, wrapped in a fs.File struct. std:http is Mah over std:socket; only TLS is native (Python’s ssl,
Rust’s rustls). std:regex parses each pattern in Mah and hands the runtime a
form that Python’s re and Rust’s regex crate read the same way.
Only standard library modules may use extern fn. New natives come with
a new bytecode minor version, and a compiled program is marked with the
lowest version it needs. An older runtime keeps running programs that
don’t use new natives. It refuses one that does, and names the natives it
lacks.