rusty-pv 0.1.0

Pipe viewer — a Rust port of Andrew Wood's `pv(1)` with progress bar, ETA, rate display, token-bucket rate limiting, IEC/SI unit math, SIGWINCH-aware terminal redraw, SIGUSR1 size refresh, multi-instance cursor coordination, and a typed library API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# rusty-pv

[![crates.io](https://img.shields.io/crates/v/rusty-pv.svg)](https://crates.io/crates/rusty-pv)
[![docs.rs](https://docs.rs/rusty-pv/badge.svg)](https://docs.rs/rusty-pv)
[![license: MIT OR Apache-2.0](https://img.shields.io/crates/l/rusty-pv.svg)](#license)

Pipe viewer. A Rust port of [Andrew Wood's `pv(1)`](https://www.ivarch.com/programs/pv.shtml) — show progress, elapsed time, ETA, rate, and bytes transferred while data flows through a pipe.

Part of the [Rusty portfolio](https://jsh562.github.io/rusty-portfolio).

## Install

```sh
cargo install rusty-pv
# or, with prebuilt binaries:
cargo binstall rusty-pv
```

## Usage

```sh
# Show progress copying a file
rusty-pv ubuntu.iso > /dev/sdb

# Throttle to 5 MiB/s
rusty-pv -L 5M big.iso > out.iso

# Pipe through with a labelled progress line
some-cmd | rusty-pv -N "stage 1" | another-cmd

# Numeric mode for dialog --gauge integration
rusty-pv -n -s 100M big.iso > out.iso
```

## Cargo Features

| Feature | Default | What it gates |
|---|---|---|
| `cli` | yes | `clap` + `clap_complete` + `anyhow` + `crossterm` + `signal-hook` (Unix) + `fd-lock` |

Library consumers can use `rusty-pv = { version = "0.1", default-features = false }` to get the throttle, EMA, and unit-suffix math without any CLI dependencies.

## Library API

```rust,no_run
use rusty_pv::{Pv, PvBuilder};
use std::io::Cursor;

let pv = PvBuilder::new()
    .total_bytes(1024 * 1024)
    .rate_limit(500_000) // 500 kB/s
    .build();
let mut reader = Cursor::new(vec![0u8; 1024 * 1024]);
let mut writer = Vec::new();
let n = pv.copy(&mut reader, &mut writer).unwrap();
assert_eq!(n, 1024 * 1024);
```

## Compatibility

`rusty-pv` has two modes:

- **Default** — clap-styled flag parser; rejects conflicting flag pairs at parse time; adds `--help`, `--version`, `completions` subcommand.
- **Strict** (`--strict`, env `RUSTY_PV_STRICT=1`, or argv[0] = `pv`/`pv-alias`) — byte-equal stderr against upstream v1.10.5 for documented diagnostics; last-wins flag resolution; no subcommands.

v0.1.0 excludes: `-F` (custom format strings), `-T` (buffer percentage), `-A` (peek window), `--bits`, `--remote`/`--query` inter-instance control, SIGUSR2 (deprecated by upstream).

The EMA smoothing constant α = 0.3 is **locked at v0.1.0** to preserve byte-equal Strict-mode compatibility; future versions may expose it via an additive library method.

## Display modes

- **Single-line redraw** (default) — carriage-return + erase-to-EOL ANSI sequence; works on every terminal that supports basic ANSI.
- **Cursor mode (`-c`)** — Unix-only in v0.1.0. Coordinates multiple `rusty-pv` instances in a pipeline so each writes to its own row. Windows emits a stderr diagnostic and falls back to single-line redraw.

## Concurrency

The `-c` per-tty file lock guarantees only one `rusty-pv` instance writes ANSI cursor escapes at a time, but the cursor-mode design is not crash-safe — if a `rusty-pv` instance is killed mid-redraw the next surviving instance may briefly overwrite its row. This matches upstream `pv` behavior.

## MSRV

Rust 1.85 (edition 2024). Re-verified against stable-minus-two policy at each release.

## License

Dual-licensed under [MIT](LICENSE) or [Apache-2.0](LICENSE-APACHE).