1 | Flexible ascii progress bar.
|
2 |
|
3 | ## Installation
|
4 |
|
5 | ```bash
|
6 | $ npm install progress
|
7 | ```
|
8 |
|
9 | ## Usage
|
10 |
|
11 | First we create a `ProgressBar`, giving it a format string
|
12 | as well as the `total`, telling the progress bar when it will
|
13 | be considered complete. After that all we need to do is `tick()` appropriately.
|
14 |
|
15 | ```javascript
|
16 | var ProgressBar = require('progress');
|
17 |
|
18 | var bar = new ProgressBar(':bar', { total: 10 });
|
19 | var timer = setInterval(function () {
|
20 | bar.tick();
|
21 | if (bar.complete) {
|
22 | console.log('\ncomplete\n');
|
23 | clearInterval(timer);
|
24 | }
|
25 | }, 100);
|
26 | ```
|
27 |
|
28 | ### Options
|
29 |
|
30 | These are keys in the options object you can pass to the progress bar along with
|
31 | `total` as seen in the example above.
|
32 |
|
33 | - `curr` current completed index
|
34 | - `total` total number of ticks to complete
|
35 | - `width` the displayed width of the progress bar defaulting to total
|
36 | - `stream` the output stream defaulting to stderr
|
37 | - `head` head character defaulting to complete character
|
38 | - `complete` completion character defaulting to "="
|
39 | - `incomplete` incomplete character defaulting to "-"
|
40 | - `renderThrottle` minimum time between updates in milliseconds defaulting to 16
|
41 | - `clear` option to clear the bar on completion defaulting to false
|
42 | - `callback` optional function to call when the progress bar completes
|
43 |
|
44 | ### Tokens
|
45 |
|
46 | These are tokens you can use in the format of your progress bar.
|
47 |
|
48 | - `:bar` the progress bar itself
|
49 | - `:current` current tick number
|
50 | - `:total` total ticks
|
51 | - `:elapsed` time elapsed in seconds
|
52 | - `:percent` completion percentage
|
53 | - `:eta` estimated completion time in seconds
|
54 | - `:rate` rate of ticks per second
|
55 |
|
56 | ### Custom Tokens
|
57 |
|
58 | You can define custom tokens by adding a `{'name': value}` object parameter to your method (`tick()`, `update()`, etc.) calls.
|
59 |
|
60 | ```javascript
|
61 | var bar = new ProgressBar(':current: :token1 :token2', { total: 3 })
|
62 | bar.tick({
|
63 | 'token1': "Hello",
|
64 | 'token2': "World!\n"
|
65 | })
|
66 | bar.tick(2, {
|
67 | 'token1': "Goodbye",
|
68 | 'token2': "World!"
|
69 | })
|
70 | ```
|
71 | The above example would result in the output below.
|
72 |
|
73 | ```
|
74 | 1: Hello World!
|
75 | 3: Goodbye World!
|
76 | ```
|
77 |
|
78 | ## Examples
|
79 |
|
80 | ### Download
|
81 |
|
82 | In our download example each tick has a variable influence, so we pass the chunk
|
83 | length which adjusts the progress bar appropriately relative to the total
|
84 | length.
|
85 |
|
86 | ```javascript
|
87 | var ProgressBar = require('progress');
|
88 | var https = require('https');
|
89 |
|
90 | var req = https.request({
|
91 | host: 'download.github.com',
|
92 | port: 443,
|
93 | path: '/visionmedia-node-jscoverage-0d4608a.zip'
|
94 | });
|
95 |
|
96 | req.on('response', function(res){
|
97 | var len = parseInt(res.headers['content-length'], 10);
|
98 |
|
99 | console.log();
|
100 | var bar = new ProgressBar(' downloading [:bar] :rate/bps :percent :etas', {
|
101 | complete: '=',
|
102 | incomplete: ' ',
|
103 | width: 20,
|
104 | total: len
|
105 | });
|
106 |
|
107 | res.on('data', function (chunk) {
|
108 | bar.tick(chunk.length);
|
109 | });
|
110 |
|
111 | res.on('end', function () {
|
112 | console.log('\n');
|
113 | });
|
114 | });
|
115 |
|
116 | req.end();
|
117 | ```
|
118 |
|
119 | The above example result in a progress bar like the one below.
|
120 |
|
121 | ```
|
122 | downloading [===== ] 39/bps 29% 3.7s
|
123 | ```
|
124 |
|
125 | ### Interrupt
|
126 |
|
127 | To display a message during progress bar execution, use `interrupt()`
|
128 | ```javascript
|
129 | var ProgressBar = require('progress');
|
130 |
|
131 | var bar = new ProgressBar(':bar :current/:total', { total: 10 });
|
132 | var timer = setInterval(function () {
|
133 | bar.tick();
|
134 | if (bar.complete) {
|
135 | clearInterval(timer);
|
136 | } else if (bar.curr === 5) {
|
137 | bar.interrupt('this message appears above the progress bar\ncurrent progress is ' + bar.curr + '/' + bar.total);
|
138 | }
|
139 | }, 1000);
|
140 | ```
|
141 |
|
142 | You can see more examples in the `examples` folder.
|
143 |
|
144 | ## License
|
145 |
|
146 | MIT
|