Struct Loader 

pub struct Loader { /* private fields */ }

A living progress reveal.

Create one with Loader::new, advance it, and finish. Dropping the last handle finishes it for you, so the terminal is always restored. 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, 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 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 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.