ww/lib/bufio/vstream.ww

// vstream — Hare-shaped vtable port of lib/bufio. Project #94
// fold-eFinal(PREP).
//
// Collapses the OLD bufio surface (bufio.ww's pre-vtable `stream` +
// `scanner` over a legacy `*io.stream` src) onto the io.vtable surface,
// as parallel `_v`-suffixed additions. The OLD surface stays untouched
// here — fold-eFinal (FLIP) deletes it, renames the `_v` suffix off
// (bufio_ctx→stream, bufio_vstream→init, scanner_v→scanner, scanbytes_v
// →scanbytes, isbuffered_v→isbuffered, …) per Hare's
// ref/hare/bufio/{stream,scanner}.ha, and migrates the few callers.
//
// SCOPE (#94 fold-eFinal): this is a COLLAPSE of the surface ww ALREADY
// ships, NOT a port of Hare's full scanner. The features OLD bufio
// never implemented — auto-grow newscanner, multibyte-delim scanbytes /
// scanstring, scanrune / readbyte / readtok / readline / readrune /
// unreadrune — are a separate future feature fold (#217) and are OUT of
// eFinal. The ported set mirrors OLD exactly: the fixed-buffer
// newscanner_buf, single-byte scanbytes (OLD scantok), single-byte
// scanline, scanbyte, finish; and the buffered-stream init / setflush /
// flush / unread / isbuffered.
//
// VALUE-RETURN (drew, gating): Hare's bufio constructors return BY
// VALUE (ref/hare/bufio/stream.ha:69 init, scanner.ha:92
// newscanner_buf). The OLD out-param shape existed only because
// wide-struct sret was unimplemented — it now round-trips
// (test/wcc/925 + 776/778 byte-id), so each constructor builds in a
// local `let r: T;`, field-assigns every slot, and `return r;`. The
// caller owns the returned struct (stack ownership, no-GC). For the
// buffered stream the caller passes `&b.vt` to the io.st_* dispatchers;
// the scanner is a plain read-ahead tokenizer (no embedded vtable —
// matching OLD), driven directly via scanbyte_v / scanbytes_v / …
//
// VTABLE-NATIVE SRC (the eFinal point): the buffered stream's `src` and
// the scanner's `src` are now `io.vstream`, and every underlying read /
// write / close goes through io.st_read / io.st_write / io.st_close
// (the vtable dispatchers) — NOT the legacy io.read / io.write /
// io.close over `*io.stream`. The io.st_* surface returns io.error
// directly, so the OLD `io.closed → nomem-widen → io.error` dance
// (per the #173 deferral) is GONE: the error simply forwards.
//
// Cast workaround per #206-payoff (ken: KEEP the explicit casts; they
// are cgen-neutral and sidestep the #214 over-acceptance surface).
// `(&fn_name): *io.<role>` at each vtable store + the isbuffered_v
// fn-ptr-equality comparand — same workaround memio/vstream.ww +
// test/wcc/775 use.
//
// #207 (struct-lit multi-tagged-field copy drops past first) and #210
// (slice-field struct-lit drop under alloc): not reachable from the
// value-return form — every struct is built field-by-field in a local
// then sret-returned, no `alloc(T{...})` struct-lit. Both filings stay
// open for the struct-lit path; this fold doesn't take it.
//
// #209 (wwstage formattable match-arm bail when fmt imported): bufio
// does NOT import fmt (only io), so test/wcc/778 runs both stages +
// cs.s == ww.s byte-id on every row — bufio's only byte-id coverage
// (it is not compiler-embedded).
//
// Mode discrimination (drew-deferred): Hare uses three vtable
// singletons (vtable_r / vtable_w / vtable_rw); bufio_vstream installs
// all three callbacks per bufio.ww:32-38's divergence (zero-length
// rbuf/wbuf degenerates the matching callback in-cb). Defer-handle
// (MANAGED_* ownership bits) also deferred — caller owns rbuf/wbuf/src;
// bclose_v flushes + forwards close but frees nothing. Both graduate
// with io fold-2 (#5).

package bufio;

import io;

// bufio_ctx — heap-free state for bufio_vstream. `vt` at offset 0 for
// the intrusive vstream→*bufio_ctx cast. `src` is an io.vstream (the
// vtable-native underlying handle), not the OLD `*io.stream`. Mirrors
// lib/bufio.stream (bufio.ww:252) modulo io.vtable + io.vstream src.
export type bufio_ctx = struct {
	vt:     io.vtable,
	src:    io.vstream,
	rbuf:   []u8,
	rstart: i32,
	rend:   i32,
	wbuf:   []u8,
	wend:   i32,
	flush:  []u8,
};

