std.text.stream

std.text.stream

std.text.stream is the shipped v1 text-stream facade for :script text work. It is bridge-backed, bounded to concrete operators, and intentionally smaller than the long-term stream algebra.

The current module exposes real string streams plus bridge-backed file handles, grep-style selection, head, skip, literal replacement, count, and joinLines. It does not yet expose callback map, callback filter, materializing collect, unique, sorting, grouping, parallelism, or automatic fusion.

Types

pub struct Provenance {
    path: str,
    line: u64,
    byte_offset: u64,
}

pub struct Line {
    text: str,
    provenance: Provenance,
}

pub struct TextStream[T] {
    _handle: usize,
}

TextStream[T] wraps an opaque bridge handle. Terminal operators consume the current stream state.

Constructors

pub func fromString(input: []const u8) -> TextStream[Line]
pub func fromFile(path: []const u8) -> TextStream[Line]
pub func fromGlob(pattern: []const u8) -> TextStream[Line]
pub func fromStdin() -> TextStream[Line]

fromString is the proven v1 constructor. fromFile, fromGlob, and fromStdin exist as bridge handles, but only string streams are covered by the current Janus smoke.

Selection

pub func grep[T](self: TextStream[T], pattern: []const u8) -> TextStream[T]
pub func grepV[T](self: TextStream[T], pattern: []const u8) -> TextStream[T]
pub func head[T](self: TextStream[T], n: usize) -> TextStream[T]
pub func skip[T](self: TextStream[T], n: usize) -> TextStream[T]

grep keeps matching records. grepV excludes matching records. head limits the emitted records; skip consumes emitted records before returning the rest.

Replacement

pub func replace[T](
    self: TextStream[T],
    pattern: []const u8,
    replacement: []const u8,
) -> TextStream[T]

pub func replaceFirst[T](
    self: TextStream[T],
    pattern: []const u8,
    replacement: []const u8,
) -> TextStream[T]

The bridge currently performs literal byte-pattern replacement. Regex-grade replacement can be layered later once the stream bridge and std.text.rex share a common matcher contract.

Terminal Operators

pub func count[T](self: TextStream[T]) -> u64
pub func joinLines[T](self: TextStream[T], sep: []const u8) -> *u8

count consumes the stream and returns the number of emitted records. joinLines consumes the stream and returns a NUL-terminated bridge-owned byte buffer.

Convenience

pub func grepFile(path: []const u8, pattern: []const u8) -> TextStream[Line]
pub func countMatches(path: []const u8, pattern: []const u8) -> u64
pub func headMatches(path: []const u8, pattern: []const u8, n: usize) -> TextStream[Line]

These are thin compositions over fromFile, grep, count, and head.

Deferred Surface

The following names are not part of the shipped v1 surface:

• callback map
• callback filter
• materializing collect
• unique
• sort/group/parallel stream algebra
• compile-time fusion guarantees

Those require a real callback/materialization bridge. The module now refuses to pretend they exist.

Verification

./scripts/zb test-text-stream

The target runs bridge unit tests and the Janus AOT smoke std/text/stream_smoke.jan, proving fromString, grep, grepV, head, skip, replace, replaceFirst, and count.