v0.4.0
Files · Lesson 19.5

Directory

Source
Create a scratch directory, list what is in it, and remove it again.

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

CallDoesThrows when
MakeDirectory(allocator, path)creates one directorythe name is already taken
ReadDirectory(allocator, path)starts a listingthe directory cannot be read
DeleteFile(allocator, path)removes one fileit is missing
DeleteDirectory(allocator, path)removes one empty directoryanything 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 --> n

try 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.txt before second.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.

Src/Main.rux
// 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

  1. 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?
  2. Call MakeDirectory twice on the same path and handle the second error with a try ... catch whose guarded arm checks for IoErrorKind::AlreadyExists.
  3. Convert each name to text with try name.View().ToText(allocator) before printing it — Main must then throw IoError | TextError. When could that conversion fail, when printing with {} never does?
  4. List the package's own Bin folder instead of the scratch directory.

Learn more