Standard library overview

The standard library lives under the std/ namespace. Each module is a thin .plu wrapper (stdlib/<name>.plu) over C native functions, so the surface is ordinary Pluvial code while the heavy work happens in C — Pluvial’s core performance strategy.

Importing

Use the quoted form or the std. shorthand (they are equivalent):

from std.io import read_file
import std.math
import std.math as m

See Modules — the std/ namespace for resolution order (PLUVIAL_STD_PATH, the system install path, then ./stdlib).

Modules at a glance

Module	Purpose
std/io	File and stdin I/O
std/strings	format() string interpolation
std/math	libm wrappers and constants
std/os	Process and environment
std/path	Pure path-string manipulation
std/json	JSON parsing and serialization
std/http	HTTP client (libcurl)
std/time	UTC time, monotonic clock, formatting
std/regex	Regular expressions (PCRE2)
std/base64	Base64 encoding (RFC 4648 + URL-safe)
std/csv	CSV parsing and writing (RFC 4180)
std/test	Assertions for the pluvial test runner

std/http and std/time have dedicated pages. The rest are summarized below.

std/io

File and stdin I/O. Most functions return Result<T>; read_all always succeeds.

Function	Type
read_file(string)	Result<string>
write_file(string, string)	Result<bool>
append_file(string, string)	Result<bool>
read_line()	Result<string> (EOF is an err)
read_all()	string (drains stdin)
file_exists(string)	bool
delete_file(string)	Result<bool>
read_bytes(string)	Result<string>
write_bytes(string, array<int>)	Result<bool>

read_bytes returns a Result<string> because Pluvial strings are arbitrary byte sequences (no enforced UTF-8), so they are binary-safe.

std/strings

format() does positional/indexed string interpolation (1 native + 7 wrappers):

format("hi {}", ["world"])               // "hi world"
format("{1} {0}", ["world", "hello"])    // "hello world"
format("{0} and {0}", ["x"])             // "x and x"
format("{{{}}}", ["y"])                  // "{y}"
format_i("a={} b={}", [1, 2])            // "a=1 b=2"

Placeholders: {} (auto-index), {N} (explicit index), {{ / }} (literal braces). An out-of-range index is a runtime error (70). Fixed-arity helpers format1 … format4 and typed helpers format_i(t, array<int>) / format_f(t, array<float>) are also provided.

std/math

22 libm wrappers. Always-succeeding functions return the value type directly; functions with a domain constraint return Result<float>.

• Always succeed (17): abs(int)→int, fabs / floor / ceil / round / exp / sin / cos / tan / sqrt_unsafe (float→float), pow(float, float)→float, min_int / max_int(int, int)→int, min_float / max_float(float, float)→float, clamp_int(int, int, int)→int, clamp_float(float, float, float)→float.
• Domain-constrained (5, Result<float>): sqrt (negative → err), log (≤ 0 → err), log2, asin, acos (outside ±1 → err).

Constants are exported as zero-argument functions:

from std.math import pi, e, inf
println(pi())            // 3.14159...
println(cos(pi()))       // -1.0

std/os

Process and environment access.

Function	Type	Notes
env(string)	Result<string>	unset → err
set_env(string, string)	Result<bool>
args()	array<string>	trailing CLI arguments after the script
exit(int)	(no value)	exits immediately with the given code
cwd()	Result<string>	current working directory
platform()	string	"macos" / "linux" / "windows" / "unknown"
pid()	int	process id

std/path

Pure string manipulation — never touches the filesystem.

Function	Example
join(string, string)→string	join("/usr", "local") → "/usr/local"; an absolute second argument overrides the first (POSIX rule)
dirname(string)→string	"/usr/local/bin/p" → "/usr/local/bin"; "file.txt" → "."; "/" → "/"
basename(string)→string	"/usr/local/p" → "p"; "file.txt" → "file.txt"; "/" → "/"

On Windows the separator is \, but / is also recognized when scanning, for portability.

std/json

std/json introduces the json type (an ObjJson runtime value) covering JSON null, bool, number, string, array, and object.

from std.json import parse_json, to_json_string,
                     json_is_null, json_is_bool, json_is_number,
                     json_is_string, json_is_array, json_is_object,
                     json_string, json_int, json_float, json_bool,
                     json_array, json_object, json_get, json_index,
                     json_length, json_keys

auto r = parse_json("{\"name\":\"Alice\",\"age\":30,\"tags\":[1,2]}")
if (r is ok) {
    auto name = json_string(r.value, "name")  // Result<string>
    auto age  = json_int(r.value, "age")      // Result<int>
    for k in json_keys(r.value) { println(k) }
}

parse_json returns a Result<json>. Accessor functions such as json_string / json_int return Result<T>. Serialization (to_json_string) writes integral numbers without a trailing .0, and emits null for NaN / Inf (which JSON cannot represent). \uXXXX escapes are handled for the BMP.

std/regex

PCRE2-based regular expressions. Because match is a Pluvial keyword, the match function is named matches.

Function	Result
matches(pat, s)	bool (partial match)
matches_full(pat, s)	bool (anchored at both ends)
find(pat, s)	Result<string>
find_all(pat, s)	array<string>
replace(pat, s, rep)	string (first match)
replace_all(pat, s, rep)	string (all matches)
split(pat, s)	array<string>
groups(pat, s)	Result<array<string>> (capture groups)

UTF mode is on by default, so \p{L}, \d, \w and similar classes work. Replacement strings use $0 / $1 / $2 for capture references.

std/base64

External-dependency-free Base64. Provides the standard alphabet (with = padding) and the URL-safe variant (- / _, no padding) as separate functions. Pluvial strings carry an explicit length, so payloads containing NUL bytes pass through cleanly.

std/csv

External-dependency-free CSV (RFC 4180): comma separator, "…" quoting, "" for a literal quote, and both CRLF and LF line endings.

Function	Result
parse(s)	array<array<string>>
parse_with_header(s)	array<map<string, string>>
stringify(rows)	string
stringify_with_header(headers, rows)	string

std/test

Assertions for the pluvial test runner: test(name, fn), expect_eq(a, b) (with _string / _float / _bool variants), expect_true / expect_false, expect_ok(r) / expect_err(r), and fail(msg). See the CLI reference for how the runner discovers and runs tests.