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.

• Docs
• Crate
• Repo

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.

#[macro_use]
extern crate duct;

use duct::{cmd, sh};

fn main() {
    // 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. `sh` commands run under the real system shell,
    // /bin/sh on Unix or cmd.exe on Windows.
    let current_branch = sh("git symbolic-ref --short HEAD").read().unwrap();

    // Log the current branch, with git taking over the terminal as usual.
    // `cmd!` commands are spawned directly, without going through the
    // shell, so there aren't any escaping issues with variable arguments.
    cmd!("git", "log", current_branch).run().unwrap();

    // More complicated expressions become trees. Here's a pipeline with two
    // child processes on the left, just because we can. In Bash this would
    // be: stdout=$((echo -n part one "" && echo part two) | sed s/p/sm/g)
    let part_one = &["-n", "part", "one", ""];
    let stdout = cmd("echo", part_one)
        .then(sh("echo part two"))
        .pipe(cmd!("sed", "s/p/sm/g"))
        .read()
        .unwrap();
    assert_eq!("smart one smart two", stdout);
}

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 line:

use duct::sh;

// This works on Windows too!
let output = sh("echo foo && echo bar >&2").stderr_to_stdout().read().unwrap();

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

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, cmd!, or sh, 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. Expressions are immutable, and they do a lot of Arc sharing internally, so all of these methods take &self and return a new Expression cheaply.
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

duct provides several impls of this trait to handle the difference between Path/PathBuf and other types of strings. In particular, duct automatically prepends a leading dot to relative paths (though not other string types) before executing them. This is required for single-component relative paths to work at all on Unix, and it prevents aliasing with programs in the global PATH on both Unix and Windows. See the trait bounds on cmd and sh.

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.
sh	Create a command from a string of shell code.