tty-progressbar 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2eaaf2c7343d9acdfb829ee31ce58673a0e57874
-  data.tar.gz: 6b7b3f3e8ccef0d0ce4eadb728404b11113330b3
+  metadata.gz: 11bc77d708ba9f54e6efc5870c1865ce8937a0fc
+  data.tar.gz: 64d970dec5a9324a5639c5713ab922447afbb1b8
 SHA512:
-  metadata.gz: c51b18a4f26219bf19628fd1c406e2cfd94d6857fb236c304a535a68723828b21e86f851d8ef524453c77761cada81e1804162d5278f06149921b31c66964ffe
-  data.tar.gz: b6b3f6800919a9b5dbc31edf85b35c23da38760c3dd580aa611febd0870fa42424bfcb7e44b61dbdd7a14d02d08f05ccd915fb1e5a4e1399b3840e33897c1c1d
+  metadata.gz: 01ac6ab2668fea2bec216aa095e226e1c08ef388e442ddbe9a72c9772cf19f749a93e54085a5fac9488fc65c5c363e9f4500f2c4f4d01194abc571885ae47ac2
+  data.tar.gz: 81c443f7bf90e2f14a4ae9cd44e8fb5ea180598cae273000e4b5b335b0302cb911dbf84c440f5559bb5e8b8cd890e12378a32d8a5280a499f51e40b2edc3deab

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Change log
 
+## [v0.12.0] - 2017-09-03
+
+### Added
+* Add :head option to allow changing bar head progression character
+* Add thread safety to allow sharing progress between multiple threads
+* Add #update to allow changing bar configuration options
+* Add #stop to stop bar in current position and terminate any further progress
+* Add #iterate to progress over a collection
+* Add validation to check if bar formatting string is provided
+* Add ability to listen for completion events such as :done, :progress and :stopped
+* Add TTY::ProgressBar::Multi for creating parallel multiple progress bars
+
+### Changed
+* Change to stop mutating strings
+* Change #reset to stop drawing and use for initialization
+
+### Fixed
+* Fix configuration to add interval option
+
 ## [v0.11.0] - 2017-04-04
 
 ### Added
@@ -108,6 +127,7 @@
 
 * Initial implementation and release
 
+[v0.12.0]: https://github.com/peter-murach/tty-progressbar/compare/v0.11.0...v0.12.0
 [v0.11.0]: https://github.com/peter-murach/tty-progressbar/compare/v0.10.1...v0.11.0
 [v0.10.1]: https://github.com/peter-murach/tty-progressbar/compare/v0.10.0...v0.10.1
 [v0.10.0]: https://github.com/peter-murach/tty-progressbar/compare/v0.9.0...v0.10.0

data/README.md

@@ -20,9 +20,11 @@
 
 ## Features
 
