Module `fs/dir`

fs/dir

Stability: unstable — `read_dir` is eager and Rust's is not. It drains the whole directory into an `ArrayList(DirEntry)` before the future resolves, so a caller that wants the first matching entry pays for every entry, and a directory with a million entries is a million-entry allocation rather than a cursor. Rust's `fs::read_dir` is an iterator of `io::Result<DirEntry>`, which also lets ONE unreadable entry be reported without failing the listing. The entry order is whatever the filesystem returns, deliberately (Rust promises nothing either), and callers that need determinism sort. Freezing follows a lazy `ReadDir` cursor beside the eager form, not a release count. — stable modules only change additively; this one may still change.

Async directory operations — create, remove, read, link, rename.

Wraps low-level std/sys/dir with typed APIs using the Exception effect.

Example

{ create_dir, remove_dir, read_dir } :: import "std/fs/dir";
{ Path } :: import "std/path";

main :: (fn(io : Io, exn : Exception) -> unit)({
  io.await(create_dir(Path.new(`/tmp/yo_test`), io), { io, exn });
  entries := io.await(read_dir(Path.new(`/tmp/yo_test`), io), { io, exn });
  io.await(remove_dir(Path.new(`/tmp/yo_test`), io), { io, exn });
});

Every operation here is async: it submits to the single-threaded event loop and must be awaited, and it reports failure by throwing IoExn carrying the OS errno as an IoError (D1), never by returning a Result. Each Path-taking function has a _str twin that differs only in accepting a borrowed str literal.

Stability

unstable — read_dir is eager and Rust's is not. It drains the whole directory into an ArrayList(DirEntry) before the future resolves, so a caller that wants the first matching entry pays for every entry, and a directory with a million entries is a million-entry allocation rather than a cursor. Rust's fs::read_dir is an iterator of io::Result<DirEntry>, which also lets ONE unreadable entry be reported without failing the listing. The entry order is whatever the filesystem returns, deliberately (Rust promises nothing either), and callers that need determinism sort. Freezing follows a lazy ReadDir cursor beside the eager form, not a release count.

Types

FileType enum

FileType

The type of a file system entry.

Variants

Variant	Fields	Description
`File`		A regular file.
`Directory`		A directory.
`Symlink`		A symbolic link.
`Other`		An unknown or unsupported file type.

DirEntry struct

DirEntry

A directory entry containing the entry name, file type, inode number, and the directory it was read from (so path() can rebuild the full path — Rust's DirEntry::path).

Fields

Name	Type	Description
`name`	String	The entry's own name, with no directory part — Rust's `DirEntry::file_name`. `.` and `..` are never reported.
`file_type`	FileType	The `FileType` of the entry at `path`, WITHOUT following a final symlink (`lstat` semantics): a symlink reports `.Symlink`, never its target's type. That is the same view `readdir`'s `d_type` gives, so a walk sees one consistent answer whatever the filesystem reports, and `WalkOptions.follow_symlinks` — not the stat — stays in charge of descent. Throws when the path cannot be stat'ed.
`ino`	u64	Inode number from the directory entry. Filesystem identity, not content: two names sharing an `ino` on one device are the same file. Always `0` on Windows, whose directory enumeration carries no inode (`Metadata.ino` has the NTFS file index instead).
`parent`	Path	The directory this entry was read from, kept so `path()` can rebuild the full path — Rust's `DirEntry` holds the same thing for the same reason. It is the path as GIVEN to `read_dir`, not a canonical one.

impl(DirEntry, ...)

path : (DirEntry) fn(self : DirEntry) -> Path

The full path of this entry: the scanned directory joined with the entry name. Rust's DirEntry::path.

Parameters

Name	Type	Notes
`self`	DirEntry

Returns: Path

Functions

create_dir function

fn(path : Path, io : Io) -> Impl(Future(unit, IoExn))

Create a directory at the given path.