Struct subprocess::Pipeline

pub struct Pipeline { /* private fields */ }

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

impl Pipeline

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

Creates a new pipeline by combining two commands.

Equivalent to cmd1 | cmd2.

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.

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 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.

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

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.

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.

pub fn join(self) -> PopenResult<ExitStatus>

Starts the pipeline, waits for it to finish, and returns the exit status of the last command.

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().

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().

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.

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

impl BitOr<Exec> for Pipeline

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

Append a command to the pipeline and return a new pipeline.

type Output = Pipeline

The resulting type after applying the | operator.

impl BitOr<Pipeline> for Pipeline

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

Append a pipeline to the pipeline and return a new pipeline.

type Output = Pipeline

The resulting type after applying the | operator.

impl Clone for 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.

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

Performs copy-assignment from source.

impl Debug for Pipeline

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.