From 69d1fe8afb0daf2009a936f7501e36e3c46724fc Mon Sep 17 00:00:00 2001 From: Avril Date: Fri, 24 Jul 2020 03:02:33 +0100 Subject: [PATCH] (hopefully) cute readme --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++ src/inter.rs | 4 +-- src/lib.rs | 11 ++++-- src/progress.rs | 49 +++++++++++++-------------- src/spinner.rs | 52 +++++++++++++++-------------- src/wheel.rs | 9 +++++ 6 files changed, 158 insertions(+), 56 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1b4fc8a --- /dev/null +++ b/README.md @@ -0,0 +1,89 @@ +# Termprogress - Terminal progress bars +Simple and customiseable terminal progress bars for Rust. + +## Features + + - Customiseable, has a traits system to allow for passing any type of progress bar around + - Prevents long titles from overflowing the terminal by using the [terminal_size][terminal-size] crate + - Interfaces for easily manipulating bar + +[terminal-size]: https://crates.io/crates/terminal_size + +## How it looks + +The bar at 50, 75, and 100%: + +``` shell +[========================= ]: 50.00% some title +[===================================== ]: 75.00% some other title +[==================================================]: 100.00% some other title +``` + +The spinner in 4 stages: + +``` shell +Some title / +Some title - +Some title \ +Some title | +``` + +## Getting started. +To quickly use the default bar and spinner, you can include the `prelude`: + +``` rust +use termprogress::prelude::*; + +let mut progress = Bar::default(); // Create a new progress bar + +progress.set_title("Work is being done..."); +/// *does work* +progress.set_progress(0.25); +progress.set_progress(0.5); +progress.println("Something happened"); +progress.set_progress(0.75); +progress.println("Almost done..."); +progress.set_progress(1.0); + +/// completes +progress.complete(); +``` + +Spinner: + +``` rust +use termprogress::prelude::*; + +let mut spinner = Spin::default(); //Create a new spinner +/// *does work* +spinner.bump(); +spinner.bump(); +progress.println("Something happened"); +spinner.bump(); +spinner.bump(); + +/// completes +progress.complete_with("Done!"); +``` + +## Traits +The library comes with traits for progress bars: `[ProgressBar][progress-bar]`, and `[Spinner][spinner]`. + +The default implementations for these are `Bar` and `Spin`, but you can provide your own implementations too for more customisability + +``` rust +pub fn does_work(bar: &mut P) +{ + //does work... + bar.set_progress(0.5); + //more work... + bar.set_progress(1.0); +} + +does_work(&mut Bar::default()); +does_work(&mut MyBar::new()); +``` + +## License +GPL'd with love <3 + diff --git a/src/inter.rs b/src/inter.rs index 0c12f1d..d1f9665 100644 --- a/src/inter.rs +++ b/src/inter.rs @@ -22,14 +22,14 @@ pub trait Display fn update_dimensions(&mut self, to: usize); } -/// A bar with progress +/// A trait for any bar with progress. You can implemnent your own styles through this trait. pub trait ProgressBar: Display { fn set_progress(&mut self, value: f64); fn get_progress(&self) -> f64; } -/// A bar without progress +/// A trait for any bar without progress. You can implemnent your own styles through this trait. pub trait Spinner: Display { fn bump(&mut self); diff --git a/src/lib.rs b/src/lib.rs index 282bf85..38ea3b3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,11 +12,16 @@ macro_rules! flush { mod util; mod inter; pub use inter::*; + pub mod progress; pub mod wheel; pub mod spinner; -#[cfg(test)] -mod tests { - +/// The prelude exposes the traits for spinners and progress bars, and the `spinner::Spin` and `progress::Bar` types for easy access and use. +pub mod prelude { + pub use super::inter::*; + pub use super::{ + spinner::Spin, + progress::Bar, + }; } diff --git a/src/progress.rs b/src/progress.rs index 84f53d0..2b2460d 100644 --- a/src/progress.rs +++ b/src/progress.rs @@ -1,8 +1,26 @@ +///! Progress bar that has a size and also a max size. + use super::*; use std::{ fmt::Write, }; +/// A progress bar with a size and optionally title. It implements the `ProgressBar` trait, and is the default progress bar. +/// +/// The bar has a max size, that is usually derived from the size of your terminal (if it can be detected) or can be set yourself, to stop the title line going over the side. +/// It also has a configurable width, which is defaulted to 50. +/// +/// # Usage +/// +/// To create a new `progress::Bar` with a max size tuned to your terminal (or `Width+20`, if it cannot be detected), and of the default size, `Bar` implements the `Default` trait: +/// ```rust +/// let mut bar = Bar::default(); //Creates a bar of width 50 by default. +/// ``` +/// +/// You can configure sizes and initial title with `new()`, `with_title()`, and `with_max()` functions. +/// # How it looks +/// It renders in the terminal like: +/// `[========================= ]: 50% this is a title that may get cut if it reaches max le...` #[derive(Debug)] pub struct Bar { @@ -13,34 +31,13 @@ pub struct Bar title: String, } -/* -#[cfg(test)] -mod tests +impl Default for Bar { - #[test] - fn display() + fn default() -> Self { - - let mut bar = Bar::new(50); - bar.set_title("hello world"); - bar.progress = 0.455456749849; - bar.update(); - bar.refresh(); - bar.progress = 0.8; - bar.update(); - bar.refresh(); - bar.progress = 0.88; - bar.update(); - bar.refresh(); - bar.set_title("almost AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"); - bar.progress = 0.99554; - bar.update(); - bar.refresh(); - - println!("\nuhh"); - panic!("h"); - } -}*/ + Self::new(50) + } +} impl Bar { diff --git a/src/spinner.rs b/src/spinner.rs index 1483ef5..b13a518 100644 --- a/src/spinner.rs +++ b/src/spinner.rs @@ -1,5 +1,21 @@ +///! A simple character spinner for bars with no known size + use super::*; +/// A single character spinner with optional title that can be told to spin whenever it wants. It implements `Spinner` trait, and is the default spinner. +/// +/// The spinner takes up a line, and renders it's spinner on the end of its title. Calling the `Spinner::bump()` function will cause the character sequence to advance. +/// +/// # Usage +/// To use the spinner you can provide it a `Wheel` (see [[wheel]] module), or it implements the `Default` trait, creating a traditional looking spinner (`|/-\`) +/// +/// ```rust +/// let mut spin = Spin::default(); //Default new spinner without a title. +/// ``` +/// +/// # How it looks +/// It renders in the terminal like: +/// `This is a spinner /` pub struct Spin { title: String, @@ -9,7 +25,9 @@ pub struct Spin impl Spin { - /// Create a new spinner with title + /// Create a new spinner with title and wheel. + /// + /// To give it the default wheel, you can pass `whl` `Default::default()` to use the default one. pub fn with_title(title: &str, whl: wheel::Wheel) -> Self { let mut chars = whl.into_iter(); @@ -20,7 +38,12 @@ impl Spin chars, } } - /// Create a new blank spinner + /// Create a new blank spinner with a wheel + /// + /// # Example + /// ```rust + /// Spin::new(Default::default()); // Create a spinner with the default wheel ('|/-\') + /// ``` pub fn new(whl: wheel::Wheel) -> Self { let mut chars = whl.into_iter(); @@ -32,12 +55,12 @@ impl Spin } } - /// Consume the spinner and complete it + /// Consume the spinner and complete it. Removes the spin character. pub fn complete(self) { println!("{} ", (8u8 as char)); } - /// Consume the spinner and complete it with a message + /// Consume the spinner and complete it with a message. Removes the spin character and then prints the message. pub fn complete_with(self, msg: &str) { println!("{}{}", (8u8 as char), msg); @@ -56,27 +79,6 @@ impl Default for Spin } } -/* -#[cfg(test)] -mod tests -{ - #[test] - fn test() - { - const MAX: usize = 1000000; - let mut spin = Spin::with_title("Working maybe...", Default::default()); - for i in 0..=MAX - { - spin.bump(); - if i == MAX / 2 { - spin.set_title("Working more..."); - } - } - spin.complete_with("OK"); - println!("Oke"); - } -}*/ - impl Display for Spin { fn refresh(&self) diff --git a/src/wheel.rs b/src/wheel.rs index ad5e278..aeeb9ca 100644 --- a/src/wheel.rs +++ b/src/wheel.rs @@ -1,4 +1,8 @@ +///! Contains infinite `char` iterators and the type wrapping them, `Wheel`. +/// An infinite repeating series of `char`. Used for `spinner::Spin`. +/// +/// It implements the `IntoIterator` trait, yielding an infinite iterator of a repeating series of `char`s. #[derive(Clone,Debug)] pub enum Wheel { @@ -8,12 +12,15 @@ pub enum Wheel impl Wheel { + /// Create a new spinner out of an interator of `char`. pub fn new(iter: T) -> Self where T: IntoIterator { let col: Vec = iter.into_iter().collect(); Self::Dynamic(col.into_boxed_slice()) } + + /// Get a reference to all the possible chars of this wheel. pub fn chars(&self) -> &[char] { match &self @@ -34,6 +41,8 @@ impl Default for Wheel const DEFAULT_WHEEL: Wheel = Wheel::Static(&['/', '-', '\\', '|']); +/// An infinite iterator of a repeating series of `char`s, used for `spinner::Spin` +#[derive(Debug, Clone)] pub struct WheelIntoIter { source: Wheel,