index.nct

//! Common user-facing I/O API.
//!
//! `std/io` exposes ordinary file and text APIs. Fallible functions return `T!`
//! and fail with the compiler built-in `error` payload. Target-specific syscall
//! results and errno wrappers stay behind `#target`-gated std internals.

see ./core.nct
see ./async_core.nct
see ./byte_helpers.nct
see ./timed.nct
see ./transfer.nct
use /string.String
use /time.Duration
use /vec.Vec
see ./file.nct
see ./async_file.nct
see ./file_identity.nct
see ./input.nct
see ./input_tests.nct
see ./output.nct
see ./output_tests.nct

/// A source that initializes at most `buffer.len()` bytes per read.
pub interface BlockingReader {
    /// Initializes at most the supplied buffer length and returns zero at end of stream.
    pub blocking method &+self.read_blocking(buffer: &+[u8]): usize!

    /// Reads until end of stream into independently owned byte storage.
    pub blocking default method &+self.read_to_end_blocking(): Vec<u8>!

    /// Reads until end of stream and validates the complete input as UTF-8.
    pub blocking default method &+self.read_to_string_blocking(): String!
}

/// A destination that accepts the complete byte view or returns an error.
pub interface BlockingWriter {
    /// Writes the complete byte view or reports an error after an observable prefix.
    pub blocking method &+self.write_blocking(value: &[u8]): void!

    /// Publishes any retained output; the default implementation has no retained state.
    pub blocking default method &+self.flush_blocking(): void!

    /// Writes the UTF-8 encoding bytes through the shared byte contract.
    pub blocking default method &+self.write_text_blocking(text: &str): void!

    /// Writes UTF-8 text followed by exactly one LF byte.
    pub blocking default method &+self.write_line_blocking(text: &str): void!
}

/// An executor-safe source that initializes at most `buffer.len()` bytes per read.
pub interface Reader {
    /// Initializes at most the supplied buffer length and returns zero at end of stream.
    pub async method &+self.read(buffer: &+[u8]): usize!

    /// Reads until end of stream into independently owned byte storage.
    pub async default method &+self.read_to_end(): Vec<u8>!

    /// Reads until end of stream and validates the complete input as UTF-8.
    pub async default method &+self.read_to_string(): String!
}

/// An executor-safe destination that accepts complete byte views.
pub interface Writer {
    /// Writes the complete byte view or reports an error after an observable prefix.
    pub async method &+self.write(value: &[u8]): void!

    /// Publishes retained output; the default implementation has no retained state.
    pub async default method &+self.flush(): void!

    /// Writes the UTF-8 encoding bytes through the shared byte contract.
    pub async default method &+self.write_text(text: &str): void!

    /// Writes UTF-8 text followed by exactly one LF byte.
    pub async default method &+self.write_line(text: &str): void!
}

/// A reader that can bound each read operation by a relative timeout.
pub interface TimedReader where Self impl Reader {
    /// Reads once, failing when the supplied relative timeout expires first.
    pub async method &+self.read_with_timeout(
        buffer: &+[u8],
        timeout: Duration,
    ): usize!
}

/// A writer that can bound each complete write operation by a relative timeout.
pub interface TimedWriter where Self impl Writer {
    /// Writes the complete view, failing when the supplied relative timeout expires first.
    pub async method &+self.write_with_timeout(
        value: &[u8],
        timeout: Duration,
    ): void!
}

/// A mutable borrowed timed reader projected through the ordinary `Reader` contract.
pub struct TimeoutReader<R>

construct TimeoutReader<R> {
    /// Borrows `source` and applies `timeout` independently to every read operation.
    pub noalloc func new(source: &+R, timeout: Duration): Self where R impl TimedReader
}

instance TimeoutReader<R> where R impl TimedReader {
    impl Reader
}

/// A mutable borrowed timed writer projected through the ordinary `Writer` contract.
pub struct TimeoutWriter<W>

construct TimeoutWriter<W> {
    /// Borrows `destination` and applies `timeout` independently to every write operation.
    pub noalloc func new(
        destination: &+W,
        timeout: Duration,
    ): Self where W impl TimedWriter
}

instance TimeoutWriter<W> where W impl TimedWriter {
    impl Writer
}

/// Transfers bytes from one executor-safe source to one destination until end of stream.
pub async func copy<R, W>(
    reader: &+R,
    writer: &+W,
): usize! where R impl Reader, W impl Writer

/// Transfers bytes from one blocking source to one destination until end of stream.
pub blocking func copy_blocking<R, W>(
    reader: &+R,
    writer: &+W,
): usize! where R impl BlockingReader, W impl BlockingWriter

/// Validates one implementation-reported read count against its supplied capacity.
pub(/) noalloc func validate_read_count(received: usize, capacity: usize): usize!

