Struct Loader 

pub struct Loader { /* private fields */ }

A live progress reveal.

Create one with Loader::new, advance it, and finish. Dropping the last handle finishes it for you, and the terminal is restored on panic and on Ctrl+C too. Not Clone; for cross-thread updates take a Handle.

Implementations

impl Loader

pub fn new(total: u64) -> Self

A determinate loader for total units of work, using the built-in dragon.

Examples found in repository

examples/loader.rs (line 35)

fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("iter") => {
            for _ in (0..100).inkling() {
                work(20);
            }
        }
        Some("spinner") => {
            let loader = Loader::spinner();
            loader.set_message("Doing something mysterious");
            work(2500);
            loader.finish();
        }
        Some("threads") => {
            let loader = Loader::new(120);
            loader.set_message("Four workers, one dragon");
            thread::scope(|s| {
                for _ in 0..4 {
                    let handle = loader.handle();
                    s.spawn(move || {
                        for _ in 0..30 {
                            work(30);
                            handle.inc(1);
                        }
                    });
                }
            });
            loader.finish();
        }
        Some("rainbow") => {
            let loader = Loader::builder()
                .total(100)
                .style(inkling::render::Style::rainbow())
                .message("Tasting the rainbow")
                .start();
            for _ in 0..100 {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
        _ => {
            let total: u64 = 100;
            let loader = Loader::new(total);
            loader.set_message("Summoning the dragon");
            for _ in 0..total {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
    }
}

pub fn spinner() -> Self

An indeterminate loader (a spinner) for work whose length you do not know.

Examples found in repository

examples/loader.rs (line 29)

fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("iter") => {
            for _ in (0..100).inkling() {
                work(20);
            }
        }
        Some("spinner") => {
            let loader = Loader::spinner();
            loader.set_message("Doing something mysterious");
            work(2500);
            loader.finish();
        }
        Some("threads") => {
            let loader = Loader::new(120);
            loader.set_message("Four workers, one dragon");
            thread::scope(|s| {
                for _ in 0..4 {
                    let handle = loader.handle();
                    s.spawn(move || {
                        for _ in 0..30 {
                            work(30);
                            handle.inc(1);
                        }
                    });
                }
            });
            loader.finish();
        }
        Some("rainbow") => {
            let loader = Loader::builder()
                .total(100)
                .style(inkling::render::Style::rainbow())
                .message("Tasting the rainbow")
                .start();
            for _ in 0..100 {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
        _ => {
            let total: u64 = 100;
            let loader = Loader::new(total);
            loader.set_message("Summoning the dragon");
            for _ in 0..total {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
    }
}

pub fn builder() -> Builder

Configure a loader with custom art, ordering, style, easing, or message.

Examples found in repository

examples/loader.rs (line 51)

fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("iter") => {
            for _ in (0..100).inkling() {
                work(20);
            }
        }
        Some("spinner") => {
            let loader = Loader::spinner();
            loader.set_message("Doing something mysterious");
            work(2500);
            loader.finish();
        }
        Some("threads") => {
            let loader = Loader::new(120);
            loader.set_message("Four workers, one dragon");
            thread::scope(|s| {
                for _ in 0..4 {
                    let handle = loader.handle();
                    s.spawn(move || {
                        for _ in 0..30 {
                            work(30);
                            handle.inc(1);
                        }
                    });
                }
            });
            loader.finish();
        }
        Some("rainbow") => {
            let loader = Loader::builder()
                .total(100)
                .style(inkling::render::Style::rainbow())
                .message("Tasting the rainbow")
                .start();
            for _ in 0..100 {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
        _ => {
            let total: u64 = 100;
            let loader = Loader::new(total);
            loader.set_message("Summoning the dragon");
            for _ in 0..total {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
    }
}

examples/download.rs (line 94)

fn main() {
    let args: Vec<String> = std::env::args().skip(1).collect();
    let rainbow = args.iter().any(|a| a == "rainbow");
    let geodesic = args.iter().any(|a| a == "geodesic");
    let art_path = args.iter().find(|a| a.ends_with(".txt")).cloned();
    let started = Instant::now();
    let gold = Color::Rgb {
        r: 232,
        g: 180,
        b: 85,
    };

    // Clear to a fresh screen and print the tool banner.
    let _ = execute!(
        io::stdout(),
        Clear(ClearType::All),
        MoveTo(0, 0),
        Print("\r\n  "),
        SetForegroundColor(gold),
        Print("dragonctl"),
        ResetColor,
        Print("  v0.2.0\r\n\r\n")
    );

    step("\u{2713}", Color::Green, "Initializing demo environment");
    pause(450);
    step("\u{2713}", Color::Green, "Updating base image index");
    pause(500);
    step("\u{2193}", Color::Cyan, "Downloading base image");
    let _ = execute!(io::stdout(), Print("\r\n"));

    // The download itself, paced unevenly: a connect stall, a hiccup, a burst, a
    // mid stall, and a slow tail.
    let total: u64 = 48 * 1024 * 1024;
    let mb = 1024.0 * 1024.0;
    let schedule: &[(f64, u64)] = &[
        (0.0, 600),
        (5.0, 300),
        (8.0, 250),
        (8.0, 650),
        (16.0, 220),
        (27.0, 180),
        (38.0, 200),
        (45.0, 450),
        (56.0, 200),
        (67.0, 220),
        (78.0, 260),
        (87.0, 320),
        (93.0, 480),
        (97.0, 520),
        (100.0, 300),
    ];

    let style = if rainbow {
        Style::rainbow()
    } else {
        Style::default()
    };
    let mut builder = Loader::builder().total(total).style(style);
    if geodesic {
        builder = builder.ordering(Geodesic::default());
    }
    if let Some(path) = &art_path {
        let text = std::fs::read_to_string(path).unwrap_or_else(|e| {
            eprintln!("could not read {path}: {e}");
            std::process::exit(1);
        });
        builder = builder.art(inkling::Art::parse(&text));
    }
    let loader = builder.start();
    for &(percent, dwell) in schedule {
        let done = (percent / 100.0 * total as f64) as u64;
        loader.set(done);
        loader.set_message(format!(
            "dragon.iso   {:.1} / {:.1} MB",
            done as f64 / mb,
            total as f64 / mb
        ));
        pause(dwell);
    }
    loader.finish();

    // A finish that ties it together.
    let _ = execute!(io::stdout(), Print("\r\n"));
    step(
        "\u{2713}",
        Color::Green,
        "Verified checksum  sha256:a1b2c3d4e5",
    );
    pause(400);
    let _ = execute!(
        io::stdout(),
        Print("\r\n  "),
        SetForegroundColor(Color::Green),
        Print("Done"),
        ResetColor,
        Print(format!(
            " in {:.1}s. dragon.iso (48.0 MB) ready.\r\n\r\n",
            started.elapsed().as_secs_f64()
        ))
    );
    let _ = io::stdout().flush();
}

pub fn inc(&self, delta: u64)

Advance the position by delta.

Examples found in repository

examples/loader.rs (line 58)

fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("iter") => {
            for _ in (0..100).inkling() {
                work(20);
            }
        }
        Some("spinner") => {
            let loader = Loader::spinner();
            loader.set_message("Doing something mysterious");
            work(2500);
            loader.finish();
        }
        Some("threads") => {
            let loader = Loader::new(120);
            loader.set_message("Four workers, one dragon");
            thread::scope(|s| {
                for _ in 0..4 {
                    let handle = loader.handle();
                    s.spawn(move || {
                        for _ in 0..30 {
                            work(30);
                            handle.inc(1);
                        }
                    });
                }
            });
            loader.finish();
        }
        Some("rainbow") => {
            let loader = Loader::builder()
                .total(100)
                .style(inkling::render::Style::rainbow())
                .message("Tasting the rainbow")
                .start();
            for _ in 0..100 {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
        _ => {
            let total: u64 = 100;
            let loader = Loader::new(total);
            loader.set_message("Summoning the dragon");
            for _ in 0..total {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
    }
}

pub fn set(&self, pos: u64)

Set the absolute position.

Examples found in repository

examples/download.rs (line 108)

fn main() {
    let args: Vec<String> = std::env::args().skip(1).collect();
    let rainbow = args.iter().any(|a| a == "rainbow");
    let geodesic = args.iter().any(|a| a == "geodesic");
    let art_path = args.iter().find(|a| a.ends_with(".txt")).cloned();
    let started = Instant::now();
    let gold = Color::Rgb {
        r: 232,
        g: 180,
        b: 85,
    };

    // Clear to a fresh screen and print the tool banner.
    let _ = execute!(
        io::stdout(),
        Clear(ClearType::All),
        MoveTo(0, 0),
        Print("\r\n  "),
        SetForegroundColor(gold),
        Print("dragonctl"),
        ResetColor,
        Print("  v0.2.0\r\n\r\n")
    );

    step("\u{2713}", Color::Green, "Initializing demo environment");
    pause(450);
    step("\u{2713}", Color::Green, "Updating base image index");
    pause(500);
    step("\u{2193}", Color::Cyan, "Downloading base image");
    let _ = execute!(io::stdout(), Print("\r\n"));

    // The download itself, paced unevenly: a connect stall, a hiccup, a burst, a
    // mid stall, and a slow tail.
    let total: u64 = 48 * 1024 * 1024;
    let mb = 1024.0 * 1024.0;
    let schedule: &[(f64, u64)] = &[
        (0.0, 600),
        (5.0, 300),
        (8.0, 250),
        (8.0, 650),
        (16.0, 220),
        (27.0, 180),
        (38.0, 200),
        (45.0, 450),
        (56.0, 200),
        (67.0, 220),
        (78.0, 260),
        (87.0, 320),
        (93.0, 480),
        (97.0, 520),
        (100.0, 300),
    ];

    let style = if rainbow {
        Style::rainbow()
    } else {
        Style::default()
    };
    let mut builder = Loader::builder().total(total).style(style);
    if geodesic {
        builder = builder.ordering(Geodesic::default());
    }
    if let Some(path) = &art_path {
        let text = std::fs::read_to_string(path).unwrap_or_else(|e| {
            eprintln!("could not read {path}: {e}");
            std::process::exit(1);
        });
        builder = builder.art(inkling::Art::parse(&text));
    }
    let loader = builder.start();
    for &(percent, dwell) in schedule {
        let done = (percent / 100.0 * total as f64) as u64;
        loader.set(done);
        loader.set_message(format!(
            "dragon.iso   {:.1} / {:.1} MB",
            done as f64 / mb,
            total as f64 / mb
        ));
        pause(dwell);
    }
    loader.finish();

    // A finish that ties it together.
    let _ = execute!(io::stdout(), Print("\r\n"));
    step(
        "\u{2713}",
        Color::Green,
        "Verified checksum  sha256:a1b2c3d4e5",
    );
    pause(400);
    let _ = execute!(
        io::stdout(),
        Print("\r\n  "),
        SetForegroundColor(Color::Green),
        Print("Done"),
        ResetColor,
        Print(format!(
            " in {:.1}s. dragon.iso (48.0 MB) ready.\r\n\r\n",
            started.elapsed().as_secs_f64()
        ))
    );
    let _ = io::stdout().flush();
}

pub fn set_length(&self, total: u64)

Change the total amount of work.

pub fn set_message<S: Into<String>>(&self, msg: S)

Set a short caption shown beneath the art.

Examples found in repository

examples/loader.rs (line 30)

fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("iter") => {
            for _ in (0..100).inkling() {
                work(20);
            }
        }
        Some("spinner") => {
            let loader = Loader::spinner();
            loader.set_message("Doing something mysterious");
            work(2500);
            loader.finish();
        }
        Some("threads") => {
            let loader = Loader::new(120);
            loader.set_message("Four workers, one dragon");
            thread::scope(|s| {
                for _ in 0..4 {
                    let handle = loader.handle();
                    s.spawn(move || {
                        for _ in 0..30 {
                            work(30);
                            handle.inc(1);
                        }
                    });
                }
            });
            loader.finish();
        }
        Some("rainbow") => {
            let loader = Loader::builder()
                .total(100)
                .style(inkling::render::Style::rainbow())
                .message("Tasting the rainbow")
                .start();
            for _ in 0..100 {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
        _ => {
            let total: u64 = 100;
            let loader = Loader::new(total);
            loader.set_message("Summoning the dragon");
            for _ in 0..total {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
    }
}

examples/download.rs (lines 109-113)

fn main() {
    let args: Vec<String> = std::env::args().skip(1).collect();
    let rainbow = args.iter().any(|a| a == "rainbow");
    let geodesic = args.iter().any(|a| a == "geodesic");
    let art_path = args.iter().find(|a| a.ends_with(".txt")).cloned();
    let started = Instant::now();
    let gold = Color::Rgb {
        r: 232,
        g: 180,
        b: 85,
    };

    // Clear to a fresh screen and print the tool banner.
    let _ = execute!(
        io::stdout(),
        Clear(ClearType::All),
        MoveTo(0, 0),
        Print("\r\n  "),
        SetForegroundColor(gold),
        Print("dragonctl"),
        ResetColor,
        Print("  v0.2.0\r\n\r\n")
    );

    step("\u{2713}", Color::Green, "Initializing demo environment");
    pause(450);
    step("\u{2713}", Color::Green, "Updating base image index");
    pause(500);
    step("\u{2193}", Color::Cyan, "Downloading base image");
    let _ = execute!(io::stdout(), Print("\r\n"));

    // The download itself, paced unevenly: a connect stall, a hiccup, a burst, a
    // mid stall, and a slow tail.
    let total: u64 = 48 * 1024 * 1024;
    let mb = 1024.0 * 1024.0;
    let schedule: &[(f64, u64)] = &[
        (0.0, 600),
        (5.0, 300),
        (8.0, 250),
        (8.0, 650),
        (16.0, 220),
        (27.0, 180),
        (38.0, 200),
        (45.0, 450),
        (56.0, 200),
        (67.0, 220),
        (78.0, 260),
        (87.0, 320),
        (93.0, 480),
        (97.0, 520),
        (100.0, 300),
    ];

    let style = if rainbow {
        Style::rainbow()
    } else {
        Style::default()
    };
    let mut builder = Loader::builder().total(total).style(style);
    if geodesic {
        builder = builder.ordering(Geodesic::default());
    }
    if let Some(path) = &art_path {
        let text = std::fs::read_to_string(path).unwrap_or_else(|e| {
            eprintln!("could not read {path}: {e}");
            std::process::exit(1);
        });
        builder = builder.art(inkling::Art::parse(&text));
    }
    let loader = builder.start();
    for &(percent, dwell) in schedule {
        let done = (percent / 100.0 * total as f64) as u64;
        loader.set(done);
        loader.set_message(format!(
            "dragon.iso   {:.1} / {:.1} MB",
            done as f64 / mb,
            total as f64 / mb
        ));
        pause(dwell);
    }
    loader.finish();

    // A finish that ties it together.
    let _ = execute!(io::stdout(), Print("\r\n"));
    step(
        "\u{2713}",
        Color::Green,
        "Verified checksum  sha256:a1b2c3d4e5",
    );
    pause(400);
    let _ = execute!(
        io::stdout(),
        Print("\r\n  "),
        SetForegroundColor(Color::Green),
        Print("Done"),
        ResetColor,
        Print(format!(
            " in {:.1}s. dragon.iso (48.0 MB) ready.\r\n\r\n",
            started.elapsed().as_secs_f64()
        ))
    );
    let _ = io::stdout().flush();
}

pub fn position(&self) -> u64

The current position.

pub fn length(&self) -> u64

The total amount of work, or 0 when indeterminate.

pub fn elapsed(&self) -> Duration

Time since the loader started.

pub fn rate(&self) -> f64

Average units of work per second so far, or 0.0 before any time passes.

pub fn eta(&self) -> Option<Duration>

Estimated time remaining, from the average rate so far.

None for an indeterminate loader, before enough has happened to extrapolate from, or once the work is done.

pub fn handle(&self) -> Handle

A cheap, clonable, Send + Sync handle for reporting progress from other threads. Handles can update but not finish the loader.

Examples found in repository

examples/loader.rs (line 39)

fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("iter") => {
            for _ in (0..100).inkling() {
                work(20);
            }
        }
        Some("spinner") => {
            let loader = Loader::spinner();
            loader.set_message("Doing something mysterious");
            work(2500);
            loader.finish();
        }
        Some("threads") => {
            let loader = Loader::new(120);
            loader.set_message("Four workers, one dragon");
            thread::scope(|s| {
                for _ in 0..4 {
                    let handle = loader.handle();
                    s.spawn(move || {
                        for _ in 0..30 {
                            work(30);
                            handle.inc(1);
                        }
                    });
                }
            });
            loader.finish();
        }
        Some("rainbow") => {
            let loader = Loader::builder()
                .total(100)
                .style(inkling::render::Style::rainbow())
                .message("Tasting the rainbow")
                .start();
            for _ in 0..100 {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
        _ => {
            let total: u64 = 100;
            let loader = Loader::new(total);
            loader.set_message("Summoning the dragon");
            for _ in 0..total {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
    }
}

pub fn wrap_read<R: Read>(&self, reader: R) -> ProgressReader<R>

Wrap a reader so every byte read advances the loader. Ideal for downloads: set the length to the content length, then read through the wrapper.

pub fn suspend<T>(&self, f: impl FnOnce() -> T) -> T

Lift the art out of the way, run f, and let the reveal redraw beneath whatever it printed.

Without this, anything your program writes to the terminal lands in the middle of the block and desynchronises the renderer, which is tracking where its own output sits. Use it for any logging you want interleaved with a live reveal.

let loader = Loader::new(3);
loader.suspend(|| eprintln!("something worth saying"));

pub fn println<S: AsRef<str>>(&self, line: S)

Print a line above the reveal, which then redraws beneath it.

Shorthand for suspend around a println!.

pub fn finish(&self)

Fill the art, leave it on screen, and restore the terminal.

Examples found in repository

examples/loader.rs (line 32)

fn main() {
    match std::env::args().nth(1).as_deref() {
        Some("iter") => {
            for _ in (0..100).inkling() {
                work(20);
            }
        }
        Some("spinner") => {
            let loader = Loader::spinner();
            loader.set_message("Doing something mysterious");
            work(2500);
            loader.finish();
        }
        Some("threads") => {
            let loader = Loader::new(120);
            loader.set_message("Four workers, one dragon");
            thread::scope(|s| {
                for _ in 0..4 {
                    let handle = loader.handle();
                    s.spawn(move || {
                        for _ in 0..30 {
                            work(30);
                            handle.inc(1);
                        }
                    });
                }
            });
            loader.finish();
        }
        Some("rainbow") => {
            let loader = Loader::builder()
                .total(100)
                .style(inkling::render::Style::rainbow())
                .message("Tasting the rainbow")
                .start();
            for _ in 0..100 {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
        _ => {
            let total: u64 = 100;
            let loader = Loader::new(total);
            loader.set_message("Summoning the dragon");
            for _ in 0..total {
                work(20);
                loader.inc(1);
            }
            loader.finish();
        }
    }
}

examples/download.rs (line 116)

fn main() {
    let args: Vec<String> = std::env::args().skip(1).collect();
    let rainbow = args.iter().any(|a| a == "rainbow");
    let geodesic = args.iter().any(|a| a == "geodesic");
    let art_path = args.iter().find(|a| a.ends_with(".txt")).cloned();
    let started = Instant::now();
    let gold = Color::Rgb {
        r: 232,
        g: 180,
        b: 85,
    };

    // Clear to a fresh screen and print the tool banner.
    let _ = execute!(
        io::stdout(),
        Clear(ClearType::All),
        MoveTo(0, 0),
        Print("\r\n  "),
        SetForegroundColor(gold),
        Print("dragonctl"),
        ResetColor,
        Print("  v0.2.0\r\n\r\n")
    );

    step("\u{2713}", Color::Green, "Initializing demo environment");
    pause(450);
    step("\u{2713}", Color::Green, "Updating base image index");
    pause(500);
    step("\u{2193}", Color::Cyan, "Downloading base image");
    let _ = execute!(io::stdout(), Print("\r\n"));

    // The download itself, paced unevenly: a connect stall, a hiccup, a burst, a
    // mid stall, and a slow tail.
    let total: u64 = 48 * 1024 * 1024;
    let mb = 1024.0 * 1024.0;
    let schedule: &[(f64, u64)] = &[
        (0.0, 600),
        (5.0, 300),
        (8.0, 250),
        (8.0, 650),
        (16.0, 220),
        (27.0, 180),
        (38.0, 200),
        (45.0, 450),
        (56.0, 200),
        (67.0, 220),
        (78.0, 260),
        (87.0, 320),
        (93.0, 480),
        (97.0, 520),
        (100.0, 300),
    ];

    let style = if rainbow {
        Style::rainbow()
    } else {
        Style::default()
    };
    let mut builder = Loader::builder().total(total).style(style);
    if geodesic {
        builder = builder.ordering(Geodesic::default());
    }
    if let Some(path) = &art_path {
        let text = std::fs::read_to_string(path).unwrap_or_else(|e| {
            eprintln!("could not read {path}: {e}");
            std::process::exit(1);
        });
        builder = builder.art(inkling::Art::parse(&text));
    }
    let loader = builder.start();
    for &(percent, dwell) in schedule {
        let done = (percent / 100.0 * total as f64) as u64;
        loader.set(done);
        loader.set_message(format!(
            "dragon.iso   {:.1} / {:.1} MB",
            done as f64 / mb,
            total as f64 / mb
        ));
        pause(dwell);
    }
    loader.finish();

    // A finish that ties it together.
    let _ = execute!(io::stdout(), Print("\r\n"));
    step(
        "\u{2713}",
        Color::Green,
        "Verified checksum  sha256:a1b2c3d4e5",
    );
    pause(400);
    let _ = execute!(
        io::stdout(),
        Print("\r\n  "),
        SetForegroundColor(Color::Green),
        Print("Done"),
        ResetColor,
        Print(format!(
            " in {:.1}s. dragon.iso (48.0 MB) ready.\r\n\r\n",
            started.elapsed().as_secs_f64()
        ))
    );
    let _ = io::stdout().flush();
}

pub fn finish_and_clear(&self)

Finish and erase the art from the screen.

Trait Implementations

impl Drop for Loader

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.