// bufio_vstream — wire a buffered stream over an underlying io.vstream
// with caller-supplied read/write buffers. Both rbuf and wbuf may be
// empty; bread_v / bwrite_v degenerate per bufio.ww:34-38. The flush
// byte-set defaults to "\n" (line-buffered writes); setflush_v swaps it.
//
// Returns the ctx BY VALUE (sret — field-by-field build then
// `return r;`); the caller passes `&b.vt` to the io.st_* dispatchers.
//
// Mirrors ref/hare/bufio/stream.ha:69 (init).
export fn bufio_vstream(src: io.vstream, rbuf: []u8, wbuf: []u8) bufio_ctx = {
	let r: bufio_ctx;
	r.vt.reader = (&bread_v):  *io.reader;
	r.vt.writer = (&bwrite_v): *io.writer;
	r.vt.closer = (&bclose_v): *io.closer;
	r.src    = src;
	r.rbuf   = rbuf;
	r.rstart = rbuf.len;
	r.rend   = rbuf.len;
	r.wbuf   = wbuf;
	r.wend   = 0;
	r.flush  = flushdefault[0:1];
	return r;
};

// setflush_v — 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 OLD setflush (bufio.ww:287) +
// ref/hare/bufio/stream.ha:128.
export fn setflush_v(b: *bufio_ctx, bs: []u8) void = {
	b.flush = bs;
};

// flush_v — drain any pending wbuf data to src. Public API AND the
// internal drain called by bwrite_v / bclose_v — OLD bufio.flush is
// itself dual-purpose (bufio.ww:294, called from bwrite/bclose), so a
// single fn serves both; no separate private callback to rename. The
// io.closed → nomem-widen of the OLD V-side is gone: io.st_write
// returns io.error directly. A 0-byte non-error write means the sink
// made no progress (memio.fixed full) — surfaced as a nomem-carried
// io.error rather than spinning, matching what io.writeall would do in
// Hare. Mirrors OLD flush (bufio.ww:294) + ref/hare/bufio/stream.ha.
export fn flush_v(b: *bufio_ctx) (void | io.error) = {
	if (b.wend == 0) { return; };
	let off: i32 = 0;
	for (off < b.wend) {
		let r: (size | io.error) = io.st_write(b.src, b.wbuf[off:b.wend]);
		match (r) {
		case let n: size => {
			if (n == 0: size) {
				let nm: nomem;
				let e: io.error = nm;
				return e;
			};
			off += n: i32;
		};
		case let e: io.error => return e;
		};
	};
	b.wend = 0;
	return;
};

