Struct bigbro::Command

pub struct Command { /* fields omitted */ }

A process builder, providing fine-grained control over how a new process should be spawned.

Strongly modelled after std::process::Command. A default configuration is generated using Command::new(program), where program gives a path to the program to be executed. Additional builder methods allow the configuration to be changed (for example, by adding arguments) prior to running:

use bigbro::Command;

let status = if cfg!(target_os = "windows") {
    Command::new("cmd")
            .args(&["/C", "echo hello"])
            .status()
            .expect("failed to execute process")
} else {
    Command::new("sh")
            .arg("-c")
            .arg("echo hello")
            .status()
            .expect("failed to execute process")
};

assert!(status.status().success());

Methods

impl Command

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

Constructs a new Command for launching the program at path program, with the following default configuration:

• No arguments to the program
• Inherit the current process's environment
• Inherit the current process's working directory
• Inherit stdin/stdout/stderr for spawn or status, but create pipes for output

Builder methods are provided to change these defaults and otherwise configure the process.

Examples

Basic usage:

use bigbro::Command;

Command::new("sh")
        .status()
        .expect("sh command failed to run");

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

Add a single argument to the command.

pub fn args<I, S>(&mut self, args: I) -> &mut Command where
    I: IntoIterator<Item = S>,
    S: AsRef<OsStr>, 

Add arguments to the command.

pub fn current_dir<P: AsRef<Path>>(&mut self, dir: P) -> &mut Command

Set the working directory for the command.

pub fn env<K, V>(&mut self, key: K, val: V) -> &mut Command where
    K: AsRef<OsStr>,
    V: AsRef<OsStr>, 

Update an environment variable mapping

Examples

use bigbro::Command;

let mut status = Command::new("sh")
                         .arg("-c")
                         .arg("echo $CFLAGS")
                         .env("CFLAGS", "--coverage")
                         .save_stdouterr()
                         .status()
                         .expect("failed to execute sh");

println!("status: {:?}", status.status());
assert!(status.status().success() );
let f = status.stdout().unwrap();
assert!(f.is_some());
let mut contents = String::new();
f.unwrap().read_to_string(&mut contents).unwrap();
assert_eq!(contents, "--coverage\n");

use bigbro::Command;

let mut status = Command::new("env")
                         .env_clear()
                         .env("FOO", "foo")
                         .save_stdouterr()
                         .status()
                         .expect("failed to execute env");

println!("status: {:?}", status.status());
assert!(status.status().success() );
let f = status.stdout().unwrap();
assert!(f.is_some());
let mut contents = String::new();
f.unwrap().read_to_string(&mut contents).unwrap();
// for some reason windows doesn't allow to clear HOME or TERM?
if ! cfg!(target_os = "windows") {
  assert_eq!(contents, "FOO=foo\n");
}

pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Command where
    I: IntoIterator<Item = (K, V)>,
    K: AsRef<OsStr>,
    V: AsRef<OsStr>, 

Add or update multiple environment variable mappings.

pub fn env_remove<K>(&mut self, key: K) -> &mut Command where
    K: AsRef<OsStr>, 

Remove an environment variable mapping

pub fn env_clear(&mut self) -> &mut Command

Clear the environment for the child

pub fn stdin(&mut self, cfg: Stdio) -> &mut Command

Set the stdin of the command.

pub fn stdout(&mut self, cfg: Stdio) -> &mut Command

Set the stdout of the command.

pub fn stderr(&mut self, cfg: Stdio) -> &mut Command

Set the stderr of the command.

pub fn save_stdouterr(&mut self) -> &mut Command

Set the stderr and stdout of the command to go to a temp file, from which they can be read after the command is run.

Examples

use bigbro::Command;

let mut status = Command::new("echo")
                         .arg("hello")
                         .save_stdouterr()
                         .status()
                         .expect("failed to execute echo");

assert!(status.status().success() );
let f = status.stdout().unwrap();
assert!(f.is_some());
let mut contents = String::new();
f.unwrap().read_to_string(&mut contents);
assert_eq!(contents, "hello\n");

pub fn log_stdouterr(&mut self, path: &Path) -> &mut Command

Set the stderr and stdout of the command to go to a file, from which they can be read after the command is run.

Examples

use bigbro::Command;

let mut logfile = std::env::temp_dir();
logfile.push("test-file");
let mut status = Command::new("echo")
                         .arg("hello")
                         .arg("world")
                         .log_stdouterr(&logfile)
                         .status()
                         .expect("failed to execute echo");

assert!(status.status().success() );
let f = status.stdout().unwrap();
assert!(f.is_some());
let mut contents = String::new();
f.unwrap().read_to_string(&mut contents).unwrap();
assert_eq!(contents, "hello world\n");

pub fn status(&mut self) -> Result<Status>

Run the Command, wait for it to complete, and return its results.

pub fn blind(&mut self, am_blind: bool) -> &mut Command

Do not actually track accesses.

Examples

use bigbro::Command;

let (tx,rx) = std::sync::mpsc::channel();
let mut cmd = Command::new("echo");
cmd.arg("hello").arg("world").save_stdouterr().blind(true);
let _killer = cmd.spawn_and_hook(move |s| { tx.send(s).ok(); })
                 .expect("failed to execute echo");
let mut status = rx.recv().unwrap().unwrap();
assert!(status.status().success() );
let f = status.stdout().unwrap();
assert!(f.is_some());
let mut f = f.unwrap();
let mut contents = String::new();
f.read_to_string(&mut contents).unwrap();
assert_eq!(contents, "hello world\n");
assert_eq!(status.read_from_files().len(), 0); // not tracking means no files listed

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

Start running the Command and return without waiting for it to complete.

pub fn spawn_and_hook<F>(self, status_hook: F) -> Result<Killer> where
    F: FnOnce(Result<Status>) + Send + 'static, 

Start running the Command and return without waiting for it to complete. Return the final status via a callback, but return the pid information with which to kill the child synchronously.

Examples

use bigbro::Command;

let mut logfile = std::env::temp_dir();
logfile.push("test-file");
println!("saving output in file {:?}", &logfile);
let (tx,rx) = std::sync::mpsc::channel();
let mut cmd = Command::new("echo");
cmd.arg("hello").arg("world").log_stdouterr(&logfile);
let _killer = cmd.spawn_and_hook(move |s| { tx.send(s).ok(); })
                 .expect("failed to execute echo");
let mut status = rx.recv().expect("should have gotten *something*!")
                   .expect("the echo command failed to run?");
assert!(status.status().success() );
let f = status.stdout().expect("unable to look at stdout?");
assert!(f.is_some());
let mut contents = String::new();
f.unwrap().read_to_string(&mut contents).expect("unable to read from logfile");
assert_eq!(contents, "hello world\n");

Trait Implementations