ww/lib/bufio/bufio.ww

// bufio — buffered I/O over [[io.stream]]. Subset of Hare's bufio::
// surface (ref/hare/bufio/{scanner,stream}.ha).
//
// Surface today:
//
//   bufio.newscanner(s: *scanner, src: *io.stream, buf: []u8) void
//   bufio.finish    (s: *scanner) void
//   bufio.scanbyte  (s: *scanner) (u8     | io.eof | io.closed)
//   bufio.scantok   (s: *scanner, delim: u8)
//                   ([]u8 | io.eof | io.closed | overflow)
//   bufio.scanline  (s: *scanner) (str    | io.eof | io.closed | overflow)
//
//   bufio.init       (b: *stream, src: *io.stream, rbuf: []u8, wbuf: []u8) void
//   bufio.flush      (b: *stream) (void | io.closed)
//   bufio.unread     (b: *stream, buf: []u8) void
//   bufio.isbuffered (s: *io.stream) bool
//
// Divergence from Hare:
//
//   • Hare returns the scanner / stream by value; ww cgen can't
//     return structs wider than 16B by value yet, so `newscanner`
//     and `init` are out-parameter shaped. Same workaround
//     memio.fixed uses.
//
//   • The scanner's read buffer is held flat as `(ptr, cap)` rather
//     than a `[]u8` field; the scanner predates struct-held slice
//     support and is wired through scanbyte/scantok/scanline. The
//     new stream writer half uses slice-typed `rbuf` / `wbuf`
//     fields directly — chained dot through a struct slice field
//     works after task #6.
//
//   • Hare's `bufio::stream` discriminates r-only / w-only / r+w
//     via three different vtable singletons (vtable_r, vtable_w,
//     vtable_rw); ww's [[io.stream]] vtable always carries all
//     three callbacks, so stream always installs `bread` /
//     `bwrite` / `bclose`. A zero-length rbuf or wbuf makes the
//     matching callback degenerate (rbuf=[]: bread short-circuits
//     to io.eof; wbuf=[]: bwrite passes through to src).
//
//   • Hare's `init` also takes a `flag` argument carrying
//     MANAGED_HANDLE / MANAGED_RDBUF / MANAGED_WRBUF ownership
//     bits; stream never owns its buffers or src, so the
//     `flags` field and the init-time argument are dropped
//     wholesale. The Hare `flush: []u8` byte-set is preserved —
//     [[init]] seeds it to `['\n']` (line buffering, matching
//     Hare's `flag::NONE` default at stream.ha:75) and
//     [[setflush]] swaps it.
//
//   • Hare's `newscanner` allocates and grows the buffer up to
//     `maxread`; we ship only the caller-supplied shape (Hare's
//     `newscanner_buf`) and pick up the auto-grow variant when an
//     append over a struct-held slice works.
//
//   • EOF-handling defaults to Hare's `EOF_DISCARD`: bytes between
//     the last delimiter and EOF are dropped and io.eof is returned
//     on the call that would have read them. Hare's EOF_GREEDY mode
//     isn't shipped (no caller needs it yet).
//
// Owning model: caller owns the scanner state, the stream state,
// the byte buffers, and the source stream. `finish` doesn't free
// the buffer and doesn't close src; it's a no-op today but stays
// on the surface so callers don't churn when bufio grows internal
// allocations. The stream vtable `close` callback flushes pending
// writes and forwards close to src; it does not free rbuf / wbuf.
//
//   let mem: memio.state;
//   let m:   io.stream;
//   memio.fixed(&mem, &m, raw[0:N]);
//   let buf: [128]u8;
//   let sc:  bufio.scanner;
//   bufio.newscanner(&sc, &m, buf[0:128]);
//   match (bufio.scanline(&sc)) { ... };
//   bufio.finish(&sc);
//
//   let b:    bufio.stream;
//   let rbuf: [256]u8;
//   let wbuf: [128]u8;
//   bufio.init(&b, src, rbuf[0:256], wbuf[0:128]);
//   let p: *io.stream = &b.vtable;	// first-field embed
//   io.write(p, msg);
//   bufio.flush(&b);

use io;

