Directory
A directory holds names: files, and other directories. The FileSystem package makes one, lists what is in it and removes it, and this program does all three to a scratch directory of its own, Bin/scratch, inside the package's build folder. The interesting part is the listing, because a directory can hold a great many names, and reading it can fail part-way through.
Four calls
| Call | Does | Throws when |
|---|---|---|
MakeDirectory(allocator, path) | creates one directory | the name is already taken |
ReadDirectory(allocator, path) | starts a listing | the directory cannot be read |
DeleteFile(allocator, path) | removes one file | it is missing |
DeleteDirectory(allocator, path) | removes one empty directory | anything is still inside |
All four declare throws IoError, so every call to one is marked with try, and none of them touches more than the one name it is given.
The files go in with two small helpers. Each converts a name to an OsString, joins it onto the directory with Join — neither of which can fail — and acts on the result:
func MakeFile(allocator: Allocator, directory: Path, name: char8[..]) throws IoError {
var holder = OsString::FromText(allocator, name);
let path = Join(allocator, directory, holder.View());
var file = try File::Open(allocator, path.AsPath(), OpenOptions::Writing());
try WriteAll(file, name);
try file.Close();
}
Listing, one name at a time
ReadDirectory does not return every name at once — that would mean holding them all at once. It returns a cursor, a DirectoryIterator, whose Next hands out one name per call:
func Next(&var self) -> OsString? throws IoError
That is the shape from Nested fallible: two questions in one call. A thrown error answers "could the directory be read?"; the optional it returns answers "is there another name?". The loop answers both in one line:
var listing = try ReadDirectory(allocator, directory);
var count = 0;
loop {
let name = try listing.Next() ?? break;
PrintLine(" {}", name.View());
count += 1;
}
flowchart LR
n["`listing.Next()`"] --> f{"threw?"}
f -- "yes" --> p["`try` passes the `IoError` on:<br/>`Main` ends with status `1`"]
f -- "no" --> o{"a name, or `none`?"}
o -- "`none`" --> b["`?? break`:<br/>every name handed out"]
o -- "a name" --> use["bind it to `name`,<br/>print it, loop again"]
use --> ntry passes an error on, and ?? break unwraps the optional — leaving the loop when it is none. The try covers the whole listing.Next() ?? break, but only the call can throw. What is left is an OsString, a name in the system's own units, for the reason Path gave; the program prints it through name.View().
Three more things about a listing:
.and..are skipped; you get only real entries.- The order is whatever the filesystem keeps. This program happens to print
first.txtbeforesecond.txt; do not rely on it. Sort the names if order matters. - The cursor holds a system handle.
listing.Release()gives it back as soon as you are done, rather than at the end of the scope.
Removal is strict
DeleteDirectory refuses a directory that still has anything in it, so removing the scratch directory too early throws. This program expects that, and handles the error rather than passing it on:
try DeleteDirectory(allocator, directory) catch {
_ => {
PrintLine("refused: the directory is not empty");
}
};
IoErrorKind has no case for "not empty", so the error arrives as Other, with the system's own code beside it. That is why this catch takes every error with the default arm _ rather than matching one kind. Then the files go first, and the empty directory after them:
try RemoveFile(allocator, directory, "first.txt");
try RemoveFile(allocator, directory, "second.txt");
try DeleteDirectory(allocator, directory);
Nothing here deletes a whole tree in one call. Removing a directory and everything below it means listing it, deleting each file, and descending into each subdirectory — which is exactly why it is not a single innocent-looking function.
The program
The whole lesson is one package in the Examples repository. Its comments explain every step.
// A directory is made, listed and removed through the `FileSystem` package, and this program does
// all three to a scratch directory it owns: `Bin/scratch`, inside this package's build folder.
//
// Listing is the interesting part. `ReadDirectory` returns a cursor, and its `Next` hands out one
// name at a time, because a directory can hold a great many and returning them all at once would
// mean holding them all at once. `Next` has the nested shape from the Errors part:
//
// func Next(&var self) -> OsString? throws IoError
//
// A thrown error means the directory could not be read. A returned value holds the next name, or
// `none` once every name has been handed out. So `try listing.Next() ?? break` passes an error
// on, stops at the end, and otherwise binds a name. The names are `OsString`s, not text, for the
// reason the Path lesson gave; `.` and `..` are skipped. The order is whatever the filesystem
// keeps, so do not rely on it.
//
// Removal is strict. `MakeDirectory` throws if the name is taken, and `DeleteDirectory` refuses a
// directory that still has anything in it, so the files go first.
import Allocator::{ Allocator, SystemAllocator };
import FileSystem::{ DeleteDirectory, DeleteFile, File, MakeDirectory, OpenOptions, ReadDirectory };
import Io::{ IoError, PrintLine, WriteAll };
import Path::{ Join, OsString, Path };
// Writes a small file called `name` inside `directory`.
func MakeFile(allocator: Allocator, directory: Path, name: char8[..]) throws IoError {
var holder = OsString::FromText(allocator, name);
let path = Join(allocator, directory, holder.View());
var file = try File::Open(allocator, path.AsPath(), OpenOptions::Writing());
try WriteAll(file, name);
try file.Close();
}
// Deletes the file called `name` inside `directory`.
func RemoveFile(allocator: Allocator, directory: Path, name: char8[..]) throws IoError {
var holder = OsString::FromText(allocator, name);
let path = Join(allocator, directory, holder.View());
try DeleteFile(allocator, path.AsPath());
}
func Main() throws IoError {
let allocator = SystemAllocator();
var holder = OsString::FromText(allocator, "Bin/scratch");
let directory = Path::FromView(holder.View());
try MakeDirectory(allocator, directory);
try MakeFile(allocator, directory, "first.txt");
try MakeFile(allocator, directory, "second.txt");
PrintLine("made {} with two files", directory);
var listing = try ReadDirectory(allocator, directory);
var count = 0;
loop {
let name = try listing.Next() ?? break;
PrintLine(" {}", name.View());
count += 1;
}
// The cursor holds a system handle; `Release` gives it back now rather than at scope end.
listing.Release();
PrintLine("listed {} entries", count);
// Removing it too early is refused, and this error is handled rather than passed on.
try DeleteDirectory(allocator, directory) catch {
_ => {
PrintLine("refused: the directory is not empty");
}
};
try RemoveFile(allocator, directory, "first.txt");
try RemoveFile(allocator, directory, "second.txt");
try DeleteDirectory(allocator, directory);
PrintLine("removed {}", directory);
}
Besides Io, its Rux.toml lists Allocator, FileSystem and Path under [Dependencies].
Run it
cd Examples/Files/Directory
rux run
made Bin/scratch with two files
first.txt
second.txt
listed 2 entries
refused: the directory is not empty
removed Bin/scratch
Common mistakes
Try it yourself
- Add a third file, and a subdirectory made with
MakeDirectory. What does the listing show for the subdirectory, and what must change before the scratch directory can be removed? - Call
MakeDirectorytwice on the same path and handle the second error with atry ... catchwhose guarded arm checks forIoErrorKind::AlreadyExists. - Convert each name to text with
try name.View().ToText(allocator)before printing it —Mainmust then throwIoError | TextError. When could that conversion fail, when printing with{}never does? - List the package's own
Binfolder instead of the scratch directory.
Learn more
- Nested fallible and Coalesce exit — the two halves of
try listing.Next() ?? break - Path join — building each file's path inside the directory
- Metadata — asking whether a name is a file or a directory
- Temporary file — scratch space that removes itself