Hojun-Cho
bb10ee73a4
Hare-shaped {} / {0} / {n:mods} parser + printf wrappers. APIs:
fprintf, fprintfln, fdprintf, fdprintfln, printf, printfln, errorfln,
fatalf, bsprintf. Parser handles indexed/positional placeholders,
alignment (- / default / =), pad-width, zero-pad (_05), radix (x X o
b), precision (.N for int pad / str trunc), sign markers (+, space),
and {{ / }} escape.
Internals: scandigits + scanmods drive a field-by-field dispatch into
formatfield, which inlines the field→formattable widen per-arm to
sidestep task #18 (24B return-by-value miscompile in for-loop
context). Render through formatraw + formatone over io.stream sinks.
formatone tail-pad uses a separate counter rather than mirroring
Hare's `?`-propagating loop: ww's memio.fixed returns partial-write
0 instead of errors::overflow, so the Hare shape would spin forever
on a full fixed buffer.
Deferred per drew's vet: asprintf/errorf (needs os.alloc, #16),
parametric width/precision dispatch (#16-family), float arm (#17),
log.printfln family wiring (#15).
Tests: 26 scenarios covering every placeholder shape, both arms of
fprintf's variadic dispatch (incl. bool/rune to pin #18 regression),
bsprintf overflow + width-against-full-buffer, closed-stream.
71 lines
3.5 KiB
Markdown
71 lines
3.5 KiB
Markdown
lib/ — Hare-shaped standard library.
|
|
|
|
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 — drop Hare's underscores per
|
|
plan 9 style (`trim_prefix` → `trimprefix`, `next_token` → `nexttoken`).
|
|
Don't invent. Don't shorten further. Don't reorder parameters.
|
|
|
|
Signatures mirror Hare too, modulo:
|
|
|
|
- Tagged-union returns are spelled with the ww `!` error tag where
|
|
Hare uses `!void` / `!T`, and indices use the underlying length
|
|
type (`i32` today, since `str.len: i32`). Example:
|
|
`strconv.stoi64(s: str, b: strconv.base) (i64 | invalid | overflow)`
|
|
— same shape as Hare's. The base parameter is the named enum
|
|
`strconv.base` (Hare uses `enum uint`; we pick `enum i32` to
|
|
match the index type).
|
|
|
|
- Static-buffer `str` returns where Hare uses them. `strconv.*tos`
|
|
returns a `const str` view into a module-level buffer that is
|
|
overwritten on the next call to the same function. Callers that
|
|
need the bytes to outlive the next call duplicate via
|
|
[[strings.dup]]. Functions that genuinely allocate a fresh
|
|
buffer (`strings.dup`, `strings.concat`) still return an owned
|
|
`str` that callers free via `os.free(r.ptr, r.len: u64)`.
|
|
|
|
- Call-site variadic sugar matches Hare. `fn f(args: T...)` declares
|
|
a Hare-style variadic; call sites either gather N args into a
|
|
fresh `[]T` (`fmt.println(42, "hi", true)`) or forward an existing
|
|
slice with `xs...` (`fdprintln(fd, args...)`). The bare `T...` form
|
|
in tagged unions still means spread-flatten (`(...inner | E)`);
|
|
the two uses don't overlap because `T...` only attaches to a
|
|
*param* decl. `lib/fmt` ships both the print family (`print` /
|
|
`println` / `fprint` / `fprintln`) and the {n}-placeholder family
|
|
(`printf` / `fprintf` / `bsprintf` / `fatalf`); the `%`-parametric
|
|
modifier form is parsed but its `*mods` arg slot aborts on dispatch.
|
|
|
|
- `(T | U)` sum-typed parameters dispatch via `match` inside the
|
|
callee. `strings.byteindex(haystack: str, needle: (str | rune))`,
|
|
`bytes.index(s: []u8, needle: (u8 | []u8))`, and `rbyteindex`/
|
|
`rindex` follow Hare's shape directly. The rune-indexed
|
|
`strings.index` (rune-wise position) isn't shipped yet — we don't
|
|
have UTF-8 rune iteration in the language stack.
|
|
|
|
Don't ship a richer surface than Hare has. A documented subset is
|
|
fine; an extension, rename, or convenience-wrapper is not — callers
|
|
should not bake the current subset shape into themselves.
|
|
|
|
Modules with intentional divergence:
|
|
|
|
- `lib/os` and `lib/net` stay below the Hare abstraction — they are
|
|
syscall wrappers, not the high-level `io::handle` / `net::socket`
|
|
API. Use them as the foundation that `lib/io` and the buffered
|
|
layers build on.
|
|
- `lib/io` keeps the ww-specific `stream` struct (vtable of fn
|
|
pointers, no closures, no methods). The Hare `io::handle` family
|
|
needs language features we don't have yet.
|
|
- `lib/bufio` and `lib/sort` will be redesigned to Hare's
|
|
`scanner` / `cmpfunc` shapes; the present minimal forms are
|
|
placeholders until then.
|
|
- `lib/time` and `lib/math` ship only what callers need today;
|
|
they're not aiming for parity yet.
|
|
|
|
When the compiler can express a Hare signature that's still in the
|
|
ww-specific shape (e.g., once a module-level `*u8` is mutable, the
|
|
strconv `*tos` family graduates to static-buffer returns), graduate
|
|
the module in one go — replace the current shape with the Hare shape
|
|
and fix the callers. Don't keep both around.
|