// flushdefault — backing storage for the default flush byte-set
// ("\n"). Hare scopes it inside `init` as `static let
// flush_default = ['\n': u8]` (ref/hare/bufio/stream.ha:75); ww
// has no function-scope statics, so it lives at module scope.
let flushdefault: [1]u8 = [10u8];

// rt_abort — terminate on a precondition violation. Used by
// [[unread]] for the "buf fits in front of rbuf" assertion that
// Hare expresses with `assert`.
@symbol("rt_abort") fn rtabort(msg: str) void;

// overflow — the scanner buffer filled before the delimiter (or
// underlying EOF) was hit. With a caller-supplied buffer we can't
// grow; bumping the budget is on the caller. Mirrors Hare bufio's
// use of errors::overflow for the same condition.
export type overflow = !void;

export type scanner = struct {
	src:   *io.stream,
	ptr:   *u8,
	cap:   i32,
	start: i32,	// index where the pending region starts in ptr
	avail: i32,	// pending byte count; pending = ptr[start..start+avail]
};

// newscanner — wire `s` to read through `src` using `buf` as the
// read-ahead window. Hare returns the scanner by value
// (newscanner_buf); we take an out-parameter pending cgen support
// for wide-struct return.
export fn newscanner(s: *scanner, src: *io.stream, buf: []u8) void = {
	s.src = src;
	s.ptr = buf.ptr;
	s.cap = buf.len;
	s.start = 0;
	s.avail = 0;
};

// finish — release scanner-owned resources. No-op today (buffer is
// caller-owned, src isn't closed); kept on the surface so callers
// won't churn when bufio later grows internal allocations.
export fn finish(s: *scanner) void = { };

// readahead — make room and read once from src into the back of the
// pending region. Returns the number of bytes newly buffered (≥0,
// can be 0 if the underlying stream made no progress), or
// io.eof/io.closed propagated from src.
fn readahead(s: *scanner) (i32 | io.eof | io.closed) = {
	if (s.start + s.avail == s.cap && s.start > 0) {
		// Shift pending region to the front of the buffer.
		let i: i32 = 0;
		for (i < s.avail) {
			s.ptr[i] = s.ptr[s.start + i];
			i += 1;
		};
		s.start = 0;
	};
	let off: i32 = s.start + s.avail;
	let v: []u8;
	v.ptr = s.ptr + (off: u64);
	v.len = s.cap - off;
	let r: (i32 | io.eof | io.closed) = io.read(s.src, v);
	match (r) {
	case let n: i32 => {
		s.avail += n;
		return n;
	};
	case io.eof => { let e: io.eof; return e; };
	case io.closed => { let e: io.closed; return e; };
	};
};

// scanbyte — pop one byte from the scanner, refilling from src on
// demand. Mirrors Hare's `scan_byte` (ref/hare/bufio/scanner.ha:204).
export fn scanbyte(s: *scanner) (u8 | io.eof | io.closed) = {
	for (s.avail == 0) {
		let r: (i32 | io.eof | io.closed) = readahead(s);
		match (r) {
		case let n: i32 => { };
		case io.eof => { let e: io.eof; return e; };
		case io.closed => { let e: io.closed; return e; };
		};
	};
	let b: u8 = s.ptr[s.start];
	s.start += 1;
	s.avail -= 1;
	return b;
};

// scantok — read up to (and not including) the next byte equal to
// `delim`. The delim byte is consumed from the stream but not
// returned. The returned slice borrows from the scanner's internal
// buffer and is invalidated by the next scan call.
//
// EOF without finding delim discards the trailing fragment and
// returns io.eof (Hare's EOF_DISCARD default). Buffer-full without
// delim returns overflow.
//
// Mirrors Hare's `scan_bytes` (ref/hare/bufio/scanner.ha:220),
// narrowed to a single-byte delimiter.
export fn scantok(s: *scanner, delim: u8) ([]u8 | io.eof | io.closed | overflow) = {
	let i: i32 = 0;
	for (true) {
		for (i < s.avail) {
			if (s.ptr[s.start + i] == delim) {
				let v: []u8;
				v.ptr = s.ptr + (s.start: u64);
				v.len = i;
				s.start += i + 1;
				s.avail -= i + 1;
				return v;
			};
			i += 1;
		};
		// No delim in pending. If the buffer is full with nowhere
		// to shift, the caller's budget is too small — overflow.
		if (s.start + s.avail == s.cap && s.start == 0) {
			let e: overflow; return e;
		};
		let r: (i32 | io.eof | io.closed) = readahead(s);
		match (r) {
		case let n: i32 => {
			// readahead may shift start to 0; the searched bytes
			// move with it, so `i` (count from start) is still
			// accurate. Resume scanning where we left off.
		};
		case io.eof => { let e: io.eof; return e; };
		case io.closed => { let e: io.closed; return e; };
		};
	};
	let e: io.eof; return e;
};

