Folders
A program can now see what is in a folder, make one, and put a path together from its parts:
import files
files.make_folder("logs/2026/november")
files.write(files.join("logs/2026/november", "20.txt"), "temp 23.5\n")
files.write(files.join("logs/2026", "notes.txt"), "calibrated\n")
for name in files.list("logs/2026") {
print(name)
}
notes.txt
november
The same list comes out of zeno run, the VM, every build in C and
LLVM, and every target, on Linux, macOS and Windows. The decisions are
59.20 to 59.23 in decisions.md.
What was added
| Written | Gives | Can fail with | |
|---|---|---|---|
| The names in a folder | files.list(folder) |
list[str], sorted |
FileError |
| Make a folder, and those above it | files.make_folder(path) |
nothing | FileError |
| Two parts of a path | files.join(first, second) |
str |
never |
files.list(folder)
The names of everything in the folder, files and folders alike, with
no . and no ... A name is the last part of the path only:
files.list("logs") gives "notes.txt", not "logs/notes.txt", and
files.join puts them back together.
The list is sorted by the numbers of the characters, which is the
order < gives two texts in Zeno. Digits come before capitals, and
capitals before small letters, and a name with a character from
beyond the first 65,536 comes after one without:
["10", "9", "C.txt", "_", "a", "a b", "a.txt", "b.txt", "z", "~", "é", "z", "😀"]
The system gives the names in an order of its own, which is not the same from Linux to Windows, nor from one disk to another. Sorting them means a program that lists a folder prints the same thing everywhere, and a test of it can be written once. Every list is a new one: a program can sort it again, or change it, and the next call still gives the folder as it is.
What can go wrong
| What happened | The message of the FileError |
|---|---|
Nothing is at the path, or the path is "" |
there is no folder `logs` |
| It is a file, or the system will not let it be read | cannot list the folder `logs` |
| A name in it is not UTF-8 | the folder `logs` holds a name that is not text |
An empty path is no folder. Several systems take "" for the folder
the program was started in, and some do not; "." says that in every
one.
files.make_folder(path)
Makes the folder and every folder above it that is not there yet, as
mkdir -p does. It worked if there is a folder at the path at the
end, so making one that is already there is no error, and a program
can call it every time it starts. Anything that is not a folder in
the way is: cannot make the folder `notes.txt/old`, and so is an
empty path.
files.join(first, second)
files.join("logs", "today.txt") # "logs/today.txt"
files.join("logs/", "today.txt") # "logs/today.txt"
files.join("logs", "/today.txt") # "logs/today.txt"
files.join("logs/", "/today.txt") # "logs/today.txt"
files.join("", "today.txt") # "today.txt"
files.join("logs", "") # "logs/"
What it does is small. Where neither part has a / at the end that
meets the other, it puts one between them; where one has, it puts in
none; where both have, it drops the one at the start of the second.
That is all: files.join("a//", "b") is "a//b", since the first
part's own // is left as it is, and files.join("logs", "") is
"logs/", a folder with nothing named in it yet. A first part that is
empty is no folder at all, and the second comes back as it is. Every system Zeno runs
on takes / in a path, Windows too, so the path is the same text
everywhere. It does no more than that: it does not look at the disk,
and does not take out .. or a / that is doubled inside a part.
join is written in Zeno, in library/files.zeno,
as math.hypot is (chapter 33). A program that calls it gets it, and
one that does not gets nothing.
On a board
A board has no folders. files.list and files.make_folder raise a
FileError there, which the program can catch, as files.read does
for a file. files.join works, since it is arithmetic on text.
What it costs a program that does not use it
Nothing. The C for listing and making a folder is a piece of the
runtime (decision 56.19), written into a program only if it calls
files.list or files.make_folder, through C and LLVM alike. A
program that calls neither is built into the same C, IR and bytecode
as before, to the byte.
The files
| File | What it holds |
|---|---|
src/builtins.rs |
list and make_folder for zeno run and the VM |
src/checker.rs |
Their types, and that both raise FileError |
library/files.zeno |
join |
src/runtime.c |
The two pieces ZENO_FILES_LIST and ZENO_FILES_MAKE_FOLDER, with POSIX and Windows inside each |
src/emit_c.rs, src/emit_llvm.rs |
A call of each, in every kind of build |
src/runtime.* |
Both for each target |
tools/targets/edge-folders.zeno |
A folder of names that sort differently in every language's own order, and every error |
What it does not do
- Remove a folder. Left for later (
plan-9-14.md, after item 12). - Say what a name is.
files.listdoes not say which names are folders.files.exists(path)is true for a file only, so it tells the two apart. - A name that is not UTF-8, on the JVM, .NET and Dart. Those
languages turn such a name into text of their own before a program
sees it, so the Java, Kotlin, C# and Dart targets give a changed name
where every other engine raises a
FileError. - A name that is not ASCII, in Java where the system's language
setting is not UTF-8. With no
LANGset, orLC_ALL=C, the JVM readséin a name as?, so the Java and Kotlin targets list a name thatfiles.readcannot open. SetLC_ALL=C.UTF-8, or any UTF-8 setting, and they list it as every other engine does. - Tell apart two names that differ only in case, on a disk that does
not. Zeno lists what the disk holds. On Windows and macOS, as they
are set up out of the box,
files.write("b.txt", ...)andfiles.write("B.txt", ...)write one file, and the folder holds one name. - A name that is not ASCII, in a C or LLVM build on Windows, made by
another program. A build reads and writes a file through the C
library's
fopen, which takes a name through the machine's code page, andfiles.listandfiles.make_foldertake names the same way, so what the program writes it lists and reads back by the same name. A name the code page cannot hold, made byzeno runor another program, is listed with question marks, and does not open. - Lua without LuaFileSystem on Windows. Lua itself cannot see into
a folder; the Lua target uses LuaFileSystem where it is installed,
and
findandmkdir -pwhere there is a POSIX shell.
How it is tested
folders_are_the_same_in_every_build(emit_c.rs): one program through the interpreter, the VM, and C and LLVM with a collector,--firmwareand--no-collector, with 0 blocks left in the last.folders_are_only_in_a_program_that_uses_them.a_folder_is_made_and_listed(interpreter.rs): the exact output, each message, a name that is not UTF-8, and what the checker says.tools/targets/edge-folders.zeno, run by every target.
Things to try
-
Run the program at the top twice. Why is the second run no error, when
files.make_folderis asked for a folder that is there? -
Make a folder with the files
a,B,éand10in it, list it, and say why"10"comes first and"é"last. Then sort the list with.sort()and see that nothing moves. -
Write
tree.zeno: a function that prints a folder's names, and the names inside each folder in it, indented. Tell a folder from a file withfiles.exists, which is false for a folder. It needsraises FileError: take that off and read whatzeno check --strictsays. -
Try
files.list("")andfiles.list("."). Which decision says why the first is an error? -
Build
tree.zenowith--no-collector --memoryand give each list an owner (let names: owned list[str] = files.list(folder)). Is anything left at the end? -
Print
files.join("a/", "/b")andfiles.join("a//", "b"). Why doesjoinmend the first and leave the second?
This page is docs/folders.md in the language repository.