(hopefully) cute readme

master
Avril 4 years ago
parent 031935cf02
commit 69d1fe8afb
Signed by: flanchan
GPG Key ID: 284488987C31F630

@ -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<P: ProgressBar>(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

@ -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);

@ -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,
};
}

@ -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()
{
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");
}
}*/
fn default() -> Self
{
Self::new(50)
}
}
impl Bar
{

@ -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)

@ -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<T>(iter: T) -> Self
where T: IntoIterator<Item=char>
{
let col: Vec<char> = 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,

Loading…
Cancel
Save