-* Fully [configurable](#2-configuration)
-* Extremly flexible progress display [formatting](#3-formatting)
-* Ability to define your custom format [tokens](#31-tokens)
+* Fully [configurable](#3-configuration)
+* Extremely flexible progress display [formatting](#4-formatting)
+* Includes many predefined tokens to calculate ETA, Bytes ... [tokens](#41-tokens)
+* Allows to define your [custom tokens](#42-custom-formatters)
+* Supports parallel multi progress bars [multi](#6-ttyprogressbarmulti-api)
 * Works on all ECMA-48 compatible terminals
 
 ## Installation
@@ -44,25 +46,42 @@ Or install it yourself as:
 ## Contents
 
 * [1. Usage](#1-usage)
-  * [1.1 advance](#11-advance)
-  * [1.2 current=](#12-current)
-  * [1.3 ratio=](#13-ratio)
-  * [1.4 width=](#14-width)
-  * [1.5 start](#15-start)
-  * [1.6 finish](#16-finish)
-  * [1.7 complete?](#17-complete)
-  * [1.8 reset](#18-reset)
-  * [1.9 resize](#19-resize)
-* [2. Configuration](#2-configuration)
-  * [2.1 Frequency](#21-frequency)
-  * [2.2 Interval](#22-interval)
-* [3. Formatting](#3-formatting)
-  * [3.1 Tokens](#31-tokens)
-  * [3.2 Custom Formatters](#32-custom-formatters)
-  * [3.3 Custom Tokens](#33-custom-tokens)
-* [4. Logging](#4-logging)
-* [5. Examples](#5-examples)
-  * [5.1 Color](#51-color)
+* [2. TTY::ProgressBar::API](#2-ttyprogressbar-api)
+  * [2.1 advance](#21-advance)
+  * [2.2 iterate](#22-iterate)
+  * [2.3 current=](#23-current)
+  * [2.4 ratio=](#24-ratio)
+  * [2.5 width=](#25-width)
+  * [2.6 start](#26-start)
+  * [2.7 update](#27-update)
+  * [2.8 finish](#28-finish)
+  * [2.9 stop](#29-stop)
+  * [2.10 reset](#210-reset)
+  * [2.11 complete?](#211-complete)
+  * [2.12 resize](#212-resize)
+  * [2.13 on](#213-on)
+* [3. Configuration](#3-configuration)
+  * [3.1 :head](#31-head)
+  * [3.2 :frequency](#32-interval)
+  * [3.3 :interval](#33-interval)
+* [4. Formatting](#4-formatting)
+  * [4.1 Tokens](#41-tokens)
+  * [4.2 Custom Formatters](#42-custom-formatters)
+  * [4.3 Custom Tokens](#43-custom-tokens)
+* [5. Logging](#5-logging)
+* [6. TTY::ProgressBar::Multi API](#6-ttyprogressbarmulti-api)
+  * [6.1 new](#61-new)
+  * [6.2 register](#62-register)
+  * [6.3 advance](#63-advance)
+  * [6.4 start](#64-start)
+  * [6.5 finish](#65-finish)
+  * [6.6 stop](#66-stop)
+  * [6.7 complete?](#67-complete)
+  * [6.8 on](#68-on)
+  * [6.9 :style](#69-style)
+* [7. Examples](#7-examples)
+  * [7.1 Color](#71-color)
+  * [7.2 Speed](#72-speed)
 
 ## 1. Usage
 
@@ -79,10 +98,36 @@ end
 This would produce animation in your terminal:
 
 ```ruby
-downloading [=======================       ]
+# downloading [=======================       ]
 ```
 
-### 1.1 advance
+Use **TTY::ProgressBar::Multi** to display multiple parallel progress bars:
+
+```ruby
+bars = TTY::ProgressBar::Multi.new("main [:bar] :percent")
+
+bar1 = bars.register("one [:bar] :percent", total: 15)
+bar2 = bars.register("two [:bar] :percent", total: 15)
+
+bars.start
+
+th1 = Thread.new { 15.times { sleep(0.1); bar1.advance } }
+th2 = Thread.new { 15.times { sleep(0.1); bar2.advance } }
+
+[th1, th2].each { |t| t.join }
+```
+
+which will produce:
+
+```ruby
+# ┌ main [===============               ] 50%
+# ├── one [=====          ] 34%
+# └── two [==========     ] 67%
+```
+
+## 2. TTY::ProgressBar API
+
+### 2.1 advance
 
 Once you have **TTY::ProgressBar** instance, you can progress the display by calling `advance` method. By default it will increase by `1` but you can pass any number of steps, for instance, when used to advance number of bytes of downloaded file.
 
@@ -98,7 +143,36 @@ bar.advance(-1)
 
 Note: If a progress bar has already finished then negative steps will not set it back to desired value.
 
-### 1.2 current=
+### 2.2 iterate
+
+To simplify progressing over an enumerable you can use `iterate` which as a first argument accepts an `Enumerable` and as a second the amount to progress the bar with.
+
+First, create a progress bar without a total which will be dynamically handled for you:
+
+```ruby
+bar = TTY::ProgressBar.new
+```
+
+Then, either directly iterate over a collection by yielding values to a block:
+
+```ruby
+bar.iterate(30.times) { |v| ... }
+```
+
+or return an 'Enumerator':
+
+```ruby
+progress = bar.iterate(30.times)
+# => #<Enumerator: #<Enumerator::Generator:0x...:each>
+```
+
+By default, progress bar is advanced by `1` but you can change it by passing second argument:
+
+```ruby
+bar.iterate(30.times, 5)
+```
+
+### 2.3 current=
 
 **TTY::ProgressBar** allows you to set progress to a given value by calling `current=` method.
 
@@ -108,7 +182,7 @@ bar.current = 50
 
 Note: If a progress bar has already finished then negative steps will not set it back to desired value.
 
-### 1.3 ratio=
+### 2.4 ratio=
 
 In order to update overall completion of a progress bar as an exact percentage use the `ratio=` method. The method accepts values between `0` and `1` inclusive. For example, a ratio of 0.5 will attempt to set the progress bar halfway:
 
@@ -116,7 +190,7 @@ In order to update overall completion of a progress bar as an exact percentage u
 bar.ratio = 0.5
 ```
 
-### 1.4 width=
+### 2.5 width=
 
 You can set how many terminal columns will the `:bar` actually span excluding any other tokens and/or text. For example if you need the bar to be always 20 columns wwide do:
 
@@ -130,7 +204,7 @@ or with configuration options:
 bar = TTY::ProgressBar.new("[:bar]", width: 20)
 ```
 
-### 1.5 start
+### 2.6 start
 
 By default the timer for internal time esitamation is started automatically when the `advance` method is called. However, if you require control on when the progression timer is started use `start` call:
 
@@ -138,7 +212,15 @@ By default the timer for internal time esitamation is started automatically when
 bar.start  # => sets timer and draws initial progress bar
 ```
 
-### 1.6 finish
+### 2.7 update
+
+Once the progress bar has been started you can change its configuration option(s) by calling `update`:
+
+```ruby
+bar.update(complete: '+', frequency: 10)
+```
+
+### 2.8 finish
 
 In order to immediately stop and finish the progress call `finish`. This will finish drawing the progress and return to new line.
 
@@ -146,15 +228,15 @@ In order to immediately stop and finish the progress call `finish`. This will fi
 bar.finish
 ```
 
-### 1.7 complete?
+### 2.9 stop
 
-During progresion you can check if bar is finished or not by calling `complete?`.
+In order to immediately stop the bar in the current position and thus finish any further progress use `stop`:
 
 ```ruby
-bar.complete? # => false
+bar.stop
 ```
 
-### 1.8 reset
+### 2.10 reset
 
 In order to reset currently running or finished progress bar to its original configuration and initial position use `reset` like so:
 
@@ -162,7 +244,17 @@ In order to reset currently running or finished progress bar to its original con
 bar.reset
 ```
 
-### 1.9 resize
+After resetting the bar if you wish to draw and start the bar and its timers use `start` call.
+
+### 2.11 complete?
+
+During progresion you can check if a bar is finished or not by calling `complete?`. The bar will only return `true` if the progression finished successfuly, otherwise `false` will be returned.
+
+```ruby
+bar.complete? # => false
+```
+
+### 2.12 resize
 
 If you wish for a progress bar to change it's current width, you can use `resize` by passing in a new desired length. However, if you don't provide any width the `resize` will use terminal current width as its base for scaling.
 
@@ -177,19 +269,42 @@ To handle automatic resizing you can trap `:WINCH` signal:
 trap(:WINCH) { bar.resize }
 ```
 
-## 2. Configuration
+### 2.13 on
+
+The progress bar fires events when it is progressing, stopped or finished. You can register to listen for events using the `on` message.
+
+Every time an `advance` is called the `:progress` event gets fired which you can listen for:
+
+```ruby
+bar.on(:progress) { ... }
+```
+
+When the progress bar finishes and completes then the `:done` event is fired. You can listen for this event:
+
+```ruby
+bar.on(:done) { ... }
+```
+
+Alternatively, when the progress bar gets stopped the `:stopped` event is fired. You can listen for this event:
+
+```ruby
+bar.on(:stopped) { ... }
+```
+
+## 3. Configuration
 
 There are number of configuration options that can be provided:
 
-* `total` total number of steps to completion
-* `width` of the bars display in terminal columns excluding formatting options. Defaults to total steps
-* `complete` completion character by default `=`
-* `incomplete` incomplete character by default single space
-* `output` the output stream defaulting to `stderr`
-* `frequency` used to throttle the output, by default `0` (see [Frequency](#21-frequency))
-* `interval` used to measure the speed, by default `1 sec` (see [Interval](#22-interval))
-* `hide_cursor` to hide display cursor defaulting to `false`
-* `clear` to clear the finished bar defaulting to `false`
+* `:total` total number of steps to completion
+* `:width` of the bars display in terminal columns excluding formatting options. Defaults to total steps
+* `:complete` completion character by default `=`
+* `:incomplete` incomplete character by default single space
+* [:head](#21-head) the head character by default `=`
+* `:output` the output stream defaulting to `stderr`
+* [:frequency](#22-frequency) used to throttle the output, by default `0`
+* [:interval](#23-interval) used to measure the speed, by default `1 sec`
+* `:hide_cursor` to hide display cursor defaulting to `false`
+* `:clear` to clear the finished bar defaulting to `false`
 
 All the above options can be passed in as hash options or block parameters:
 
@@ -201,7 +316,17 @@ TTY::ProgressBar.new "[:bar]" do |config|
 end
 ```
 
-### 2.1 Frequency
+### 3.1 :head
+
+If you prefer for the animated bar to display a specific character for a head of progression then use `:head` option:
+
+```ruby
+bar = TTY::ProressBar.new("[:bar]", head: '>')
+#
+# [=======>      ]
+```
+
+### 3.2 :frequency
 
 Each time the `advance` is called it causes the progress bar to repaint. In cases when there is a huge number of updates per second, you may need to limit the rendering process by using the `frequency` option.
 
@@ -211,7 +336,7 @@ The `frequency` option accepts `integer` representing number of `Hz` units, for
 TTY::ProgressBar.new("[:bar]", total: 30, frequency: 10) # 10 Hz
 ```
 
-### 2.2 Interval
+### 3.3 :interval
 
 For every call of `advance` method the **ProgressBar** takes a sample for speed measurement. By default the samples are grouped per second but you can change that by passing the `interval` option.
 
@@ -223,7 +348,7 @@ TTY::ProgressBar.new(":rate/minute", total: 100, interval: 60) # 1 minute
 TTY::ProgressBar.new(":rate/hour", total: 100, interval: 3600) # 1 hour
 ```
 
-## 3. Formatting
+## 4. Formatting
 
 Every **TTY::ProgressBar** instance requires a format string, which apart from regular characters accepts special tokens to display dynamic information. For instance, a format to measure download progress could be:
 
@@ -231,7 +356,7 @@ Every **TTY::ProgressBar** instance requires a format string, which apart from r
 "downloading [:bar] :elapsed :percent"
 ```
 
-### 3.1 Tokens
+### 4.1 Tokens
 
 These are the tokens that are currently supported:
 
@@ -248,7 +373,7 @@ These are the tokens that are currently supported:
 * `:mean_rate` the averaged rate of progression per second
 * `:mean_byte` the averaged rate of progression in bytes per second
 
-### 3.2 Custom Formatters
+### 4.2 Custom Formatters
 
 If the provided tokens do not meet your needs, you can write your own formatter and instrument formatting pipeline to use a formatter you prefer. This option is preferred if you are going to rely on progress bar internal data such as `rate`, `current` etc. which will all be available on the passed in progress bar instance.
 
@@ -291,7 +416,7 @@ and then invoke progression:
 bar.advance
 ```
 
-### 3.3 Custom Tokens
+### 4.3 Custom Tokens
 
 You can define custom tokens by passing pairs `name: value` to `advance` method in order to dynamically update formatted bar. This option is useful for lightweight content replacement such as titles that doesn't depend on the internal data of progressbar. For example:
 
@@ -308,7 +433,7 @@ which outputs:
 (4) Bye Piotr!
 ```
 
-## 4. Logging
+## 5. Logging
 
 If you want to print messages out to terminal along with the progress bar use the `log` method. The messages will appear above the progress bar and will continue scrolling up as more are logged out.
 
@@ -320,15 +445,135 @@ bar.advance
 will result in:
 
 ```ruby
-Piotrrrrr
-downloading [=======================       ]
+# Piotrrrrr
+# downloading [=======================       ]
+```
+
+## 6. TTY::ProgressBar::Multi API
+
+### 6.1 new
+
+The multi progress bar can be created in two ways. If you simply want to group multiple progress bars you can create multi bar like so:
+
+```ruby
+TTY::ProgressBar::Multi.new
+```
+
+
+However, if you want a top level multibar that tracks all the registered progress bars then provide a formatted string:
+
+```ruby
+TTY::ProgressBar::Multi.new("main [:bar] :percent")
+```
+
+### 6.2 register
+
+To create a `TTY::ProgressBar` under the multibar use `register` like so:
+
+```ruby
+multibar = TTY::ProgressBar::Multi.new
+bar = multibar.register("[:bar]", total: 30)
+```
+
+The `register` call returns the newly created progress bar which answers all the progress bar api messages.
+
+Please remember to specify total value for each registered progress bar, either when sending `register` message or when using `update` to dynamicaly assign the total value.
+
+### 6.3 advance
+
+Once multi progress bar has been created you can advance each registered progress bar individually, either by executing them one after the other synchronously or by placing them in separate threads thus progressing each bar asynchronously. The multi bar handles synchronization and display of all bars as they continue their respective rendering.
+
+For example, to display two bars async, first register them with the multi bar:
+
+```ruby
+bar1 = multibar.register("one [:bar]", total: 20)
+bar2 = multibar.register("two [:bar]", total: 30)
+```
+
+Next place the progress behaviour in separate process or thread:
+
+```ruby
+th1 = Thread.new { 20.times { expensive_work(); bar1.advance } }
+th2 = Thread.new { 30.times { expensive_work(); bar2.advance } }
+```
+
+Finally, wait for the threads to finish:
+
+```ruby
+[th1, th2].each { |t| t.join }
+```
+
+### 6.4 start
+
+If you want your top level multi bar to be rendered as the first bar in the terminal before any registered bars call `start`:
+
+```ruby
+multibar.start
+```
+
+### 6.5 finish
+
+In order to finish all progress bars call `finish`. This will finish the top level progress bar, if it exists, all any registered progress bars still in progress.
+
+```ruby
+multibar.finish
+```
+
+### 6.6 stop
+
+Use `stop` to terminate immediately all progress bars registered with the multibar.
+
+```ruby
+multibar.stop
+```
+
+### 6.7 complete?
+
+To check if all registered progress bars have been successfully finished use `complete?`
+
+```ruby
+multibar.complete? # => true
+```
+
+### 6.8 on
+
+Similar to `TTY::ProgressBar` the multi bar fires events when it is progressing, stopped or finished. You can register to listen for events using the `on` message.
+
+Every time any of the registered progress bars progresses the `:progress` event is fired which you can listen for:
+
+```ruby
+multibar.on(:progress) { ... }
+```
+
+When all the registered progress bars finish and complete then the `:done` event is fired. You can listen for this event:
+
+```ruby
+multibar.on(:done) { ... }
+```
+
+Finally, when any of the progress bars gets stopped the `:stopped` event is fired. You can listen for this event:
+
+```ruby
+multibar.on(:stopped) { ... }
+```
+
+### 6.9 :style
+
+In addition to all [configuration options](#3-configuration) you can style multi progress bar:
+
+```ruby
+TTY::ProgressBar::Multi.new("[:bar]", style: {
+  top: '. '
+  middle: '|-> '
+  bottom: '|__ '
+})
 ```
 
-## 5. Examples
+## 7. Examples
 
 This section demonstrates some of the possible uses for the **TTY::ProgressBar**, for more please see examples folder in the source directory.
 
-### 5.1 Colors
+### 7.1 Colors
 
 Creating a progress bar that displays in color is as simple as coloring the `:complete` and `:incomplete` character options. In order to help with coloring you can use [pastel](https://github.com/piotrmurach/pastel) library like so:
 
@@ -359,7 +604,7 @@ To see how a progress bar is reported in terminal you can do:
 end
 ```
 
-### 5.2 Speed
+### 7.2 Speed
 
 Commonly a progress bar is utilized to measure download speed per second. This can be done like so:
 
@@ -373,7 +618,7 @@ end
 This will result in output similar to:
 
 ```ruby
-downloading [=======================       ] 4.12MB/s
+# downloading [=======================       ] 4.12MB/s
 ```
 
 ## Contributing