// scanline — read up to (and not including) the next '\n'. The
// newline is consumed; the returned str view borrows from the
// scanner buffer and is invalidated by the next scan call.
// Hare's `scan_line` is `scan_string(s, "\n")`; we route through
// scantok directly since lib/strings doesn't yet ship `toutf8` over
// a multi-byte delim.
export fn scanline(s: *scanner) (str | io.eof | io.closed | overflow) = {
	let r: ([]u8 | io.eof | io.closed | overflow) = scantok(s, 10u8);
	match (r) {
	case let bs: []u8 => {
		let v: str;
		v.ptr = bs.ptr;
		v.len = bs.len;
		return v;
	};
	case io.eof => { let e: io.eof; return e; };
	case io.closed => { let e: io.closed; return e; };
	case overflow => { let e: overflow; return e; };
	};
};

// stream — buffered read+write over an underlying *io.stream.
//
// `vtable` is the first field so a `*stream` is castable to an
// `*io.stream` via address-of-field (`&b.vtable`). Higher layers
// (fmt.fprint, scanner, …) only see the io.stream view; bufio
// recovers the outer stream by casting the dispatch arg back to
// `*stream` inside the bread/bwrite/bclose callbacks.
//
// rbuf[rstart..rend] is pending read data; wbuf[0..wend] is pending
// write data. rbuf or wbuf may be zero-length: read-empty makes
// bread return io.eof immediately, write-empty makes bwrite a
// pass-through to src (uses src.write directly, no buffering).
export type stream = struct {
	vtable: io.stream,
	src:    *io.stream,
	rbuf:   []u8,
	rstart: i32,
	rend:   i32,
	wbuf:   []u8,
	wend:   i32,
	flush:  []u8,
};

// init — wire `b` over `src` with caller-supplied buffers. Both
// rbuf and wbuf may be empty slices; the corresponding direction
// degenerates (see [[stream]]). The flush byte-set defaults to
// "\n" (line-buffered writes); [[setflush]] swaps it.
export fn init(b: *stream, src: *io.stream, rbuf: []u8, wbuf: []u8) void = {
	b.vtable.ctx = b: *void;
	b.vtable.read = bread;
	b.vtable.write = bwrite;
	b.vtable.close = bclose;
	b.src = src;
	b.rbuf = rbuf;
	// rstart=rbuf.len, rend=rbuf.len: pre-read unread budget = rbuf.len
	// (Hare bufio/stream.ha:101).
	b.rstart = rbuf.len;
	b.rend = rbuf.len;
	b.wbuf = wbuf;
	b.wend = 0;
	b.flush = flushdefault[0:1];
};

// setflush — install a new flush byte-set. Any byte from `bs`
// appearing in a write payload triggers an automatic flush after
// the write copies into wbuf. Mirrors Hare's `setflush`
// (ref/hare/bufio/stream.ha:128).
export fn setflush(b: *stream, bs: []u8) void = {
	b.flush = bs;
};

// flush — drain any pending wbuf data to src. Hare returns
// `(void | io::error)`; ww's io.stream write-side error channel
// is `io.closed` alone, so the return shape narrows.
export fn flush(b: *stream) (void | io.closed) = {
	if (b.wend == 0) { return; };
	let off: i32 = 0;
	for (off < b.wend) {
		let r: (i32 | io.closed) = io.write(b.src, b.wbuf[off:b.wend]);
		match (r) {
		case let n: i32 => {
			if (n == 0) {
				// Underlying stream made no progress. Treat as
				// closed rather than spin; matches what
				// io.writeall would do in Hare.
				let e: io.closed; return e;
			};
			off += n;
		};
		case io.closed => { let e: io.closed; return e; };
		};
	};
	b.wend = 0;
	return;
};

