index.nct

//! Path-oriented filesystem operations.
//!
//! Whole-file functions compose the stream contracts in `std/io`. Raw target
//! paths, errno values, syscalls, and metadata layout remain in `std/internal/os`.

see ./filesystem.nct

see ./durable.nct

see ./directory.nct

see ./directory_mutation.nct

see ./directory_prefix.nct

see ./async_recursive_mutation.nct

see ./async_mutation.nct

see ./async_metadata.nct

see ./links.nct

see ./path_output.nct

see ./canonicalization.nct

see ./recursive_policy.nct

see ./recursive_removal.nct

see ./recursive_traversal.nct

see ./directory_mutation_tests.nct

see ./recursive_tests.nct

use /iter/asynchronous.AsyncIterator
use /path.Utf8Path
use /string.String
use /time.SystemTime
use /vec.Vec

/// Portable classification of a filesystem entry.
pub enum FileType {
    regular
    directory
    symlink
    other
}

/// Portable metadata for one filesystem entry.
pub copy struct Metadata

/// One owned UTF-8 directory entry snapshot.
pub struct DirEntry

/// One fallible owning directory stream.
pub struct ReadDir

/// One explicitly synchronous fallible owning directory stream.
pub struct BlockingReadDir

/// One bounded executor-safe depth-first directory traversal.
pub struct WalkDir

/// One explicitly synchronous bounded depth-first directory traversal.
pub struct BlockingWalkDir

instance Metadata {
    /// Returns the portable entry classification.
    pub method &self.file_type(): FileType

    /// Returns the target-reported byte length.
    pub method &self.len(): u64

    /// Returns the target-reported last-content-modification instant.
    pub method &self.modified(): SystemTime

    /// Reports whether the entry is a regular file.
    pub method &self.is_file(): bool

    /// Reports whether the entry is a directory.
    pub method &self.is_directory(): bool
}

instance DirEntry {
    /// Returns the owned entry name without a lossy encoding conversion.
    pub method &self.file_name(): &str

    /// Returns an owned path formed by joining the opened path spelling and entry name.
    pub method &self.path(): &Utf8Path

    /// Classifies the entry itself without following a symbolic link.
    pub method &self.file_type(): FileType
}

instance ReadDir {
    impl AsyncIterator { .Item = DirEntry }

    /// Returns the next entry, `none` at end, or an error from this terminal stream.
    pub async method &+self.next(): DirEntry?!

    /// Closes the stream through the executor-safe retirement service.
    pub async method &+self.close(): void!
}

instance BlockingReadDir {
    /// Synchronously returns the next entry, `none` at end, or a terminal error.
    pub blocking method &+self.next_blocking(): DirEntry?!

    /// Closes the stream. Later `next_blocking` calls return `none`.
    pub method &+self.close(): void
}

instance WalkDir {
    impl AsyncIterator { .Item = DirEntry }

    /// Returns the next descendant, excluding the supplied root itself.
    pub async method &+self.next(): DirEntry?!

    /// Closes every retained directory stream through executor-safe retirement.
    pub async method &+self.close(): void!
}

instance BlockingWalkDir {
    /// Synchronously returns the next descendant, excluding the supplied root itself.
    pub blocking method &+self.next_blocking(): DirEntry?!

    /// Closes every retained directory stream.
    pub method &+self.close(): void
}

/// Reads an entire file into independently owned byte storage.
pub async func read(path: &str): Vec<u8>!

/// Reads an entire file and validates it as UTF-8.
pub async func read_to_string(path: &str): String!

/// Creates or truncates a file and writes every supplied byte.
pub async func write(path: &str, value: &[u8]): void!

/// Creates or truncates a file and writes the UTF-8 text.
pub async func write_text(path: &str, text: &str): void!

/// Durably replaces one file with complete bytes through an exclusive sibling and atomic rename.
pub async func write_durable(path: &str, value: &[u8]): void!

/// Durably replaces one file with complete UTF-8 text.
pub async func write_text_durable(path: &str, text: &str): void!

/// Creates an absent file and synchronizes its directory entry, or refreshes an existing entry.
pub(/) async func prepare_durable_file(path: &str): void!

/// Synchronously reads an entire file into independently owned byte storage.
pub blocking func read_blocking(path: &str): Vec<u8>!

