PaaS I/O
Wrap a stream so that it reports what passed through it: the bytes read or written, and the number of read or write operations.
Adapted from Exercism’s problem specification (MIT). Listed under Collections & Algorithms.
// FILE: paasio.nomi
//# Readers and writers that count the bytes and operations passing through
//# them.
import std::io.{self, Reader, Writer}
/// What a stream has carried: how many bytes, in how many operations.
pub struct Stats
bytes: Int = 0
operations: Int = 0
end
impl Stats
/// `stats` after one more operation that carried `bytes` bytes.
fn add(stats: Stats, bytes: Int) -> Stats
{bytes: stats.bytes + bytes, operations: stats.operations + 1}
end
end
/// A reader that counts what is read through it. The reader underneath is a
/// stream that moves on as it is read; the counts are a value, so each read
/// answers the meter after it.
pub struct MeteredReader
reader: Reader
stats: Stats = Stats{}
end
impl MeteredReader
/// A meter over `reader` that has counted nothing.
pub fn new(reader: Reader) -> MeteredReader
{reader:}
end
/// The next bytes of the stream, at most `max`, or `None` at its end,
/// with the meter after the read. Every read counts as an operation, the
/// one that finds the end too. An error is the reader's, and counts
/// nothing.
pub fn read(
meter: MeteredReader,
max: PositiveInt = 65536,
) -> Result<(Maybe<Bytes>, MeteredReader), io.Error>
data = Reader.read(meter.reader, max)?
bytes = data |> Maybe.map(Bytes.length) |> Maybe.with_default(0)
Ok((data, {..meter, stats: Stats.add(.., bytes)}))
end
end
/// A writer that counts what is written through it, as `MeteredReader`
/// counts reads.
pub struct MeteredWriter
writer: Writer
stats: Stats = Stats{}
end
impl MeteredWriter
/// A meter over `writer` that has counted nothing.
pub fn new(writer: Writer) -> MeteredWriter
{writer:}
end
/// Writes `data` and answers the meter after the write. An error is the
/// writer's, and counts nothing.
pub fn write(meter: MeteredWriter, data: Bytes) -> Result<MeteredWriter, io.Error>
Writer.write(meter.writer, data)?
Ok({..meter, stats: Stats.add(.., Bytes.length(data))})
end
end
// FILE: paasio_test.nomi
import
std::io.{self, Reader}
paasio.{MeteredReader, MeteredWriter, Stats}
end
/// Reads `meter` to the end, `max` bytes at a time, and answers the bytes
/// read and the meter after the last read.
fn read_to_end(meter: MeteredReader, max: PositiveInt) -> Result<(Bytes, MeteredReader), io.Error>
(data, meter) = MeteredReader.read(meter, max)?
case data
None ->
Ok((Bytes.from_list([]), meter))
Some(bytes) ->
(rest, meter) = read_to_end(meter, max)?
Ok((bytes + rest, meter))
end
end
test "a new meter has counted nothing"
reader = Reader.from_text("hello") |> MeteredReader.new()
writer = MeteredWriter.new(io.stdout)
assert reader.stats == Stats{bytes: 0, operations: 0}
assert writer.stats == Stats{bytes: 0, operations: 0}
end
test "reads count their bytes and themselves"
meter = Reader.from_text("hello world") |> MeteredReader.new()
(data, meter) = read_to_end(meter, 4)?
assert data == String.to_bytes("hello world")
assert meter.stats == Stats{bytes: 11, operations: 4}
end
test "one read takes what fits, and the next finds the end"
meter = Reader.from_text("hello world") |> MeteredReader.new()
(data, meter) = read_to_end(meter, 1024)?
assert data == String.to_bytes("hello world")
assert meter.stats == Stats{bytes: 11, operations: 2}
end
test "reading an empty stream is one operation and no bytes"
meter = Reader.from_text("") |> MeteredReader.new()
(data, meter) = MeteredReader.read(meter)?
assert data == None
assert meter.stats == Stats{bytes: 0, operations: 1}
end
test "a read error passes through"
meter = Reader.from_fn(fn -> Err(io.Error.TimedOut)) |> MeteredReader.new()
assert Err(io.Error.TimedOut) = MeteredReader.read(meter)
end
test "writes count their bytes and themselves"
run = io.capture("", fn ->
meter = MeteredWriter.new(io.stdout)
meter = MeteredWriter.write(meter, String.to_bytes("hello"))?
meter = MeteredWriter.write(meter, String.to_bytes(", "))?
meter = MeteredWriter.write(meter, String.to_bytes("world"))?
Ok(meter.stats)
end)
assert run.output == "hello, world"
assert run.value == Ok(Stats{bytes: 12, operations: 3})
end
test "earlier meters keep their own counts"
first = Reader.from_text("abcdef") |> MeteredReader.new()
(_, second) = MeteredReader.read(first, 2)?
(_, third) = MeteredReader.read(second, 2)?
assert first.stats == Stats{bytes: 0, operations: 0}
assert second.stats == Stats{bytes: 2, operations: 1}
assert third.stats == Stats{bytes: 4, operations: 2}
endok a new meter has counted nothing
ok reads count their bytes and themselves
ok one read takes what fits, and the next finds the end
ok reading an empty stream is one operation and no bytes
ok a read error passes through
ok writes count their bytes and themselves
ok earlier meters keep their own counts
test result: ok. 7 passed, 0 failed
How it’s written
Section titled “How it’s written”- Adapted: the exercise asks for a wrapper object around a file or a network connection that keeps running totals as it is used. Nomi values cannot change, so a meter is a value that pairs the stream with its
Statsso far, and eachreadorwriteanswers the meter after it; the caller threads it as it would thread any state. The stream underneath is std/io’sReaderorWriter, which already moves on as it is read or written; std has no network connection, so files and sockets are both whateverReaderandWriterstand for. Statsis a struct ofbytesandoperationsthat both default to 0, andMeteredReaderandMeteredWriterhold a stream and theirStats. Every read counts as an operation, the one that finds the end of the stream too, since it is a call the platform served; an error is passed up as the stream’sio.Errorand counts nothing.- A meter is an ordinary value, so an earlier meter keeps the counts it had: the last test reads twice and checks all three meters.
- The meter is a value the caller threads, so it is not itself a
Reader: code that reads throughReader.read_all_textcannot be handed aMeteredReaderand be counted, because that function’s reading loop is its own and a count needs a loop to ride in. Where the reading loop is the caller’s, the count is a fold:Reader.chunks(r) |> Iter.try_reduce((0, 0), fn (total, reads), chunk -> Ok((total + Bytes.length(chunk?), reads + 1))). This port threads a meter because the exercise reads and writes one call at a time. - The exercise has no canonical data. The tests follow the other tracks’ in spirit: reads and writes count bytes and operations, the data passes through unchanged, an error passes through. Reads go over
Reader.from_text, writes toio.stdoutinsideio.capture, and the failing read overReader.from_fn.