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:
()
: In case you don’t want to capture anything. See alsorun
.- To capture output streams:
StdoutTrimmed
: To capturestdout
, trimmed of whitespace.StdoutUntrimmed
: To capturestdout
untrimmed.Stderr
: To capturestderr
.
Status
: To capture the command’sExitStatus
.
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.
fn from_child_output(
config: &Config,
result: &ChildOutput
) -> Result<Self, Error>
fn from_child_output(
config: &Config,
result: &ChildOutput
) -> Result<Self, Error>
Converts ChildOutput
s
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.
impl<A, B, C, D, E> Output for (A, B, C, D, E) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
impl<A, B, C, D, E, F> Output for (A, B, C, D, E, F) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
impl<A, B, C, D, E, F, G> Output for (A, B, C, D, E, F, G) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
impl<A, B, C, D, E, F, G, H> Output for (A, B, C, D, E, F, G, H) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
impl<A, B, C, D, E, F, G, H, I> Output for (A, B, C, D, E, F, G, H, I) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
impl<A, B, C, D, E, F, G, H, I, J> Output for (A, B, C, D, E, F, G, H, I, J) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
J: Output,
impl<A, B, C, D, E, F, G, H, I, J, K> Output for (A, B, C, D, E, F, G, H, I, J, K) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
J: Output,
K: Output,
impl<A, B, C, D, E, F, G, H, I, J, K, L> Output for (A, B, C, D, E, F, G, H, I, J, K, L) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
J: Output,
K: Output,
L: Output,
impl<A, B, C, D, E, F, G, H, I, J, K, L, M> Output for (A, B, C, D, E, F, G, H, I, J, K, L, M) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
J: Output,
K: Output,
L: Output,
M: Output,
impl<A, B, C, D, E, F, G, H, I, J, K, L, M, N> Output for (A, B, C, D, E, F, G, H, I, J, K, L, M, N) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
J: Output,
K: Output,
L: Output,
M: Output,
N: Output,
impl<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O> Output for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
J: Output,
K: Output,
L: Output,
M: Output,
N: Output,
O: Output,
impl<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P> Output for (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P) where
A: Output,
B: Output,
C: Output,
D: Output,
E: Output,
F: Output,
G: Output,
H: Output,
I: Output,
J: Output,
K: Output,
L: Output,
M: Output,
N: Output,
O: Output,
P: Output,
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.