Struct Command

pub struct Command {
    pub program: PathBuf,
    pub args: Vec<OsString>,
    pub dir: Option<PathBuf>,
    pub log_to: LogTo,
    pub log_command: bool,
    pub log_output_on_error: bool,
    pub check: bool,
    pub capture: bool,
    pub combine_output: bool,
    pub clear_env: bool,
    pub env: HashMap<OsString, OsString>,
}

A command to run in a subprocess and options for how it is run.

Some notable trait implementations:

• Derives Clone, Debug, Eq, and PartialEq
• Default (see docstrings for each field for what the corresponding default is)
• From<&Command> for std::process::Command to convert to a std::process::Command

Fields

program: PathBuf

Program path.

The path can be just a file name, in which case the $PATH is searched.

args: Vec<OsString>

Arguments passed to the program.

dir: Option<PathBuf>

Directory from which to run the program.

If not set (the default), the current working directory is used.

log_to: LogTo

Where log messages go. The default is stdout.

log_command: bool

If true (the default), log the command before running it.

log_output_on_error: bool

If true, log the output if the command exits non-zero or due to a signal. This does nothing is capture is false or if check is false. The default is false.

check: bool

If true (the default), check if the command exited successfully and return an error if not.

capture: bool

If true, capture the stdout and stderr of the command. The default is false.

combine_output: bool

If true, send stderr to stdout; the stderr field in Output will be empty. The default is false.

clear_env: bool

If false (the default), inherit environment variables from the current process.

env: HashMap<OsString, OsString>

Add or update environment variables in the child process.

Implementations

impl Command

pub fn new<S: AsRef<OsStr>>(program: S) -> Self

Make a new Command with the given program.

All other fields are set to the defaults.

pub fn with_args<I, S1, S2>(program: S1, args: I) -> Self

where S1: AsRef<OsStr>, S2: AsRef<OsStr>, I: IntoIterator<Item = S2>,

Make a new Command with the given program and args.

All other fields are set to the defaults.

pub fn from_whitespace_separated_str(s: &str) -> Option<Self>

Create a Command from a whitespace-separated string. If the string is empty or all whitespace, None is returned.

This function does not do unquoting or escaping.

pub fn add_arg<S: AsRef<OsStr>>(&mut self, arg: S) -> &mut Self

Append a single argument.

pub fn add_arg_pair<S1, S2>(&mut self, arg1: S1, arg2: S2) -> &mut Self

where S1: AsRef<OsStr>, S2: AsRef<OsStr>,

Append two arguments.

This is equivalent to calling add_arg twice; it is for the common case where the arguments have different types, e.g. a literal string for the first argument and a Path for the second argument.

pub fn add_args<I, S>(&mut self, args: I) -> &mut Self

where S: AsRef<OsStr>, I: IntoIterator<Item = S>,

Append multiple arguments.

pub fn enable_capture(&mut self) -> &mut Self

Set capture to true.

pub fn combine_output(&mut self) -> &mut Self

Set combine_output to true.

pub fn set_dir<S: AsRef<OsStr>>(&mut self, dir: S) -> &mut Self

Set the directory from which to run the program.

pub fn disable_check(&mut self) -> &mut Self

Set check to false.

pub fn run(&self) -> Result<Output, Error>

Run the command.

If capture is true, the command’s output (stdout and stderr) is returned along with the status. If not, the stdout and stderr are empty.

If the command fails to start an error is returned. If check is set, an error is also returned if the command exits non-zero or due to a signal.

If log_command is true then the command line is logged before running it. If the command fails the error is not logged or printed, but the resulting error type implements Display and can be used for this purpose.

pub fn command_line_lossy(&self) -> String

Format as a space-separated command line.

The program path and the arguments are converted to strings with String::from_utf8_lossy.

If any component contains characters that are not ASCII alphanumeric or in the set /-_,:.=+, the component is quoted with ' (single quotes). This is both too aggressive (unnecessarily quoting things that don’t need to be quoted) and incorrect (e.g. a single quote will itself be quoted with a single quote). This method is mostly intended for logging though, and it should work reasonably well for that.

Trait Implementations

impl Clone for Command

fn clone(&self) -> Command

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Command

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

Formats the value using the given formatter.

impl Default for Command

fn default() -> Self

Returns the “default value” for a type.

impl From<&Command> for Command

fn from(cmd: &Command) -> Self

Converts to this type from the input type.

impl PartialEq for Command

fn eq(&self, other: &Command) -> 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 Command

impl StructuralPartialEq for Command