visionmedia#178 - Add config method

The config method allows the progress bar to be reconfigured at any point, such as from the
callback. Also changed the order so that the callback is called before the final render,
so that the callback can reconfigure the bar for the final render.

examples/update-on-finish.js

@@ -0,0 +1,17 @@
+var ProgressBar = require('..');
+
+var bar = new ProgressBar('  [:bar]', {
+  complete: '=',
+  incomplete: '-',
+  total: 20,
+  callback: function () {
+    bar.config({ complete: '▓' });
+  }
+});
+
+var id = setInterval(function (){
+  bar.tick();
+  if (bar.complete) {
+    clearInterval(id);
+  }
+}, 100);

lib/node-progress.js

@@ -56,22 +56,28 @@ function ProgressBar(fmt, options) {
   }
 
   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.config(options);
   this.lastRender = -Infinity;
-  this.callback = options.callback || function () {};
   this.tokens = {};
   this.lastDraw = '';
 }
 
+/**
+ * Configures (or reconfigures) the progress bar. Only those options that are specified
+ * in the argument are updated. See the constructor function for information on available options.
+ */
+ProgressBar.prototype.config = function (options) {
+  updateConfig(this, options, 'curr', 0);
+  updateConfig(this, options, 'total');
+  updateConfig(this, options, 'width', this.total);
+  updateConfig(this, options, 'clear');
+  this.chars = this.chars || {};
+  updateConfig(this.chars, options, 'complete', '=');
+  updateConfig(this.chars, options, 'incomplete', '-');
+  updateConfig(this, options, 'renderThrottle', 16);
+  updateConfig(this, options, 'callback', function () {});
+}
+
 /**
  * "tick" the progress bar with optional `len` and optional `tokens`.
  *
@@ -98,10 +104,10 @@ ProgressBar.prototype.tick = function(len, tokens){
 
   // progress complete
   if (this.curr >= this.total) {
-    this.render(undefined, true);
     this.complete = true;
-    this.terminate();
     this.callback(this);
+    this.render(undefined, true);
+    this.terminate();
     return;
   }
 };
@@ -162,7 +168,7 @@ ProgressBar.prototype.render = function (tokens, force) {
 
   /* add head to the complete string */
   if(completeLength > 0)
-    complete = complete.slice(0, -1) + this.chars.head;
+    complete = complete.slice(0, -1) + (this.chars.head || this.chars.complete);
 
   /* fill in the actual progress bar */
   str = str.replace(':bar', complete + incomplete);
@@ -234,3 +240,22 @@ ProgressBar.prototype.terminate = function () {
     this.stream.write('\n');
   }
 };
+
+/**
+ * Helper function used to configure one property of a target based on the same property
+ * of an options object, or from a default value if not present in either the target or the
+ * options.
+ * 
+ * @param {object} target The object to set properties on.
+ * @param {object} options The object that contains the configuration properties.
+ * @param {String} property The name of the property to configure.
+ * @param {*} [defValue] The default value. If not specified, `undefined`.
+ */
+function updateConfig(target, options, property, defValue) {
+  if (options.hasOwnProperty(property)) {
+    target[property] = options[property];
+  } else if (!target.hasOwnProperty(property)) {
+    target[property] = defValue;
+  }
+}
+

package.json

@@ -1,6 +1,6 @@
 {
   "name": "progress",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Flexible ascii progress bar",
   "repository": {
     "type": "git",