Struct devx_cmd::Cmd

#[must_use =
  "commands are not executed until run(), read() or spawn() is called"]pub struct Cmd(_);

More convenient version of std::process::Command. Allows for spawning child processes with or without capturing their stdout. It also comes with inbuilt logging of the invocations to stderr.

All the methods for invoking a Cmd:

• spawn_piped
• spawn
• run
• read
• read_bytes

For more laconic usage see cmd and other macros.

Example:

let mut cmd = Cmd::new("cargo");
cmd
    // `arg*()` methods append arguments
    .arg("metadata")
    .arg2("--color", "never")
    .args(&["--verbose", "--no-deps", "--all-features"])
    .replace_arg(3, "--quiet")
    // `echo*()` are `true` by default
    .echo_cmd(false)
    .echo_err(false)
    // repetated `stdin*()` calls overwrite previous ones
    .stdin("Hi")
    .stdin_bytes(vec![0, 1, 2]);

let () = cmd.run()?;
let output: String = cmd.read()?;
let output: Vec<u8> = cmd.read_bytes()?;
let process: Child = cmd.spawn()?;

Implementations

impl Cmd

pub fn new(bin: impl Into<PathBuf>) -> Self

Returns a command builder that invokes the binary at bin. You should also be able to pass the command by name if it is in PATH.

Does not verify that the binary is actually available at the given path. If it isn't, then an error will be returned when executing the command.

pub fn try_at(bin_path: impl Into<PathBuf>) -> Option<Self>

Returns a command builder if there is some file available at bin_path. If there is no file at the given path returns None. Beware that this won't take PATH env variable into account. This function expects a relative or absolute filesystem path to the binary, and tries to check if there is some file there (retrying with .exe extension on windows).

If you want to find a binary through PATH, you should use Cmd::lookup_in_path

pub fn lookup_in_path(bin_name: &str) -> Option<Self>

Returns a command builder for the given bin_name only if this bin_name is accessible trough PATH env variable, otherwise returns None

pub fn bin(&mut self, bin: impl Into<PathBuf>) -> &mut Self

Set binary path, overwrites the path that was set before.

pub fn current_dir(&mut self, dir: impl Into<PathBuf>) -> &mut Self

Set the current directory for the child process.

Inherits this process current dir by default.

pub fn echo_cmd(&mut self, yes: bool) -> &mut Self

When set to true the command with its arguments will be logged to stderr. The command's output will also be logged to stderr.

Default: true

pub fn echo_err(&mut self, yes: bool) -> &mut Self

When set to true the invocation error will be logged to stderr. Set it to false if non-zero exit code is an expected/recoverable error which doesn't need to be logged.

Default: true

pub fn stdin(&mut self, stdin: impl Into<String>) -> &mut Self

Sets the string input passed to child process's stdin. This overwrites the previous value.

Use Cmd::stdin_bytes if you need to pass non-utf8 byte sequences.

Nothing is written to stdin by default.

pub fn stdin_bytes(&mut self, stdin: Vec<u8>) -> &mut Self

Sets the bytes input passed to child process's stdin. This overwrites the previous value.

Nothing is written to stdin by default.

pub fn arg2(
    &mut self,
    arg1: impl Into<OsString>,
    arg2: impl Into<OsString>
) -> &mut Self

Same as cmd.arg(arg1).arg(arg2). This is just a convenient shortcut mostly used to lexically group related arguments (for example named arguments).

pub fn arg(&mut self, arg: impl Into<OsString>) -> &mut Self

Appends a single argument to the list of arguments passed to the child process.

pub fn replace_arg(&mut self, idx: usize, arg: impl Into<OsString>) -> &mut Self

Replaces the argument at the given index with a new value.

Panics

Panics if the given index is out of range of the arguments already set on this command builder.

pub fn args<I>(&mut self, args: I) -> &mut Self where
    I: IntoIterator,
    I::Item: Into<OsString>, 

Extends the array of arguments passed to the child process with args.

pub fn run(&self) -> Result<()>

Same as cmd.spawn()?.wait() See Child::wait for details.

pub fn read(&self) -> Result<String>

Same as cmd.spawn_piped()?.read() See Child::read for details.

pub fn read_bytes(&self) -> Result<Vec<u8>>

Same as cmd.spawn_piped()?.read_bytes() See Child::read_bytes for details.

pub fn spawn(&self) -> Result<Child>

Spawns a child process returning a handle to it. The child inherits both stdout and stderr. See the docs for Child for more details. Note that reading the child process output streams will panic! If you want to read the output, see Cmd::spawn_piped

pub fn spawn_piped(&self) -> Result<Child>

Spawns a child process returning a handle to it. Child's stdout will be piped for further reading from it, but stderr will be inherited. See the docs for Child for more details.

Trait Implementations

impl Clone for Cmd

fn clone(&self) -> Cmd

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Cmd

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

Formats the value using the given formatter.

impl Display for Cmd

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

Formats the value using the given formatter.