/// Base and signed displacement for one cursor-changing file operation.
pub enum SeekFrom {
    start(position: i64)
    end(displacement: i64)
    current(displacement: i64)
}

/// An executor-safe owner for one local file.
pub struct File

/// An explicit synchronous owner or borrowed wrapper for one local file descriptor.
pub struct BlockingFile

/// Returns the process standard-input stream without taking ownership of the descriptor.
pub noalloc func stdin(): BlockingFile

/// Returns the process standard-output stream without taking ownership of the descriptor.
pub noalloc func stdout(): BlockingFile

/// Returns the process standard-error stream without taking ownership of the descriptor.
pub noalloc func stderr(): BlockingFile

construct File {
    /// Opens an existing file for reading.
    pub async func open(path: &str): Self!

    /// Creates or truncates a file for writing.
    pub async func create(path: &str): Self!

    /// Creates a new file for writing and fails when the path already exists.
    pub async func create_new(path: &str): Self!

    /// Opens or creates a file and positions writes at its end.
    pub async func append(path: &str): Self!

    /// Opens or creates a destination without truncating it before a copy identity check.
    pub(/) async func open_copy_destination(path: &str): Self!

    /// Opens one directory for package-internal metadata synchronization.
    pub(/) async func open_directory(path: &str): Self!
}

construct BlockingFile {
    /// Opens an existing file for synchronous reading.
    pub blocking func open(path: &str): Self!

    /// Creates or truncates a file for synchronous writing.
    pub blocking func create(path: &str): Self!

    /// Creates a new file for synchronous writing and fails when the path already exists.
    pub blocking func create_new(path: &str): Self!

    /// Opens or creates a file for synchronous append.
    pub blocking func append(path: &str): Self!

    /// Opens or creates a destination without truncating it before a copy identity check.
    pub(/) blocking func open_copy_destination(path: &str): Self!

    /// Opens one directory for package-internal metadata synchronization.
    pub(/) blocking func open_directory(path: &str): Self!
}

/// Compares the identities of two already-open executor-safe files.
pub(/) async func files_share_identity(left: &+File, right: &+File): bool!

/// Compares the identities of two already-open blocking files.
pub(/) blocking func blocking_files_share_identity(
    left: &BlockingFile,
    right: &BlockingFile,
): bool!

instance File {
    /// Makes this owner terminal and waits for its descriptor retirement.
    pub async method &+self.close(): void!
    /// Synchronizes this file or directory through the target durability boundary.
    pub async method &+self.sync(): void!
    /// Acquires an exclusive lock immediately or fails when another owner retains it.
    pub(/) async method &+self.try_lock_exclusive(): void!
    /// Returns the current shared cursor position.
    pub async method &+self.position(): usize!
    /// Changes and returns the shared cursor position.
    pub async method &+self.seek(from: SeekFrom): usize!
    /// Changes the file length without changing the shared cursor.
    pub async method &+self.truncate(length: usize): void!
    /// Reads without changing the shared cursor.
    pub async method &+self.read_at(buffer: &+[u8], offset: u64): usize!
    /// Writes the complete view without changing the shared cursor.
    pub async method &+self.write_at(value: &[u8], offset: u64): void!
    impl Reader
    impl Writer
}

instance BlockingFile {
    /// Makes this wrapper terminal and closes its descriptor only when it owns it.
    pub noalloc method &+self.close(): void
    /// Synchronizes this file or directory through the target durability boundary.
    pub noalloc blocking method &+self.sync_blocking(): void!
    /// Returns the current shared cursor position.
    pub noalloc blocking method &+self.position_blocking(): usize!
    /// Changes and returns the shared cursor position.
    pub noalloc blocking method &+self.seek_blocking(from: SeekFrom): usize!
    /// Changes the file length without changing the shared cursor.
    pub noalloc blocking method &+self.truncate_blocking(length: usize): void!
    /// Reads without changing the shared cursor.
    pub noalloc blocking method &+self.read_at_blocking(buffer: &+[u8], offset: u64): usize!
    /// Writes the complete view without changing the shared cursor.
    pub noalloc blocking method &+self.write_at_blocking(value: &[u8], offset: u64): void!
    impl BlockingReader
    impl BlockingWriter
}

/// Writes UTF-8 text to standard output without adding a newline.
pub noalloc blocking func print(text: &str): void!

/// Writes UTF-8 text and one LF byte to standard output.
pub noalloc blocking func println(text: &str): void!

/// Writes UTF-8 text to standard error without adding a newline.
pub noalloc blocking func eprint(text: &str): void!

/// Writes UTF-8 text and one LF byte to standard error.
pub noalloc blocking func eprintln(text: &str): void!