www.aleph1.co.uk Git - yaffs-website/blob - node_modules/progress/Readme.md

   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 - `total` total number of ticks to complete
  34 - `width` the displayed width of the progress bar defaulting to total
  35 - `stream` the output stream defaulting to stderr
  36 - `complete` completion character defaulting to "="
  37 - `incomplete` incomplete character defaulting to "-"
  38 - `clear` option to clear the bar on completion defaulting to false
  39 - `callback` optional function to call when the progress bar completes
  40
  41 ### Tokens
  42
  43 These are tokens you can use in the format of your progress bar.
  44
  45 - `:bar` the progress bar itself
  46 - `:current` current tick number
  47 - `:total` total ticks
  48 - `:elapsed` time elapsed in seconds
  49 - `:percent` completion percentage
  50 - `:eta` estimated completion time in seconds
  51
  52 ## Examples
  53
  54 ### Download
  55
  56 In our download example each tick has a variable influence, so we pass the chunk
  57 length which adjusts the progress bar appropriately relative to the total
  58 length.
  59
  60 ```javascript
  61 var ProgressBar = require('../');
  62 var https = require('https');
  63
  64 var req = https.request({
  65   host: 'download.github.com',
  66   port: 443,
  67   path: '/visionmedia-node-jscoverage-0d4608a.zip'
  68 });
  69
  70 req.on('response', function(res){
  71   var len = parseInt(res.headers['content-length'], 10);
  72
  73   console.log();
  74   var bar = new ProgressBar('  downloading [:bar] :percent :etas', {
  75     complete: '=',
  76     incomplete: ' ',
  77     width: 20,
  78     total: len
  79   });
  80
  81   res.on('data', function (chunk) {
  82     bar.tick(chunk.length);
  83   });
  84
  85   res.on('end', function () {
  86     console.log('\n');
  87   });
  88 });
  89
  90 req.end();
  91 ```
  92
  93 The above example result in a progress bar like the one below.
  94
  95 ```
  96 downloading [=====             ] 29% 3.7s
  97 ```
  98
  99 You can see more examples in the `examples` folder.
 100
 101 ## License
 102
 103 MIT