osc94 0.1.3

Library for handling progress bar sequences (OSC 9;4).
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
86
87
88
89
90
91
92
93
94
95
96
97

# osc94

[![GitHub License](https://img.shields.io/github/license/PRO-2684/osc94?logo=opensourceinitiative)](https://github.com/PRO-2684/osc94/blob/main/LICENSE)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/PRO-2684/osc94/release.yml?logo=githubactions)](https://github.com/PRO-2684/osc94/blob/main/.github/workflows/release.yml)
[![GitHub Release](https://img.shields.io/github/v/release/PRO-2684/osc94?logo=githubactions)](https://github.com/PRO-2684/osc94/releases)
[![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/PRO-2684/osc94/total?logo=github)](https://github.com/PRO-2684/osc94/releases)
[![Crates.io Version](https://img.shields.io/crates/v/osc94?logo=rust)](https://crates.io/crates/osc94)
[![Crates.io Total Downloads](https://img.shields.io/crates/d/osc94?logo=rust)](https://crates.io/crates/osc94)
[![docs.rs](https://img.shields.io/docsrs/osc94?logo=rust)](https://docs.rs/osc94)

Library for handling progress bar sequences (OSC 9;4).

## 💡 Example

```rust
# #[cfg(feature = "std")]
# {
use osc94::ProgressIteratorExt;

# fn work() {}
#
fn main() {
    for _ in (0..100).with_progress() {
        work();
    }
}
# }
```

We've got you covered if you want finer control. See more examples in the [examples directory](./examples/), or check out the usage section below.

## 📖 Usage

This library provides different levels of abstraction for working with progress bar sequences. From high-level to low-level:

1. [`ProgressIteratorExt`] and [`ProgressIter`]: Iterator adapters for automatic progress updates. Lives under [`iter.rs`](./src/iter.rs).
2. [`Progress`]: A struct that manages progress state and ensures proper cleanup when dropped. Lives under [`progress.rs`](./src/progress.rs).
3. [`OSC94`] and [`ProgressState`]: Low-level APIs for formatting progress sequences, giving you finer control over the output. Lives under [`raw.rs`](./src/raw.rs).

## 🚩 Feature flags

Default features include `std`.

| Feature | Default | Description                                                                                                  |
| ------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `std`   | Yes     | Enables [`Progress`] and iterator wrappers, which write progress sequences to `std::io::Write` destinations. |
| `cli`   | No      | Enables the `osc94` binary. This also enables `std`.                                                         |

Disable default features to use the crate in `no_std` contexts:

```toml
osc94 = { version = "0.1", default-features = false }
```

With default features disabled, [`OSC94`] and [`ProgressState`] remain available for formatting progress sequences, while [`Progress`] and iterator wrappers are not exported.

## 📥 Binary

The provided binary allows you to play with progress bar sequences:

```shell
$ osc94
Sets the progress state and value of the progress bar for 1 second.

Usage: osc94 <state> <progress>

States:
  0/hidden
  1/normal
  2/error
  3/indeterminate
  4/warning

Progress: 0-100
```

It can be installed via the following methods:

### Using [`binstall`](https://github.com/cargo-bins/cargo-binstall)

```shell
cargo binstall osc94
```

### Downloading from Releases

Navigate to the [Releases page](https://github.com/PRO-2684/osc94/releases) and download respective binary for your platform. Make sure to give it execute permissions.

### Compiling from Source

```shell
cargo install osc94 --features cli
```

## 🎉 Credits

- Microsoft Docs on [progress bar sequences](https://learn.microsoft.com/en-us/windows/terminal/tutorials/progress-bar-sequences) ([GitHub](https://github.com/MicrosoftDocs/terminal/blob/main/TerminalDocs/tutorials/progress-bar-sequences.md))