Crate croshet 

croshet

A cross-platform UNIX-like shell scripting library, developed by pesde primarily to solve the annoying rimraf problem.

Examples

Shorthand macro

Execute a singular command, or run them in bulk without much control over how:

println!(
    "singular exec result: {}, bulk exec results: {:?}",
    sh!("echo hello, croshet!").await?,
    sh!["echo $(pwd)", "mkdir hi_mom", "rm -rf hi_mom", "exit 1"].await?
);

Manual execution

Lower level API to manually run commands with full control over the options and lifecycle of the process:

// Parse the text
let list = croshet::parser::parse(&text)?;
let kill_signal = KillSignal::default();

let options = croshet::ExecuteOptionsBuilder::new()
  .args(std::env::args_os().collect())          // Args to be passed to the shell itself
  .env_vars(std::env::vars_os().collect())      // Environment variables that are set globally
  .cwd(std::env::current_dir()?)                // The working directory of the shell process
  .custom_commands(...)                         // HashMap of custom commands to be defined
  .kill_signal(kill_signal.clone())             // Pass the kill signal to control termination fo the process
  .stdin(croshet::ShellPipeReader::stdin())     // The standard input pipe
  .stdout(croshet::ShellPipeWriter::stdout())   // The standard output pipe
  .stderr(croshet::ShellPipeWriter::stderr())   // The standard error pipe
  .build()?;

// Execute!
println!("Command exited with code: {}", croshet::execute(list.clone(), options.clone()).await);

// ...Or, execute with a timeout
// Set up a separate task to cancel the execution in 5s
tokio::task::spawn(async move {
    tokio::time::sleep(tokio::time::Duration::from_secs(5)).await;
    kill_signal.send(croshet::SignalKind::SIGKILL); 
});

let exit_code = croshet::execute(list, options).await;
println!("Command exited with code: {}", exit_code);

What’s with the name?

This project was initially forked from Deno’s deno_task_shell, which we found a bit too boring of a name :p

Instead, we settled for the name croshet, pronounced /kroʊˈʃeɪ/ (or simply, ‘crochet’), as the library “crochets together” several UNIX-y shell features (most POSIX sh and some bash features, common UNIX command line tools, etc.) with a bit of shell related flair.

Modules

parser

Macros

sh

Macro to simplify running command(s) without having to construct a SequentialList and pass options manually. The macro results in a Future returning a Result with an i32 or a Vec<i32> when executing in bulk. Sets the working directory to the process’ working directory.

Structs

Error

An error originating in croshet, wrapping around any dynamic error, including (but not limited to), command syntax parsing, execution, or standard library errors.

ExecutableCommand

Command that resolves the command name and executes it in a separate process.

ExecuteCommandArgsContext

ExecuteOptions

Options for executing a command or process.

ExecuteOptionsBuilder

Builder pattern constructor for ExecuteOptions.

KillSignal

Used to send signals to commands.

KillSignalDropGuard

Guard that on drop will send a signal on the associated KillSignal.

ShellCommandContext

ShellState

Enums

CommandPathResolutionError

Error when a command path could not be resolved.

EnvChange

ExecuteResult

ShellPipeReader

Reader side of a pipe.

ShellPipeWriter

Writer side of a pipe.

SignalKind

Traits

ShellCommand

Functions

execute

Executes a SequentialList of commands in a croshet environment.

pipe

Used to communicate between commands.

Type Aliases

Result