ww/lib/CLAUDE.md at d68d3c7eb4c44318fc89bde307ac39be27d138a2

Files

Hojun-Cho bb10ee73a4 lib/fmt+test: add {n}-placeholder printf family

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.

2026-05-16 00:45:30 +09:00

3.5 KiB

Raw Blame History

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.

3.5 KiB Raw Blame History

3.5 KiB

Raw Blame History