Examples

What private is for: a module that keeps its insides to itself

The 2 files of examples/ring/, and what zeno run examples/ring/main.zeno prints.

ring/main.zeno
# What `private` is for: a module that keeps its insides to itself.
#
#     zeno run examples/ring/main.zeno
#
# `ring.zeno` declares a queue of a fixed size. This file uses it
# through the four functions the module lets it see.
import ring

let queue = ring.ring(4)

for byte in [10, 20, 30, 40, 50] {
    if not queue.put(byte) {
        print(f"no room for {byte}")
    }
}
print(f"{queue.size()} waiting, room for {queue.room()}")

# Two come out, and two more fit in: the ring goes round.
print(queue.get())
print(queue.get())
queue.put(60)
queue.put(70)

var next = queue.get()
while next is not none {
    print(next)
    next = queue.get()
}
print(f"{queue.size()} waiting, room for {queue.room()}")

# Each of these lines is refused by `zeno check`, with a message that
# says the name is private:
#
#     queue.count = 0
#     print(queue.slots)
#     let mine = ring.Ring([1, 2], 0, 2)
#     print(ring.wrapped(5, 4))
ring/ring.zeno
# The module `ring`: a queue of bytes that never grows.
#
# A ring keeps its bytes in a list of a fixed size and goes round it:
# after the last slot comes the first again. An interrupt that receives
# bytes and a main loop that reads them share one of these on almost
# every board.
#
# `private` in front of a declaration keeps it to this file. Another
# file can call `put`, `get`, `size` and `room`. It cannot touch
# `slots`, `first` or `count`, so it cannot make a ring whose count
# says one thing and whose slots say another.

class Ring {
    private slots: list[int]
    private first: int       # the slot the oldest byte is in
    private count: int       # how many bytes are waiting

    # Put a byte in. False if the ring is full: the byte is not kept.
    function put(self, byte: int) -> bool {
        if self.count == len(self.slots) {
            return false
        }
        self.slots[self.slot(self.count)] = byte
        self.count += 1
        return true
    }

    # Take the oldest byte out, or `none` if nothing is waiting.
    function get(self) -> int or none {
        if self.count == 0 {
            return none
        }
        let byte = self.slots[self.first]
        self.first = self.slot(1)
        self.count -= 1
        return byte
    }

    function size(self) -> int {
        return self.count
    }

    function room(self) -> int {
        return len(self.slots) - self.count
    }

    # The slot that is `steps` after the oldest byte, going round.
    private function slot(self, steps: int) -> int {
        return wrapped(self.first + steps, len(self.slots))
    }
}

# Only this file can build a `Ring`, because only this file can fill in
# its private fields. So it gives the others a function that does.
function ring(size: int) -> Ring raises ValueError {
    if size < 1 {
        raise ValueError("a ring has room for one byte at least")
    }
    return Ring([0 for slot in range(size)], 0, 0)
}

# A function the other files have no use for.
private function wrapped(place: int, size: int) -> int {
    return place % size
}

# The tests of this module. `zeno test examples/ring` runs them, and a
# build leaves them out. They stand in the file they test, so they can
# see what is private to it.

test "a new ring is empty" {
    let queue = ring(4)
    assert queue.size() == 0
    assert queue.room() == 4
    assert queue.get() is none
}

test "bytes come out in the order they went in" {
    let queue = ring(3)
    queue.put(10)
    queue.put(20)
    assert queue.get() == 10
    assert queue.get() == 20
    assert queue.size() == 0
}

test "a full ring keeps what it has" {
    let queue = ring(2)
    assert queue.put(1)
    assert queue.put(2)
    assert not queue.put(3)
    assert queue.slots == [1, 2]
}

test "the ring goes round" {
    let queue = ring(2)
    queue.put(1)
    queue.put(2)
    queue.get()
    queue.put(3)
    assert queue.first == 1
    assert queue.slots == [3, 2]
    assert wrapped(5, 4) == 1
}

test "a ring of no size is refused" {
    assert raises ValueError {
        ring(0)
    }
}
zeno run examples/ring/main.zeno
no room for 50
4 waiting, room for 0
10
20
30
40
60
70
0 waiting, room for 4

See it on GitHub: examples/ring/.