36 lines
1.7 KiB
Markdown
36 lines
1.7 KiB
Markdown
lib/ — Hare-shaped standard library, deliberately a subset.
|
|
|
|
Scope: every `lib/*` directory except `lib/ww/`, which is the compiler
|
|
frontend port and has its own rules (see `lib/ww/CLAUDE.md`).
|
|
|
|
Names mirror Hare. Before adding a function, find its counterpart in
|
|
`ref/hare/<module>/` and copy the name verbatim (`strings.compare`,
|
|
`bytes.index`, `strconv.stoi64`, `io.read`, `path.init`). Don't
|
|
invent. Don't shorten. Don't reorder parameters.
|
|
|
|
Signatures are intentionally a Plan 9 / pre-tagged-union subset,
|
|
because the wwstage compiler doesn't yet have ergonomic tagged-union
|
|
returns or full variadic ABI:
|
|
|
|
- `i32` with `-1` sentinel stands in for Hare's `(size | void)` and
|
|
`(size | io::EOF)`. Example: `bytes.indexbyte(s, c) i32` returning
|
|
`-1` for not-found.
|
|
- Plain `str` errors stand in for tagged error types (`invalid`,
|
|
`overflow`, `io::error`). Example: `strconv.parse64(s) (i64 | str)`
|
|
where the `str` is the message Hare would have tagged.
|
|
- `lib/fmt` is print/println-only — printf-family waits on a variadic
|
|
ABI.
|
|
- Allocation-free at the boundary: where Hare returns a freshly-
|
|
allocated slice, take a caller-supplied buffer. No GC, and the `rt`
|
|
allocator is not a stable public surface yet.
|
|
|
|
Don't ship a richer surface than Hare has. A documented subset is
|
|
fine; an extension, rename, or convenience-wrapper is not — return
|
|
shapes will change as the compiler gains tagged unions, variadics,
|
|
and a stable `rt` allocator, and callers should not bake the current
|
|
subset shape into themselves.
|
|
|
|
When the compiler can express the full Hare signature, graduate the
|
|
module — replace the `-1` / `str` shape with the tagged-union shape
|
|
in one go and fix the callers. Don't keep both around.
|