Struct grep_cli::CommandReader

pub struct CommandReader { /* fields omitted */ }

A streaming reader for a command's output.

The purpose of this reader is to provide an easy way to execute processes whose stdout is read in a streaming way while also making the processes' stderr available when the process fails with an exit code. This makes it possible to execute processes while surfacing the underlying failure mode in the case of an error.

Moreover, by default, this reader will asynchronously read the processes' stderr. This prevents subtle deadlocking bugs for noisy processes that write a lot to stderr. Currently, the entire contents of stderr is read on to the heap.

Example

This example shows how to invoke gzip to decompress the contents of a file. If the gzip command reports a failing exit status, then its stderr is returned as an error.

use std::io::Read;
use std::process::Command;
use grep_cli::CommandReader;

let mut cmd = Command::new("gzip");
cmd.arg("-d").arg("-c").arg("/usr/share/man/man1/ls.1.gz");

let mut rdr = CommandReader::new(&mut cmd)?;
let mut contents = vec![];
rdr.read_to_end(&mut contents)?;

Methods

impl CommandReader

pub fn new(cmd: &mut Command) -> Result<CommandReader, CommandError>

Create a new streaming reader for the given command using the default configuration.

The caller should set everything that's required on the given command before building a reader, such as its arguments, environment and current working directory. Settings such as the stdout and stderr (but not stdin) pipes will be overridden so that they can be controlled by the reader.

If there was a problem spawning the given command, then its error is returned.

If the caller requires additional configuration for the reader returned, then use CommandReaderBuilder.

Trait Implementations

impl Debug for CommandReader

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

Formats the value using the given formatter.

impl Read for CommandReader

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

🔬 This is a nightly-only experimental API. (io)

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

fn chain<R>(self, next: R) -> Chain<Self, R> where     R: Read,

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.