// unread_v — push `buf` back into the read buffer so the next bread_v
// 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
// rtabort (declared in bufio.ww, same package). Mirrors OLD unread
// (bufio.ww:321) + ref/hare/bufio/stream.ha:164.
export fn unread_v(b: *bufio_ctx, buf: []u8) void = {
	if (b.rstart < buf.len) {
		rtabort("bufio.unread_v: 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_v — true when `s` was returned by [[bufio_vstream]].
// Hare uses callback-identity (ref/hare/bufio/stream.ha:179); matches
// the OLD isbuffered shape (bufio.ww:338) over the new `_v` symbols.
// Either reader or writer matching is sufficient.
export fn isbuffered_v(s: io.vstream) bool = {
	match (s.reader) {
	case let r: *io.reader => {
		if (r == (&bread_v): *io.reader) { return true; };
	};
	case void => { };
	};
	match (s.writer) {
	case let w: *io.writer => {
		if (w == (&bwrite_v): *io.writer) { return true; };
	};
	case void => { };
	};
	return false;
};

// ---- buffered-stream vtable callbacks ------------------------------------

// bread_v — vstream-side buffered read. Recover ctx via the intrusive
// cast; refill rbuf from src via io.st_read on empty pending region.
// Mirrors bufio.ww:346 (OLD bread) modulo the io.vstream src +
// io.st_read dispatch (io.error forwards directly — no nomem-widen).
fn bread_v(s: io.vstream, buf: []u8) (size | io.eof | io.error) = {
	let b: *bufio_ctx = s: *bufio_ctx;
	if (b.rbuf.len == 0) {
		let e: io.eof; return e;
	};
	if (b.rstart >= b.rend) {
		b.rstart = 0;
		b.rend = 0;
		let r: (size | io.eof | io.error) = io.st_read(b.src, b.rbuf);
		match (r) {
		case let n: size => { b.rend = n: i32; };
		case io.eof => { let e: io.eof; return e; };
		case let e: io.error => 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: size;
};

// bwrite_v — vstream-side buffered write. wbuf-empty passes through to
// src; otherwise default-flush scan + per-batch copy + post-write
// conditional flush. Mirrors bufio.ww:376 (OLD bwrite) modulo the
// io.vstream src + io.st_write dispatch. Labeled-break inlined per
// bufio.ww:382 (ww has no labeled break).
fn bwrite_v(s: io.vstream, buf: []u8) (size | io.error) = {
	let b: *bufio_ctx = s: *bufio_ctx;
	if (b.wbuf.len == 0) {
		return io.st_write(b.src, buf);
	};
	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 fr: (void | io.error) = flush_v(b);
			match (fr) {
			case void => { };
			case let e: io.error => 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 fr: (void | io.error) = flush_v(b);
		match (fr) {
		case void => { };
		case let e: io.error => return e;
		};
	};
	return buf.len: size;
};

// bclose_v — flush pending wbuf, forward close to src via io.st_close.
// Mirrors bufio.ww:431. Caller-owned buffers/src are not freed (drew
// defer-handle deferral, bufio.ww:33-47).
fn bclose_v(s: io.vstream) (void | io.error) = {
	let b: *bufio_ctx = s: *bufio_ctx;
	let fr: (void | io.error) = flush_v(b);
	match (fr) {
	case void => { };
	case let e: io.error => return e;
	};
	let cr: (void | io.error) = io.st_close(b.src);
	match (cr) {
	case void => return void;
	case let e: io.error => return e;
	};
};

// ---- scanner (read-ahead tokenizer over an io.vstream src) ---------------
//
// Plain tokenizer — no embedded vtable (matching OLD bufio.scanner,
// bufio.ww:104); the scanner is driven directly via scanbyte_v /
// scanbytes_v / scanline_v, not through io.st_*. Its `src` is an
// io.vstream and refills go through io.st_read. Value-return
// constructor (Hare newscanner_buf, scanner.ha:92).
//
// ptr/cap kept flat (no `buf: []u8`) per the OLD scanner shape
// (bufio.ww:104-110); the scanner predates struct-held slice support.

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

// newscannerbuf_v — wire a scanner to read through `src` using `buf` as
// the fixed read-ahead window. Returns the scanner BY VALUE. This is
// Hare's newscanner_buf (ref/hare/bufio/scanner.ha:92); the auto-grow
// newscanner is a separate feature (#217, OUT of eFinal). Mirrors OLD
// newscanner (bufio.ww:116), which is itself the fixed-buffer form.
export fn newscannerbuf_v(src: io.vstream, buf: []u8) scanner_v = {
	let r: scanner_v;
	r.src = src;
	r.ptr = buf.ptr;
	r.cap = buf.len;
	r.start = 0;
	r.avail = 0;
	return r;
};

// finish_v — release scanner-owned resources. No-op (buffer is
// caller-owned, src isn't closed); kept on the surface so callers won't
// churn. Mirrors OLD finish (bufio.ww:127) + scanner.ha:110.
export fn finish_v(s: *scanner_v) void = { };

// readahead_v — make room and read once from src into the back of the
// pending region. Returns bytes newly buffered (>=0), or io.eof/io.error
// from src. Mirrors OLD readahead (bufio.ww:133) modulo io.st_read +
// io.error (no nomem-widen). Returns i32 (OLD shape); the size from
// io.st_read narrows to i32 (buffer-length type).
fn readahead_v(s: *scanner_v) (i32 | io.eof | io.error) = {
	if (s.start + s.avail == s.cap && s.start > 0) {
		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: (size | io.eof | io.error) = io.st_read(s.src, v);
	match (r) {
	case let n: size => {
		s.avail += n: i32;
		return n: i32;
	};
	case io.eof => { let e: io.eof; return e; };
	case let e: io.error => return e;
	};
};

// scanbyte_v — pop one byte, refilling from src on demand. Mirrors OLD
// scanbyte (bufio.ww:160) + ref/hare/bufio/scanner.ha:204.
export fn scanbyte_v(s: *scanner_v) (u8 | io.eof | io.error) = {
	for (s.avail == 0) {
		let r: (i32 | io.eof | io.error) = readahead_v(s);
		match (r) {
		case let n: i32 => { };
		case io.eof => { let e: io.eof; return e; };
		case let e: io.error => return e;
		};
	};
	let b: u8 = s.ptr[s.start];
	s.start += 1;
	s.avail -= 1;
	return b;
};

// scanbytes_v — read up to (and not including) the next byte equal to
// `delim`. The delim is consumed but not returned. The returned slice
// borrows from the scanner buffer and is invalidated by the next scan.
// EOF without delim discards the trailing fragment and returns io.eof
// (Hare EOF_DISCARD default); buffer-full without delim returns
// overflow. Single-byte delim only — Hare's `(u8 | []u8)` multibyte
// form is #217 (OUT). drew renames OLD scantok → scanbytes. Mirrors OLD
// scantok (bufio.ww:186) + ref/hare/bufio/scanner.ha:220 (narrowed).
export fn scanbytes_v(s: *scanner_v, delim: u8) ([]u8 | io.eof | io.error | 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;
		};
		if (s.start + s.avail == s.cap && s.start == 0) {
			let e: overflow; return e;
		};
		let r: (i32 | io.eof | io.error) = readahead_v(s);
		match (r) {
		case let n: i32 => { };
		case io.eof => { let e: io.eof; return e; };
		case let e: io.error => return e;
		};
	};
	let e: io.eof; return e;
};

// scanline_v — read up to (and not including) the next '\n'. The newline
// is consumed; the returned str view borrows from the scanner buffer.
// Single-byte route (Hare's scan_line = scan_string(s, "\n"); the
// arbitrary multibyte-delim scan_string is #217, OUT). Mirrors OLD
// scanline (bufio.ww:225) + ref/hare/bufio/scanner.ha:307.
export fn scanline_v(s: *scanner_v) (str | io.eof | io.error | overflow) = {
	let r: ([]u8 | io.eof | io.error | overflow) = scanbytes_v(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 let e: io.error => return e;
	case overflow => { let e: overflow; return e; };
	};
};