The Zeno Book Zeno 0.1 zeno-lang.org

21 Programs in Several Files

A program of a few hundred lines is easier to read when it is cut into files: one for the sensors, one for the report, one for the serial port. In Zeno a file is a module, and import brings one file’s names into another.

21.1 A module is a file

There is nothing to declare and nothing to register. The file sensors.zeno is the module sensors:

sensors.zeno

class Reading {
    name: str
    value: float
}

let highest = ["temperature": 60.0, "humidity": 100.0]

function check(reading: Reading) -> str {
    let limit = highest.get(reading.name)
    if limit is none {
        return "no limit is known"
    }
    if reading.value > limit {
        return f"over {limit}"
    }
    return "good"
}

main.zeno

import sensors

let readings = [
    sensors.Reading("temperature", 21.5),
    sensors.Reading("humidity", 104.0),
    sensors.Reading("wind", 12.0),
]
for reading in readings {
    print(reading.name, sensors.check(reading))
}
print(readings[0])
temperature good
humidity over 100.0
wind no limit is known
Reading(name="temperature", value=21.5)

import sensors reads sensors.zeno from the folder of the file that zeno run was given. Its names are then written with the module’s name in front: sensors.check, sensors.Reading. A value prints by the name its own file gave it, Reading.

21.2 Two ways to import

Written Means
import sensors read sensors.zeno; its names are written sensors.check
import drivers.uart read drivers/uart.zeno; a dot is a folder, and the names are written drivers.uart.send
from sensors import check, Reading read sensors.zeno, and let these names be written with nothing in front

These are the same two forms that the modules which come with Zeno have: import math and from time import sleep. A file of your own is used exactly as one of those is.

drivers/uart.zeno

let speed = 9600
var sent = 0

function send(text: str) {
    print(f"uart> {text}")
    sent += len(text) + 1
}

station.zeno

import drivers.uart
from sensors import Reading, check

let r = Reading("temperature", 21.5)
drivers.uart.send(f"{r.name}: {check(r)}")
drivers.uart.send("done")
print(drivers.uart.sent, "bytes sent at", drivers.uart.speed)
uart> temperature: good
uart> done
23 bytes sent at 9600

A type from a module is written the same way, sensors.Reading, and so is an enum case in a match, case shapes.Circle(r), and an error class in an except.

A file is already a unit that people name, open and send to each other, so it is the module. A separate declaration of what a module is, as in Java’s package lines or Rust’s mod, would be a second name for the same thing that could disagree with the first. (Decision 7.1.)

21.3 The rules

What can be imported.

Everything a file declares at its top: functions, classes, enums and their cases, let, var and const. What the file itself imports is not passed on. A declaration marked private is for its own file only, below.

When an imported file runs.

Once, before the file that imports it, however many files import it. So imports go at the top of a file.

Files cannot import each other,

directly or round a longer circle. One of them would have to run first, and none can:

a.zeno

import b
let x = 1

b.zeno

import a
let y = 2
error: `b.zeno` is the file the program starts in, and no file imports that one. Move what the files share into a file of its own, and import that
 --> a.zeno:1:1
  |
1 | import b
  | ^

What two files share goes into a third, which both import.

Only a module changes its own variables.

Other files read them, and ask the module to change them through a function:

meddle.zeno

import drivers.uart
drivers.uart.sent = 0
error: `drivers.uart.sent` is a variable of the module `drivers.uart`, and only the file of `drivers.uart` gives it a new value. Give `drivers.uart` a function that changes it, and call that
 --> meddle.zeno:2:1
  |
2 | drivers.uart.sent = 0
  | ^

No name has two meanings.

Importing check from two modules, or declaring your own check beside an imported one, is refused. A name declared inside a function hides an imported one, as it hides any name from the top of the file.

A misspelt name is named,

with the names the module does have:

typo.zeno

import sensors
print(sensors.chek)
error: module `sensors` has no `chek`. It has `Reading`, `highest` and `check`
 --> typo.zeno:2:7
  |
