command-stream 0.9.0 → 0.9.2

package/rust/src/events.rs

@@ -0,0 +1,305 @@
+//! Event emitter for stream events
+//!
+//! This module provides an EventEmitter-like implementation for ProcessRunner
+//! events, similar to the JavaScript StreamEmitter class.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+
+use crate::trace::trace_lazy;
+
+/// Event types that can be emitted by ProcessRunner
+#[derive(Debug, Clone, Hash, Eq, PartialEq)]
+pub enum EventType {
+    /// Stdout data received
+    Stdout,
+    /// Stderr data received
+    Stderr,
+    /// Combined data event (contains type and data)
+    Data,
+    /// Process ended
+    End,
+    /// Process exited with code
+    Exit,
+    /// Error occurred
+    Error,
+    /// Process spawned
+    Spawn,
+}
+
+impl std::fmt::Display for EventType {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            EventType::Stdout => write!(f, "stdout"),
+            EventType::Stderr => write!(f, "stderr"),
+            EventType::Data => write!(f, "data"),
+            EventType::End => write!(f, "end"),
+            EventType::Exit => write!(f, "exit"),
+            EventType::Error => write!(f, "error"),
+            EventType::Spawn => write!(f, "spawn"),
+        }
+    }
+}
+
+/// Event data variants
+#[derive(Debug, Clone)]
+pub enum EventData {
+    /// String data (for stdout, stderr)
+    String(String),
+    /// Exit code
+    ExitCode(i32),
+    /// Data event with type and content
+    TypedData { data_type: String, data: String },
+    /// Command result
+    Result(crate::CommandResult),
+    /// Error message
+    Error(String),
+    /// No data
+    None,
+}
+
+/// Type alias for event listeners
+type Listener = Arc<dyn Fn(EventData) + Send + Sync>;
+
+/// Event emitter for ProcessRunner events
+///
+/// Provides on(), once(), off(), and emit() methods similar to Node.js EventEmitter.
+pub struct StreamEmitter {
+    listeners: RwLock<HashMap<EventType, Vec<Listener>>>,
+}
+
+impl Default for StreamEmitter {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl StreamEmitter {
+    /// Create a new event emitter
+    pub fn new() -> Self {
+        StreamEmitter {
+            listeners: RwLock::new(HashMap::new()),
+        }
+    }
+
+    /// Register a listener for an event
+    ///
+    /// # Arguments
+    /// * `event` - The event type to listen for
+    /// * `listener` - The callback function to invoke
+    ///
+    /// # Example
+    /// ```ignore
+    /// emitter.on(EventType::Stdout, |data| {
+    ///     if let EventData::String(s) = data {
+    ///         println!("Got stdout: {}", s);
+    ///     }
+    /// });
+    /// ```
+    pub async fn on<F>(&self, event: EventType, listener: F)
+    where
+        F: Fn(EventData) + Send + Sync + 'static,
+    {
+        trace_lazy("StreamEmitter", || {
+            format!("on() called for event: {}", event)
+        });
+
+        let mut listeners = self.listeners.write().await;
+        listeners
+            .entry(event)
+            .or_default()
+            .push(Arc::new(listener));
+    }
+
+    /// Register a one-time listener for an event
+    ///
+    /// The listener will be removed after it is invoked once.
+    pub async fn once<F>(&self, event: EventType, listener: F)
+    where
+        F: Fn(EventData) + Send + Sync + 'static,
+    {
+        trace_lazy("StreamEmitter", || {
+            format!("once() called for event: {}", event)
+        });
+
+        // Wrap the listener to track if it's been called
+        let called = Arc::new(std::sync::atomic::AtomicBool::new(false));
+        let called_clone = called.clone();
+
+        let once_listener = move |data: EventData| {
+            if !called_clone.swap(true, std::sync::atomic::Ordering::SeqCst) {
+                listener(data);
+            }
+        };
+
+        self.on(event, once_listener).await;
+    }
+
+    /// Emit an event to all registered listeners
+    ///
+    /// # Arguments
+    /// * `event` - The event type to emit
+    /// * `data` - The event data to pass to listeners
+    pub async fn emit(&self, event: EventType, data: EventData) {
+        let listeners = self.listeners.read().await;
+
+        if let Some(event_listeners) = listeners.get(&event) {
+            trace_lazy("StreamEmitter", || {
+                format!(
+                    "Emitting event {} to {} listeners",
+                    event,
+                    event_listeners.len()
+                )
+            });
+
+            for listener in event_listeners {
+                listener(data.clone());
+            }
+        }
+    }
+
+    /// Remove all listeners for an event
+    ///
+    /// # Arguments
+    /// * `event` - The event type to clear listeners for
+    pub async fn off(&self, event: EventType) {
+        trace_lazy("StreamEmitter", || {
+            format!("off() called for event: {}", event)
+        });
+
+        let mut listeners = self.listeners.write().await;
+        listeners.remove(&event);
+    }
+
+    /// Get the number of listeners for an event
+    pub async fn listener_count(&self, event: &EventType) -> usize {
+        let listeners = self.listeners.read().await;
+        listeners.get(event).map(|v| v.len()).unwrap_or(0)
+    }
+
+    /// Remove all listeners for all events
+    pub async fn remove_all_listeners(&self) {
+        trace_lazy("StreamEmitter", || "Removing all listeners".to_string());
+        let mut listeners = self.listeners.write().await;
+        listeners.clear();
+    }
+}
+
+impl std::fmt::Debug for StreamEmitter {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("StreamEmitter")
+            .field("listeners", &"<RwLock<HashMap<...>>>")
+            .finish()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicUsize, Ordering};
+
+    #[tokio::test]
+    async fn test_emit_basic() {
+        let emitter = StreamEmitter::new();
+        let counter = Arc::new(AtomicUsize::new(0));
+        let counter_clone = counter.clone();
+
+        emitter
+            .on(EventType::Stdout, move |_| {
+                counter_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter
+            .emit(EventType::Stdout, EventData::String("test".to_string()))
+            .await;
+
+        assert_eq!(counter.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn test_once() {
+        let emitter = StreamEmitter::new();
+        let counter = Arc::new(AtomicUsize::new(0));
+        let counter_clone = counter.clone();
+
+        emitter
+            .once(EventType::Exit, move |_| {
+                counter_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        // Emit twice
+        emitter.emit(EventType::Exit, EventData::ExitCode(0)).await;
+        emitter.emit(EventType::Exit, EventData::ExitCode(0)).await;
+
+        // Should only be called once
+        assert_eq!(counter.load(Ordering::SeqCst), 1);
+    }
+
+    #[tokio::test]
+    async fn test_off() {
+        let emitter = StreamEmitter::new();
+        let counter = Arc::new(AtomicUsize::new(0));
+        let counter_clone = counter.clone();
+
+        emitter
+            .on(EventType::Stdout, move |_| {
+                counter_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter.off(EventType::Stdout).await;
+        emitter
+            .emit(EventType::Stdout, EventData::String("test".to_string()))
+            .await;
+
+        assert_eq!(counter.load(Ordering::SeqCst), 0);
+    }
+
+    #[tokio::test]
+    async fn test_listener_count() {
+        let emitter = StreamEmitter::new();
+
+        assert_eq!(emitter.listener_count(&EventType::Stdout).await, 0);
+
+        emitter.on(EventType::Stdout, |_| {}).await;
+        assert_eq!(emitter.listener_count(&EventType::Stdout).await, 1);
+
+        emitter.on(EventType::Stdout, |_| {}).await;
+        assert_eq!(emitter.listener_count(&EventType::Stdout).await, 2);
+    }
+
+    #[tokio::test]
+    async fn test_multiple_events() {
+        let emitter = StreamEmitter::new();
+        let stdout_counter = Arc::new(AtomicUsize::new(0));
+        let stderr_counter = Arc::new(AtomicUsize::new(0));
+
+        let stdout_clone = stdout_counter.clone();
+        let stderr_clone = stderr_counter.clone();
+
+        emitter
+            .on(EventType::Stdout, move |_| {
+                stdout_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter
+            .on(EventType::Stderr, move |_| {
+                stderr_clone.fetch_add(1, Ordering::SeqCst);
+            })
+            .await;
+
+        emitter
+            .emit(EventType::Stdout, EventData::String("out".to_string()))
+            .await;
+        emitter
+            .emit(EventType::Stderr, EventData::String("err".to_string()))
+            .await;
+
+        assert_eq!(stdout_counter.load(Ordering::SeqCst), 1);
+        assert_eq!(stderr_counter.load(Ordering::SeqCst), 1);
+    }
+}

package/rust/src/lib.rs

@@ -9,40 +9,93 @@
 //!
 //! - 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
 //!
 //! ```rust,no_run
-//! use command_stream::run;
+//! 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(())
 //! }
 //! ```
 
+// Modular utility modules (following JavaScript modular pattern)
+pub mod ansi;
+pub mod events;
+#[doc(hidden)]
+pub mod macros;
+pub mod pipeline;
+pub mod quote;
+pub mod state;
+pub mod stream;
+pub mod trace;
+
+// Core modules
 pub mod commands;
 pub mod shell_parser;
 pub mod utils;
 
 use std::collections::HashMap;
-use std::env;
 use std::path::PathBuf;
 use std::process::Stdio;
-use std::sync::Arc;
 use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 use tokio::process::{Child, Command};
-use tokio::sync::{mpsc, Mutex};
+use tokio::sync::mpsc;
 
 pub use commands::{CommandContext, StreamChunk};
 pub use shell_parser::{parse_shell_command, needs_real_shell, ParsedCommand};
-pub use utils::{AnsiConfig, AnsiUtils, CommandResult, VirtualUtils, quote, trace};
+pub use utils::{CommandResult, VirtualUtils};
+
+// Re-export modular utilities at crate root for convenient access
+pub use ansi::{AnsiConfig, AnsiUtils};
+pub use events::{EventData, EventType, StreamEmitter};
+pub use pipeline::{Pipeline, PipelineExt, PipelineBuilder};
+pub use quote::quote;
+pub use state::{global_state, reset_global_state, get_shell_settings, set_shell_option, unset_shell_option, GlobalState, ShellSettings};
+pub use stream::{StreamingRunner, OutputStream, OutputChunk, AsyncIterator, IntoStream};
+pub use trace::trace;
 
 /// Error type for command-stream operations
 #[derive(Debug, thiserror::Error)]
@@ -66,21 +119,6 @@ pub enum Error {
 /// Result type for command-stream operations
 pub type Result<T> = std::result::Result<T, Error>;
 
-/// Shell settings for controlling execution behavior
-#[derive(Debug, Clone, Default)]
-pub struct ShellSettings {
-    /// Exit immediately if a command exits with non-zero status (set -e)
-    pub errexit: bool,
-    /// Print commands as they are executed (set -v)
-    pub verbose: bool,
-    /// Print trace of commands (set -x)
-    pub xtrace: bool,
-    /// Return value of a pipeline is the status of the last command to exit with non-zero (set -o pipefail)
-    pub pipefail: bool,
-    /// Treat unset variables as an error (set -u)
-    pub nounset: bool,
-}
-
 /// Options for command execution
 #[derive(Debug, Clone)]
 pub struct RunOptions {
@@ -179,8 +217,8 @@ impl ProcessRunner {
             return Ok(());
         }
 
-        // Parse command for shell operators
-        let parsed = if self.options.shell_operators && !needs_real_shell(&self.command) {
+        // Parse command for shell operators (for future use with virtual command pipelines)
+        let _parsed = if self.options.shell_operators && !needs_real_shell(&self.command) {
             parse_shell_command(&self.command)
         } else {
             None
@@ -364,6 +402,16 @@ impl ProcessRunner {
     pub fn result(&self) -> Option<&CommandResult> {
         self.result.as_ref()
     }
+
+    /// Get the command string
+    pub fn command(&self) -> &str {
+        &self.command
+    }
+
+    /// Get the options
+    pub fn options(&self) -> &RunOptions {
+        &self.options
+    }
 }
 
 /// Shell configuration
@@ -452,41 +500,4 @@ pub fn run_sync(command: impl Into<String>) -> Result<CommandResult> {
     rt.block_on(run(command))
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[tokio::test]
-    async fn test_simple_echo() {
-        let result = run("echo hello").await.unwrap();
-        assert!(result.is_success());
-        assert!(result.stdout.contains("hello"));
-    }
-
-    #[tokio::test]
-    async fn test_virtual_echo() {
-        let mut runner = ProcessRunner::new("echo test virtual", RunOptions::default());
-        let result = runner.run().await.unwrap();
-        assert!(result.is_success());
-        assert!(result.stdout.contains("test virtual"));
-    }
-
-    #[tokio::test]
-    async fn test_process_runner() {
-        let mut runner = ProcessRunner::new("echo hello world", RunOptions {
-            mirror: false,
-            ..Default::default()
-        });
-
-        let result = runner.run().await.unwrap();
-        assert!(result.is_success());
-    }
-
-    #[tokio::test]
-    async fn test_virtual_pwd() {
-        let mut runner = ProcessRunner::new("pwd", RunOptions::default());
-        let result = runner.run().await.unwrap();
-        assert!(result.is_success());
-        assert!(!result.stdout.is_empty());
-    }
-}
+// Tests are located in tests/ directory for better organization

package/rust/src/macros.rs

@@ -0,0 +1,165 @@
+//! Macros for ergonomic command execution
+//!
+//! This module provides command execution macros that offer a similar experience
+//! to JavaScript's `$` tagged template literal for shell command execution.
+//!
+//! ## Available Macros
+//!
+//! - `s!` - Short, concise macro (recommended for most use cases)
+//! - `sh!` - Shell macro (alternative short form)
+//! - `cmd!` - Command macro (explicit name)
+//! - `cs!` - Command-stream macro (another alternative)
+//!
+//! All macros are aliases and provide identical functionality.
+//!
+//! ## Usage
+//!
+//! ```rust,no_run
+//! use command_stream::s;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     // Simple command
+//!     let result = s!("echo hello world").await?;
+//!
+//!     // With interpolation (values are automatically quoted for safety)
+//!     let name = "John Doe";
+//!     let result = s!("echo Hello, {}", name).await?;
+//!
+//!     // Multiple arguments
+//!     let file = "test.txt";
+//!     let dir = "/tmp";
+//!     let result = s!("cp {} {}", file, dir).await?;
+//!
+//!     Ok(())
+//! }
+//! ```
+
+/// Build a shell command with interpolated values safely quoted
+///
+/// This function is used internally by the `cmd!` macro to build
+/// shell commands with properly quoted interpolated values.
+pub fn build_shell_command(parts: &[&str], values: &[&str]) -> String {
+    let mut result = String::new();
+
+    for (i, part) in parts.iter().enumerate() {
+        result.push_str(part);
+        if i < values.len() {
+            result.push_str(&crate::quote::quote(values[i]));
+        }
+    }
+
+    result
+}
+
+/// Helper function to create a ProcessRunner from a command string
+pub fn create_runner(command: String) -> crate::ProcessRunner {
+    crate::ProcessRunner::new(command, crate::RunOptions {
+        mirror: true,
+        capture: true,
+        ..Default::default()
+    })
+}
+
+/// Helper function to create a ProcessRunner with custom options
+pub fn create_runner_with_options(command: String, options: crate::RunOptions) -> crate::ProcessRunner {
+    crate::ProcessRunner::new(command, options)
+}
+
+/// The `cmd!` macro for ergonomic shell command execution
+///
+/// This macro provides a similar experience to JavaScript's `$` tagged template literal.
+/// Values interpolated into the command are automatically quoted for shell safety.
+///
+/// Note: Consider using the shorter `s!` or `sh!` aliases for more concise code.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// use command_stream::s;
+///
+/// # async fn example() -> Result<(), command_stream::Error> {
+/// // Simple command (returns a future that can be awaited)
+/// let result = s!("echo hello").await?;
+///
+/// // With string interpolation
+/// let name = "world";
+/// let result = s!("echo hello {}", name).await?;
+///
+/// // With multiple values
+/// let src = "source.txt";
+/// let dst = "dest.txt";
+/// let result = s!("cp {} {}", src, dst).await?;
+///
+/// // Values with special characters are automatically quoted
+/// let filename = "file with spaces.txt";
+/// let result = s!("cat {}", filename).await?; // Safely handles spaces
+/// # Ok(())
+/// # }
+/// ```
+///
+/// # Safety
+///
+/// All interpolated values are automatically quoted using shell-safe quoting,
+/// preventing command injection attacks.
+#[macro_export]
+macro_rules! cmd {
+    // No interpolation - just a plain command string
+    ($cmd:expr) => {{
+        async {
+            $crate::run($cmd).await
+        }
+    }};
+
+    // With format-style interpolation
+    ($fmt:expr, $($arg:expr),+ $(,)?) => {{
+        // Build command with quoted values
+        let mut result = String::new();
+        let values: Vec<String> = vec![$(format!("{}", $arg)),+];
+        let values_ref: Vec<&str> = values.iter().map(|s| s.as_str()).collect();
+        let fmt_parts: Vec<&str> = $fmt.split("{}").collect();
+        for (i, part) in fmt_parts.iter().enumerate() {
+            result.push_str(part);
+            if i < values_ref.len() {
+                result.push_str(&$crate::quote::quote(values_ref[i]));
+            }
+        }
+
+        async move {
+            $crate::run(result).await
+        }
+    }};
+}
+
+/// The `sh!` macro - alias for `cmd!`
+///
+/// This is an alternative name for `cmd!` that some users may find
+/// more intuitive for shell command execution.
+#[macro_export]
+macro_rules! sh {
+    ($($args:tt)*) => {
+        $crate::cmd!($($args)*)
+    };
+}
+
+/// The `s!` macro - short alias for `cmd!`
+///
+/// This is a concise alternative to `cmd!` for quick shell command execution.
+/// Recommended for use in documentation and examples.
+#[macro_export]
+macro_rules! s {
+    ($($args:tt)*) => {
+        $crate::cmd!($($args)*)
+    };
+}
+
+/// The `cs!` macro - alias for `cmd!`
+///
+/// Short for "command-stream", this provides another alternative
+/// for shell command execution.
+#[macro_export]
+macro_rules! cs {
+    ($($args:tt)*) => {
+        $crate::cmd!($($args)*)
+    };
+}