Crate cradle[−][src]
Expand description
(cradle
is in an early stage of development.
APIs may change drastically!
Use at your own risk!)
cradle
provides the cmd!
macro, that makes
it easy to run child processes from rust programs.
use cradle::prelude::*; let StdoutTrimmed(stdout) = cmd!(%"echo foo"); assert_eq!(stdout, "foo");
Arguments
You can pass in multiple arguments (of different types) to cmd!
to specify arguments, as long as they implement the Input
trait:
use cradle::prelude::*; let StdoutTrimmed(stdout) = cmd!("echo", "foo", "bar"); assert_eq!(stdout, "foo bar");
For all possible inputs to cmd!
, see the documentation of Input
.
Whitespace Splitting
cradle
does not split given string arguments on whitespace by default.
So for example this code fails:
use cradle::prelude::*; let StdoutTrimmed(_) = cmd!("echo foo");
In this code cradle
tries to run a process from an executable called
"echo foo"
, including the space in the file name of the executable.
That fails, because an executable with that name doesn’t exist.
cradle
provides a new-type wrapper Split
to help with that:
use cradle::prelude::*; let StdoutTrimmed(output) = cmd!(Split("echo foo")); assert_eq!(output, "foo");
Wrapping an argument of type &str
in Split
will cause cradle
to first
split it by whitespace and then use the resulting words as if they were passed
into cmd!
as separate arguments.
And – since this is such a common case – cradle
provides a syntactic shortcut
for Split
, the %
symbol:
use cradle::prelude::*; let StdoutTrimmed(output) = cmd!(%"echo foo"); assert_eq!(output, "foo");
Output
You can choose which return type you want cmd!
to return,
as long as the chosen return type implements Output
.
For example you can use e.g. StdoutTrimmed
to collect what the child process writes to stdout
,
trimmed of leading and trailing whitespace:
use cradle::prelude::*; let StdoutTrimmed(output) = cmd!(%"echo foo"); assert_eq!(output, "foo");
(By default, the child’s stdout
is written to the parent’s stdout
.
Using StdoutTrimmed
as the return type suppresses that.)
If you don’t want any result from cmd!
, you can use ()
as the return value:
use cradle::prelude::*; let () = cmd!(%"touch foo");
Since that’s a very common case, cradle
provides the cmd_unit!
shortcut.
It’s named after the unit type ()
.
It behaves exactly like cmd!
but always returns ()
.
use cradle::prelude::*; cmd_unit!(%"touch foo");
See the implementations for Output
for all the supported types.
Error Handling
By default cmd!
panics for a few reasons, e.g.:
- when the child process exits with a non-zero exitcode,
- when the given executable cannot be found,
- when no strings are given as arguments to
cmd!
.
For example:
use cradle::prelude::*; // panics with "false:\n exited with exit code: 1" cmd_unit!("false");
You can suppress panics caused by non-zero exit codes by using the
Status
type as a return type of cmd!
:
use cradle::prelude::*; let Status(exit_status) = cmd!("false"); assert_eq!(exit_status.code(), Some(1));
You can also turn all panics into std::result::Result::Err
s
by using cmd_result!
. This will return a value of type
Result<T, cradle::Error>
, where
T
is any type that implements Output
.
Here’s some examples:
use cradle::prelude::*; let result: Result<(), cradle::Error> = cmd_result!("false"); let error_message = format!("{}", result.unwrap_err()); assert_eq!( error_message, "false:\n exited with exit code: 1" ); let result = cmd_result!(%"echo foo"); let StdoutTrimmed(output) = result.unwrap(); assert_eq!(output, "foo".to_string());
cmd_result
can also be combined with ?
to handle errors in an
idiomatic way, for example:
use cradle::prelude::*; fn build() -> Result<(), Error> { cmd_result!(%"which make")?; cmd_result!(%"which gcc")?; cmd_result!(%"which ld")?; cmd_result!(%"make build")?; Ok(()) }
Prior Art
cradle
is heavily inspired by shake,
specifically by its
cmd
function.
Re-exports
pub use error::Error;
Modules
The Error
type used in the return type of cmd_result!
.
The Input
trait that defines all possible inputs to cmd!
,
cmd_unit!
and cmd_result!
.
The Output
trait that defines all possible outputs of cmd!
,
cmd_unit!
and cmd_result!
.
Cradle’s prelude
module.
It re-exports the most commonly used items from cradle.
We recommend importing cradle like this:
use cradle::prelude::*;
Macros
Execute child processes. See the module documentation on how to use it.
Like cmd!
, but fixes the return type to Result<T, Error>
,
where T
is any type that implements Output
.
Like cmd!
, but fixes the return type to ()
.
It’s named after the unit type ()
.