Crate bawawa

process management

this module provides some wrapping around the standard library’s std::process::Command and std::process::Child and associated types.

Here we provide an opinionated API where we capture standard inputs and outputs by default. The errors are also wrapped to provide better understanding of what did fail (especially the PID or the command line).

There are a couple of items to keep in mind when utilising this API:

• as soon as Process is dropped the associated process will be terminated;
• Process captures Stdout and Stderr, if you don’t read the standard output it won’t be visible on your terminal;
• Process control Stdin too
• the API utilizes the Future framework. If you don’t push it in a runtime or call wait the functions will do nothing.

the Program

Program is an object that guarantees (within reason) the existence of a program within the execution environment. When constructing, the Program is checked so that once created it is known if it exists and if it has appropriate execution rights.

let rustc = Program::new("rustc".to_owned())?;

the Command

this is the command line, the Program, the parameters and the associated environment variables necessary to spawn a new Process.

let mut get_rustc_version = Command::new(rustc);
get_rustc_version.arguments(&["--version"]);

println!("{}", get_rustc_version);

spawn a Process

Once the Command is ready with the appropriate parameter it is possible to spawn a Process. The trait Control allows to follow the life cycle of the spawned Process.

let process = Process::spawn(get_rustc_version)?;

println!("spawned command: '{}' (PID: {})", process.command(), process.id());

We provide functions to capture the standard output and standard error output utilising the StandardOutput::capture_stdout or StandardError::capture_stderr and to send items to the standard inputs with StandardInput::send_stdin.

let mut capture_stdout = process
    .capture_stdout(
        // specify the codec, the way to decode data
        // from the captured output. Here we read line
        // by line.
        tokio_codec::LinesCodec::new()
    )
    .wait(); // from the _futures_ crate's Stream trait

println!("compiler: {}", capture_stdout.next().unwrap()?);
// compiler: rustc 1.35.0 (3c235d560 2019-05-20)

Structs

Capture

capture the standard output or standard error output from a running process

Command

just like standard Command but keeps the components in a human readable format so we can actually display it when needed. or keep trace of it.

Error

The Error type.

Process

a Process object to monitor the execution of a Command.

Program

a program, pre-checked and known to exist in the environment $PATH

SendStdin

provide API to control the sending part to the standard input. created from StandardInput::send_stdin.

Enums

ErrorKind

The kind of an error.

Traits

Control

Process control trait, access Program ID, the command line or kill the running process

ResultExt

Additional methods for Result, for easy interaction with this crate.

StandardError

Access the standard error output of a running Process

StandardInput

Access the standard input of a running Process

StandardOutput

Access the standard output of a running Process

Type Aliases

Result

Convenient wrapper around std::Result.