Standard library overview

The modules that ship with PickleScript and what each one does.

vlatest

The standard library is a set of std modules. They are ordinary PickleScript source in the stdlib/ directory of the repository, and they are importable from any file inside a clone of that repository.

Importing

import { parse, stringify } from std.json
import { Stack } from std.collections.stack
import { join, contains } from std.text.format

Each module exports a flat set of names. There is no export keyword, every top-level declaration in a module is importable, so import what you need.

The modules

Module Import path Contents
Collections std.collections.list sliceOf, filled, containsElem, indexOfElem
std.collections.set Set<T>, union, intersect, difference
std.collections.orderedmap OrderedMap<K, V>
std.collections.deque Deque<T>
std.collections.stack Stack<T>
std.collections.queue Queue<T>
std.collections.priorityqueue PriorityQueue<T>
Text std.text.format Padding, slicing, search, hex conversion
std.text.stringbuilder StringBuilder
std.text.utf8 UTF-8 decoding and encoding primitives
Files std.fs Path, File, Dir, path helpers
I/O std.io write, writeln, writeErr, writelnErr
JSON std.json Json enum, parse, stringify, accessors
OS std.os argv, exitWith
Processes std.process proc, git, pipe, Proc, Result
Threads std.thread spawn, Task, Channel, Mutex, AtomicInt, …
Testing std.test The test-harness model used by the runner

What lives where

The library is deliberately small. Numeric helpers are built in rather than in a std.math module: abs, min, max, clamp and range are language builtins, see Builtin functions. String work is in std.text. Time is std.thread.sleep(ms).

Two modules you should not treat as public API

std.text.ccm and std.text.lexer belong to the compiler, not to application code. ccm holds the UTF-8 tables and lexer is the tokenizer the compiler itself uses, so both change with the compiler and should not be depended on.

The prototype constructor

An empty list literal cannot be typed, and List<T>() is not a valid call, so each standard-library collection class takes a prototype value instead: a sample of the element type that exists only to give the empty collection a type.

import { Stack } from std.collections.stack

fn main() {
    let s = Stack<int>(0)      // `0` is a prototype, not a starting element
    println("size {s.size()}") // 0
    s.push(1)
    println("size {s.size()}") // 1
}

Stack<int>(0), Deque<string>(""), Set<float>(0.0). The prototype is never stored as an element.

Builtins versus the standard library

Many things people look for in a standard library are actually builtins and need no import:

Area Builtin
Output print, println
Numbers abs, min, max, clamp, range
Collections len, and the List / Map methods
Files read_file, write_file, file_exists, delete, mkdir, list_dir
Bytes bytes, str
Processes args, run_cmd, run_spawn, proc_*
Threads thread_*, mutex_*, channel_*, atomic_*
Control assert, exit, alloc, free

The standard library wraps these in friendlier APIs, std.process.Proc instead of run_cmd, Stack instead of raw indexing. Prefer the module when one covers your case.

Iteration

The compiler seeds Iterable<T> and Iterator<T> into every module, so your own types work in for loops without importing anything. See Lists and maps.

Next steps