streamweave-stdio

Standard I/O integration for StreamWeave
Read from stdin and write to stdout/stderr with StreamWeave pipelines.

The streamweave-stdio package provides producers and consumers for integrating StreamWeave with POSIX standard streams (stdin, stdout, stderr). It enables building command-line tools and interactive pipelines that process data from standard input and output results to standard output or error streams.

✨ Key Features

• StdinProducer: Read lines from standard input
• StdoutConsumer: Write items to standard output
• StderrConsumer: Write items to standard error
• Line-by-Line Processing: Process input line by line
• Interactive Pipelines: Build interactive command-line tools

📦 Installation

Add this to your Cargo.toml:

[dependencies]
streamweave-stdio = "0.3.0"

🚀 Quick Start

Basic Pipeline

use streamweave_stdio::{StdinProducer, StdoutConsumer};
use streamweave_pipeline::PipelineBuilder;

let pipeline = PipelineBuilder::new()
    .producer(StdinProducer::new())
    .transformer(/* your transformer */)
    .consumer(StdoutConsumer::new());

pipeline.run().await?;

Reading from Stdin

use streamweave_stdio::StdinProducer;

let producer = StdinProducer::new();
// Reads lines from stdin and produces them as String items

Writing to Stdout

use streamweave_stdio::StdoutConsumer;

let consumer = StdoutConsumer::new();
// Writes items to stdout

Writing to Stderr

use streamweave_stdio::StderrConsumer;

let consumer = StderrConsumer::new();
// Writes items to stderr (for error output)

📖 API Overview

StdinProducer

Reads lines from standard input:

pub struct StdinProducer {
    // Internal state
}

Key Methods:

• new() - Create new stdin producer
• produce() - Generate stream from stdin

StdoutConsumer

Writes items to standard output:

pub struct StdoutConsumer {
    // Internal state
}

Key Methods:

• new() - Create new stdout consumer
• consume(stream) - Write stream items to stdout

StderrConsumer

Writes items to standard error:

pub struct StderrConsumer {
    // Internal state
}

Key Methods:

• new() - Create new stderr consumer
• consume(stream) - Write stream items to stderr

📚 Usage Examples

Simple Echo Pipeline

Echo input to output:

use streamweave_stdio::{StdinProducer, StdoutConsumer};
use streamweave_pipeline::PipelineBuilder;

let pipeline = PipelineBuilder::new()
    .producer(StdinProducer::new())
    .consumer(StdoutConsumer::new());

pipeline.run().await?;

Transform and Output

Transform input before outputting:

use streamweave_stdio::{StdinProducer, StdoutConsumer};
use streamweave_pipeline::PipelineBuilder;
use streamweave_transformers::MapTransformer;

let pipeline = PipelineBuilder::new()
    .producer(StdinProducer::new())
    .transformer(MapTransformer::new(|line: String| {
        line.to_uppercase()
    }))
    .consumer(StdoutConsumer::new());

pipeline.run().await?;

Error Output

Write errors to stderr:

use streamweave_stdio::{StdinProducer, StderrConsumer};
use streamweave_pipeline::PipelineBuilder;

let pipeline = PipelineBuilder::new()
    .producer(StdinProducer::new())
    .transformer(/* filter errors */)
    .consumer(StderrConsumer::new());

pipeline.run().await?;

Interactive Processing

Process input interactively:

use streamweave_stdio::{StdinProducer, StdoutConsumer};
use streamweave_pipeline::PipelineBuilder;

// Process input as it arrives
let pipeline = PipelineBuilder::new()
    .producer(StdinProducer::new())
    .transformer(/* process each line */)
    .consumer(StdoutConsumer::new());

// Run interactively
pipeline.run().await?;

🏗️ Architecture

Standard I/O integration:

┌──────────┐
│  stdin   │───> StdinProducer ───> Stream ───> Transformer ───> Stream ───> StdoutConsumer ───> stdout
└──────────┘                                                                                      └──────────┘
                                                                                                  ┌──────────┐
                                                                                                  │  stderr  │
                                                                                                  └──────────┘

I/O Flow:

1. StdinProducer reads lines from stdin
2. Lines flow through transformers
3. StdoutConsumer writes to stdout
4. StderrConsumer writes to stderr (for errors)

🔧 Configuration

Producer Configuration

Configure stdin producer:

let producer = StdinProducer::new()
    .with_config(ProducerConfig::default()
        .with_name("stdin".to_string()));

Consumer Configuration

Configure stdout/stderr consumers:

let consumer = StdoutConsumer::new()
    .with_config(ConsumerConfig {
        error_strategy: ErrorStrategy::Skip,
        name: "stdout".to_string(),
    });

🔍 Error Handling

Standard I/O errors are handled through the error system:

use streamweave_error::ErrorStrategy;

let pipeline = PipelineBuilder::new()
    .with_error_strategy(ErrorStrategy::Skip)
    .producer(StdinProducer::new())
    .consumer(StdoutConsumer::new());

⚡ Performance Considerations

• Line Buffering: Input is read line by line
• Streaming: Output is streamed, not buffered
• Interactive: Suitable for interactive use
• Memory Efficient: Processes one line at a time

📝 Examples

For more examples, see:

• Standard I/O Example
• Command-Line Tools

🔗 Dependencies

streamweave-stdio depends on:

• streamweave - Core traits
• streamweave-error - Error handling
• streamweave-message (optional) - Message envelope support
• tokio - Async runtime
• futures - Stream utilities
• async-stream - Stream generation

🎯 Use Cases

Standard I/O is used for:

1. Command-Line Tools: Build CLI tools that process stdin/stdout
2. Interactive Pipelines: Process data interactively
3. Unix Pipelines: Integrate with Unix pipe operations
4. Text Processing: Process text streams line by line
5. Error Handling: Separate normal output from error output

📖 Documentation

• Full API Documentation
• Repository
• StreamWeave Main Documentation

🔗 See Also

• streamweave - Core traits
• streamweave-file - File I/O
• streamweave-pipeline - Pipeline API

🤝 Contributing

Contributions are welcome! Please see the Contributing Guide for details.

📄 License

This project is licensed under the CC BY-SA 4.0 license.