#shell #process #command #run-command #command-output

bossy

Opinionated convenience wrappers for std::process::Command and friends

6 releases

0.2.1 Jan 8, 2021
0.2.0 Dec 22, 2020
0.1.4 Dec 10, 2020
0.1.3 Nov 5, 2020
0.1.0 Mar 11, 2020

#1104 in Rust patterns

Download history 14/week @ 2024-05-26 18/week @ 2024-06-02 17/week @ 2024-06-09 16/week @ 2024-06-16 38/week @ 2024-06-23 14/week @ 2024-06-30 26/week @ 2024-07-07 27/week @ 2024-07-14 15/week @ 2024-07-21 29/week @ 2024-07-28 15/week @ 2024-08-04 20/week @ 2024-08-11 22/week @ 2024-08-18 32/week @ 2024-08-25 33/week @ 2024-09-01 25/week @ 2024-09-08

114 downloads per month
Used in 3 crates

Apache-2.0/MIT

27KB
568 lines

bossy

docs.rs badge CI Status

Opinionated convenience wrappers for std::process::Command and friends.

This crate arose from patterns I found while working on cargo-mobile, which does a ton of subprocessing. In my not-entirely-humble opinion, bossy makes working with commands super convenient!

use bossy::Command;
use std::{io::Write as _, path::Path};

// `bossy::Error` contains detailed error information; the process failing to
// spawn, the process exiting with a non-zero status, stderr contents, etc.
// For commands with piped output, you'll even have access to the stdout
// contents.
fn main() -> bossy::Result<()> {
    // We generate a ton of helpful logging, if you're into that sort of thing.
    simple_logger::init().unwrap();

    let path = Path::new("src");
    println!("{:?} directory contents:", path);
    // `impure` indicates that this command inherits the parent process's
    // environment. For more reproducability, you can use `pure` to get a
    // completely empty environment.
    let status = Command::impure_parse("ls -l")
        // `std::process::Command::arg` takes `&mut self` and returns
        // `&mut Self`; our equivalent of that is `add_arg`, but I personally
        // prefer using `with_arg`, which takes `self` and returns `Self`.
        .with_arg(path)
        // We use more explicit names for our run methods than
        // `std::process::Command` does:
        // - `run` (equivalent to `spawn`)
        // - `run_and_wait` (equivalent to `status`)
        // - `run_and_wait_for_output` (equivalent to `output`)
        .run_and_wait()?;
    // `bossy::ExitStatus` is just a re-export of `std::process::ExitStatus`.
    println!("exited with code {:?}", status.code());

    let readme_output = Command::impure_parse("cat README.md")
        // Just like with `std::process::Command::output`, this will
        // automatically pipe stdout and stderr.
        .run_and_wait_for_output()?;
    // `bossy::Output` has cute conveniences for the very common task of
    // converting output to a string.
    println!(
        "README.md contents:\n{}",
        readme_output
            .stdout_str()
            .expect("README.md contained invalid utf-8")
    );

    let mut handle = Command::impure("shasum")
        // We also have methods that let you set these using `bossy::Stdio`
        // (which is currently just a re-export of `std::process::Stdio`), but
        // this spares you some typing and an import.
        .with_stdin_piped()
        .with_stdout_piped()
        .with_stderr_piped()
        .run()?;
    handle
        .stdin()
        // This will only be `None` if you forgot to set stdin to piped above.
        .expect("developer error: `handle` stdin not captured")
        .write_all(readme_output.stdout())
        .expect("failed to write to `handle` stdin");
    // `bossy::Handle` is very similar to `std::process::Child`, but will
    // log an error message if it's dropped without being waited on.
    let shasum_output = handle.wait_for_output()?;
    println!(
        "README.md SHA-1 sum: {}",
        shasum_output
            .stdout_str()
            .expect("shasum output contained invalid utf-8")
    );

    Ok(())
}

You can run the example to see the exact same code as above, but like, with output:

cargo run --example commands

There isn't a ton of documentation, but this is a pretty thin wrapper, so documentation for std::process will typically apply here as well.

Dependencies

~46–305KB