Struct subprocess::Pipeline

pub struct Pipeline { /* fields omitted */ }

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

Execite 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()?.output_str();

Methods

impl Pipeline

fn new(cmd1: Exec, cmd2: Exec) -> Pipeline

Create a new pipeline by combining two commands.

Equivalent to cmd1 | cmd2.

fn stdin<T: IntoInputRedirection>(self, stdin: T) -> Pipeline

Specify 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 for Redirection::File(file);
• a Vec<u8> or &str, which will set up a Redirection::Pipe for stdin, making sure that capture feeds that data into the standard input of the subprocess.
• NullFile, which will redirect the standard input to read from /dev/null.

fn stdout<T: IntoOutputRedirection>(self, stdout: T) -> Pipeline

Specify 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 for Redirection::File(file);
• NullFile, which will redirect the standard input to read from /dev/null.

fn popen(self) -> PopenResult<Vec<Popen>>

Start all commands in the pipeline, and return the 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.

fn join(self) -> PopenResult<ExitStatus>

Start the pipeline, wait for it to finish, and return the exit status of the last command.

fn stream_stdout(self) -> PopenResult<Box<Read>>

Start the pipeline and return a Read trait object 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().

fn stream_stdin(self) -> PopenResult<Box<Write>>

Start the pipeline and return a Write trait object that writes to the standard input of the first 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().

fn capture(self) -> PopenResult<CaptureOutput>

Start the pipeline, collect its output, and wait for all commands to finish.

The return value provides the standard output of the last command error as bytes or optionally strings, as well as the exit status of the last command.

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

impl Debug for Pipeline

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Clone for Pipeline

fn clone(&self) -> Pipeline

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl BitOr<Exec> for Pipeline

type Output = Pipeline

The resulting type after applying the | operator

fn bitor(self, rhs: Exec) -> Pipeline

The method for the | operator

impl BitOr for Pipeline

type Output = Pipeline

The resulting type after applying the | operator

fn bitor(self, rhs: Pipeline) -> Pipeline

The method for the | operator