rattles 0.2.1

A collection of terminal spinners
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# 🪇 Rattles

![Demo](./.github/assets/demo.gif)

**Rattles** is a terminal spinner library for Rust with an extensive preset collection and lets you define custom spinners at compile time.

- **Rattles** is *compile-time first*; all spinner data is baked in at compile time aiming for minimal overhead.

- **Rattles** is *minimal*; it makes no assumptions about how the output will be used, and just works with no prior configuration required. It also has zero dependencies.

## Philosophy

Most spinner libraries are built as actors or widgets. Rattles is neither. It has no runtime, no lifecycle, and requires no integration by default.

Spinners can be constructed directly in the render loop with negligible cost. The result is a library that gets out of your way.

## Quick Start

```sh
cargo add rattles
```

### Basic usage

```rust
use std::{io::Write, time::Duration};
use rattles::presets::prelude as presets;

fn main() {
    let rattle = presets::waverows();

    // change default interval
    // let rattle = presets::waverows().set_interval(Duration::from_millis(100));

    // reverse direction
    // let rattle = presets::waverows().reverse();

    loop {
        print!("\r{}", rattle.current_frame());
        std::io::stdout().flush().unwrap();
        std::thread::sleep(Duration::from_millis(20));
    }
}
```

### Custom keyframes

```rust
rattle!(
    Custom, // struct name
    custom, // method name
    1,      // row count (width of the spinner)
    100,    // interval in milliseconds
    ["⣾", "⣷", "⣯", "⣟", "⣻", "⣽", "⣾"] // keyframes
)
```

### `no_std`

`rattles` enables the `std` feature by default. To opt out:

```sh
cargo add rattles --no-default-features
```

Without `std`, the global clock is unavailable. Animations can still be driven three ways:

- Time-based, with an external clock: 
    ```rs
    rattle.frame_at(elapsed)
    ```
- Index-based:
    ```rs
    rattle.frame(n)
    ```
- Tick-based:
    ```rust
    let mut rattle = presets::dots().into_ticked();
    rattle.tick();
    let frame = rattle.current_frame();
    ```
    Note that `TickedRattler` is stateful and must be stored.

## Presets

Built-in presets are organized by category:

- `presets::arrows`
- `presets::ascii`
- `presets::braille`
- `presets::emoji`

A prelude is available `rattles::presets::prelude`.

## Examples

Example showcasing all presets, built with [ratatui](https://ratatui.rs/):

```bash
cargo run --example showcase
```

There's also a minimal no_std-oriented usage example found [here](./examples/no_std.rs), including:

- `TickedRattler` usage via `into_ticked()`
- elapsed-time driven usage via `frame_at(...)`
- index-driven usage via `frame(...)`

## Acknowledgements

- [sindresorhus/cli-spinners](https://github.com/sindresorhus/cli-spinners)
- [gunnargray-dev/unicode-animations](https://github.com/gunnargray-dev/unicode-animations)