2 | print(sensors.chek)
  |       ^

A mistake inside an imported file is shown in that file, with its name and line.

21.4 private

Every module has parts it is for and parts it only uses to get its work done. private in front of a declaration keeps it to the file it is written in. It goes in front of a function, class, enum, let, var or const at the top of a file, and in front of a field or a method of a class.

Here is a queue of a fixed size whose count must always agree with its slots:

ring.zeno

class Ring {
    private slots: list[int]
    private first: int
    private count: int

    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
    }

    function get(self) -> int or none {
        if self.count == 0 {
            return none
        }
        let byte = self.slots[self.first]
        self.first = wrapped(self.first + 1, len(self.slots))
        self.count -= 1
        return byte
    }

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

    private function slot(self, steps: int) -> int {
        return wrapped(self.first + steps, len(self.slots))
    }
}

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)
}

private function wrapped(place: int, size: int) -> int {
    return place % size
}

main.zeno

import ring

let queue = ring.ring(3)
for byte in [10, 20, 30, 40] {
    print(byte, queue.put(byte))
}
print(queue.get(), queue.get(), queue.size())
10 true
20 true
30 true
40 false
10 20 1

Each of these, in another file, is refused:

bad1.zeno

import ring
let queue = ring.ring(3)
queue.count = 0
error: `count` is private in the class `ring.Ring`: only the file that declares the class can use it. To use it from another file, take the word `private` off where it is declared
 --> bad1.zeno:3:1
  |
3 | queue.count = 0
  | ^

1 error found. Nothing was run.

bad2.zeno

import ring
print(ring.wrapped(5, 4))
error: `wrapped` is private in the module `ring`: only its own file can use it. To use it from another file, take the word `private` off where it is declared
 --> bad2.zeno:2:7
  |
2 | print(ring.wrapped(5, 4))
  |       ^

bad3.zeno

import ring
let mine = ring.Ring([1, 2], 0, 2)
error: `ring.Ring` has the private field `slots`, so only the file that declares the class can build one. Write a function in that file that builds one and returns it, and call that function here
 --> bad3.zeno:2:12
  |
2 | let mine = ring.Ring([1, 2], 0, 2)
  |            ^

1 error found. Nothing was run.

The last is the important one. A class with a private field can be built only by its own file, because only that file can fill the field in. So the only way to get a Ring is through the function ring, which checks the size. Every line that changes the count is in ring.zeno, in front of whoever reads it.

One word, in front of the thing it is about, at the place a reader is already looking. Python’s leading underscore is only a habit that nothing checks; Java’s four levels of access are three more than a file needs. Private is for the file and not for the class because the file is what one person writes and reads at a time, and functions beside a class often need to see inside it. (Decisions 10.1 to 10.3.)

21.5 How it works

Before the checker sees anything, a stage of the compiler loads every file the program imports, renames each top-level name with its module in front, and joins the files into one program, in the order they must run. Everything after that, the checker, the interpreter and the compilers, sees a single program. zeno join shows it:

joined.zeno

import drivers.uart
drivers.uart.send("hi")
$ zeno join joined.zeno
let drivers.uart.speed = 9600
var drivers.uart.sent = 0
function drivers.uart.send(text: str)
    print(f"uart> {text}")
    drivers.uart.sent += (len(text) + 1)
drivers.uart.send("hi")

Inside Zeno has more on the stages of the compiler.

A file is a module. import name reads name.zeno from the program’s folder, a dot is a folder, and from name import a, b brings single names. Imported files run once, first, and cannot import each other. Only a module changes its own variables. private keeps a declaration, a field or a method to its own file, and a class with a private field can only be built there.

  1. Move the Log class from Classes into a file of its own and use it from main.zeno.

  2. Make the readings field of Log private, and give it a function log(limit: int) -> Log that refuses a limit below 1.

  3. Make two files import each other, and read the message. Then move what they share into a third.

  4. Run zeno join on a program of three files, and find where each file’s statements went.