Trait cradle::CmdOutput

pub trait CmdOutput: Sized { }

All possible return types of cmd! have to implement this trait. For documentation about what these return types do, see the individual implementations below.

Except for tuples: All CmdOutput implementations for tuples serve the same purpose: combining multiple types that implement CmdOutput to retrieve more information from a child process. The following code for example retrieves what’s written to stdout and the ExitStatus:

use cradle::*;

let (StdoutUntrimmed(stdout), Exit(status)) = cmd!(%"echo foo");
assert_eq!(stdout, "foo\n");
assert!(status.success());

Implementations on Foreign Types

impl CmdOutput for ()

Use this when you don’t need any result from the child process.

impl<A> CmdOutput for (A,) where
    A: CmdOutput, 

impl<A, B> CmdOutput for (A, B) where
    A: CmdOutput,
    B: CmdOutput, 

impl<A, B, C> CmdOutput for (A, B, C) where
    A: CmdOutput,
    B: CmdOutput,
    C: CmdOutput, 

Implementors

impl CmdOutput for Exit

Using Exit as the return type for cmd! allows to retrieve the ExitStatus of the child process:

use cradle::*;

let Exit(status) = cmd!(%"echo foo");
assert!(status.success());

Also, when using Exit, non-zero exit codes won’t result in neither a panic nor a std::result::Result::Err:

use cradle::*;

let Exit(status) = cmd!("false");
assert_eq!(status.code(), Some(1));
let result: Result<Exit, cradle::Error> = cmd_result!("false");
assert!(result.is_ok());
assert_eq!(result.unwrap().0.code(), Some(1));

Also see the section about error handling in the module documentation.

impl CmdOutput for Stderr

Stderr allows to capture the stderr of a child process:

use cradle::*;

// (`Exit` is used here to suppress panics caused by `ls`
// terminating with a non-zero exit code.)
let (Stderr(stderr), Exit(_)) = cmd!(%"ls does-not-exist");
assert!(stderr.contains("No such file or directory"));

This assumes that the output written to stderr is encoded as utf-8, and will error otherwise.

By default, what is written to stderr by the child process is relayed to the parent’s stderr. However, when Stderr is used, this is switched off.

impl CmdOutput for StdoutTrimmed

Returns what the child process writes to stdout, interpreted as utf-8, collected into a string, trimmed of leading and trailing whitespace. This also suppresses output of the child’s stdout to the parent’s stdout. (Which would be the default when not using StdoutTrimmed as the return value.)

It’s recommended to pattern-match to get to the inner String. This will make sure that the return type can be inferred. Here’s an example:

use std::path::Path;
use cradle::*;

let StdoutTrimmed(output) = cmd!(%"which ls");
assert!(Path::new(&output).exists());

fn prepare_config(config: &mut Config)

fn from_run_result(
    config: &Config,
    result: Result<RunResult, Error>
) -> Result<Self, Error>

impl CmdOutput for StdoutUntrimmed

Same as StdoutTrimmed, but does not trim whitespace from the output:

use cradle::*;

let StdoutUntrimmed(output) = cmd!(%"echo foo");
assert_eq!(output, "foo\n");