[−][src]Crate duct

A cross-platform library for running child processes and building pipelines.

duct wants to make shelling out in Rust as easy and flexible as it is in Bash. It takes care of gotchas and inconsistencies in the way different platforms shell out. And it's a cross-language library; the original implementation is in Python, with an identical API.

Changelog

Version 0.11 introduced the before_spawn method.
Version 0.10 changed how environment variable casing is handled on Windows. See the docs for env_remove.
Version 0.9 removed the sh function. It now lives in its own crate, duct_sh.

Example

duct tries to be as concise as possible, so that you don't wish you were back writing shell scripts. At the same time, it's explicit about what happens to output, and strict about error codes in child processes.

// Read the name of the current git branch. If git exits with an error
// code here (because we're not in a git repo, for example), `read` will
// return an error too.
let current_branch = cmd!("git", "symbolic-ref", "--short", "HEAD").read()?;

// Log the current branch, with git taking over the terminal as usual.
// The `cmd` function works just like the `cmd!` macro, but it takes a
// collection instead of a variable list of arguments.
let args = &["log", &current_branch];
cmd("git", args).run()?;

// Log again, but this time read the output from a pipe of our own. We
// use the os_pipe crate to create the pipe, but any type implementing
// IntoRawFd works here, including File.
let (pipe_reader, pipe_writer) = os_pipe::pipe()?;
let child = cmd!("git", "log", "--oneline").stdout_handle(pipe_writer).start()?;
for line in BufReader::new(pipe_reader).lines() {
    assert!(!line?.contains("heck"), "profanity filter triggered");
}

duct uses os_pipe internally, and the docs for that one include a big example that takes a dozen lines of code to read both stdout and stderr from a child process. duct can do that in one (moderately long) line:

let output = cmd!("sh", "-c", "echo foo && echo bar 2>&1").stderr_to_stdout().read().unwrap();

assert!(output.split_whitespace().eq(vec!["foo", "bar"]));

Modules

unix	Unix-specific extensions to duct, for sending signals.

Macros

cmd	Create a command with any number of of positional arguments, which may be different types (anything that implements `Into<OsString>`). See also the `cmd` function, which takes a collection of arguments.

Structs

Expression	The central objects in `duct`, Expressions are created with `cmd` or `cmd!`, combined with `pipe` or `then`, and finally executed with `start`, `run`, or `read`. They also support several methods to control their execution, like `input`, `env`, and `unchecked`.
Handle	A handle to a running expression, returned by the `start` method. Calling `start` followed by `output` on the handle is equivalent to `run`. Note that unlike `std::process::Child`, most of the methods on `Handle` take `&self` rather than `&mut self`, and a `Handle` may be shared between multiple threads.

Traits

ToExecutable

An implementation detail of cmd, to distinguish paths from other string types.

Functions

cmd	Create a command given a program name and a collection of arguments. See also the `cmd!` macro, which doesn't require a collection.