1Flexible ascii progress bar. 2 3## Installation 4 5```bash 6$ npm install progress 7``` 8 9## Usage 10 11First we create a `ProgressBar`, giving it a format string 12as well as the `total`, telling the progress bar when it will 13be considered complete. After that all we need to do is `tick()` appropriately. 14 15```javascript 16var ProgressBar = require('progress'); 17 18var bar = new ProgressBar(':bar', { total: 10 }); 19var 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 30These 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 46These 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 58You can define custom tokens by adding a `{'name': value}` object parameter to your method (`tick()`, `update()`, etc.) calls. 59 60```javascript 61var bar = new ProgressBar(':current: :token1 :token2', { total: 3 }) 62bar.tick({ 63 'token1': "Hello", 64 'token2': "World!\n" 65}) 66bar.tick(2, { 67 'token1': "Goodbye", 68 'token2': "World!" 69}) 70``` 71The above example would result in the output below. 72 73``` 741: Hello World! 753: Goodbye World! 76``` 77 78## Examples 79 80### Download 81 82In our download example each tick has a variable influence, so we pass the chunk 83length which adjusts the progress bar appropriately relative to the total 84length. 85 86```javascript 87var ProgressBar = require('progress'); 88var https = require('https'); 89 90var req = https.request({ 91 host: 'download.github.com', 92 port: 443, 93 path: '/visionmedia-node-jscoverage-0d4608a.zip' 94}); 95 96req.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 116req.end(); 117``` 118 119The above example result in a progress bar like the one below. 120 121``` 122downloading [===== ] 39/bps 29% 3.7s 123``` 124 125### Interrupt 126 127To display a message during progress bar execution, use `interrupt()` 128```javascript 129var ProgressBar = require('progress'); 130 131var bar = new ProgressBar(':bar :current/:total', { total: 10 }); 132var 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 142You can see more examples in the `examples` folder. 143 144## License 145 146MIT 147