Crate command_stream 

command-stream

Modern shell command execution library with streaming, async iteration, and event support.

This library provides a Rust equivalent to the JavaScript command-stream library, offering powerful shell command execution with streaming capabilities.

Features

• Async command execution with tokio
• Streaming output via async iterators
• Event-based output handling (on, once, emit)
• Virtual commands for common operations (cat, ls, mkdir, etc.)
• Shell operator support (&&, ||, ;, |)
• Pipeline support with .pipe() method and Pipeline builder
• Global state management for shell settings
• cmd! macro for ergonomic command creation (similar to JS $ tagged template literals)
• Cross-platform support

Module Organization

The codebase follows a modular architecture similar to the JavaScript implementation:

• ansi - ANSI escape code handling utilities
• commands - Virtual command implementations
• events - Event emitter for stream events
• macros - The cmd! macro for ergonomic command creation
• pipeline - Pipeline execution support
• quote - Shell quoting utilities
• shell_parser - Shell command parsing
• state - Global state management
• stream - Async streaming and iteration support
• trace - Logging and tracing utilities
• utils - Command results and virtual command helpers

Quick Start

use command_stream::{run, cmd};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Execute a simple command
    let result = run("echo hello world").await?;
    println!("{}", result.stdout);

    // Using the cmd! macro (similar to JS $ tagged template)
    let name = "world";
    let result = cmd!("echo hello {}", name).await?;
    println!("{}", result.stdout);

    // Using pipelines
    use command_stream::Pipeline;
    let result = Pipeline::new()
        .add("echo hello world")
        .add("grep world")
        .run()
        .await?;

    Ok(())
}

Re-exports

pub use commands::CommandContext;

pub use commands::StreamChunk;

pub use shell_parser::needs_real_shell;

pub use shell_parser::parse_shell_command;

pub use shell_parser::ParsedCommand;

pub use utils::CommandResult;

pub use utils::VirtualUtils;

pub use ansi::AnsiConfig;

pub use ansi::AnsiUtils;

pub use events::EventData;

pub use events::EventType;

pub use events::StreamEmitter;

pub use pipeline::Pipeline;

pub use pipeline::PipelineBuilder;

pub use pipeline::PipelineExt;

pub use quote::quote;

pub use state::get_shell_settings;

pub use state::global_state;

pub use state::reset_global_state;

pub use state::set_shell_option;

pub use state::unset_shell_option;

pub use state::GlobalState;

pub use state::ShellSettings;

pub use stream::AsyncIterator;

pub use stream::IntoStream;

pub use stream::OutputChunk;

pub use stream::OutputStream;

pub use stream::StreamingRunner;

pub use trace::trace;

pub use run as execute;

Modules

ansi

ANSI control character utilities for command-stream

commands

Virtual command implementations

events

Event emitter for stream events

pipeline

Pipeline execution support

quote

Shell quoting utilities for command-stream

shell_parser

Enhanced shell command parser that handles &&, ||, ;, and () operators This allows virtual commands to work properly with shell operators

state

Global state management for command-stream

stream

Streaming and async iteration support

trace

Trace/logging utilities for command-stream

utils

Utility functions and types for command-stream

Macros

cmd

The cmd! macro for ergonomic shell command execution

cs

The cs! macro - alias for cmd!

s

The s! macro - short alias for cmd!

sh

The sh! macro - alias for cmd!

Structs

ProcessRunner

A running or completed process

RunOptions

Options for command execution

Enums

Error

Error type for command-stream operations

StdinOption

Standard input options

Functions

create

Create a new process runner without starting it

exec

Execute a command with custom options

run

Execute a command and return the result

run_sync

Execute a command synchronously (blocking)

Type Aliases

Result

Result type for command-stream operations