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