Modules and the standard library
One file is one module. use, pub, ext and @lib, and what io, fmt, mem, os and bufio contain.
#Modules
One file is one module. use name; imports the module in name.ln next to the importing file, or else the standard module of that name; its pub functions are called as name.function(...). pub exports a declaration: a function, a constant, a record or an enum, reached from another module as module.NAME or module.Type, also in the type of a field or a parameter. A name that is not pub is refused, and a module's own errors are reported in that module.
A module with some public and some private declarations:
pub CAP :: 8;
HIDDEN :: 3;
pub enum Open { a }
enum Closed { a }
pub rec Pub { u8 a; }
rec Priv { u8 a; }
Verified: one module of a multi-module program.
Using a private name from another module is an error:
use limits;
nul main() { limits.Priv p; }
Verified: the compiler refuses this program (exit code 1). Compiler output:
main.ln:2:14: error: `limits.Priv` is not `pub`
The module path and package layout are not decided yet.
#C imports and exports
ext with ; imports a C-ABI symbol and ext with a body exports one. @lib names the library. A slice cannot cross the C ABI (pass a pointer and a length), neither can an array (pass a pointer), nor a record. An ext function takes no access modes; it takes pointers.
@lib("kernel32") ext *nul VirtualAlloc(*nul address, usz size, u32 kind, u32 protect);
@lib("kernel32") ext i32 VirtualFree(*nul address, usz size, u32 kind);
From the standard library module mem. It is written in Lane.
rec A { u32 x; }
@lib("x") ext nul f(A a);
nul main() { }
Verified: the compiler refuses this program (exit code 1). Compiler output:
main.ln:2:11: error: a record cannot cross the C ABI; pass a pointer
#The standard library
The standard library is embedded in the compiler and written in Lane on ext imports of the host operating system's API (kernel32 on Windows). A std module may use another. Only these functions are pub; paths and text are []u8 without a terminator.
| Module | Contents |
|---|---|
io | print, eprint (standard error), println, print_u64 |
fmt | dec(u64, wr [20]u8), dec_signed(i64, wr [20]u8), hex(u64, wr [16]u8): the digits as the tail of the buffer; hex is lowercase without leading zeros |
mem | rec Arena, arena_init, alloc, reset, release, copy, eq, fill |
os | exit, arg_count, arg, read_file, write_file, file_size, ticks, ticks_per_second |
bufio | rec Writer, stdout_writer, stderr_writer, flush, write |
#io
pub nul print([]u8 s) {
From the standard library module io. It is written in Lane.
pub nul println([]u8 s) {
From the standard library module io. It is written in Lane.
#fmt
fmt formats into a buffer the caller owns and returns the digits as the tail of it.
pub []u8 dec(u64 v, wr [DEC_DIGITS]u8 buf) {
From the standard library module fmt. It is written in Lane.
pub []u8 hex(u64 v, wr [HEX_DIGITS]u8 buf) {
From the standard library module fmt. It is written in Lane.
#mem
An Arena is a block from VirtualAlloc handed out in order. alloc returns zeroed memory aligned as asked (a power of two) or an empty slice when it does not fit, and reset zeroes what was used. copy takes min(dst.len, src.len) bytes and handles overlap. See Memory.
pub bool arena_init(out Arena a, usz cap) {
From the standard library module mem. It is written in Lane.
pub nul copy(wr []u8 dst, []u8 src) {
From the standard library module mem. It is written in Lane.
pub bool eq([]u8 a, []u8 b) {
From the standard library module mem. It is written in Lane.
pub nul fill(wr []u8 dst, u8 v) {
From the standard library module mem. It is written in Lane.
#os
arg(0) is the program name and arg_count counts it. Command-line arguments are ASCII: a character outside ASCII becomes the byte 0xff. Paths are ASCII, and a path with a byte above 0x7f or a zero byte is not usable. read_file stores the file in arena memory and sets its out []u8 parameter; on any failure it returns false, sets the slice to empty and leaves the arena as it was. Only disk files are read.
pub nul exit(i32 code) {
From the standard library module os. It is written in Lane.
pub bool read_file([]u8 path, wr mem.Arena a, out []u8 data) {
From the standard library module os. It is written in Lane.
pub bool write_file([]u8 path, []u8 data) {
From the standard library module os. It is written in Lane.
pub u64 ticks() {
From the standard library module os. It is written in Lane.
#bufio
A bufio.Writer collects output in a buffer the caller owns, so that many small writes become few system calls. Nothing is written by itself at the end of the program: call flush.
pub rec Writer { bool to_error; *u8 buf; usz len; usz cap; }
From the standard library module bufio. It is written in Lane.
pub nul write(wr Writer w, []u8 s) {
From the standard library module bufio. It is written in Lane.
pub nul flush(wr Writer w) {
From the standard library module bufio. It is written in Lane.