/*!
|
* node-progress
|
* Copyright(c) 2011 TJ Holowaychuk <tj@vision-media.ca>
|
* MIT Licensed
|
*/
|
|
/**
|
* Expose `ProgressBar`.
|
*/
|
|
exports = module.exports = ProgressBar;
|
|
/**
|
* Initialize a `ProgressBar` with the given `fmt` string and `options` or
|
* `total`.
|
*
|
* Options:
|
*
|
* - `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
|
* - `callback` optional function to call when the progress bar completes
|
* - `clear` will clear the progress bar upon termination
|
*
|
* Tokens:
|
*
|
* - `:bar` the progress bar itself
|
* - `:current` current tick number
|
* - `:total` total ticks
|
* - `:elapsed` time elapsed in seconds
|
* - `:percent` completion percentage
|
* - `:eta` eta in seconds
|
* - `:rate` rate of ticks per second
|
*
|
* @param {string} fmt
|
* @param {object|number} options or total
|
* @api public
|
*/
|
|
function ProgressBar(fmt, options) {
|
this.stream = options.stream || process.stderr;
|
|
if (typeof(options) == 'number') {
|
var total = options;
|
options = {};
|
options.total = total;
|
} else {
|
options = options || {};
|
if ('string' != typeof fmt) throw new Error('format required');
|
if ('number' != typeof options.total) throw new Error('total required');
|
}
|
|
this.fmt = fmt;
|
this.curr = options.curr || 0;
|
this.total = options.total;
|
this.width = options.width || this.total;
|
this.clear = options.clear
|
this.chars = {
|
complete : options.complete || '=',
|
incomplete : options.incomplete || '-',
|
head : options.head || (options.complete || '=')
|
};
|
this.renderThrottle = options.renderThrottle !== 0 ? (options.renderThrottle || 16) : 0;
|
this.lastRender = -Infinity;
|
this.callback = options.callback || function () {};
|
this.tokens = {};
|
this.lastDraw = '';
|
}
|
|
/**
|
* "tick" the progress bar with optional `len` and optional `tokens`.
|
*
|
* @param {number|object} len or tokens
|
* @param {object} tokens
|
* @api public
|
*/
|
|
ProgressBar.prototype.tick = function(len, tokens){
|
if (len !== 0)
|
len = len || 1;
|
|
// swap tokens
|
if ('object' == typeof len) tokens = len, len = 1;
|
if (tokens) this.tokens = tokens;
|
|
// start time for eta
|
if (0 == this.curr) this.start = new Date;
|
|
this.curr += len
|
|
// try to render
|
this.render();
|
|
// progress complete
|
if (this.curr >= this.total) {
|
this.render(undefined, true);
|
this.complete = true;
|
this.terminate();
|
this.callback(this);
|
return;
|
}
|
};
|
|
/**
|
* Method to render the progress bar with optional `tokens` to place in the
|
* progress bar's `fmt` field.
|
*
|
* @param {object} tokens
|
* @api public
|
*/
|
|
ProgressBar.prototype.render = function (tokens, force) {
|
force = force !== undefined ? force : false;
|
if (tokens) this.tokens = tokens;
|
|
if (!this.stream.isTTY) return;
|
|
var now = Date.now();
|
var delta = now - this.lastRender;
|
if (!force && (delta < this.renderThrottle)) {
|
return;
|
} else {
|
this.lastRender = now;
|
}
|
|
var ratio = this.curr / this.total;
|
ratio = Math.min(Math.max(ratio, 0), 1);
|
|
var percent = Math.floor(ratio * 100);
|
var incomplete, complete, completeLength;
|
var elapsed = new Date - this.start;
|
var eta = (percent == 100) ? 0 : elapsed * (this.total / this.curr - 1);
|
var rate = this.curr / (elapsed / 1000);
|
|
/* populate the bar template with percentages and timestamps */
|
var str = this.fmt
|
.replace(':current', this.curr)
|
.replace(':total', this.total)
|
.replace(':elapsed', isNaN(elapsed) ? '0.0' : (elapsed / 1000).toFixed(1))
|
.replace(':eta', (isNaN(eta) || !isFinite(eta)) ? '0.0' : (eta / 1000)
|
.toFixed(1))
|
.replace(':percent', percent.toFixed(0) + '%')
|
.replace(':rate', Math.round(rate));
|
|
/* compute the available space (non-zero) for the bar */
|
var availableSpace = Math.max(0, this.stream.columns - str.replace(':bar', '').length);
|
if(availableSpace && process.platform === 'win32'){
|
availableSpace = availableSpace - 1;
|
}
|
|
var width = Math.min(this.width, availableSpace);
|
|
/* TODO: the following assumes the user has one ':bar' token */
|
completeLength = Math.round(width * ratio);
|
complete = Array(Math.max(0, completeLength + 1)).join(this.chars.complete);
|
incomplete = Array(Math.max(0, width - completeLength + 1)).join(this.chars.incomplete);
|
|
/* add head to the complete string */
|
if(completeLength > 0)
|
complete = complete.slice(0, -1) + this.chars.head;
|
|
/* fill in the actual progress bar */
|
str = str.replace(':bar', complete + incomplete);
|
|
/* replace the extra tokens */
|
if (this.tokens) for (var key in this.tokens) str = str.replace(':' + key, this.tokens[key]);
|
|
if (this.lastDraw !== str) {
|
this.stream.cursorTo(0);
|
this.stream.write(str);
|
this.stream.clearLine(1);
|
this.lastDraw = str;
|
}
|
};
|
|
/**
|
* "update" the progress bar to represent an exact percentage.
|
* The ratio (between 0 and 1) specified will be multiplied by `total` and
|
* floored, representing the closest available "tick." For example, if a
|
* progress bar has a length of 3 and `update(0.5)` is called, the progress
|
* will be set to 1.
|
*
|
* A ratio of 0.5 will attempt to set the progress to halfway.
|
*
|
* @param {number} ratio The ratio (between 0 and 1 inclusive) to set the
|
* overall completion to.
|
* @api public
|
*/
|
|
ProgressBar.prototype.update = function (ratio, tokens) {
|
var goal = Math.floor(ratio * this.total);
|
var delta = goal - this.curr;
|
|
this.tick(delta, tokens);
|
};
|
|
/**
|
* "interrupt" the progress bar and write a message above it.
|
* @param {string} message The message to write.
|
* @api public
|
*/
|
|
ProgressBar.prototype.interrupt = function (message) {
|
// clear the current line
|
this.stream.clearLine();
|
// move the cursor to the start of the line
|
this.stream.cursorTo(0);
|
// write the message text
|
this.stream.write(message);
|
// terminate the line after writing the message
|
this.stream.write('\n');
|
// re-display the progress bar with its lastDraw
|
this.stream.write(this.lastDraw);
|
};
|
|
/**
|
* Terminates a progress bar.
|
*
|
* @api public
|
*/
|
|
ProgressBar.prototype.terminate = function () {
|
if (this.clear) {
|
if (this.stream.clearLine) {
|
this.stream.clearLine();
|
this.stream.cursorTo(0);
|
}
|
} else {
|
this.stream.write('\n');
|
}
|
};
|
