Goop has three API layers:
| Layer | Import needed? | Location |
|---|---|---|
| Language builtins | No | option, result, 'a list, chan, etc. |
| Prelude | No | Always in scope; defined in src/internal/prelude/prelude.go |
std.* modules |
Yes — import goop "std.io" |
std/ directory |
Go’s standard library is the Goop standard library for library coverage.
Reach Go packages with import go "net/http" { ... } (and curated .gosigs as they land).
std.* exists only for OCaml-idiomatic / Goop-native primitives — thin wrappers around language builtins and prelude helpers (list, option, result, array, string, chan, ref), plus a small I/O helper. It is not a mirror of Go’s stdlib.
Belongs in std.* |
Does not belong in std.* |
|---|---|
OCaml-shaped helpers (Map, isSome, length) |
std.net, std.http, std.json, std.codec, … |
Thin re-exports of prelude (Array.*, Chan.*, String.*) |
Re-wrapping every Go package “for consistency” |
Goop-native linear / effect surfaces (owned_chan) |
Large framework APIs that already exist in Go |
std.list staying small is intentional: list construction is builtin; the module only adds what the language does not.
Prelude reference — println, sprintf, List.filter / map / fold / find, ref, failwith, Map.*, Chan.*, OwnedChan.*, Lazy.*, string helpers, assertions.
Language builtins — primitive types, list, array, map[K] V, ref, option, result, lazy, channels.
| Module | Import path | Role | Reference |
|---|---|---|---|
std.io |
import goop "std.io" |
Thin fmt wrapper (Println) |
std.io |
std.list |
import goop "std.list" |
Re-exports prelude List.* (Filter / Map / Fold) |
std.list |
std.map |
import goop "std.map" |
Thin re-export of prelude Map.* |
prelude Maps · tutorial · maps.goop |
std.array |
import goop "std.array" |
Re-export of prelude Array.* |
std.array |
std.option |
import goop "std.option" |
Option predicates | std.option |
std.result |
import goop "std.result" |
Result predicates | std.result |
std.string |
import goop "std.string" |
Re-export of prelude string ops | std.string |
std.chan |
import goop "std.chan" |
Re-export of Chan.* / OwnedChan.* (std/channel) |
std.chan |
std.ref |
import goop "std.ref" |
Re-export of prelude ref |
std.ref |
std.decimal |
import goop "std.decimal" |
Fixed-point money (shopspring/decimal) |
std.decimal |
| Candidate | Status | Notes |
|---|---|---|
More std.list combinators |
Landed prelude List.filter / map / fold / find (Go generics) |
Keep thin |
std.lazy |
Deferred | Keyword lazy cannot appear in 'a lazy annotations inside a std.lazy wrapper (PARSE001); prelude Lazy.* / lazy e stay |
| Decimal / money | Landed | std.decimal + cross-module Decimal annotations (25-decimal.md); H5/H6 polish remain |
std.net / std.codec / … |
Out of scope | Use import go |
import goop "std.io" // qualified: must use module exports by name
import goop . "std.io" // dot: Println in scope
import io goop "std.io" // alias: io.Println
Resolution is configured in goop.toml [mappings] and defaults in the compiler. See modules guide.
| Layer | Convention | Example |
|---|---|---|
| Prelude | snake_case / qualified Module.name |
println, String.length, Chan.make |
std.* re-exports |
lowercase matching OCaml module style | make, length, concat |
std.* helpers |
PascalCase or camelCase |
Println, Map, isSome |
| Constructors | PascalCase |
Some, Ok, OrderId |
Keyword module names (chan, ref, lazy) cannot appear as module … headers; std.chan lives in std/channel, and std.ref uses module Ref.
This reference is hand-written from compiler sources (prelude.go, std/*/*.goop). When adding prelude bindings or std.* exports, update the matching page here and [mappings] in goop.toml / src/internal/config/config.go. Cross-check binding names against prelude.go (see 31-language-update-checklist.md).
goop doc emits Markdown API signatures for .goop modules (and .gosig stubs) to stdout — it complements this hand reference; see 20-cli-artifacts.md.