Struct CommandRunner 

pub struct CommandRunner { /* private fields */ }

Runs external commands and captures their output.

CommandRunner runs one Command synchronously on the caller thread and returns captured process output. The runner always preserves raw output bytes. Its lossy-output option controls whether CommandOutput::stdout and CommandOutput::stderr reject invalid UTF-8 or return replacement characters.

Author

Haixing Hu

Implementations

impl CommandRunner

pub fn new() -> Self

Creates a command runner with default settings.

Returns

A runner with no timeout, inherited working directory, success exit code 0, strict UTF-8 output text accessors, unlimited in-memory output capture, and no output tee files.

pub const fn timeout(self, timeout: Duration) -> Self

Sets the command timeout.

Parameters

• timeout - Maximum duration allowed for each command.

Returns

The updated command runner.

pub const fn without_timeout(self) -> Self

Disables timeout handling.

Returns

The updated command runner.

pub fn working_directory<P>(self, working_directory: P) -> Self

where P: Into<PathBuf>,

Sets the default working directory.

Parameters

• working_directory - Directory used when a command has no per-command working directory override.

Returns

The updated command runner.

pub fn success_exit_code(self, exit_code: i32) -> Self

Sets the only exit code treated as successful.

Parameters

• exit_code - Exit code considered successful.

Returns

The updated command runner.

pub fn success_exit_codes(self, exit_codes: &[i32]) -> Self

Sets all exit codes treated as successful.

Parameters

• exit_codes - Exit codes considered successful.

Returns

The updated command runner.

pub const fn disable_logging(self, disable_logging: bool) -> Self

Enables or disables command execution logs.

Parameters

• disable_logging - true to suppress runner logs.

Returns

The updated command runner.

pub const fn lossy_output(self, lossy_output: bool) -> Self

Configures whether output text accessors use lossy UTF-8 conversion.

Parameters

• lossy_output - true to replace invalid UTF-8 bytes with the Unicode replacement character when CommandOutput::stdout or CommandOutput::stderr is called.

Returns

The updated command runner.

pub const fn max_stdout_bytes(self, max_bytes: usize) -> Self

Sets the maximum stdout bytes retained in memory.

The reader still drains the complete stdout stream. Bytes beyond this limit are not retained in CommandOutput, but they are still written to a configured stdout tee file.

Parameters

• max_bytes - Maximum number of stdout bytes to retain.

Returns

The updated command runner.

pub const fn max_stderr_bytes(self, max_bytes: usize) -> Self

Sets the maximum stderr bytes retained in memory.

The reader still drains the complete stderr stream. Bytes beyond this limit are not retained in CommandOutput, but they are still written to a configured stderr tee file.

Parameters

• max_bytes - Maximum number of stderr bytes to retain.

Returns

The updated command runner.

pub const fn max_output_bytes(self, max_bytes: usize) -> Self

Sets the same in-memory capture limit for stdout and stderr.

Parameters

• max_bytes - Maximum number of bytes retained for each stream.

Returns

The updated command runner.

pub fn tee_stdout_to_file<P>(self, path: P) -> Self

where P: Into<PathBuf>,

Streams stdout to a file while still capturing it in memory.

The file is created or truncated before the command is spawned. Combine this with Self::max_stdout_bytes to avoid unbounded memory use for large stdout streams.

Parameters

• path - Destination file path for stdout bytes.

Returns

The updated command runner.

pub fn tee_stderr_to_file<P>(self, path: P) -> Self

where P: Into<PathBuf>,

Streams stderr to a file while still capturing it in memory.

The file is created or truncated before the command is spawned. Combine this with Self::max_stderr_bytes to avoid unbounded memory use for large stderr streams.

Parameters

• path - Destination file path for stderr bytes.

Returns

The updated command runner.

pub const fn configured_timeout(&self) -> Option<Duration>

Returns the configured timeout.

Returns

Some(duration) when timeout handling is enabled, otherwise None.

pub fn configured_working_directory(&self) -> Option<&Path>

Returns the default working directory.

Returns

Some(path) when a default working directory is configured, otherwise None to inherit the current process working directory.

pub fn configured_success_exit_codes(&self) -> &[i32]

Returns the configured successful exit codes.

Returns

Borrowed list of exit codes treated as successful.

pub const fn is_logging_disabled(&self) -> bool

Returns whether logging is disabled.

Returns

true when runner logs are disabled.

pub const fn is_lossy_output_enabled(&self) -> bool

Returns whether output text accessors use lossy UTF-8 conversion.

Returns

true when invalid UTF-8 bytes are replaced before output is returned by CommandOutput::stdout or CommandOutput::stderr.

pub const fn configured_max_stdout_bytes(&self) -> Option<usize>

Returns the configured stdout capture limit.

Returns

Some(max_bytes) when stdout capture is limited, otherwise None.

pub const fn configured_max_stderr_bytes(&self) -> Option<usize>

Returns the configured stderr capture limit.

Returns

Some(max_bytes) when stderr capture is limited, otherwise None.

pub fn configured_stdout_file(&self) -> Option<&Path>

Returns the stdout tee file path.

Returns

Some(path) when stdout is streamed to a file, otherwise None.

pub fn configured_stderr_file(&self) -> Option<&Path>

Returns the stderr tee file path.

Returns

Some(path) when stderr is streamed to a file, otherwise None.

pub fn run(&self, command: Command) -> Result<CommandOutput, CommandError>

Runs a command and captures stdout and stderr.

This method blocks the caller thread until the child process exits or the configured timeout is reached. When a timeout is configured, Unix children run as leaders of new process groups and Windows children run in Job Objects. This lets timeout killing target the process tree instead of only the direct child process. Without a configured timeout, commands use the platform’s normal process-spawning behavior.

Captured output is retained as raw bytes up to the configured per-stream limits. Reader threads still drain complete streams so the child is not blocked on full pipes. If lossy output mode is enabled, invalid UTF-8 is replaced only for CommandOutput::stdout and CommandOutput::stderr; byte accessors still return the retained raw process output.

Parameters

• command - Structured command to run.

Returns

Captured output when the process exits with a configured success code.

Errors

Returns CommandError if the process cannot be spawned, cannot be waited on, times out, cannot be killed after timing out, emits output that cannot be read or written to a tee file, cannot receive configured stdin, or exits with a code not configured as successful.

Trait Implementations

impl Clone for CommandRunner

fn clone(&self) -> CommandRunner

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CommandRunner

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CommandRunner

fn default() -> Self

Creates a command runner with the default exit-code policy.

Returns

A runner with no timeout, inherited working directory, success exit code 0, strict UTF-8 output text accessors, unlimited in-memory output capture, and no output tee files.

impl PartialEq for CommandRunner

fn eq(&self, other: &CommandRunner) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for CommandRunner

impl StructuralPartialEq for CommandRunner