Trait cradle::output::Output[−][src]

pub trait Output: Sized {
    fn configure(config: &mut Config);

    fn from_child_output(
        config: &Config, 
        result: &ChildOutput
    ) -> Result<Self, Error>;
}
Expand description

All possible return types of run!, run_output! or run_result! must implement this trait. This return-type polymorphism makes cradle very flexible. For example, if you want to capture what a command writes to stdout you can do that using StdoutUntrimmed:

use cradle::prelude::*;

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

But if instead you want to capture the command’s ExitStatus, you can use Status:

use cradle::prelude::*;

let Status(exit_status) = run_output!("false");
assert_eq!(exit_status.code(), Some(1));

For documentation on what all the possible return types do, see the documentation for the individual impls of Output. Here’s a non-exhaustive list of the more commonly used return types to get you started:

Also, Output is implemented for tuples. You can use this to combine multiple return types that implement Output. The following code for example retrieves the command’s ExitStatus and what it writes to stdout:

use cradle::prelude::*;

let (Status(exit_status), StdoutUntrimmed(stdout)) = run_output!(%"echo foo");
assert!(exit_status.success());
assert_eq!(stdout, "foo\n");

Custom Output impls

It is possible, but not recommended, to write Output implementations for your own types. The API is inconvenient, under-documented, and easy to misuse, i.e. it is easily possible to provoke Internal errors.

See Issue 184: Provide a better API for writing custom Output impls for more details and discussion.

Required methods

Configures the given Config for the Output type. This is an internal function that should be ignored.

See also Custom Output impls.

Converts ChildOutputs from running a child process into values of the Output type. This is an internal function that should be ignored.

See also Custom Output impls.

Implementations on Foreign Types

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

use cradle::prelude::*;

let () = run_output!(%"touch ./foo");

Since run_output! (and run_result) use return type polymorphism, you have to make sure the compiler can figure out which return type you want to use. In this example that happens through the let () =. So you can’t just omit that.

See also run! for a more convenient way to use () as the return type.

Using bool as the return type for run_output! will return true if the command returned successfully, and false otherwise:

use cradle::prelude::*;

if !run_output!(%"which cargo") {
    panic!("Cargo is not installed!");
}

Also, when using bool, non-zero exit codes will not result in a panic or std::result::Result::Err:

use cradle::prelude::*;

let success: bool = run_output!("false");
assert!(!success);
let result: Result<bool, cradle::Error> = run_result!("false");
assert!(result.is_ok());
assert_eq!(result.unwrap(), false);

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

Implementors