index.nct

//! User-facing `std/process` API.
//!
//! exit is a standard-library API, not a compiler primitive. The target-specific
//! implementation calls the active target boundary.

use /mem.TryAllocator
use /string.String
use /vec.Vec
see ./command_child_darwin.nct
see ./command_io_darwin.nct
see ./command_io_session_darwin.nct
see ./command_io_tests_darwin.nct
see ./configuration.nct
see ./darwin.nct
see ./command.nct
see ./command_darwin.nct
see ./launch_plan_darwin.nct
see ./launch_report_darwin.nct
see ./launch_report_tests_darwin.nct
see ./pipe_darwin.nct
see ./pipe_tests_darwin.nct
see ./subprocess_darwin.nct

/// An owning exact-path subprocess request.
pub struct Command

/// One observed terminal state of a reaped child process.
pub copy struct ExitStatus

/// Complete owned output from one synchronously observed child process.
pub struct Output {
    /// The child's observed terminal state.
    pub status: ExitStatus

    /// Every byte captured from the child's standard output, in stream order.
    pub stdout: Vec<u8>

    /// Every byte captured from the child's standard error, in stream order.
    pub stderr: Vec<u8>
}

construct Command {
    /// Copies and validates one exact executable path.
    pub func new(path: &str): Self!
}

instance Command {
    /// Appends one exact argument after copying and validating it.
    pub method &+self.arg(value: &str): void!

    /// Sets the working directory used before executable replacement.
    pub method &+self.current_dir(path: &str): void!

    /// Sets one exact child environment value, replacing an equal name.
    pub method &+self.env(name: &str, value: &str): void!

    /// Removes one child environment name if inherited or explicitly set.
    pub method &+self.remove_env(name: &str): void!

    /// Removes every inherited and explicitly configured environment entry.
    pub method &+self.clear_env(): void

    /// Copies finite bytes that replace inherited standard input.
    pub method &+self.input(value: &[u8]): void

    /// Launches the command, waits for its child, and consumes all command storage.
    pub method self.status(): ExitStatus!

    /// Launches the command and returns its terminal state and complete output streams.
    pub method self.output(): Output!
}

instance ExitStatus {
    /// Returns true exactly for ordinary exit code zero.
    pub noalloc method self.success(): bool

    /// Returns the ordinary exit code, or `none` for signal termination.
    pub noalloc method self.code(): i32?

    /// Returns the terminating signal, or `none` for ordinary exit.
    pub noalloc method self.signal(): i32?
}

/// One borrowed name/value pair from the process environment.
pub copy struct EnvironmentEntry {
    /// Borrowed environment-variable name retained by process storage.
    pub name: &str

    /// Borrowed environment-variable value retained by process storage.
    pub value: &str
}

/// Copies all process arguments into an owning Vec of process-lifetime views.
pub func args(): Vec<&str>!

/// Returns the number of process arguments, including the executable spelling.
pub noalloc func arg_count(): usize

/// Returns one process argument, `none` out of range, or a decoding failure.
pub noalloc func arg(index: usize): &str?!

/// Returns the number of environment entries.
pub noalloc func environment_count(): usize

/// Returns one environment entry, `none` out of range, or a decoding failure.
pub noalloc func environment(index: usize): EnvironmentEntry?!

/// Returns the value of one environment variable, `none` when absent, or a decoding failure.
pub noalloc func env(name: &str): &str?!

/// Returns the current working directory in current-context storage.
pub func cwd(): String!

/// Returns the current working directory using recoverable storage from `allocator`.
pub func try_cwd(allocator: &+TryAllocator): String!

/// Terminates the process with `code` and does not return.
pub func exit(code: i32): never

/// Terminates the process immediately with an unsuccessful status.
pub func abort(): never