Package index

OSL ships its standard library as importable packages:

import "std:fs"

log fs.readFile("notes.txt")

An import adds a package value with the same name. For example, std:fs adds fs. Use the std: prefix in new code. The older osl/ spelling still works, but the compiler reports a migration warning.

How imports work

Form	Meaning
import "std:fs"	A standard-library package listed below
import "./helpers.osl"	A local OSL file, relative to the importing file
import "utils" or import "./utils"	Every .osl file directly inside a local directory
import "git.rotur.dev/me/tools"	A Git dependency installed by Opal
import "go:net/http"	A Go package

Directory imports sort files by name and do not recurse. Import or re-export child directories yourself.

Missing third-party Go dependencies are fetched automatically when you compile.

Module objects

The statement form merges another file's declarations into the current scope. Its top-level statements run once, where OSL first imports the file. The expression form returns its public API as an object instead:

object math = import("./math.osl")

log math.add(2, 3)
log math.square(4)

Without an export statement, a file exposes all of its declarations. Adding an export statement turns on an explicit public API for that file:

export {add, subtract as difference}
export {Vector} from "./geometry/vector.osl"
export * as geometry from "./geometry"

Consumers can import the full API, selected names, or a namespace:

import * from "./math.osl"
import {add, subtract as difference} from "./math.osl"
import * as math from "./math.osl"

Files in the same directory can share private declarations. Consumers in another directory see only exported declarations. Missing, duplicate, and conflicting exports are compile errors.

// math.osl
def _double(number n) number (
  return n * 2
)

def square(number n) number (
  return n * n
)

def quadruple(number n) number (
  return _double(_double(n))
)

Here math.square and math.quadruple are callable from outside. import(...) works with local .osl files whose path is a string literal.

Returned objects

Some packages give you an object to keep working with. For example, db.open() returns a database handle, and you call further methods on that:

import "std:db"

*db.DB handle = db.open("app.db")
handle.exec("CREATE TABLE users (id INTEGER, name TEXT)")
array rows = handle.query("SELECT * FROM users")

Each package page lists handle methods in a separate section.

The standard library at a glance

Web & networking

Package	Description
serve	HTTP server / web framework (routing, middleware, contexts).
ws	WebSocket client and server.
originchats	Bot framework for OriginChats servers.
requests	HTTP client methods including get, post, and put.
net	Low-level TCP/UDP sockets and DNS lookups.
url	URL parsing, building and query-string handling.
ftp	FTP file transfers.
ssh	SSH connections, remote commands and SCP.
s3	S3-compatible object storage client.
webpush	Web Push notifications (VAPID).

Data & serialization

Package	Description
json	JSON parsing and encoding.
yaml	YAML parsing and encoding.
schema	Composable validation and normalization schemas.
csv	CSV parsing plus a small dataframe-style toolkit.
xml	XML parsing and querying.
template	Lightweight {{ }} templating with HTML escaping.
md	Markdown to HTML (CommonMark + GFM via goldmark).
mime	MIME-type lookup and parsing.
diff	Text/line/word diffing.

Databases & storage

Package	Description
db	Embedded SQLite - SQL plus a document/collection API.
save	Simple persistent key-value storage.
cache	In-memory LRU cache with TTLs.
env	Environment variables and .env files.

Filesystem & system

Package	Description
fs	Files, directories and path utilities.
mem	Runtime memory counters, heap snapshots, and live pprof diagnostics.
sys	System info, environment, and running shell commands.
process	Spawn, manage and signal processes.
zip	ZIP / TAR / GZIP compression.

Crypto & security

Package	Description
crypto	Hashing, HMAC, AES, password hashing, file encryption, random.
jwt	JSON Web Token signing and verification.

Text, math & time

Package	Description
emoji	Emoji detection, extraction, replacement, flags, and skin tones.
regex	Regular expressions plus validators and text helpers.
semver	Semantic-version parsing and comparison.
math	Maths, statistics and number theory.
random	Seedable pseudo-random numbers.
date	Dates, durations and time zones.
cron	Cron-style job scheduling.
retry	Bounded retries with exponential backoff and jitter.

Terminal & logging

Package	Description
tui	Terminal UI: colours, boxes, tables, prompts, menus, charts.
log	Levelled, colourful logging.
notify	Desktop notifications.

Media & documents

Package	Description
img	Load, transform and save images.
qr	QR codes and barcodes.
pdf	Generate PDF documents.
canvas	In-memory pixel canvas.
colors	Build colour values (used by image-producing packages).
sound	Audio playback.

Graphics & windowing

Package	Description
shader	GLSL and OSL-style shader transpilation and rendering to images and windows.
raylib	Native windowing, input, 2D drawing, collision helpers, shaders, and textures.
window	Open a window and draw to it (the originOS graphics model).
win-buttons	Install native window controls.

Scripting & concurrency

Package	Description
testing	Assertions and the osl test workflow.
js	Run sandboxed JavaScript with hard resource limits.
lua	Embed and run Lua scripts.
thread	Background threads, parallel workers, racing, and message channels.
sync	Named locks, scoped locking, one-time execution, and wait groups.

Utilities & data structures

Package	Description
box2d	Box2D-compatible rigid-body worlds, bodies, and fixtures.
map	An ordered key-value map type.
set	A set type.
option	Optional values (some/none).
result	Success/error result values.
ptr	Low-level pointer operations.

More

Package	Description
email	Compose and send email (SMTP).
torrent	Create and parse .torrent files.

To read a package's source directly from the CLI:

osl package fs       # print the fs package source
osl package          # list every available package