Skip to content

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}
end
  • 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 Stats so far, and each read or write answers the meter after it; the caller threads it as it would thread any state. The stream underneath is std/io’s Reader or Writer, which already moves on as it is read or written; std has no network connection, so files and sockets are both whatever Reader and Writer stand for.
  • Stats is a struct of bytes and operations that both default to 0, and MeteredReader and MeteredWriter hold a stream and their Stats. 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’s io.Error and 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 through Reader.read_all_text cannot be handed a MeteredReader and 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 to io.stdout inside io.capture, and the failing read over Reader.from_fn.