// unread — push `buf` back into the read buffer so the next bread
// returns it first. The bytes must fit in front of the pending
// region (rstart >= buf.len); Hare aborts on overflow, ww does the
// same via rt_abort. Mirrors Hare's `stream_unread`
// (ref/hare/bufio/stream.ha:164).
export fn unread(b: *stream, buf: []u8) void = {
	if (b.rstart < buf.len) {
		rtabort("bufio.unread: more data than rbuf has room for");
	};
	let i: i32 = 0;
	for (i < buf.len) {
		b.rbuf[b.rstart - buf.len + i] = buf[i];
		i += 1;
	};
	b.rstart -= buf.len;
};

// isbuffered — true when `s` is a [[bufio.stream]]'s embedded
// vtable. Hare's discriminator is callback identity
// (ref/hare/bufio/stream.ha:179); we match the shape directly. The
// read or write callback being bread / bwrite is sufficient (close
// alone isn't unique to bufio).
export fn isbuffered(s: *io.stream) bool = {
	if (s.read == bread) { return true; };
	if (s.write == bwrite) { return true; };
	return false;
};

// ---- vtable callbacks ------------------------------------------------

fn bread(s: *io.stream, buf: []u8) (i32 | io.eof | io.closed) = {
	let b: *stream = s.ctx: *stream;
	// No read buffer configured: surface eof immediately rather
	// than punch through to src (callers asked for a write-only
	// stream, reads against it are a misuse).
	if (b.rbuf.len == 0) { let e: io.eof; return e; };
	// Empty pending region: refill from src. Reset rstart so
	// unread has the full buffer to push back into.
	if (b.rstart >= b.rend) {
		b.rstart = 0;
		b.rend = 0;
		let r: (i32 | io.eof | io.closed) = io.read(b.src, b.rbuf);
		match (r) {
		case let n: i32 => { b.rend = n; };
		case io.eof => { let e: io.eof; return e; };
		case io.closed => { let e: io.closed; return e; };
		};
	};
	let avail: i32 = b.rend - b.rstart;
	let n: i32 = buf.len;
	if (avail < n) { n = avail; };
	let i: i32 = 0;
	for (i < n) {
		buf[i] = b.rbuf[b.rstart + i];
		i += 1;
	};
	b.rstart += n;
	return n;
};

fn bwrite(s: *io.stream, buf: []u8) (i32 | io.closed) = {
	let b: *stream = s.ctx: *stream;
	// No write buffer configured: pass through to src directly.
	if (b.wbuf.len == 0) { return io.write(b.src, buf); };
	// Scan the write payload for any byte present in b.flush — a
	// hit triggers a post-copy flush. Hare uses a labeled break to
	// exit both loops on first hit (stream.ha:236-246); ww has no
	// labeled break, so we bump both indices past their bounds.
	let doflush: bool = false;
	if (b.flush.len != 0) {
		let i: i32 = 0;
		for (i < buf.len) {
			let j: i32 = 0;
			for (j < b.flush.len) {
				if (buf[i] == b.flush[j]) {
					doflush = true;
					i = buf.len;
					j = b.flush.len;
				};
				j += 1;
			};
			i += 1;
		};
	};
	let z: i32 = 0;
	for (z < buf.len) {
		let avail: i32 = b.wbuf.len - b.wend;
		if (avail == 0) {
			let r: (void | io.closed) = flush(b);
			match (r) {
			case void => { };
			case io.closed => { let e: io.closed; return e; };
			};
			avail = b.wbuf.len;
		};
		let n: i32 = buf.len - z;
		if (avail < n) { n = avail; };
		let i: i32 = 0;
		for (i < n) {
			b.wbuf[b.wend + i] = buf[z + i];
			i += 1;
		};
		b.wend += n;
		z += n;
	};
	if (doflush) {
		let r: (void | io.closed) = flush(b);
		match (r) {
		case void => { };
		case io.closed => { let e: io.closed; return e; };
		};
	};
	return buf.len;
};

fn bclose(s: *io.stream) (void | io.closed) = {
	let b: *stream = s.ctx: *stream;
	let r: (void | io.closed) = flush(b);
	match (r) {
	case void => { };
	case io.closed => { let e: io.closed; return e; };
	};
	return io.close(b.src);
};