Struct shell_candy::ShellTask

pub struct ShellTask { /* private fields */ }

A ShellTask runs commands and provides a passthrough log handler for each log line.

Implementations

impl ShellTask

pub fn new(command: &str) -> Result<Self>

Create a new ShellTask with a log line handler.

pub fn env<K, V>(&mut self, key: K, value: V) -> &mut ShellTaskwhere
    K: AsRef<OsStr>,
    V: AsRef<OsStr>,

Adds an environment variable to the command run by ShellTask.

pub fn current_dir<P>(&mut self, path: P)where
    P: AsRef<Path>,

Sets the directory the command should be run in.

pub fn descriptor(&self) -> String

Returns the full command that was used to instantiate this ShellTask.

pub fn bash_descriptor(&self) -> String

Returns the ShellTask::descriptor with the classic $ shell prefix.

pub fn run<F, T>(&self, log_handler: F) -> Result<ShellTaskOutput<T>>where
    F: Fn(ShellTaskLog) -> ShellTaskBehavior<T> + Send + Sync + 'static,
    T: Send + Sync + 'static,

Run a ShellTask, applying the log handler to each line.

You can make the task terminate early if your log_handler returns ShellTaskBehavior::EarlyReturn<T>. When this variant is returned from a log handler, ShellTask::run will return Some<T>.

Example

use anyhow::anyhow;
use shell_candy::{ShellTask, ShellTaskLog, ShellTaskOutput, ShellTaskBehavior};

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    let result = ShellTask::new("rustc --version")?.run(|line| {
        match line {
            ShellTaskLog::Stderr(_) => {
                ShellTaskBehavior::Passthrough
            },
            ShellTaskLog::Stdout(message) => {
                eprintln!("{}", &message);
                ShellTaskBehavior::EarlyReturn(Ok(message))
            }
        }
    })?;
    assert!(matches!(result, ShellTaskOutput::EarlyReturn { .. }));
    Ok(())
}

If your log_handler returns ShellTaskBehavior::Passthrough for the entire lifecycle of the task, ShellTask::run will return ShellTaskOutput::CompleteOutput.

Example

use anyhow::anyhow;
use shell_candy::{ShellTask, ShellTaskLog, ShellTaskOutput, ShellTaskBehavior};

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    let result = ShellTask::new("rustc --version")?.run(|line| {
        match line {
            ShellTaskLog::Stderr(message) | ShellTaskLog::Stdout(message) => {
                eprintln!("info: {}", &message);
                ShellTaskBehavior::<()>::Passthrough
            }
        }
    })?;
    assert!(matches!(result, ShellTaskOutput::CompleteOutput { .. }));
    Ok(())
}

Trait Implementations

impl Debug for ShellTask

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

Formats the value using the given formatter.