tty-progressbar 0.14.0 → 0.18.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/CHANGELOG.md +98 -21
- data/LICENSE.txt +1 -1
- data/README.md +511 -119
- data/lib/tty-progressbar.rb +2 -2
- data/lib/tty/progressbar.rb +216 -87
- data/lib/tty/progressbar/configuration.rb +124 -16
- data/lib/tty/progressbar/converter.rb +16 -19
- data/lib/tty/progressbar/formats.rb +120 -0
- data/lib/tty/progressbar/formatter.rb +33 -38
- data/lib/tty/progressbar/formatter/bar.rb +87 -29
- data/lib/tty/progressbar/formatter/byte_rate.rb +6 -20
- data/lib/tty/progressbar/formatter/current.rb +4 -19
- data/lib/tty/progressbar/formatter/current_byte.rb +9 -17
- data/lib/tty/progressbar/formatter/elapsed.rb +9 -18
- data/lib/tty/progressbar/formatter/estimated.rb +14 -18
- data/lib/tty/progressbar/formatter/estimated_time.rb +37 -0
- data/lib/tty/progressbar/formatter/mean_byte.rb +6 -20
- data/lib/tty/progressbar/formatter/mean_rate.rb +6 -20
- data/lib/tty/progressbar/formatter/percent.rb +10 -16
- data/lib/tty/progressbar/formatter/rate.rb +5 -19
- data/lib/tty/progressbar/formatter/total.rb +10 -16
- data/lib/tty/progressbar/formatter/total_byte.rb +14 -18
- data/lib/tty/progressbar/formatters.rb +53 -0
- data/lib/tty/progressbar/meter.rb +2 -2
- data/lib/tty/progressbar/multi.rb +69 -23
- data/lib/tty/progressbar/pipeline.rb +13 -6
- data/lib/tty/progressbar/timer.rb +89 -0
- data/lib/tty/progressbar/version.rb +3 -1
- metadata +65 -151
- data/.codeclimate.yml +0 -11
- data/.gitignore +0 -14
- data/.rspec +0 -3
- data/.travis.yml +0 -25
- data/CODE_OF_CONDUCT.md +0 -74
- data/Gemfile +0 -14
- data/Rakefile +0 -8
- data/appveyor.yml +0 -21
- data/examples/color.rb +0 -18
- data/examples/failure.rb +0 -12
- data/examples/iterator.rb +0 -5
- data/examples/lazy.rb +0 -6
- data/examples/multi/main_bar.rb +0 -13
- data/examples/multi/simple.rb +0 -13
- data/examples/simple.rb +0 -7
- data/examples/slow_process.rb +0 -29
- data/examples/speed.rb +0 -11
- data/examples/threaded.rb +0 -14
- data/examples/tokens.rb +0 -12
- data/spec/spec_helper.rb +0 -50
- data/spec/unit/advance_spec.rb +0 -25
- data/spec/unit/clear_spec.rb +0 -17
- data/spec/unit/complete_spec.rb +0 -16
- data/spec/unit/converter/to_bytes_spec.rb +0 -47
- data/spec/unit/converter/to_seconds_spec.rb +0 -15
- data/spec/unit/converter/to_time_spec.rb +0 -19
- data/spec/unit/custom_formatter_spec.rb +0 -26
- data/spec/unit/custom_token_spec.rb +0 -14
- data/spec/unit/events_spec.rb +0 -33
- data/spec/unit/finish_spec.rb +0 -15
- data/spec/unit/formatter/bar_spec.rb +0 -16
- data/spec/unit/formatter/byte_rate_spec.rb +0 -32
- data/spec/unit/formatter/current_byte_spec.rb +0 -16
- data/spec/unit/formatter/current_spec.rb +0 -14
- data/spec/unit/formatter/elapsed_spec.rb +0 -58
- data/spec/unit/formatter/estimated_spec.rb +0 -27
- data/spec/unit/formatter/mean_byte_spec.rb +0 -32
- data/spec/unit/formatter/mean_rate_spec.rb +0 -31
- data/spec/unit/formatter/percent_spec.rb +0 -16
- data/spec/unit/formatter/rate_spec.rb +0 -31
- data/spec/unit/formatter/total_byte_spec.rb +0 -16
- data/spec/unit/formatter/total_spec.rb +0 -16
- data/spec/unit/frequency_spec.rb +0 -27
- data/spec/unit/head_spec.rb +0 -32
- data/spec/unit/hide_cursor_spec.rb +0 -27
- data/spec/unit/inspect_spec.rb +0 -11
- data/spec/unit/iterate_spec.rb +0 -79
- data/spec/unit/log_spec.rb +0 -29
- data/spec/unit/meter_spec.rb +0 -70
- data/spec/unit/multi/advance_spec.rb +0 -123
- data/spec/unit/multi/events_spec.rb +0 -115
- data/spec/unit/multi/finish_spec.rb +0 -41
- data/spec/unit/multi/line_inset_spec.rb +0 -65
- data/spec/unit/multi/register_spec.rb +0 -35
- data/spec/unit/multi/stop_spec.rb +0 -15
- data/spec/unit/new_spec.rb +0 -66
- data/spec/unit/pipeline_spec.rb +0 -19
- data/spec/unit/ratio_spec.rb +0 -31
- data/spec/unit/reset_spec.rb +0 -31
- data/spec/unit/resize_spec.rb +0 -35
- data/spec/unit/set_current_spec.rb +0 -43
- data/spec/unit/start_spec.rb +0 -14
- data/spec/unit/stop_spec.rb +0 -19
- data/spec/unit/update_spec.rb +0 -22
- data/spec/unit/width_spec.rb +0 -21
- data/tasks/console.rake +0 -9
- data/tasks/coverage.rake +0 -9
- data/tasks/spec.rake +0 -27
- data/tty-progressbar.gemspec +0 -30
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: d266b064379d48a7f7efa620115e1de7d289d7d469f09ef3879cc1ccaceb71db
|
|
4
|
+
data.tar.gz: 14ec207136b4910387f398f443351632e12c60744d389c1747a90ddf90cae5cd
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: e872707b643d2b01f89fb056f31654f0d6aef50c9665936442c8c9f9cb8310f6bb8af447506d6ff3197284b4365595d475c799dc9d1c4dd20f0bc2d9fc395412
|
|
7
|
+
data.tar.gz: d695aa270398d79899aea3dcaa58964f6f24ea8888d84cecbb191982cb52717b82526eeb92561ee50af1ec00e1ddba8d0b378c6d5484c8ed70e2e6890f0e07f4
|
data/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,78 @@
|
|
|
1
1
|
# Change log
|
|
2
2
|
|
|
3
|
-
## [v0.
|
|
3
|
+
## [v0.18.0] - 2021-01-20
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
* Add #resume to allow stopped or paused bar to continue progressing
|
|
7
|
+
* Add :clear_head option to remove head when progress is done
|
|
8
|
+
* Add #configure to allow runtime configuration
|
|
9
|
+
* Add Multi#done? to check if all bar are stopped or finished
|
|
10
|
+
* Add indeterminate progress support when no total is given
|
|
11
|
+
* Add :bar_format option to allow selecting preconfigured bar displays
|
|
12
|
+
* Add :eta_time format token to display the estimated time of day at completion
|
|
13
|
+
* Add measurement of the total elapsed time that ignores stopped time intervals
|
|
14
|
+
* Add #pause to prevent bar from continuing progression and suspend time measurements
|
|
15
|
+
* Add Multi#pause to allow suspending progression of all registered bars at once
|
|
16
|
+
* Add Multi#resume to start again all registered bars that are stopped or paused
|
|
17
|
+
* Add Timer class to handle the total elapsed time measurements
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
* Change Multi#stopped? to check that all bars are stopped
|
|
21
|
+
* Change gemspec to load version directly and remove test artifacts
|
|
22
|
+
* Change to update strings-ansi and tty-screen dependencies
|
|
23
|
+
* Change Pipeline to inject progress bar instance only once
|
|
24
|
+
* Change :elapsed and :eta to show days after running for 24 hours
|
|
25
|
+
* Change to ensure complete, incomplete and unknown option cannot be an empty string
|
|
26
|
+
* Change to allow setting total to nil via accessor
|
|
27
|
+
* Change gemspec to allow version 2.0 of unicode-display_width dependency
|
|
28
|
+
* Change #stop to show hidden cursor after render similar to #finish
|
|
29
|
+
|
|
30
|
+
### Fixed
|
|
31
|
+
* Fix MultiBar top bar to allow resuming progress when stopped/done (@d4be4st)
|
|
32
|
+
* Fix MultiBar to only set width when top bar present
|
|
33
|
+
|
|
34
|
+
## [v0.17.0] - 2019-05-31
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
* Change gemspec to load files directly without git
|
|
38
|
+
* Change to update tty-cursor and tty-screen dependencies
|
|
39
|
+
|
|
40
|
+
## [v0.16.0] - 2018-08-27
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
* Add strings-ansi dependency
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
* Change tty-cursor dependency version
|
|
47
|
+
|
|
48
|
+
### Fixed
|
|
49
|
+
* Fix to handle ANSI codes in bar formatting to allow correct size calculation
|
|
50
|
+
|
|
51
|
+
## [v0.15.1] - 2018-07-19
|
|
52
|
+
|
|
53
|
+
### Fixed
|
|
54
|
+
* Fix to always restore hidden cursor by Eric Hodel(@drbrain)
|
|
55
|
+
|
|
56
|
+
## [v0.15.0] - 2018-06-24
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
* Add #format= for overriding formatting string
|
|
60
|
+
* Add #display_columns for determining display width of multibyte characters
|
|
61
|
+
* Add :inset option to bar configuration options
|
|
62
|
+
* Add ability to configure width for multi bar with top level bar
|
|
63
|
+
* Add unicode-display_width dependency
|
|
64
|
+
|
|
65
|
+
### Changed
|
|
66
|
+
* Change #update to only set configuration if actually present
|
|
67
|
+
* Change bar formatter to handle multibyte characters
|
|
68
|
+
|
|
69
|
+
### Fixed
|
|
70
|
+
* Fix to stop reseting multibar state when registered bar reset by Eric Hodel(@drbrain)
|
|
71
|
+
* Fix rendered bar to pad formatted output when it gets shorter by Eric Hodel(@drbrain)
|
|
72
|
+
* Fix multi bar to advance in steps matching each bar advance progress
|
|
73
|
+
* Fix multi bar rendering for widths exceeding screen columns count
|
|
74
|
+
|
|
75
|
+
## [v0.14.0] - 2018-01-17
|
|
4
76
|
|
|
5
77
|
### Changed
|
|
6
78
|
* Change to only output to a console and stop output to a file, pipe etc...
|
|
@@ -160,23 +232,28 @@
|
|
|
160
232
|
|
|
161
233
|
* Initial implementation and release
|
|
162
234
|
|
|
163
|
-
[v0.
|
|
164
|
-
[v0.
|
|
165
|
-
[v0.
|
|
166
|
-
[v0.
|
|
167
|
-
[v0.
|
|
168
|
-
[v0.
|
|
169
|
-
[v0.
|
|
170
|
-
[v0.
|
|
171
|
-
[v0.
|
|
172
|
-
[v0.
|
|
173
|
-
[v0.
|
|
174
|
-
[v0.
|
|
175
|
-
[v0.
|
|
176
|
-
[v0.
|
|
177
|
-
[v0.
|
|
178
|
-
[v0.
|
|
179
|
-
[v0.
|
|
180
|
-
[v0.
|
|
181
|
-
[v0.
|
|
182
|
-
[v0.1
|
|
235
|
+
[v0.18.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.17.0...v0.18.0
|
|
236
|
+
[v0.17.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.16.0...v0.17.0
|
|
237
|
+
[v0.16.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.15.1...v0.16.0
|
|
238
|
+
[v0.15.1]: https://github.com/piotrmurach/tty-progressbar/compare/v0.15.0...v0.15.1
|
|
239
|
+
[v0.15.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.14.0...v0.15.0
|
|
240
|
+
[v0.14.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.13.0...v0.14.0
|
|
241
|
+
[v0.13.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.12.2...v0.13.0
|
|
242
|
+
[v0.12.2]: https://github.com/piotrmurach/tty-progressbar/compare/v0.12.1...v0.12.2
|
|
243
|
+
[v0.12.1]: https://github.com/piotrmurach/tty-progressbar/compare/v0.12.0...v0.12.1
|
|
244
|
+
[v0.12.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.11.0...v0.12.0
|
|
245
|
+
[v0.11.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.10.1...v0.11.0
|
|
246
|
+
[v0.10.1]: https://github.com/piotrmurach/tty-progressbar/compare/v0.10.0...v0.10.1
|
|
247
|
+
[v0.10.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.9.0...v0.10.0
|
|
248
|
+
[v0.9.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.8.2...v0.9.0
|
|
249
|
+
[v0.8.2]: https://github.com/piotrmurach/tty-progressbar/compare/v0.8.1...v0.8.2
|
|
250
|
+
[v0.8.1]: https://github.com/piotrmurach/tty-progressbar/compare/v0.8.0...v0.8.1
|
|
251
|
+
[v0.8.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.7.0...v0.8.0
|
|
252
|
+
[v0.7.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.6.0...v0.7.0
|
|
253
|
+
[v0.6.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.5.1...v0.6.0
|
|
254
|
+
[v0.5.1]: https://github.com/piotrmurach/tty-progressbar/compare/v0.5.0...v0.5.1
|
|
255
|
+
[v0.5.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.4.0...v0.5.0
|
|
256
|
+
[v0.4.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.3.0...v0.4.0
|
|
257
|
+
[v0.3.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.2.0...v0.3.0
|
|
258
|
+
[v0.2.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.1.0...v0.2.0
|
|
259
|
+
[v0.1.0]: https://github.com/piotrmurach/tty-progressbar/compare/v0.1.0
|
data/LICENSE.txt
CHANGED
data/README.md
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo"/></a>
|
|
3
|
+
</div>
|
|
4
|
+
|
|
1
5
|
# TTY::ProgressBar [][gitter]
|
|
2
6
|
|
|
3
7
|
[][gem]
|
|
4
|
-
[][gh_actions_ci]
|
|
5
9
|
[][appveyor]
|
|
6
10
|
[][codeclimate]
|
|
7
11
|
[][coverage]
|
|
@@ -9,40 +13,46 @@
|
|
|
9
13
|
|
|
10
14
|
[gitter]: https://gitter.im/piotrmurach/tty
|
|
11
15
|
[gem]: http://badge.fury.io/rb/tty-progressbar
|
|
12
|
-
[
|
|
16
|
+
[gh_actions_ci]: https://github.com/piotrmurach/tty-progressbar/actions?query=workflow%3ACI
|
|
13
17
|
[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-progressbar
|
|
14
18
|
[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-progressbar/maintainability
|
|
15
19
|
[coverage]: https://coveralls.io/github/piotrmurach/tty-progressbar
|
|
16
20
|
[inchpages]: http://inch-ci.org/github/piotrmurach/tty-progressbar
|
|
17
21
|
|
|
18
|
-
> A flexible progress
|
|
22
|
+
> A flexible and extensible progress bar for terminal applications.
|
|
19
23
|
|
|
20
|
-
**TTY::ProgressBar** provides independent progress
|
|
24
|
+
**TTY::ProgressBar** provides independent progress bar component for [TTY](https://github.com/piotrmurach/tty) toolkit.
|
|
21
25
|
|
|
22
26
|
## Features
|
|
23
27
|
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
28
|
+
* **Customisable.** Choose from many [configuration](#3-configuration) options to get the behaviour you want.
|
|
29
|
+
* **Flexible.** Describe bar [format](#4-formatting) and pick from many predefined [tokens](#41-tokens) and [bar styles](#37-bar_format).
|
|
30
|
+
* **Extensible.** Define [custom tokens](#42-custom-formatters) to fit your needs.
|
|
31
|
+
* **Powerful.** Display [multi](#6-ttyprogressbarmulti-api) progress bars in parallel.
|
|
32
|
+
* Show an unbounded operation with [indeterminate](#31-total) progress.
|
|
33
|
+
* [Pause](#210-pause) and [resume](#212-resume) progress at any time.
|
|
34
|
+
* Include [Unicode](#44-unicode) characters in progress bar.
|
|
35
|
+
* Works on all ECMA-48 compatible terminals.
|
|
30
36
|
|
|
31
37
|
## Installation
|
|
32
38
|
|
|
33
39
|
Add this line to your application's Gemfile:
|
|
34
40
|
|
|
35
41
|
```ruby
|
|
36
|
-
gem
|
|
42
|
+
gem "tty-progressbar"
|
|
37
43
|
```
|
|
38
44
|
|
|
39
45
|
And then execute:
|
|
40
46
|
|
|
41
|
-
|
|
47
|
+
```
|
|
48
|
+
$ bundle
|
|
49
|
+
```
|
|
42
50
|
|
|
43
51
|
Or install it yourself as:
|
|
44
52
|
|
|
45
|
-
|
|
53
|
+
```
|
|
54
|
+
$ gem install tty-progressbar
|
|
55
|
+
```
|
|
46
56
|
|
|
47
57
|
## Contents
|
|
48
58
|
|
|
@@ -57,19 +67,34 @@ Or install it yourself as:
|
|
|
57
67
|
* [2.7 update](#27-update)
|
|
58
68
|
* [2.8 finish](#28-finish)
|
|
59
69
|
* [2.9 stop](#29-stop)
|
|
60
|
-
* [2.10
|
|
61
|
-
* [2.11
|
|
62
|
-
* [2.12
|
|
63
|
-
* [2.13
|
|
70
|
+
* [2.10 pause](#210-pause)
|
|
71
|
+
* [2.11 reset](#211-reset)
|
|
72
|
+
* [2.12 resume](#212-resume)
|
|
73
|
+
* [2.13 complete?](#213-complete)
|
|
74
|
+
* [2.14 paused?](#214-paused)
|
|
75
|
+
* [2.15 stopped?](#215-stopped)
|
|
76
|
+
* [2.16 indeterminate?](#216-indeterminate)
|
|
77
|
+
* [2.17 resize](#217-resize)
|
|
78
|
+
* [2.18 on](#218-on)
|
|
64
79
|
* [3. Configuration](#3-configuration)
|
|
65
|
-
* [3.1 :
|
|
66
|
-
* [3.
|
|
67
|
-
* [3.3 :
|
|
68
|
-
* [3.4 :
|
|
80
|
+
* [3.1 :total](#31-total)
|
|
81
|
+
* [3.1 :width](#32-width)
|
|
82
|
+
* [3.3 :complete](#33-complete)
|
|
83
|
+
* [3.4 :incomplete](#34-incomplete)
|
|
84
|
+
* [3.5 :head](#35-head)
|
|
85
|
+
* [3.6 :unknown](#36-unknown)
|
|
86
|
+
* [3.7 :bar_format](#37-bar_format)
|
|
87
|
+
* [3.8 :output](#38-output)
|
|
88
|
+
* [3.9 :frequency](#39-frequency)
|
|
89
|
+
* [3.10 :interval](#310-interval)
|
|
90
|
+
* [3.11 :hide_cursor](#311-hide_cursor)
|
|
91
|
+
* [3.12 :clear](#312-clear)
|
|
92
|
+
* [3.13 :clear_head](#313-clear_head)
|
|
69
93
|
* [4. Formatting](#4-formatting)
|
|
70
94
|
* [4.1 Tokens](#41-tokens)
|
|
71
95
|
* [4.2 Custom Formatters](#42-custom-formatters)
|
|
72
96
|
* [4.3 Custom Tokens](#43-custom-tokens)
|
|
97
|
+
* [4.4 Unicode](#44-unicode)
|
|
73
98
|
* [5. Logging](#5-logging)
|
|
74
99
|
* [6. TTY::ProgressBar::Multi API](#6-ttyprogressbarmulti-api)
|
|
75
100
|
* [6.1 new](#61-new)
|
|
@@ -78,40 +103,63 @@ Or install it yourself as:
|
|
|
78
103
|
* [6.4 start](#64-start)
|
|
79
104
|
* [6.5 finish](#65-finish)
|
|
80
105
|
* [6.6 stop](#66-stop)
|
|
81
|
-
* [6.7
|
|
82
|
-
* [6.8
|
|
83
|
-
* [6.9
|
|
106
|
+
* [6.7 pause](#67-pause)
|
|
107
|
+
* [6.8 resume](#68-resume)
|
|
108
|
+
* [6.9 complete?](#69-complete)
|
|
109
|
+
* [6.10 paused?](#610-paused)
|
|
110
|
+
* [6.11 stopped?](#611-stopped)
|
|
111
|
+
* [6.12 on](#612-on)
|
|
112
|
+
* [6.13 :style](#613-style)
|
|
84
113
|
* [7. Examples](#7-examples)
|
|
85
114
|
* [7.1 Color](#71-color)
|
|
86
115
|
* [7.2 Speed](#72-speed)
|
|
87
116
|
|
|
88
117
|
## 1. Usage
|
|
89
118
|
|
|
90
|
-
**TTY::ProgressBar** requires only format string and total number of steps to completion
|
|
119
|
+
**TTY::ProgressBar** requires only a format string with `:bar` [token](#41-tokens) and total number of steps to completion:
|
|
91
120
|
|
|
92
121
|
```ruby
|
|
93
122
|
bar = TTY::ProgressBar.new("downloading [:bar]", total: 30)
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Once initialized, use [advance](#21-advance) method to indicated progress:
|
|
126
|
+
|
|
127
|
+
```ruby
|
|
94
128
|
30.times do
|
|
95
129
|
sleep(0.1)
|
|
96
|
-
bar.advance
|
|
130
|
+
bar.advance # by default increases by 1
|
|
97
131
|
end
|
|
98
132
|
```
|
|
99
133
|
|
|
100
|
-
This would produce animation in your terminal:
|
|
134
|
+
This would produce the following animation in your terminal:
|
|
101
135
|
|
|
102
136
|
```ruby
|
|
103
137
|
# downloading [======================= ]
|
|
104
138
|
```
|
|
105
139
|
|
|
106
|
-
|
|
140
|
+
You can further change a progress bar behaviour and display by changing [configuration](#3-configuration) options and using many predefined [tokens](#41-tokens) and [bar formats](#37-bar_format).
|
|
141
|
+
|
|
142
|
+
When you don't know the total yet, you can set it to `nil` to switch to [indeterminate](#31-total) progress:
|
|
143
|
+
|
|
144
|
+
```ruby
|
|
145
|
+
# downloading [ <=> ]
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Use [TTY::ProgressBar::Multi](#6-ttyprogressbarmulti-api) to display multiple parallel progress bars.
|
|
149
|
+
|
|
150
|
+
Declare a top level bar and then register child bars:
|
|
107
151
|
|
|
108
152
|
```ruby
|
|
109
153
|
bars = TTY::ProgressBar::Multi.new("main [:bar] :percent")
|
|
110
154
|
|
|
111
155
|
bar1 = bars.register("one [:bar] :percent", total: 15)
|
|
112
156
|
bar2 = bars.register("two [:bar] :percent", total: 15)
|
|
157
|
+
```
|
|
113
158
|
|
|
114
|
-
bars
|
|
159
|
+
Then progress the child bars in parallel:
|
|
160
|
+
|
|
161
|
+
```ruby
|
|
162
|
+
bars.start # starts all registered bars timers
|
|
115
163
|
|
|
116
164
|
th1 = Thread.new { 15.times { sleep(0.1); bar1.advance } }
|
|
117
165
|
th2 = Thread.new { 15.times { sleep(0.1); bar2.advance } }
|
|
@@ -119,7 +167,7 @@ th2 = Thread.new { 15.times { sleep(0.1); bar2.advance } }
|
|
|
119
167
|
[th1, th2].each { |t| t.join }
|
|
120
168
|
```
|
|
121
169
|
|
|
122
|
-
|
|
170
|
+
A possible terminal output may look like this:
|
|
123
171
|
|
|
124
172
|
```ruby
|
|
125
173
|
# ┌ main [=============== ] 50%
|
|
@@ -131,10 +179,10 @@ which will produce:
|
|
|
131
179
|
|
|
132
180
|
### 2.1 advance
|
|
133
181
|
|
|
134
|
-
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,
|
|
182
|
+
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, a number of bytes for a downloaded file:
|
|
135
183
|
|
|
136
184
|
```ruby
|
|
137
|
-
bar.advance(
|
|
185
|
+
bar.advance(1024)
|
|
138
186
|
```
|
|
139
187
|
|
|
140
188
|
You can also pass negative steps if you wish to backtrack the progress:
|
|
@@ -143,13 +191,13 @@ You can also pass negative steps if you wish to backtrack the progress:
|
|
|
143
191
|
bar.advance(-1)
|
|
144
192
|
```
|
|
145
193
|
|
|
146
|
-
Note
|
|
194
|
+
*Note:* If a progress bar has already finished then any negative steps will not set it back to desired value.
|
|
147
195
|
|
|
148
196
|
### 2.2 iterate
|
|
149
197
|
|
|
150
198
|
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.
|
|
151
199
|
|
|
152
|
-
First, create a progress bar without a total which will be
|
|
200
|
+
First, create a progress bar without a total which will be automatically updated for you once iteration starts:
|
|
153
201
|
|
|
154
202
|
```ruby
|
|
155
203
|
bar = TTY::ProgressBar.new("[:bar]")
|
|
@@ -161,7 +209,7 @@ Then, either directly iterate over a collection by yielding values to a block:
|
|
|
161
209
|
bar.iterate(30.times) { |v| ... }
|
|
162
210
|
```
|
|
163
211
|
|
|
164
|
-
|
|
212
|
+
Or return an `Enumerator`:
|
|
165
213
|
|
|
166
214
|
```ruby
|
|
167
215
|
progress = bar.iterate(30.times)
|
|
@@ -189,7 +237,7 @@ downloader = Enumerator.new do |y|
|
|
|
189
237
|
end
|
|
190
238
|
```
|
|
191
239
|
|
|
192
|
-
|
|
240
|
+
Would be used with progress bar with the total size matching the content size like so:
|
|
193
241
|
|
|
194
242
|
```ruby
|
|
195
243
|
bar = TTY::ProgressBar.new("[:bar]", total: content_size)
|
|
@@ -203,17 +251,17 @@ Please run [slow_process example](examples/slow_process.rb) to see this in actio
|
|
|
203
251
|
|
|
204
252
|
### 2.3 current=
|
|
205
253
|
|
|
206
|
-
|
|
254
|
+
A progress doesn't have to start from zero. You can set it to a given value using `current=` method:
|
|
207
255
|
|
|
208
256
|
```ruby
|
|
209
257
|
bar.current = 50
|
|
210
258
|
```
|
|
211
259
|
|
|
212
|
-
Note
|
|
260
|
+
*Note:* If a progress bar has already finished then setting current value will not have any effect.
|
|
213
261
|
|
|
214
262
|
### 2.4 ratio=
|
|
215
263
|
|
|
216
|
-
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:
|
|
264
|
+
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:
|
|
217
265
|
|
|
218
266
|
```ruby
|
|
219
267
|
bar.ratio = 0.5
|
|
@@ -221,13 +269,15 @@ bar.ratio = 0.5
|
|
|
221
269
|
|
|
222
270
|
### 2.5 width=
|
|
223
271
|
|
|
224
|
-
You can set how many terminal columns will the `:bar` actually span excluding any other tokens and/or text.
|
|
272
|
+
You can set how many terminal columns will the `:bar` actually span excluding any other tokens and/or text.
|
|
273
|
+
|
|
274
|
+
For example, if you need the bar to be always 20 columns wide do:
|
|
225
275
|
|
|
226
276
|
```ruby
|
|
227
277
|
bar.width = 20
|
|
228
278
|
```
|
|
229
279
|
|
|
230
|
-
|
|
280
|
+
Or with configuration options:
|
|
231
281
|
|
|
232
282
|
```ruby
|
|
233
283
|
bar = TTY::ProgressBar.new("[:bar]", width: 20)
|
|
@@ -235,7 +285,7 @@ bar = TTY::ProgressBar.new("[:bar]", width: 20)
|
|
|
235
285
|
|
|
236
286
|
### 2.6 start
|
|
237
287
|
|
|
238
|
-
By default the timer for internal time
|
|
288
|
+
By default the timer for internal time estimation is started automatically when the `advance` method is called. However, if you require control on when the progression timer is started use `start` call:
|
|
239
289
|
|
|
240
290
|
```ruby
|
|
241
291
|
bar.start # => sets timer and draws initial progress bar
|
|
@@ -243,15 +293,15 @@ bar.start # => sets timer and draws initial progress bar
|
|
|
243
293
|
|
|
244
294
|
### 2.7 update
|
|
245
295
|
|
|
246
|
-
Once
|
|
296
|
+
Once a progress bar has been started, you can change its configuration option(s) by calling `update`:
|
|
247
297
|
|
|
248
298
|
```ruby
|
|
249
|
-
bar.update(complete:
|
|
299
|
+
bar.update(complete: "+", frequency: 10)
|
|
250
300
|
```
|
|
251
301
|
|
|
252
302
|
### 2.8 finish
|
|
253
303
|
|
|
254
|
-
In order to immediately stop and finish
|
|
304
|
+
In order to immediately stop and finish progress of a bar call `finish`. This will finish drawing the progress by advancing it to 100% and returning to a new line.
|
|
255
305
|
|
|
256
306
|
```ruby
|
|
257
307
|
bar.finish
|
|
@@ -259,13 +309,23 @@ bar.finish
|
|
|
259
309
|
|
|
260
310
|
### 2.9 stop
|
|
261
311
|
|
|
262
|
-
In order to immediately stop
|
|
312
|
+
In order to immediately stop a bar in the current position and thus prevent any further progress use `stop`:
|
|
263
313
|
|
|
264
314
|
```ruby
|
|
265
315
|
bar.stop
|
|
266
316
|
```
|
|
267
317
|
|
|
268
|
-
### 2.10
|
|
318
|
+
### 2.10 pause
|
|
319
|
+
|
|
320
|
+
A running progress bar can be paused at the current position using `pause` method:
|
|
321
|
+
|
|
322
|
+
```ruby
|
|
323
|
+
bar.pause
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
A paused progress bar will stop accumulating any time measurements like elapsed time. It also won't return to a new line, so a progress animation can be smoothly resumed.
|
|
327
|
+
|
|
328
|
+
### 2.11 reset
|
|
269
329
|
|
|
270
330
|
In order to reset currently running or finished progress bar to its original configuration and initial position use `reset` like so:
|
|
271
331
|
|
|
@@ -273,23 +333,57 @@ In order to reset currently running or finished progress bar to its original con
|
|
|
273
333
|
bar.reset
|
|
274
334
|
```
|
|
275
335
|
|
|
276
|
-
After resetting
|
|
336
|
+
After resetting a progress bar, if you wish to draw and start a bar and its timers use `start` call.
|
|
337
|
+
|
|
338
|
+
### 2.12 resume
|
|
339
|
+
|
|
340
|
+
When a bar is stopped or paused, you can continue its progression using the `resume` method.
|
|
341
|
+
|
|
342
|
+
```ruby
|
|
343
|
+
bar.resume
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
A resumed progression will continue accumulating the total elapsed time without including time intervals for pausing or stopping.
|
|
277
347
|
|
|
278
|
-
### 2.
|
|
348
|
+
### 2.13 complete?
|
|
279
349
|
|
|
280
|
-
During
|
|
350
|
+
During progression you can check whether a bar is finished or not by calling `complete?`. The bar will only return `true` if the progression finished successfully, otherwise `false` will be returned.
|
|
281
351
|
|
|
282
352
|
```ruby
|
|
283
353
|
bar.complete? # => false
|
|
284
354
|
```
|
|
285
355
|
|
|
286
|
-
### 2.
|
|
356
|
+
### 2.14 paused?
|
|
357
|
+
|
|
358
|
+
To check whether a progress bar is paused or not use `paused?`:
|
|
359
|
+
|
|
360
|
+
```ruby
|
|
361
|
+
bar.paused? # => true
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
### 2.15 stopped?
|
|
365
|
+
|
|
366
|
+
To check whether a progress bar is stopped or not use `stopped?`:
|
|
367
|
+
|
|
368
|
+
```ruby
|
|
369
|
+
bar.stopped? # => true
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
### 2.16 indeterminate?
|
|
287
373
|
|
|
288
|
-
|
|
374
|
+
You can make a progress bar indeterminate by setting `:total` to `nil`. In this state, a progress bar animation is displayed to show unbounded task. You can check whether the progress bar is indeterminate with the `indeterminate?` method:
|
|
289
375
|
|
|
290
376
|
```ruby
|
|
291
|
-
bar.
|
|
292
|
-
|
|
377
|
+
bar.indeterminate? # => false
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
### 2.17 resize
|
|
381
|
+
|
|
382
|
+
If you want to change a progress bar's current width, use `resize` and pass 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.
|
|
383
|
+
|
|
384
|
+
```ruby
|
|
385
|
+
bar.resize # determine terminal width and scale accordingly
|
|
386
|
+
bar.resize(50) # will resize bar proportionately from this point onwards
|
|
293
387
|
```
|
|
294
388
|
|
|
295
389
|
To handle automatic resizing you can trap `:WINCH` signal:
|
|
@@ -298,66 +392,229 @@ To handle automatic resizing you can trap `:WINCH` signal:
|
|
|
298
392
|
trap(:WINCH) { bar.resize }
|
|
299
393
|
```
|
|
300
394
|
|
|
301
|
-
### 2.
|
|
395
|
+
### 2.18 on
|
|
302
396
|
|
|
303
|
-
|
|
397
|
+
A progress bar fires events when it is progressing, paused, stopped or finished. You can register to listen for these events using the `on` message.
|
|
304
398
|
|
|
305
|
-
Every time an `advance` is called the `:progress` event gets fired which you can listen for:
|
|
399
|
+
Every time an `advance` is called the `:progress` event gets fired which you can listen for inside a block. A first yielded argument is the actual amount of progress:
|
|
306
400
|
|
|
307
401
|
```ruby
|
|
308
|
-
bar.on(:progress) { ... }
|
|
402
|
+
bar.on(:progress) { |amount| ... }
|
|
309
403
|
```
|
|
310
404
|
|
|
311
|
-
When
|
|
405
|
+
When a progress bar finishes and completes then the `:done` event is fired. You can listen for this event:
|
|
312
406
|
|
|
313
407
|
```ruby
|
|
314
408
|
bar.on(:done) { ... }
|
|
315
409
|
```
|
|
316
410
|
|
|
317
|
-
Alternatively, when
|
|
411
|
+
Alternatively, when a progress bar gets stopped the `:stopped` event is fired. You can listen for this event:
|
|
318
412
|
|
|
319
413
|
```ruby
|
|
320
414
|
bar.on(:stopped) { ... }
|
|
321
415
|
```
|
|
322
416
|
|
|
417
|
+
Anytime a progress bar is paused the `:paused` event will be fired. To listen for this event do:
|
|
418
|
+
|
|
419
|
+
```ruby
|
|
420
|
+
bar.on(:paused) { ... }
|
|
421
|
+
```
|
|
422
|
+
|
|
323
423
|
## 3. Configuration
|
|
324
424
|
|
|
325
425
|
There are number of configuration options that can be provided:
|
|
326
426
|
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
331
|
-
* [:head](#
|
|
332
|
-
* [:
|
|
333
|
-
* [:
|
|
334
|
-
* [:
|
|
335
|
-
*
|
|
336
|
-
*
|
|
427
|
+
* [:total](#31-total) - the total number of steps to completion.
|
|
428
|
+
* [:width](#32-width) - the number of terminal columns for displaying a bar excluding other tokens. Defaults to total steps.
|
|
429
|
+
* [:complete](#33-complete) - the completion character, by default `=`.
|
|
430
|
+
* [:incomplete](#34-incomplete) - the incomplete character, by default single space.
|
|
431
|
+
* [:head](#35-head) - the head character, by default `=`.
|
|
432
|
+
* [:unknown](#36-unknown) - the character(s) used to show indeterminate progress, defaults to `<=>`.
|
|
433
|
+
* [:bar_format](#37-bar_format) - the predefined bar format, by default `:classic`.
|
|
434
|
+
* [:output](#38-output) - the output stream defaulting to `stderr`.
|
|
435
|
+
* [:frequency](#39-frequency) - used to throttle the output, by default `0`.
|
|
436
|
+
* [:interval](#310-interval) - the time interval used to measure rate, by default `1 sec`.
|
|
437
|
+
* [:hide_cursor](#311-hide_cursor) - whether to hide the console cursor or not, defaults to `false`.
|
|
438
|
+
* [:clear](#312-clear) - whether to clear the finished bar or not, defaults to `false`.
|
|
439
|
+
* [:clear_head](#313-clear_head) - whether to clear the head character when the progress is done or not, defaults to `false`.
|
|
337
440
|
|
|
338
441
|
All the above options can be passed in as hash options or block parameters:
|
|
339
442
|
|
|
340
443
|
```ruby
|
|
341
|
-
TTY::ProgressBar.new
|
|
444
|
+
bar = TTY::ProgressBar.new("[:bar]") do |config|
|
|
342
445
|
config.total = 30
|
|
343
446
|
config.frequency = 10
|
|
344
447
|
config.clear = true
|
|
345
448
|
end
|
|
346
449
|
```
|
|
347
450
|
|
|
348
|
-
|
|
451
|
+
The progress bar's configuration can also be changed at runtime with `configure`:
|
|
452
|
+
|
|
453
|
+
```ruby
|
|
454
|
+
bar.configure do |config|
|
|
455
|
+
config.total = 100 # takes precedence over the original value
|
|
456
|
+
config.frequencye = 20
|
|
457
|
+
end
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
Or with the [update](#27-update) method:
|
|
461
|
+
|
|
462
|
+
```ruby
|
|
463
|
+
bar.update(total: 100, frequency: 20)
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
### 3.1 :total
|
|
467
|
+
|
|
468
|
+
The `:total` option determines the final value at which the progress bar fills up and stops.
|
|
469
|
+
|
|
470
|
+
```ruby
|
|
471
|
+
TTY::ProgressBar.new("[:bar]", total: 30)
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
Setting `:total` to `nil` or leaving it out will cause the progress bar to switch to indeterminate mode. Instead of showing completeness for a task, it will render animation like `<=>` that moves left and right:
|
|
475
|
+
|
|
476
|
+
```ruby
|
|
477
|
+
# [ <=> ]
|
|
478
|
+
```
|
|
479
|
+
|
|
480
|
+
The indeterminate mode is useful to show time-consuming and unbounded task.
|
|
481
|
+
|
|
482
|
+
Run [examples/indeterminate](https://github.com/piotrmurach/tty-progressbar/blob/master/examples/indeterminate.rb) to see indeterminate progress animation in action.
|
|
483
|
+
|
|
484
|
+
### 3.2 :width
|
|
485
|
+
|
|
486
|
+
The progress bar width defaults to the total value and is capped at the maximum terminal width minus all the labels. If you want to enforce the bar to have a specific length use the `:width` option:
|
|
487
|
+
|
|
488
|
+
```ruby
|
|
489
|
+
TTY::ProgressBar.new("[:bar]", width: 30)
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
### 3.3 :complete
|
|
493
|
+
|
|
494
|
+
By default, the `=` character is used to mark progression but this can be changed with `:complete` option:
|
|
495
|
+
|
|
496
|
+
```ruby
|
|
497
|
+
TTY::ProgressBar.new("[:bar]", complete: "x")
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
Then the output could look like this:
|
|
501
|
+
|
|
502
|
+
```ruby
|
|
503
|
+
# [xxxxxxxx ]
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
### 3.4 :incomplete
|
|
507
|
+
|
|
508
|
+
By default no characters are shown to mark the remaining progress in the `:classic` bar format. Other [bar styles](#37-bar_format) often have incomplete character. You can change this with `:incomplete` option:
|
|
509
|
+
|
|
510
|
+
```ruby
|
|
511
|
+
TTY::ProgressBar.new("[:bar]", incomplete: "_")
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
A possible output may look like this:
|
|
515
|
+
|
|
516
|
+
```ruby
|
|
517
|
+
# [======_________]
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
### 3.5 :head
|
|
349
521
|
|
|
350
522
|
If you prefer for the animated bar to display a specific character for a head of progression then use `:head` option:
|
|
351
523
|
|
|
352
524
|
```ruby
|
|
353
|
-
|
|
354
|
-
|
|
525
|
+
TTY::ProgressBar.new("[:bar]", head: ">")
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
This could result in output like this:
|
|
529
|
+
|
|
530
|
+
```ruby
|
|
355
531
|
# [=======> ]
|
|
356
532
|
```
|
|
357
533
|
|
|
358
|
-
### 3.
|
|
534
|
+
### 3.6 :unknown
|
|
535
|
+
|
|
536
|
+
By default, a progress bar shows indeterminate progress using `<=>` characters:
|
|
537
|
+
|
|
538
|
+
```ruby
|
|
539
|
+
# [ <=> ]
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
Other [bar formats](#37-bar_format) use different characters.
|
|
543
|
+
|
|
544
|
+
You can change this with the `:unknown` option:
|
|
545
|
+
|
|
546
|
+
```ruby
|
|
547
|
+
TTY::ProgressBar.new("[:bar]", unknown: "<?>")
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
This may result in the following output:
|
|
551
|
+
|
|
552
|
+
```ruby
|
|
553
|
+
# [ <?> ]
|
|
554
|
+
````
|
|
555
|
+
|
|
556
|
+
### 3.7 :bar_format
|
|
557
|
+
|
|
558
|
+
There are number of preconfigured bar formats you can choose from.
|
|
559
|
+
|
|
560
|
+
| Name | Determinate | Indeterminate |
|
|
561
|
+
|:-----------|:-------------|:--------------|
|
|
562
|
+
| `:arrow` | `▸▸▸▸▸▹▹▹▹▹` | `◂▸` |
|
|
563
|
+
| `:asterisk`| `✱✱✱✱✱✳✳✳✳✳` | `✳✱✳` |
|
|
564
|
+
| `:blade` | `▰▰▰▰▰▱▱▱▱▱` | `▱▰▱` |
|
|
565
|
+
| `:block` | `█████░░░░░` | `█` |
|
|
566
|
+
| `:box` | `■■■■■□□□□□` | `□■□` |
|
|
567
|
+
| `:bracket` | `❭❭❭❭❭❭❭❭❭❭` | `❬=❭` |
|
|
568
|
+
| `:burger` | `≡≡≡≡≡≡≡≡≡≡` | `<≡>` |
|
|
569
|
+
| `:button` | `⦿⦿⦿⦿⦿⦾⦾⦾⦾⦾` | `⦾⦿⦾` |
|
|
570
|
+
| `:chevron` | `››››››››››` | `‹=›` |
|
|
571
|
+
| `:circle` | `●●●●●○○○○○` | `○●○` |
|
|
572
|
+
| `:classic` | `==========` | `<=>` |
|
|
573
|
+
| `:crate` | `▣▣▣▣▣⬚⬚⬚⬚⬚` | `⬚▣⬚` |
|
|
574
|
+
| `:diamond` | `♦♦♦♦♦♢♢♢♢♢` | `♢♦♢` |
|
|
575
|
+
| `:dot` | `･･････････` | `･･･` |
|
|
576
|
+
| `:heart` | `♥♥♥♥♥♡♡♡♡♡` | `♡♥♡` |
|
|
577
|
+
| `:rectangle` | `▮▮▮▮▮▯▯▯▯▯` | `▯▮▯` |
|
|
578
|
+
| `:square` | `▪▪▪▪▪▫▫▫▫▫` | `▫▪▫` |
|
|
579
|
+
| `:star` | `★★★★★☆☆☆☆☆` | `☆★☆` |
|
|
580
|
+
| `:track` | `▬▬▬▬▬═════` | `═▬═` |
|
|
581
|
+
| `:tread` | `❱❱❱❱❱❱❱❱❱❱` | `❰=❱` |
|
|
582
|
+
| `:triangle`| `▶▶▶▶▶▷▷▷▷▷` | `◀▶` |
|
|
583
|
+
| `:wave` | `~~~~~_____` | `<~>` |
|
|
584
|
+
|
|
585
|
+
For example, you can specify `:box` format with the `:bar_format` option:
|
|
586
|
+
|
|
587
|
+
```ruby
|
|
588
|
+
TTY::ProgressBar.new("[:bar]", bar_format: :box)
|
|
589
|
+
```
|
|
590
|
+
|
|
591
|
+
This will result in output like this:
|
|
592
|
+
|
|
593
|
+
```ruby
|
|
594
|
+
# [■■■■■□□□□□□□□□□]
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
You can overwrite `:complete`, `:incomplete`, `:head` and `:unknown` characters:
|
|
359
598
|
|
|
360
|
-
|
|
599
|
+
```ruby
|
|
600
|
+
TTY::ProgressBar.new("[:bar]", bar_format: :box, incomplete: " ", unknown: "?")
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
This will display the following when total is given:
|
|
604
|
+
|
|
605
|
+
```ruby
|
|
606
|
+
# [■■■■■ ]
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
And for the unknown progress the `?` character will move from left to right:
|
|
610
|
+
|
|
611
|
+
```ruby
|
|
612
|
+
# [ ? ]
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
### 3.8 :output
|
|
616
|
+
|
|
617
|
+
A progress bar only outputs to a console. When the output is, for example, redirected to a file or a pipe, the progress bar doesn't get printed. This is so, for example, your error logs do not overflow with progress bar output.
|
|
361
618
|
|
|
362
619
|
You can change where console output is streamed with `:output` option:
|
|
363
620
|
|
|
@@ -367,7 +624,7 @@ bar = TTY::ProgressBar.new(output: $stdout)
|
|
|
367
624
|
|
|
368
625
|
The output stream defaults to `stderr`.
|
|
369
626
|
|
|
370
|
-
### 3.
|
|
627
|
+
### 3.9 :frequency
|
|
371
628
|
|
|
372
629
|
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.
|
|
373
630
|
|
|
@@ -377,9 +634,9 @@ The `frequency` option accepts `integer` representing number of `Hz` units, for
|
|
|
377
634
|
TTY::ProgressBar.new("[:bar]", total: 30, frequency: 10) # 10 Hz
|
|
378
635
|
```
|
|
379
636
|
|
|
380
|
-
### 3.
|
|
637
|
+
### 3.10 :interval
|
|
381
638
|
|
|
382
|
-
|
|
639
|
+
Every time `advance` method is called, a time sample is taken for speed measurement. By default, all the samples are grouped in second intervals to provide a rate of speed. You can change this by passing the `interval` option.
|
|
383
640
|
|
|
384
641
|
The `interval` option is an `integer` that represents the number of seconds, for example, interval of `60` would mean that speed is measured per 1 minute.
|
|
385
642
|
|
|
@@ -389,6 +646,55 @@ TTY::ProgressBar.new(":rate/minute", total: 100, interval: 60) # 1 minute
|
|
|
389
646
|
TTY::ProgressBar.new(":rate/hour", total: 100, interval: 3600) # 1 hour
|
|
390
647
|
```
|
|
391
648
|
|
|
649
|
+
### 3.11 :hide_cursor
|
|
650
|
+
|
|
651
|
+
By default the cursor is visible during progress bar rendering. If you wish to hide it, you can do so with the `:hide_cursor` option.
|
|
652
|
+
|
|
653
|
+
Please note that hiding cursor changes user's terminal and you need to ensure that the cursor is made visible after your code finishes. This means also handling premature interrupt signals and other unpredictable events.
|
|
654
|
+
|
|
655
|
+
One solution is to wrap your progress rendering inside the `begin` and `ensure` like so:
|
|
656
|
+
|
|
657
|
+
```ruby
|
|
658
|
+
progress = TTY::ProgressBar.new("[:bar]", hide_cursor: true)
|
|
659
|
+
|
|
660
|
+
begin
|
|
661
|
+
# logic to advance progress bar
|
|
662
|
+
ensure
|
|
663
|
+
progress.stop # or progress.finish
|
|
664
|
+
# both methods will ensure that cursor is made visible again
|
|
665
|
+
end
|
|
666
|
+
```
|
|
667
|
+
|
|
668
|
+
### 3.12 :clear
|
|
669
|
+
|
|
670
|
+
By default, when a progress bar finishes it returns to a new line leaving the last progress output behind.
|
|
671
|
+
|
|
672
|
+
If you prefer to erase a progress bar when it is finished use `:clear` option:
|
|
673
|
+
|
|
674
|
+
```ruby
|
|
675
|
+
TTY::ProgressBar.new("[:bar]", clear: true)
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
### 3.13 :clear_head
|
|
679
|
+
|
|
680
|
+
When a progress bar finishes and its animation includes [:head](#35-head) character, the character will remain in the output:
|
|
681
|
+
|
|
682
|
+
```ruby
|
|
683
|
+
# [=============>]
|
|
684
|
+
```
|
|
685
|
+
|
|
686
|
+
To replace a head character when a progress bar is finished use `:clear_head` option:
|
|
687
|
+
|
|
688
|
+
```ruby
|
|
689
|
+
TTY::ProgressBar.new("[:bar]", clear_head: true)
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
This will result in the following output:
|
|
693
|
+
|
|
694
|
+
```ruby
|
|
695
|
+
# [==============]
|
|
696
|
+
```
|
|
697
|
+
|
|
392
698
|
## 4. Formatting
|
|
393
699
|
|
|
394
700
|
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:
|
|
@@ -408,38 +714,55 @@ These are the tokens that are currently supported:
|
|
|
408
714
|
* `:total_byte` the total progress in bytes
|
|
409
715
|
* `:percent` the completion percentage
|
|
410
716
|
* `:elapsed` the elapsed time in seconds
|
|
411
|
-
* `:eta` the
|
|
717
|
+
* `:eta` the estimated time to completion in seconds
|
|
718
|
+
* `:eta_time` the estimated time of day at completion
|
|
412
719
|
* `:rate` the current rate of progression per second
|
|
413
|
-
* `:byte_rate` the current rate of
|
|
720
|
+
* `:byte_rate` the current rate of progression in bytes per second
|
|
414
721
|
* `:mean_rate` the averaged rate of progression per second
|
|
415
722
|
* `:mean_byte` the averaged rate of progression in bytes per second
|
|
416
723
|
|
|
724
|
+
In the indeterminate mode, the progress bar displays `-` for tokens that cannot be calculated like `:total`, `:total_byte`, `:percent` and `:eta`. The following format:
|
|
725
|
+
|
|
726
|
+
```ruby
|
|
727
|
+
"[:bar] :current/:total :total_byte :percent ET::elapsed ETA::eta :rate/s"
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
Will result in:
|
|
731
|
+
|
|
732
|
+
```ruby
|
|
733
|
+
# [ <=> ] 23/- -B -% ET: 1s ETA:--s 18.01/s
|
|
734
|
+
```
|
|
735
|
+
|
|
417
736
|
### 4.2 Custom Formatters
|
|
418
737
|
|
|
419
738
|
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.
|
|
420
739
|
|
|
421
|
-
For example,
|
|
740
|
+
For example, let's say you want to add `:time` token. First, start by creating a custom formatter class called `TimeFormatter` that will dynamically update `:time` token in the formatted string. In order for the `TimeFormatter` to recognise the `:time` token, you'll need to include the `TTY::ProgressBar::Formatter` module with a regular expression matching the token like so:
|
|
422
741
|
|
|
423
742
|
```ruby
|
|
424
743
|
class TimeFormatter
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
744
|
+
include TTY::ProgressBar::Formatter[/:time/i]
|
|
745
|
+
...
|
|
746
|
+
end
|
|
747
|
+
```
|
|
428
748
|
|
|
429
|
-
|
|
430
|
-
value.to_s =~ /:time/
|
|
431
|
-
end
|
|
749
|
+
Next, add `call` method that will substitute the matched token with an actual value. For example, to see the time elapsed since the start do:
|
|
432
750
|
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
751
|
+
```ruby
|
|
752
|
+
class TimeFormatter
|
|
753
|
+
include TTY::ProgressBar::Formatter[/:time/i]
|
|
754
|
+
|
|
755
|
+
def call(value) # specify how display string is formatted
|
|
756
|
+
# access current progress bar instance to read start time
|
|
757
|
+
elapsed = (Time.now - progress.start_time).to_s
|
|
758
|
+
value.gsub(matcher, elapsed) # replace :time token with a value
|
|
436
759
|
end
|
|
437
760
|
end
|
|
438
761
|
```
|
|
439
762
|
|
|
440
|
-
Notice that you have access to all the configuration options inside the formatter by simply invoking them on the
|
|
763
|
+
Notice that you have access to all the configuration options inside the formatter by simply invoking them on the `progress` instance.
|
|
441
764
|
|
|
442
|
-
Create **TTY::ProgressBar** instance
|
|
765
|
+
Create **TTY::ProgressBar** instance using the new token:
|
|
443
766
|
|
|
444
767
|
```ruby
|
|
445
768
|
bar = TTY::ProgressBar.new(":time", total: 30)
|
|
@@ -451,7 +774,7 @@ Then add `TimeFormatter` to the pipeline like so:
|
|
|
451
774
|
bar.use TimeFormatter
|
|
452
775
|
```
|
|
453
776
|
|
|
454
|
-
|
|
777
|
+
Then invoke progression:
|
|
455
778
|
|
|
456
779
|
```ruby
|
|
457
780
|
bar.advance
|
|
@@ -459,19 +782,47 @@ bar.advance
|
|
|
459
782
|
|
|
460
783
|
### 4.3 Custom Tokens
|
|
461
784
|
|
|
462
|
-
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
|
|
785
|
+
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 a progress bar. For example:
|
|
463
786
|
|
|
464
787
|
```ruby
|
|
465
788
|
bar = TTY::ProgressBar.new("(:current) :title", total: 4)
|
|
466
|
-
bar.advance(title:
|
|
467
|
-
bar.advance(3, title:
|
|
789
|
+
bar.advance(title: "Hello Piotr!")
|
|
790
|
+
bar.advance(3, title: "Bye Piotr!")
|
|
791
|
+
```
|
|
792
|
+
|
|
793
|
+
This will output:
|
|
794
|
+
|
|
795
|
+
```ruby
|
|
796
|
+
# (1) Hello Piotr!
|
|
797
|
+
# (4) Bye Piotr!
|
|
798
|
+
```
|
|
799
|
+
|
|
800
|
+
### 4.4 Unicode
|
|
801
|
+
|
|
802
|
+
The format string as well as [:complete](#33-complete), [:head](#35-head), [:incomplete](#34-incomplete) and [:unknown](#36-unknown) configuration options can contain Unicode characters that aren't monospaced.
|
|
803
|
+
|
|
804
|
+
For example, you can specify complete bar progression character to be Unicode non-monospaced:
|
|
805
|
+
|
|
806
|
+
```ruby
|
|
807
|
+
bar = TTY::ProgressBar.new("Unicode [:bar]", total: 30, complete: "あ")
|
|
808
|
+
```
|
|
809
|
+
|
|
810
|
+
Advancing above progress bar to completion will fit `あ` characters in 30 terminal columns:
|
|
811
|
+
|
|
812
|
+
```ruby
|
|
813
|
+
# Unicode [あああああああああああああああ]
|
|
814
|
+
```
|
|
815
|
+
|
|
816
|
+
Similarly, the formatted string can include Unicode characters:
|
|
817
|
+
|
|
818
|
+
```ruby
|
|
819
|
+
bar = TTY::ProgressBar.new("あめかんむり[:bar]", total: 20)
|
|
468
820
|
```
|
|
469
821
|
|
|
470
|
-
|
|
822
|
+
A finished progress bar will also fit within allowed width:
|
|
471
823
|
|
|
472
824
|
```ruby
|
|
473
|
-
|
|
474
|
-
(4) Bye Piotr!
|
|
825
|
+
# あめかんむり[== ]
|
|
475
826
|
```
|
|
476
827
|
|
|
477
828
|
## 5. Logging
|
|
@@ -479,11 +830,11 @@ which outputs:
|
|
|
479
830
|
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.
|
|
480
831
|
|
|
481
832
|
```ruby
|
|
482
|
-
bar.log(
|
|
833
|
+
bar.log("Piotrrrrr")
|
|
483
834
|
bar.advance
|
|
484
835
|
```
|
|
485
836
|
|
|
486
|
-
|
|
837
|
+
This could result in the following output:
|
|
487
838
|
|
|
488
839
|
```ruby
|
|
489
840
|
# Piotrrrrr
|
|
@@ -494,14 +845,13 @@ will result in:
|
|
|
494
845
|
|
|
495
846
|
### 6.1 new
|
|
496
847
|
|
|
497
|
-
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:
|
|
848
|
+
The multi progress bar can be created in two ways. If you simply want to group multiple progress bars together, you can create multi bar without a format string like so:
|
|
498
849
|
|
|
499
850
|
```ruby
|
|
500
851
|
TTY::ProgressBar::Multi.new
|
|
501
852
|
```
|
|
502
853
|
|
|
503
|
-
|
|
504
|
-
However, if you want a top level multibar that tracks all the registered progress bars then provide a formatted string:
|
|
854
|
+
However, if you want a top level multibar that tracks progress of all the registered progress bars then you need to provide a formatted string:
|
|
505
855
|
|
|
506
856
|
```ruby
|
|
507
857
|
TTY::ProgressBar::Multi.new("main [:bar] :percent")
|
|
@@ -516,15 +866,15 @@ multibar = TTY::ProgressBar::Multi.new
|
|
|
516
866
|
bar = multibar.register("[:bar]", total: 30)
|
|
517
867
|
```
|
|
518
868
|
|
|
519
|
-
The `register` call returns the newly created progress bar
|
|
869
|
+
The `register` call returns the newly created progress bar that can be changed using all the available [progress bar API](#2-ttyprogressbar-api) methods.
|
|
520
870
|
|
|
521
|
-
|
|
871
|
+
*Note:* Remember to specify total value for each registered progress bar, either when sending `register` message or when using `update` to dynamically assign the total value.
|
|
522
872
|
|
|
523
873
|
### 6.3 advance
|
|
524
874
|
|
|
525
875
|
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.
|
|
526
876
|
|
|
527
|
-
For example, to display two bars
|
|
877
|
+
For example, to display two bars asynchronously, first register them with the multi bar:
|
|
528
878
|
|
|
529
879
|
```ruby
|
|
530
880
|
bar1 = multibar.register("one [:bar]", total: 20)
|
|
@@ -546,7 +896,7 @@ Finally, wait for the threads to finish:
|
|
|
546
896
|
|
|
547
897
|
### 6.4 start
|
|
548
898
|
|
|
549
|
-
By default the top level multi bar will be rendered as the first bar and have its timer started when
|
|
899
|
+
By default the top level multi bar will be rendered as the first bar and have its timer started when one of the registered bars advances. However, if you wish to start timers and draw the top level multi bar do:
|
|
550
900
|
|
|
551
901
|
```ruby
|
|
552
902
|
multibar.start # => sets timer and draws top level multi progress bar
|
|
@@ -554,7 +904,7 @@ multibar.start # => sets timer and draws top level multi progress bar
|
|
|
554
904
|
|
|
555
905
|
### 6.5 finish
|
|
556
906
|
|
|
557
|
-
In order to finish all progress bars call `finish`. This will finish the top level progress bar, if it exists,
|
|
907
|
+
In order to finish all progress bars call `finish`. This will finish the top level progress bar, if it exists, and any registered progress bar still in progress.
|
|
558
908
|
|
|
559
909
|
```ruby
|
|
560
910
|
multibar.finish
|
|
@@ -568,7 +918,23 @@ Use `stop` to terminate immediately all progress bars registered with the multib
|
|
|
568
918
|
multibar.stop
|
|
569
919
|
```
|
|
570
920
|
|
|
571
|
-
### 6.7
|
|
921
|
+
### 6.7 pause
|
|
922
|
+
|
|
923
|
+
All running progress bars can be paused at their current positions using the `pause` method:
|
|
924
|
+
|
|
925
|
+
```ruby
|
|
926
|
+
multibar.pause
|
|
927
|
+
````
|
|
928
|
+
|
|
929
|
+
### 6.8 resume
|
|
930
|
+
|
|
931
|
+
When one or more registered progress bar is stopped or paused, they can be resumed all at once using the `resume` method:
|
|
932
|
+
|
|
933
|
+
```ruby
|
|
934
|
+
multibar.resume
|
|
935
|
+
```
|
|
936
|
+
|
|
937
|
+
### 6.9 complete?
|
|
572
938
|
|
|
573
939
|
To check if all registered progress bars have been successfully finished use `complete?`
|
|
574
940
|
|
|
@@ -576,7 +942,23 @@ To check if all registered progress bars have been successfully finished use `co
|
|
|
576
942
|
multibar.complete? # => true
|
|
577
943
|
```
|
|
578
944
|
|
|
579
|
-
### 6.
|
|
945
|
+
### 6.10 paused?
|
|
946
|
+
|
|
947
|
+
To check whether all progress bars are paused or not use `paused?`:
|
|
948
|
+
|
|
949
|
+
```ruby
|
|
950
|
+
multibar.paused? # => true
|
|
951
|
+
```
|
|
952
|
+
|
|
953
|
+
### 6.11 stopped?
|
|
954
|
+
|
|
955
|
+
To check whether all progress bars are stopped or not use `stopped?`:
|
|
956
|
+
|
|
957
|
+
```ruby
|
|
958
|
+
multibar.stopped? # => true
|
|
959
|
+
```
|
|
960
|
+
|
|
961
|
+
### 6.12 on
|
|
580
962
|
|
|
581
963
|
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.
|
|
582
964
|
|
|
@@ -592,21 +974,27 @@ When all the registered progress bars finish and complete then the `:done` event
|
|
|
592
974
|
multibar.on(:done) { ... }
|
|
593
975
|
```
|
|
594
976
|
|
|
595
|
-
|
|
977
|
+
When any of the progress bars gets stopped the `:stopped` event is fired. You can listen for this event:
|
|
596
978
|
|
|
597
979
|
```ruby
|
|
598
980
|
multibar.on(:stopped) { ... }
|
|
599
981
|
```
|
|
600
982
|
|
|
601
|
-
|
|
983
|
+
Anytime a registered progress bar pauses, a `:paused` event will be fired. To listen for this event do:
|
|
984
|
+
|
|
985
|
+
```ruby
|
|
986
|
+
multibar.on(:paused) { ... }
|
|
987
|
+
```
|
|
988
|
+
|
|
989
|
+
### 6.13 :style
|
|
602
990
|
|
|
603
991
|
In addition to all [configuration options](#3-configuration) you can style multi progress bar:
|
|
604
992
|
|
|
605
993
|
```ruby
|
|
606
994
|
TTY::ProgressBar::Multi.new("[:bar]", style: {
|
|
607
|
-
top:
|
|
608
|
-
middle:
|
|
609
|
-
bottom:
|
|
995
|
+
top: ". ",
|
|
996
|
+
middle: "|-> ",
|
|
997
|
+
bottom: "|__ "
|
|
610
998
|
})
|
|
611
999
|
```
|
|
612
1000
|
|
|
@@ -619,7 +1007,7 @@ This section demonstrates some of the possible uses for the **TTY::ProgressBar**
|
|
|
619
1007
|
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:
|
|
620
1008
|
|
|
621
1009
|
```ruby
|
|
622
|
-
require
|
|
1010
|
+
require "pastel"
|
|
623
1011
|
|
|
624
1012
|
pastel = Pastel.new
|
|
625
1013
|
green = pastel.on_green(" ")
|
|
@@ -672,6 +1060,10 @@ This will result in output similar to:
|
|
|
672
1060
|
|
|
673
1061
|
This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
|
674
1062
|
|
|
1063
|
+
## Code of Conduct
|
|
1064
|
+
|
|
1065
|
+
Everyone interacting in the TTY::ProgressBar project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-progressbar/blob/master/CODE_OF_CONDUCT.md).
|
|
1066
|
+
|
|
675
1067
|
## Copyright
|
|
676
1068
|
|
|
677
|
-
Copyright (c) 2014
|
|
1069
|
+
Copyright (c) 2014 Piotr Murach. See LICENSE for further details.
|