/// Synchronously reads an entire file and validates it as UTF-8.
pub blocking func read_to_string_blocking(path: &str): String!

/// Synchronously creates or truncates a file and writes every supplied byte.
pub blocking func write_blocking(path: &str, value: &[u8]): void!

/// Synchronously creates or truncates a file and writes the UTF-8 text.
pub blocking func write_text_blocking(path: &str, text: &str): void!

/// Synchronously and durably replaces one file with complete bytes.
pub blocking func write_durable_blocking(path: &str, value: &[u8]): void!

/// Synchronously and durably replaces one file with complete UTF-8 text.
pub blocking func write_text_durable_blocking(path: &str, text: &str): void!

/// Asynchronously returns target metadata after following symbolic links.
pub async func metadata(path: &str): Metadata!

/// Synchronously returns target metadata after following symbolic links.
pub blocking func metadata_blocking(path: &str): Metadata!

/// Asynchronously returns metadata without following the final symbolic link.
pub async func symlink_metadata(path: &str): Metadata!

/// Synchronously returns metadata without following the final symbolic link.
pub blocking func symlink_metadata_blocking(path: &str): Metadata!

/// Asynchronously creates one symbolic link containing the supplied target spelling.
pub async func symlink(target: &str, link: &str): void!

/// Synchronously creates one symbolic link containing the supplied target spelling.
pub blocking func symlink_blocking(target: &str, link: &str): void!

/// Asynchronously reads and validates the UTF-8 target stored in one symbolic link.
pub async func read_link(path: &str): Utf8Path!

/// Synchronously reads and validates the UTF-8 target stored in one symbolic link.
pub blocking func read_link_blocking(path: &str): Utf8Path!

/// Resolves an existing path to its absolute canonical UTF-8 spelling.
pub async func canonicalize(path: &str): Utf8Path!

/// Synchronously resolves an existing path to its absolute canonical UTF-8 spelling.
pub blocking func canonicalize_blocking(path: &str): Utf8Path!

/// Copies one regular byte stream after proving the opened files have distinct identities.
pub async func copy(from: &str, to: &str): usize!

/// Synchronously copies one regular byte stream after proving distinct opened-file identities.
pub blocking func copy_blocking(from: &str, to: &str): usize!

/// Asynchronously opens one directory without sorting its entries.
pub async func read_dir(path: &str): ReadDir!

/// Synchronously opens one directory without sorting its entries.
pub blocking func read_dir_blocking(path: &str): BlockingReadDir!

/// Opens one bounded depth-first traversal without following symbolic links.
pub async func walk_dir(path: &str): WalkDir!

/// Synchronously opens one bounded depth-first traversal without following symbolic links.
pub blocking func walk_dir_blocking(path: &str): BlockingWalkDir!

/// Asynchronously returns false only when the path is absent.
pub async func exists(path: &str): bool!

/// Synchronously returns false only when the path is absent.
pub blocking func exists_blocking(path: &str): bool!

/// Removes one non-directory entry, including a symbolic link itself.
pub async func remove_file(path: &str): void!

/// Renames one entry without a copy-and-delete fallback.
pub async func rename(from: &str, to: &str): void!

/// Creates exactly one directory.
pub async func create_dir(path: &str): void!

/// Synchronously removes one non-directory entry, including a symbolic link itself.
pub blocking func remove_file_blocking(path: &str): void!

/// Synchronously renames one entry without a copy-and-delete fallback.
pub blocking func rename_blocking(from: &str, to: &str): void!

/// Synchronously creates exactly one directory.
pub blocking func create_dir_blocking(path: &str): void!

/// Asynchronously creates every missing directory prefix in the authored spelling.
pub async func create_dir_all(path: &str): void!

/// Synchronously creates every missing directory prefix in the authored spelling.
pub blocking func create_dir_all_blocking(path: &str): void!

/// Removes exactly one empty directory without following a final symbolic link.
pub async func remove_dir(path: &str): void!

/// Synchronously removes exactly one empty directory without following a final symbolic link.
pub blocking func remove_dir_blocking(path: &str): void!

/// Recursively removes one directory tree without following symbolic links.
pub async func remove_dir_all(path: &str): void!

/// Synchronously removes one directory tree without following symbolic links.
pub blocking func remove_dir_all_blocking(path: &str): void!