ww/lib/log/log.ww

// log — process logger over a [[io.stream]] sink. Subset of Hare's
// lib/log (ref/hare/log/{logger,funcs,global,silent}.ha).
//
// Surface today:
//
//   log.logger     — vtable with a single `println` slot
//   log.stdlogger  — first-field embed of logger + a `*io.stream` sink
//   log.new        (sl: *stdlogger, sink: *io.stream) void
//   log.silent     *logger — a logger that discards every record
//   log.default    *logger — a stdlogger writing to stderr
//   log.global     *logger — the dispatch target for [[println]] / [[fatal]]
//   log.println    (args: fmt.formattable...) void
//   log.lprintln   (log: *logger, args: fmt.formattable...) void
//   log.fatal      (args: fmt.formattable...) never
//   log.lfatal     (log: *logger, args: fmt.formattable...) never
//   log.setlogger  (log: *logger) void
//
// Divergences from Hare:
//
//   • Hare returns the stdlogger from `new` by value; ww cgen can't
//     return wide structs, so [[new]] is out-parameter shaped. Same
//     workaround as memio.fixed / bufio.init.
//
//   • Hare initialises silent / default / _default via module-scope
//     struct literal lets. cstage `emit_lets` (cmd/w6c/cgen.c:6176)
//     only constexprs primitive / str-literal / array-literal lets —
//     struct- and pointer-literal init aren't reachable. ww drops to
//     a lazy [[ensureinit]] (lib/temp's `rnginit==0` pattern) called
//     from every exported fn. The public *logger globals are zero
//     initially and become non-nil after the first lib/log call;
//     callers that read globals directly (rather than going through
//     [[println]] / [[lprintln]] / [[setlogger]] / etc.) must call
//     some lib/log fn first so init runs.
//
//   • printfln / lprintfln / fatalf / lfatalf are skipped — they
//     need a fmt {n}-placeholder parser that isn't shipped yet. The
//     logger vtable carries only `println` today; the format-string
//     entries graduate with the parser.
//
// Sink today is [[io.stream]] only — lib/io has no fd-backed stream
// yet (Hare's `io::handle = file | int` collapses to one variant).
// The default logger writes to stderr via a private io.stream that
// dispatches through an rt_syscall write callback; mirrors lib/fmt's
// defensive `rawwrite` / `rawexit` shape for the same C-symbol
// collision reason (lib/os and lib/io both export `write`/`read`/
// `close`, and `use os;` from log would re-trip #17). Both fmt and
// log drop their rt_syscall stubs in one cleanup commit once #17
// (cgen module-mangling of fn labels) lands.
//
// Compiler note: wwstage cgen's variadic dispatch is name-based
// (`fnparamslookup(callee.str)`), which would conflate the
// `logger.println` vtable field with the top-level [[println]] fn
// if both stages compiled this module. cstage uses type-driven
// dispatch via the call-node's lhs type and handles fn-pointer
// variadic calls correctly. Today lib/log is consumed only by tests
// routed through `ww run` (cstage), so this is a latent issue
// covered by #11 (wwstage checkfile pass).
//
//   let buf: [128]u8;
//   let mem: memio.state;
//   let s:   io.stream;
//   memio.fixed(&mem, &s, buf[0:128]);
//
//   let sl: log.stdlogger;
//   log.new(&sl, &s);
//   log.lprintln(&sl.logger, "hello", 42i64);
//   // mem now holds "hello 42\n"
//
//   log.setlogger(&sl.logger);
//   log.println("through global");
//
//   log.setlogger(log.silent);
//   log.println("dropped");

use fmt;
use io;

// Direct rt_syscall bindings rather than `use os;` — os exports
// read/write/close, which collide with io.read/write/close under the
// driver's flat-scope concat. Mirrors lib/fmt and lib/memio. Removed
// once #17 (cgen mod-mangle for fn labels) lands.
@symbol("rt_syscall") fn rtsyscall3(num: i64, a: i64, b: i64, c: i64) i64;
@symbol("rt_syscall") fn rtsyscall1(num: i64, a: i64) i64;

// rawwrite — Linux write(2) syscall (nr=1). Private stderr sink uses
// this so log's exported surface stays clear of the os.write symbol.
fn rawwrite(fd: i32, p: *u8, n: u64) i64 = {
	return rtsyscall3(1i64, fd: i64, p: i64, n: i64);
};

// rawexit — Linux exit(2) syscall (nr=60). Used by [[fatal]] and
// [[lfatal]] for the process-terminating arm.
fn rawexit(code: i32) void = {
	rtsyscall1(60i64, code: i64);
};

// logger — interface for log dispatch. v1 carries a single vtable
// slot. Hare layers a `printfln` slot for format-string callbacks;
// that comes back when lib/fmt grows a {n}-placeholder parser.
//
// TODO: needs fmt {n}-placeholder parser (future task) — adds a
// `printfln: fn(l: *logger, fmt: str, args: fmt.field...) void`
// slot here.
export type logger = struct {
	println: fn(l: *logger, args: fmt.formattable...) void,
};

