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 ./directory.nct
see ./directory_mutation.nct
see ./directory_mutation_tests.nct

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

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 {
    /// Returns the next entry, `none` at end, or an error from this terminal stream.
    pub method &+self.next(): DirEntry?!

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

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

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

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

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

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

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

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

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

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

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

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

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