Standard library overview
The modules that ship with PickleScript and what each one does.
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.