// stdlogger — concrete logger forwarding to a `*io.stream` sink.
// First-field embed: `&sl.logger` yields a `*logger` (same shape as
// bufio.bstream over its embedded io.stream vtable). The vtable
// callback recovers the outer stdlogger by casting the dispatch arg
// back to `*stdlogger`.
export type stdlogger = struct {
	logger: logger,
	sink:   *io.stream,
};

// stderrsink — private io.stream wired through the raw stderr fd (2)
// via [[rawwrite]]. Used as [[default]]'s sink. Independent of lib/io's
// future fd-backed stream — when that lands, this collapses to a
// thin wrapper and graduates in one go.
let stderrsink: io.stream;

// _silent — backing storage for the [[silent]] global.
let _silent: logger;

// _default — backing storage for the [[default]] global. Its sink
// points at [[stderrsink]] after [[ensureinit]] runs.
let _default: stdlogger;

// silent / default / global — Hare-style *logger globals. Zero-init
// at link time; lazily wired by [[ensureinit]] on the first call to
// any exported fn. See the file header for the divergence rationale.
export let silent:  *logger;
export let default: *logger;
export let global:  *logger;

// initdone — guards [[ensureinit]] so the one-shot wiring runs once.
// Mirrors lib/temp's `rnginit` pattern.
let initdone: i32 = 0;

fn ensureinit() void = {
	if (initdone != 0) { return; };
	stderrsink.ctx   = nil;
	stderrsink.read  = stderrread;
	stderrsink.write = stderrwrite;
	stderrsink.close = stderrclose;

	_silent.println = silentprintln;

	_default.logger.println = stdprintln;
	_default.sink = &stderrsink;

	silent  = &_silent;
	default = &_default.logger;
	global  = default;
	initdone = 1;
};

// stderrread / stderrwrite / stderrclose — io.stream callbacks for
// the private stderr sink. Read is a no-op returning io.eof; close
// is a no-op (the process owns fd 2). Write forwards to write(2)
// and translates a negative-errno into io.closed.
fn stderrread(s: *io.stream, buf: []u8) (i32 | io.eof | io.closed) = {
	let e: io.eof;
	return e;
};

fn stderrwrite(s: *io.stream, buf: []u8) (i32 | io.closed) = {
	let r: i64 = rawwrite(2, buf.ptr, buf.len: u64);
	if (r < 0) {
		let e: io.closed;
		return e;
	};
	return r: i32;
};

fn stderrclose(s: *io.stream) (void | io.closed) = { return; };

// stdprintln — vtable callback for stdlogger. Forwards to
// [[fmt.fprintln]] on the sink; the (i32 | io.closed) result is
// dropped — lib/log's surface is `void` (matches Hare).
fn stdprintln(l: *logger, args: fmt.formattable...) void = {
	let sl: *stdlogger = l: *stdlogger;
	fmt.fprintln(sl.sink, args...);
};

// silentprintln — vtable callback for the silent logger. Discards
// every record without dispatching through fmt; keeps silent truly
// silent if fmt ever gets stateful.
fn silentprintln(l: *logger, args: fmt.formattable...) void = { };

// new — wire `sl` as a stdlogger over `sink`. Hare returns by value
// (ref/hare/log/logger.ha:20); ww cgen can't return wide structs,
// so we take an out-parameter pointer (same shape as memio.fixed,
// bufio.init).
export fn new(sl: *stdlogger, sink: *io.stream) void = {
	ensureinit();
	sl.logger.println = stdprintln;
	sl.sink = sink;
};

// lprintln — dispatch `args` through `log`. Hare's lib/log/funcs.ha
// counterpart at line 8.
export fn lprintln(log: *logger, args: fmt.formattable...) void = {
	ensureinit();
	log.println(log, args...);
};

// println — dispatch through the [[global]] logger.
export fn println(args: fmt.formattable...) void = {
	ensureinit();
	lprintln(global, args...);
};

// lfatal — lprintln to `log` then exit(255). `never` return marks
// the bottom type so flow-control checks treat callers as terminated.
// Hare's lib/log/funcs.ha counterpart at line 28.
export fn lfatal(log: *logger, args: fmt.formattable...) never = {
	lprintln(log, args...);
	rawexit(255);
};

// fatal — lprintln to [[global]] then exit(255). Hare's lib/log/
// funcs.ha counterpart at line 45.
export fn fatal(args: fmt.formattable...) never = {
	println(args...);
	rawexit(255);
};

// setlogger — install `log` as the [[global]] logger. Hare's
// lib/log/global.ha counterpart at line 20.
export fn setlogger(log: *logger) void = {
	ensureinit();
	global = log;
};

// TODO: needs fmt {n}-placeholder parser (future task) — adds
// `lprintfln` / `printfln` / `lfatalf` / `fatalf` here once the
// printfln vtable slot is in place.