3 * Copyright(c) 2011 TJ Holowaychuk <tj@vision-media.ca>
8 * Expose `ProgressBar`.
11 exports = module.exports = ProgressBar;
14 * Initialize a `ProgressBar` with the given `fmt` string and `options` or
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
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
37 * @param {object|number} options or total
41 function ProgressBar(fmt, options) {
42 this.stream = options.stream || process.stderr;
44 if (typeof(options) == 'number') {
47 options.total = total;
49 options = options || {};
50 if ('string' != typeof fmt) throw new Error('format required');
51 if ('number' != typeof options.total) throw new Error('total required');
56 this.total = options.total;
57 this.width = options.width || this.total;
58 this.clear = options.clear
60 complete : options.complete || '=',
61 incomplete : options.incomplete || '-'
63 this.callback = options.callback || function () {};
68 * "tick" the progress bar with optional `len` and optional `tokens`.
70 * @param {number|object} len or tokens
71 * @param {object} tokens
75 ProgressBar.prototype.tick = function(len, tokens){
80 if ('object' == typeof len) tokens = len, len = 1;
83 if (0 == this.curr) this.start = new Date;
89 if (this.curr >= this.total) {
98 * Method to render the progress bar with optional `tokens` to place in the
99 * progress bar's `fmt` field.
101 * @param {object} tokens
105 ProgressBar.prototype.render = function (tokens) {
106 if (!this.stream.isTTY) return;
108 var ratio = this.curr / this.total;
109 ratio = Math.min(Math.max(ratio, 0), 1);
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);
116 /* populate the bar template with percentages and timestamps */
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)
123 .replace(':percent', percent.toFixed(0) + '%');
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);
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);
134 /* fill in the actual progress bar */
135 str = str.replace(':bar', complete + incomplete);
137 /* replace the extra tokens */
138 if (tokens) for (var key in tokens) str = str.replace(':' + key, tokens[key]);
140 if (this.lastDraw !== str) {
141 this.stream.clearLine();
142 this.stream.cursorTo(0);
143 this.stream.write(str);
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
155 * A ratio of 0.5 will attempt to set the progress to halfway.
157 * @param {number} ratio The ratio (between 0 and 1 inclusive) to set the
158 * overall completion to.
162 ProgressBar.prototype.update = function (ratio, tokens) {
163 var goal = Math.floor(ratio * this.total);
164 var delta = goal - this.curr;
166 this.tick(delta, tokens);
170 * Terminates a progress bar.
175 ProgressBar.prototype.terminate = function () {
177 this.stream.clearLine();
178 this.stream.cursorTo(0);
179 } else console.log();