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 * - `curr` current completed index
20 * - `total` total number of ticks to complete
21 * - `width` the displayed width of the progress bar defaulting to total
22 * - `stream` the output stream defaulting to stderr
23 * - `head` head character defaulting to complete character
24 * - `complete` completion character defaulting to "="
25 * - `incomplete` incomplete character defaulting to "-"
26 * - `renderThrottle` minimum time between updates in milliseconds defaulting to 16
27 * - `callback` optional function to call when the progress bar completes
28 * - `clear` will clear the progress bar upon termination
32 * - `:bar` the progress bar itself
33 * - `:current` current tick number
34 * - `:total` total ticks
35 * - `:elapsed` time elapsed in seconds
36 * - `:percent` completion percentage
37 * - `:eta` eta in seconds
38 * - `:rate` rate of ticks per second
41 * @param {object|number} options or total
45 function ProgressBar(fmt, options) {
46 this.stream = options.stream || process.stderr;
48 if (typeof(options) == 'number') {
51 options.total = total;
53 options = options || {};
54 if ('string' != typeof fmt) throw new Error('format required');
55 if ('number' != typeof options.total) throw new Error('total required');
59 this.curr = options.curr || 0;
60 this.total = options.total;
61 this.width = options.width || this.total;
62 this.clear = options.clear
64 complete : options.complete || '=',
65 incomplete : options.incomplete || '-',
66 head : options.head || (options.complete || '=')
68 this.renderThrottle = options.renderThrottle !== 0 ? (options.renderThrottle || 16) : 0;
69 this.lastRender = -Infinity;
70 this.callback = options.callback || function () {};
76 * "tick" the progress bar with optional `len` and optional `tokens`.
78 * @param {number|object} len or tokens
79 * @param {object} tokens
83 ProgressBar.prototype.tick = function(len, tokens){
88 if ('object' == typeof len) tokens = len, len = 1;
89 if (tokens) this.tokens = tokens;
92 if (0 == this.curr) this.start = new Date;
100 if (this.curr >= this.total) {
101 this.render(undefined, true);
102 this.complete = true;
110 * Method to render the progress bar with optional `tokens` to place in the
111 * progress bar's `fmt` field.
113 * @param {object} tokens
117 ProgressBar.prototype.render = function (tokens, force) {
118 force = force !== undefined ? force : false;
119 if (tokens) this.tokens = tokens;
121 if (!this.stream.isTTY) return;
123 var now = Date.now();
124 var delta = now - this.lastRender;
125 if (!force && (delta < this.renderThrottle)) {
128 this.lastRender = now;
131 var ratio = this.curr / this.total;
132 ratio = Math.min(Math.max(ratio, 0), 1);
134 var percent = Math.floor(ratio * 100);
135 var incomplete, complete, completeLength;
136 var elapsed = new Date - this.start;
137 var eta = (percent == 100) ? 0 : elapsed * (this.total / this.curr - 1);
138 var rate = this.curr / (elapsed / 1000);
140 /* populate the bar template with percentages and timestamps */
142 .replace(':current', this.curr)
143 .replace(':total', this.total)
144 .replace(':elapsed', isNaN(elapsed) ? '0.0' : (elapsed / 1000).toFixed(1))
145 .replace(':eta', (isNaN(eta) || !isFinite(eta)) ? '0.0' : (eta / 1000)
147 .replace(':percent', percent.toFixed(0) + '%')
148 .replace(':rate', Math.round(rate));
150 /* compute the available space (non-zero) for the bar */
151 var availableSpace = Math.max(0, this.stream.columns - str.replace(':bar', '').length);
152 if(availableSpace && process.platform === 'win32'){
153 availableSpace = availableSpace - 1;
156 var width = Math.min(this.width, availableSpace);
158 /* TODO: the following assumes the user has one ':bar' token */
159 completeLength = Math.round(width * ratio);
160 complete = Array(Math.max(0, completeLength + 1)).join(this.chars.complete);
161 incomplete = Array(Math.max(0, width - completeLength + 1)).join(this.chars.incomplete);
163 /* add head to the complete string */
164 if(completeLength > 0)
165 complete = complete.slice(0, -1) + this.chars.head;
167 /* fill in the actual progress bar */
168 str = str.replace(':bar', complete + incomplete);
170 /* replace the extra tokens */
171 if (this.tokens) for (var key in this.tokens) str = str.replace(':' + key, this.tokens[key]);
173 if (this.lastDraw !== str) {
174 this.stream.cursorTo(0);
175 this.stream.write(str);
176 this.stream.clearLine(1);
182 * "update" the progress bar to represent an exact percentage.
183 * The ratio (between 0 and 1) specified will be multiplied by `total` and
184 * floored, representing the closest available "tick." For example, if a
185 * progress bar has a length of 3 and `update(0.5)` is called, the progress
188 * A ratio of 0.5 will attempt to set the progress to halfway.
190 * @param {number} ratio The ratio (between 0 and 1 inclusive) to set the
191 * overall completion to.
195 ProgressBar.prototype.update = function (ratio, tokens) {
196 var goal = Math.floor(ratio * this.total);
197 var delta = goal - this.curr;
199 this.tick(delta, tokens);
203 * "interrupt" the progress bar and write a message above it.
204 * @param {string} message The message to write.
208 ProgressBar.prototype.interrupt = function (message) {
209 // clear the current line
210 this.stream.clearLine();
211 // move the cursor to the start of the line
212 this.stream.cursorTo(0);
213 // write the message text
214 this.stream.write(message);
215 // terminate the line after writing the message
216 this.stream.write('\n');
217 // re-display the progress bar with its lastDraw
218 this.stream.write(this.lastDraw);
222 * Terminates a progress bar.
227 ProgressBar.prototype.terminate = function () {
229 if (this.stream.clearLine) {
230 this.stream.clearLine();
231 this.stream.cursorTo(0);
234 this.stream.write('\n');