Enumerate and classify paths

Use std.path to represent a native path and std.fs to enumerate it lazily. Each generator item is a Result because advancement can fail after opening:

import std.fs as fs
import std.path as path

def main() -> Result[(), AllocError | IoError]:
    write_text("sample.txt", "abc")?
    root = path.from_text(".")?
    for result in fs.entries(fs.read_dir(&root)?):
        entry = result?
        name = entry.file_name()?
        if name.to_text()? == "sample.txt":
            print(entry.file_type()? == fs.FileType.File)?
            print(entry.metadata()?.size())?
    Ok(())

True
3

entries consumes the directory owner. Exhaustion closes it; an early break, return or propagated error drops it. Keep a named mutable ReadDir when you want manual next() calls or explicit close(). Entries own their data and remain valid after the directory closes. Enumeration includes dot-prefixed names and has unspecified order.

entry.file_type() and entry.metadata() inspect a symlink itself. fs.metadata(&path) follows its target; fs.symlink_metadata(&path) does not. A dangling link can therefore be inspected without requiring its target. Types distinguish regular files, directories, links and other native objects.

Path text conversion is checked. For arbitrary Unix filenames, use name.as_bytes() and NUL-framed transport, avoiding text decoding. These filesystem APIs currently require 64-bit Linux and statx for metadata. See the directory reference.

Use fs.symlink to create a link and fs.canonicalize when you need its resolved absolute name. Relative link targets are relative to the link’s parent:

import std.fs as fs
import std.path as path

def main() -> Result[(), IoError]:
    write_text("original.txt", "data")?
    target = path.from_text("original.txt")?
    link = path.from_text("alias.txt")?
    fs.symlink(&target, &link)?
    print(fs.read_link(&link)?.to_text()?)?
    resolved = fs.canonicalize(&link)?
    print(resolved.is_absolute(), fs.metadata(&resolved)?.size())?
    Ok(())

original.txt
True 4

Canonicalization requires existing components and can fail for dangling links or loops. Its result can become stale immediately: it does not secure a later open against replacement. For operations through a held directory, use rooted filesystem helpers. The metadata and links reference documents native path limits and error behavior.