Standard library

The standard library is the set of packages you reach with import std.*. It covers files, text formatting, math, collections helpers, structured logging, encoding, networking, processes, threads, time, randomness, and low-level machine access.

You import a package by its dotted name and then call into it by its last name:

import std.io
import std.encoding.json

fn main() {
    io.println("hello")
    let value: json.Value = json.parse("[1, 2, 3]").expect("parse")
}

Two kinds of packages

The library comes in two layers.

• Beans-source packages. These are written in Beans and ship with the compiler under stdlib/std/<pkg>/<pkg>.b. You can read their code. Examples: std.fmt at stdlib/std/fmt/fmt.b, std.collections, std.math, std.path, std.fs, std.log, and the encoding packages. Some source packages use a native bridge for their operating-system or third-party-library work.
• Native modules. These are built into the compiler and runtime, not into stdlib/std/. They are the parts that must talk to the operating system or the CPU directly: std.io, std.os, std.thread, std.time, std.random, std.target, std.cpu, std.intrinsic, and std.asm.

You do not need to think about which layer a package is in while you write code. It only matters when you go looking for the source.

One rule for making objects

Beans has no free “constructor functions” in modules. Anything that produces an object is either a new on that object’s class or a named static on the class, never a plain module function.

import std.net

fn main() {
    // a class instance: use new
    let addr: net.Address = new net.Address("localhost", 8080)
    // fallible construction: a named static returning Result
    let stream: Result<net.TcpStream> = net.TcpStream.connect("localhost", 8080)
}

So new process.Command("ls") builds a command, and File.open(path, "r") opens a file (it can fail, so it is a named static that returns a Result).

Pointing the loader at another root

The compiler finds the standard library on its own. If you need to override where it looks, set the BEANS_STDLIB environment variable to another root directory and the loader will read packages from there instead.

Package pages

Package	What it covers
std.io and std.os	printing, reading input, program arguments, environment, exit
std.collections	generic helpers over List and Map
std.fmt	number and text formatting
std.math	small numeric helpers
std.bytes	CRC-32 and varint helpers over Bytes
std.path	path string math, no filesystem
std.fs	read and write whole files
std.reader	buffered line reading over a File
std.reflect	runtime types, members, annotations, checked field access and calls
std.log	asynchronous structured logging, files, rotation, NDJSON and export sinks
std.encoding.json	JSON parsing and building
std.encoding.xml	XML parsing and building
std.encoding.base64	Base64 encode and decode
std.encoding.binary	fixed-width integers and varints over Bytes
std.net	TCP and UDP sockets
std.process	run other programs, no shell
std.poll	wait on many descriptors at once
std.signal	receive OS signals as data
std.dylib	open dynamic libraries at run time
std.thread	run closures on OS threads
std.time and std.random	clocks, sleeping, and secure random
std.target	facts about the selected target, at compile time
std.cpu and std.intrinsic	ask the CPU, and low-level intrinsics
std.asm	constrained inline assembly

See also

• Builtins, the types the compiler gives you without an import.
• The language guide for how Option, Result, and ? work.