red/README.md

# Red - Rust Stream Editor

An experimental drop-in replacement for GNU sed, written in Rust.

[![Crates.io](https://img.shields.io/crates/v/red-sed.svg)](https://crates.io/crates/red-sed)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg?logo=rust)](https://www.rust-lang.org/)
[![CI](https://github.com/vyavdoshenko/red/actions/workflows/ci.yml/badge.svg)](https://github.com/vyavdoshenko/red/actions/workflows/ci.yml)

---

## About This Project

This project started as an experiment to understand how far one can go in creating a Rust replacement for GNU sed.

**Functional Compatibility**: As far as I know, `red` currently achieves 100% functional compatibility with GNU sed behavior.

**Performance**: There's still work to be done on the performance front. For performance comparisons and benchmarks, please refer to the [Benchmarking](#benchmarking) section below.

**Documentation**: For usage instructions, please refer to the [GNU sed manual](https://www.gnu.org/software/sed/manual/). Red is designed to work exactly like GNU sed.

---

## Features

- **GNU sed Compatible**: Drop-in replacement for GNU sed
- **Cross-Platform**: Runs on Linux, macOS, and Windows
- **SELinux Support**: Preserves SELinux contexts during in-place editing (Linux)
- **Memory Safe**: Written in Rust
- **Full Command Support**: All GNU sed commands

---

## Command-Line Options

```
Usage: red [OPTION]... {SCRIPT} [FILE]...
       red [OPTION]... -e SCRIPT... -f FILE... [FILE]...

Options:
  -n, --quiet, --silent    suppress automatic printing of pattern space
  -e SCRIPT, --expression=SCRIPT
                           add the script to the commands to be executed
  -f FILE, --file=FILE     add the contents of script-file to the commands
  -i[SUFFIX], --in-place[=SUFFIX]
                           edit files in place (makes backup if SUFFIX supplied)
  -r, -E, --regexp-extended
                           use extended regular expressions
  -s, --separate           consider files as separate rather than continuous
  -l N, --line-length=N    specify line-wrap length for 'l' command
  -u, --unbuffered         load minimal amounts of data and flush output often
  -z, --null-data          use NUL character as line separator
      --posix              disable all GNU extensions
      --follow-symlinks    follow symlinks when processing in place
      --sandbox            disable e/r/w commands
      --help               display this help and exit
      --version            output version information and exit
```

---

## Architecture

Red uses a two-phase architecture:

1. **Compile Phase**: Parse and validate scripts once
2. **Execute Phase**: Apply commands to input data

For detailed documentation, see [ARCHITECTURE.md](ARCHITECTURE.md).

---

## Testing

### Running Tests

```bash
# Unit tests
cargo test

# Fetch GNU sed tests (required once)
./scripts/fetch_gnused_tests.sh

# GNU sed compatibility tests
./scripts/run_gnused_tests.sh

# Specific test
./scripts/run_gnused_tests.sh --test-pattern "help.sh"

# Fast mode
./scripts/run_gnused_tests.sh --fast
```

### Benchmarking

Compare performance with GNU sed:

```bash
# Install hyperfine
cargo install hyperfine

# Run benchmarks
./scripts/benchmark.sh

# Custom runs
RUNS=50 WARMUP=5 ./scripts/benchmark.sh

RED_BIN=./target/release/red SED_BIN=/usr/bin/sed ./scripts/benchmark.sh
```

---

## Development

### Building

```bash
# Debug build
cargo build

# Release build
cargo build --release

# Build with SELinux support (Linux only)
cargo build --release --features selinux
```

---

## Releases

### Download

Pre-built binaries are available on the [Releases](https://github.com/vyavdoshenko/red/releases) page:

| Platform | File | Notes |
|----------|------|-------|
| Linux x86_64 | `red-linux-x86_64-musl.tar.gz` | Static binary, works on any Linux |
| Linux ARM64 | `red-linux-aarch64-musl.tar.gz` | Static binary for ARM64 |
| Linux x86_64 + SELinux | `red-linux-x86_64-gnu-selinux.tar.gz` | For Fedora, RHEL, CentOS |
| Linux ARM64 + SELinux | `red-linux-aarch64-gnu-selinux.tar.gz` | ARM64 with SELinux |
| macOS Intel | `red-darwin-x86_64.tar.gz` | macOS 10.15+ |
| macOS Apple Silicon | `red-darwin-aarch64.tar.gz` | macOS 11+ (M1/M2/M3) |
| Windows | `red-windows-x86_64.zip` | Windows 10+ |

### Install

**From crates.io:**
```bash
cargo install red-sed
```

**Linux:**
```bash
curl -LO https://github.com/vyavdoshenko/red/releases/latest/download/red-linux-x86_64-musl.tar.gz
tar -xzf red-linux-x86_64-musl.tar.gz
sudo mv red /usr/local/bin/
```

**macOS:**
```bash
curl -LO https://github.com/vyavdoshenko/red/releases/latest/download/red-darwin-aarch64.tar.gz
tar -xzf red-darwin-aarch64.tar.gz
xattr -d com.apple.quarantine red   # Remove Gatekeeper quarantine
sudo mv red /usr/local/bin/
```

**Verify:**
```bash
red --version
```

### Creating a Release (Maintainers)

1. Update version in `red/Cargo.toml`
2. Commit changes
3. Create and push a tag:

```bash
git tag v1.0.0
git push origin v1.0.0
```

GitHub Actions will automatically build all platforms and create a release with artifacts.

Use `-` in tag for pre-releases (e.g., `v1.0.0-beta`).

---

## License

MIT