Crate cradle[−][src]
Expand description
(cradle
is currently in an experimental stage.
There’s no promises on API stability yet, so 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::*; 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 CmdArgument
trait:
use cradle::*; let StdoutTrimmed(stdout) = cmd!("echo", "foo", "bar"); assert_eq!(stdout, "foo bar");
Arguments of type &str
will be split by whitespace into words.
You can also pass in arrays of type [[&str]
]. All elements will
be used as arguments:
use cradle::*; let StdoutTrimmed(stdout) = cmd!("echo", ["foo", "bar"]); assert_eq!(stdout, "foo bar");
Elements of arrays are not being split by whitespace, so you can use that to avoid whitespace splitting:
use std::path::PathBuf; use cradle::*; let StdoutTrimmed(_) = cmd!("touch", ["filename with spaces"]); assert!(PathBuf::from("filename with spaces").exists());
Before rust version 1.51
, instead of arrays, use Vec<&str>
:
use std::path::PathBuf; use cradle::*; let StdoutTrimmed(_) = cmd!("touch", vec!["filename with spaces"]); assert!(PathBuf::from("filename with spaces").exists());
For all possible inputs to cmd!
, see CmdArgument
.
Output
You can choose which return type you want cmd!
to return,
as long as the chosen return type implements CmdOutput
.
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::*; 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::*; let () = cmd!("touch foo");
Since that’s a very common case, cradle
provides the cmd_unit!
shortcut, that behaves exactly like cmd!
, but pins the return
type down to ()
:
use cradle::*; cmd_unit!("touch foo");
See the implementations for CmdOutput
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::*; // 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
Exit
type as a return type of cmd!
:
use cradle::*; let Exit(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 CmdOutput
.
Here’s some examples:
use cradle::*; 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::*; fn build() -> Result<(), Error> { cmd_result!("which make")?; cmd_result!("which gcc")?; cmd_result!("which ld")?; cmd_result!("make build")?; Ok(()) }
Macros
cmd | Execute child processes. See the module documentation on how to use it. |
cmd_result | Like |
cmd_unit | Like |
Structs
CurrentDir | See the |
Exit | |
LogCommand | See the |
Stderr | |
StdoutTrimmed | See the |
StdoutUntrimmed | See the |
Enums
Error |
Traits
CmdArgument | All types that are possible arguments to |
CmdOutput | All possible return types of |