www.aleph1.co.uk Git - yaffs-website/blob - node_modules/progress/lib/node-progress.js

   1 /*!
   2  * node-progress
   3  * Copyright(c) 2011 TJ Holowaychuk <tj@vision-media.ca>
   4  * MIT Licensed
   5  */
   6
   7 /**
   8  * Expose `ProgressBar`.
   9  */
  10
  11 exports = module.exports = ProgressBar;
  12
  13 /**
  14  * Initialize a `ProgressBar` with the given `fmt` string and `options` or
  15  * `total`.
  16  *
  17  * Options:
  18  *
  19  *   - `total` total number of ticks to complete
  20  *   - `width` the displayed width of the progress bar defaulting to total
  21  *   - `stream` the output stream defaulting to stderr
  22  *   - `complete` completion character defaulting to "="
  23  *   - `incomplete` incomplete character defaulting to "-"
  24  *   - `callback` optional function to call when the progress bar completes
  25  *   - `clear` will clear the progress bar upon termination
  26  *
  27  * Tokens:
  28  *
  29  *   - `:bar` the progress bar itself
  30  *   - `:current` current tick number
  31  *   - `:total` total ticks
  32  *   - `:elapsed` time elapsed in seconds
  33  *   - `:percent` completion percentage
  34  *   - `:eta` eta in seconds
  35  *
  36  * @param {string} fmt
  37  * @param {object|number} options or total
  38  * @api public
  39  */
  40
  41 function ProgressBar(fmt, options) {
  42   this.stream = options.stream || process.stderr;
  43
  44   if (typeof(options) == 'number') {
  45     var total = options;
  46     options = {};
  47     options.total = total;
  48   } else {
  49     options = options || {};
  50     if ('string' != typeof fmt) throw new Error('format required');
  51     if ('number' != typeof options.total) throw new Error('total required');
  52   }
  53
  54   this.fmt = fmt;
  55   this.curr = 0;
  56   this.total = options.total;
  57   this.width = options.width || this.total;
  58   this.clear = options.clear
  59   this.chars = {
  60     complete   : options.complete || '=',
  61     incomplete : options.incomplete || '-'
  62   };
  63   this.callback = options.callback || function () {};
  64   this.lastDraw = '';
  65 }
  66
  67 /**
  68  * "tick" the progress bar with optional `len` and optional `tokens`.
  69  *
  70  * @param {number|object} len or tokens
  71  * @param {object} tokens
  72  * @api public
  73  */
  74
  75 ProgressBar.prototype.tick = function(len, tokens){
  76   if (len !== 0)
  77     len = len || 1;
  78
  79   // swap tokens
  80   if ('object' == typeof len) tokens = len, len = 1;
  81
  82   // start time for eta
  83   if (0 == this.curr) this.start = new Date;
  84
  85   this.curr += len
  86   this.render(tokens);
  87
  88   // progress complete
  89   if (this.curr >= this.total) {
  90     this.complete = true;
  91     this.terminate();
  92     this.callback(this);
  93     return;
  94   }
  95 };
  96
  97 /**
  98  * Method to render the progress bar with optional `tokens` to place in the
  99  * progress bar's `fmt` field.
 100  *
 101  * @param {object} tokens
 102  * @api public
 103  */
 104
 105 ProgressBar.prototype.render = function (tokens) {
 106   if (!this.stream.isTTY) return;
 107
 108   var ratio = this.curr / this.total;
 109   ratio = Math.min(Math.max(ratio, 0), 1);
 110
 111   var percent = ratio * 100;
 112   var incomplete, complete, completeLength;
 113   var elapsed = new Date - this.start;
 114   var eta = (percent == 100) ? 0 : elapsed * (this.total / this.curr - 1);
 115
 116   /* populate the bar template with percentages and timestamps */
 117   var str = this.fmt
 118     .replace(':current', this.curr)
 119     .replace(':total', this.total)
 120     .replace(':elapsed', isNaN(elapsed) ? '0.0' : (elapsed / 1000).toFixed(1))
 121     .replace(':eta', (isNaN(eta) || !isFinite(eta)) ? '0.0' : (eta / 1000)
 122       .toFixed(1))
 123     .replace(':percent', percent.toFixed(0) + '%');
 124
 125   /* compute the available space (non-zero) for the bar */
 126   var availableSpace = Math.max(0, this.stream.columns - str.replace(':bar', '').length);
 127   var width = Math.min(this.width, availableSpace);
 128
 129   /* TODO: the following assumes the user has one ':bar' token */
 130   completeLength = Math.round(width * ratio);
 131   complete = Array(completeLength + 1).join(this.chars.complete);
 132   incomplete = Array(width - completeLength + 1).join(this.chars.incomplete);
 133
 134   /* fill in the actual progress bar */
 135   str = str.replace(':bar', complete + incomplete);
 136
 137   /* replace the extra tokens */
 138   if (tokens) for (var key in tokens) str = str.replace(':' + key, tokens[key]);
 139
 140   if (this.lastDraw !== str) {
 141     this.stream.clearLine();
 142     this.stream.cursorTo(0);
 143     this.stream.write(str);
 144     this.lastDraw = str;
 145   }
 146 };
 147
 148 /**
 149  * "update" the progress bar to represent an exact percentage.
 150  * The ratio (between 0 and 1) specified will be multiplied by `total` and
 151  * floored, representing the closest available "tick." For example, if a
 152  * progress bar has a length of 3 and `update(0.5)` is called, the progress
 153  * will be set to 1.
 154  *
 155  * A ratio of 0.5 will attempt to set the progress to halfway.
 156  *
 157  * @param {number} ratio The ratio (between 0 and 1 inclusive) to set the
 158  *   overall completion to.
 159  * @api public
 160  */
 161
 162 ProgressBar.prototype.update = function (ratio, tokens) {
 163   var goal = Math.floor(ratio * this.total);
 164   var delta = goal - this.curr;
 165
 166   this.tick(delta, tokens);
 167 };
 168
 169 /**
 170  * Terminates a progress bar.
 171  *
 172  * @api public
 173  */
 174
 175 ProgressBar.prototype.terminate = function () {
 176   if (this.clear) {
 177     this.stream.clearLine();
 178     this.stream.cursorTo(0);
 179   } else console.log();
 180 };