Mah
DocsStdlibBlogChangelog
GitHub
Menu
DocsStdlibBlogChangelog GitHub

  • std:math
  • std:random
  • std:collections
  • std:time

  • std:path
  • std:json
  • std:csv
  • std:regex
  • std:bytes
  • std:url

  • std:async
  • std:fs
  • std:process
  • std:thread

  • std:socket
  • std:http

  • std:reflect
  • std:test

Standard library

Mah ships with a standard library of 18 modules, written in Mah itself (with a few natives underneath) so the Python VM and the Rust mah-vm behave identically. Each page below explains what a module is for, walks through using it, and lists its full API.

Importing a module

Standard library modules are imported with a std: path, either namespaced (everything is reached through the name you give it) or flat (its exports become plain names in your file):

import json from "std:json"           # namespaced: json.parse(...), json.JsonError
import "std:collections"              # flat: Set, Deque, PriorityQueue

let config = try json.parse("{\"port\": 8080}") else [:]
let seen = Set.of(["a", "b", "a"])
print(config["port"], seen.len())     # 8080 2
  • std: names are reserved: they never refer to a file of yours, and an unknown one (import "std:nope") is a compile error.
  • A module's types are reached like its functions (json.JsonError, fs.File) and are module-scoped, so your own struct Match never clashes with regex.Match.
  • Errors a module throws are ordinary structs or enums you catch by type; the type checker knows what each function throws (see Errors).
  • In your editor, hover, completion and go-to-definition work on standard library functions like on your own.

Basics

std:math Constants, rounding, min/max/clamp, square roots and powers, trigonometry, exponentials and logarithms.std:random Seedable pseudo-random numbers, integers in a range, picking, shuffling and sampling, identical on every runtime.std:collections Set, Deque and PriorityQueue, the data structures beyond Vector and Map, all iterable and printable.std:time The current time, a monotonic clock for measuring, UTC dates, formatting and parsing with %-codes, ISO 8601.

Text & data

std:path Join, split and normalize file paths as Strings, without touching the file system.std:json Parse and write JSON, and decode it straight into your own structs and enums with precise error messages.std:csv Read and write RFC 4180 CSV, as rows of fields or as records keyed by the header row.std:regex Regular expressions with named groups, find/replace/split, and flags, matching identically on every runtime.std:bytes Build and decode binary data, from hex, base64 and Vectors of byte values, for the built-in Bytes type.std:url Parse, build and resolve URLs, and percent-encode text and query strings.

Async & system

std:async Wait for many Promises at once (all, race, timeout) and run timers (set_timeout, set_interval).std:fs Read and write text and binary files, open files for streaming, and manage directories, globs and temp dirs.std:process Command-line arguments, environment variables, exit codes, and running other programs or shell commands.std:thread Run jobs on other threads, share variables between them with shared let and atomic blocks, and pass messages through channels.

Networking

std:socket TCP clients and servers, line and byte reads with timeouts, and TLS for clients (with certificate verification) and servers.std:http An HTTP/1.1 client (http and https, JSON and form bodies, redirects, proxies) and server (handler functions, keep-alive, limits, graceful shutdown, TLS).

Language & testing

std:reflect Inspect types, functions, docs and decorators at run time; build values and call functions dynamically; hooks.std:test Assertions for mah test, assert, assert_eq, assert_throws, fail and skip, with readable failure reports.

How it's built

Each module is a Mah file inside the mah package (mah/std/math.mh). The functions that need the machine (math.tan, file and socket I/O, TLS) are declared with extern fn, which binds a Mah function to a native the VM provides. Only standard library modules may use extern fn. New natives come with a new bytecode minor version: a compiled program is marked with the lowest version it needs, and an older runtime refuses it, naming the natives it lacks.

Mah — ماه, "moon" in Persian. Built from scratch, pure Python (plus a Rust runtime).

Docs Stdlib Blog Changelog RSS GitHub