Struct subprocess::Pipeline
source · [−]pub struct Pipeline { /* private fields */ }
Expand description
A builder for multiple Popen
instances connected via
pipes.
A pipeline is a sequence of two or more Exec
commands
connected via pipes. Just like in a Unix shell pipeline, each
command receives standard input from the previous command, and
passes standard output to the next command. Optionally, the
standard input of the first command can be provided from the
outside, and the output of the last command can be captured.
In most cases you do not need to create Pipeline
instances
directly; instead, combine Exec
instances using the |
operator which produces Pipeline
.
Examples
Execute a pipeline and return the exit status of the last command:
let exit_status =
(Exec::shell("ls *.bak") | Exec::cmd("xargs").arg("rm")).join()?;
Capture the pipeline’s output:
let dir_checksum = {
Exec::cmd("find . -type f") | Exec::cmd("sort") | Exec::cmd("sha1sum")
}.capture()?.stdout_str();
Implementations
sourceimpl Pipeline
impl Pipeline
sourcepub fn new(cmd1: Exec, cmd2: Exec) -> Pipeline
pub fn new(cmd1: Exec, cmd2: Exec) -> Pipeline
Creates a new pipeline by combining two commands.
Equivalent to cmd1 | cmd2
.
sourcepub fn from_exec_iter<I>(iterable: I) -> Pipeline where
I: IntoIterator<Item = Exec>,
pub fn from_exec_iter<I>(iterable: I) -> Pipeline where
I: IntoIterator<Item = Exec>,
Creates a new pipeline from a list of commands. Useful if a pipeline should be created dynamically.
Example:
use subprocess::Exec;
let commands = vec![
Exec::shell("echo tset"),
Exec::shell("tr '[:lower:]' '[:upper:]'"),
Exec::shell("rev")
];
let pipeline = subprocess::Pipeline::from_exec_iter(commands);
let output = pipeline.capture().unwrap().stdout_str();
assert_eq!(output, "TEST\n");
use subprocess::Exec;
let commands = vec![
Exec::shell("echo tset"),
];
// This will panic as the iterator contains less than two (2) items.
let pipeline = subprocess::Pipeline::from_exec_iter(commands);
Errors:
- Panics when the passed iterator contains less than two (2) items.
sourcepub fn stdin(self, stdin: impl Into<InputRedirection>) -> Pipeline
pub fn stdin(self, stdin: impl Into<InputRedirection>) -> Pipeline
Specifies how to set up the standard input of the first command in the pipeline.
Argument can be:
- a
Redirection
; - a
File
, which is a shorthand forRedirection::File(file)
; - a
Vec<u8>
or&str
, which will set up aRedirection::Pipe
for stdin, making sure thatcapture
feeds that data into the standard input of the subprocess. NullFile
, which will redirect the standard input to read from /dev/null.
sourcepub fn stdout(self, stdout: impl Into<OutputRedirection>) -> Pipeline
pub fn stdout(self, stdout: impl Into<OutputRedirection>) -> Pipeline
Specifies how to set up the standard output of the last command in the pipeline.
Argument can be:
- a
Redirection
; - a
File
, which is a shorthand forRedirection::File(file)
; NullFile
, which will redirect the standard output to write to /dev/null.
sourcepub fn stderr_to(self, to: File) -> Pipeline
pub fn stderr_to(self, to: File) -> Pipeline
Specifies a file to which to redirect the standard error of all the commands in the pipeline.
It is useful for capturing the standard error of the pipeline as a
whole. Unlike stdout()
, which only affects the last command in
the pipeline, this affects all commands. The difference is
because standard output is piped from one command to the next, so
only the output of the last command is “free”. In contrast, the
standard errors are not connected in any way. This is also the
reason only a File
is supported - it allows for efficient
sharing of the same file by all commands.
sourcepub fn popen(self) -> PopenResult<Vec<Popen>>
pub fn popen(self) -> PopenResult<Vec<Popen>>
Starts all commands in the pipeline, and returns a
Vec<Popen>
whose members correspond to running commands.
If some command fails to start, the remaining commands
will not be started, and the appropriate error will be
returned. The commands that have already started will be
waited to finish (but will probably exit immediately due
to missing output), except for the ones for which
detached()
was called. This is equivalent to what the
shell does.
sourcepub fn join(self) -> PopenResult<ExitStatus>
pub fn join(self) -> PopenResult<ExitStatus>
Starts the pipeline, waits for it to finish, and returns the exit status of the last command.
sourcepub fn stream_stdout(self) -> PopenResult<impl Read>
pub fn stream_stdout(self) -> PopenResult<impl Read>
Starts the pipeline and returns a value implementing the Read
trait that reads from the standard output of the last command.
This will automatically set up
stdout(Redirection::Pipe)
, so it is not necessary to do
that beforehand.
When the trait object is dropped, it will wait for the
pipeline to finish. If this is undesirable, use
detached()
.
sourcepub fn stream_stdin(self) -> PopenResult<impl Write>
pub fn stream_stdin(self) -> PopenResult<impl Write>
Starts the pipeline and returns a value implementing the Write
trait that writes to the standard input of the last command.
This will automatically set up stdin(Redirection::Pipe)
,
so it is not necessary to do that beforehand.
When the trait object is dropped, it will wait for the
process to finish. If this is undesirable, use
detached()
.
sourcepub fn communicate(self) -> PopenResult<Communicator>
pub fn communicate(self) -> PopenResult<Communicator>
Starts the pipeline and returns a Communicator
handle.
This is a lower-level API that offers more choice in how
communication is performed, such as read size limit and timeout,
equivalent to Popen::communicate
.
Unlike capture()
, this method doesn’t wait for the pipeline to
finish, effectively detaching it.
sourcepub fn capture(self) -> PopenResult<CaptureData>
pub fn capture(self) -> PopenResult<CaptureData>
Starts the pipeline, collects its output, and waits for all commands to finish.
The return value provides the standard output of the last command, the combined standard error of all commands, and the exit status of the last command. The captured outputs can be accessed as bytes or strings.
Unlike Popen::communicate
, this method actually waits for the
processes to finish, rather than simply waiting for the output to
close. If this is undesirable, use detached()
.
Trait Implementations
sourceimpl Clone for Pipeline
impl Clone for Pipeline
sourcefn clone(&self) -> Pipeline
fn clone(&self) -> Pipeline
Returns a copy of the value.
This method is guaranteed not to fail as long as none of
the Redirection
values contain a Redirection::File
variant. If a redirection to File
is present, cloning
that field will use File::try_clone
method, which
duplicates a file descriptor and can (but is not likely
to) fail. In that scenario, Exec::clone
panics.
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
Auto Trait Implementations
impl RefUnwindSafe for Pipeline
impl !Send for Pipeline
impl !Sync for Pipeline
impl Unpin for Pipeline
impl UnwindSafe for Pipeline
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more