subprocess/
lib.rs

1//! Execution of and interaction with external processes and pipelines.
2//!
3//! The main entry points to the crate are the [`Exec`] and [`Pipeline`] builders.
4//! They provide a builder-pattern API with convenient methods for streaming and capturing
5//! of output, as well as combining commands into pipelines.
6//!
7//! Compared to `std::process`, the crate provides these additional features:
8//!
9//! * Connecting multiple commands into OS-level [pipelines](Pipeline).
10//!
11//! * The *capture* and *communicate* [family of methods](Job::capture) for
12//!   deadlock-free capturing of subprocess output/error, while simultaneously feeding
13//!   data to its standard input.  Capturing supports optional timeout and read size
14//!   limit.
15//!
16//! * Flexible [redirection options](Redirection), such as connecting standard streams to
17//!   arbitrary [open files](Redirection::File), or [merging](Redirection::Merge) output
18//!   streams like shell's `2>&1` and `1>&2` operators.
19//!
20//! * Non-blocking and timeout methods to wait on the process: [`poll`](Process::poll),
21//!   [`wait`](Process::wait), and [`wait_timeout`](Process::wait_timeout).
22//!
23//! # Examples
24//!
25//! Execute a command and capture its output:
26//!
27//! ```
28//! # use subprocess::*;
29//! # fn dummy() -> std::io::Result<()> {
30//! let out = Exec::cmd("echo").arg("hello").capture()?.stdout_str();
31//! assert!(out.contains("hello"));
32//! # Ok(())
33//! # }
34//! ```
35//!
36//! Combine [`Exec`] instances with `|` to build a [`Pipeline`] and capture its output:
37//!
38//! ```no_run
39//! # use subprocess::*;
40//! # fn dummy() -> std::io::Result<()> {
41//! let dir_checksum = {
42//!     Exec::shell("find . -type f") | Exec::cmd("sort") | Exec::cmd("sha1sum")
43//! }.capture()?.stdout_str();
44//! # Ok(())
45//! # }
46//! ```
47
48#![warn(missing_debug_implementations, missing_docs)]
49#![allow(clippy::type_complexity)]
50#![cfg_attr(docsrs, feature(doc_cfg))]
51#![cfg_attr(docsrs, doc(auto_cfg(hide(docsrs))))]
52
53mod communicate;
54mod exec;
55mod job;
56mod pipeline;
57mod process;
58mod spawn;
59mod util;
60
61#[cfg(unix)]
62mod posix;
63
64#[cfg(windows)]
65mod win32;
66
67#[cfg(test)]
68mod tests;
69
70pub use communicate::Communicator;
71pub use exec::Redirection;
72#[cfg(unix)]
73pub use exec::unix::ExecExt;
74#[cfg(unix)]
75pub use exec::unix::JobExt;
76#[cfg(unix)]
77pub use exec::unix::PipelineExt;
78#[cfg(windows)]
79pub use exec::windows::ExecExt;
80pub use exec::{Capture, Exec, InputData, IntoInputSource, IntoOutputSink};
81pub use job::Job;
82pub use pipeline::Pipeline;
83pub use process::ExitStatus;
84pub use process::Process;
85
86/// Subprocess extensions for Unix platforms.
87#[cfg(unix)]
88pub mod unix {
89    pub use super::exec::unix::JobExt;
90    pub use super::exec::unix::PipelineExt;
91    pub use super::process::ExitStatusExt;
92    pub use super::process::ProcessExt;
93}
94
95/// Subprocess extensions for Windows platforms.
96#[cfg(any(windows, docsrs))]
97pub mod windows {
98    pub use super::exec::windows::*;
99    pub use super::process::windows::ExitStatusExt;
100}
subprocess/lib.rs

subprocess/
lib.rs
