feature(interrupt): added feature to interrupt the bar and display a message

Author: James Martin

Readme.md

@@ -119,6 +119,23 @@ The above example result in a progress bar like the one below.
 downloading [=====             ] 29% 3.7s
 ```
 
+### Interrupt
+
+To display a message during progress bar execution, use `interupt()`
+```javascript
+var ProgressBar = require('progress');
+
+var bar = new ProgressBar(':bar :current/:total', { total: 10 });
+var timer = setInterval(function () {
+  bar.tick();
+  if (bar.complete) {
+    clearInterval(timer);
+  } else if (bar.curr === 5) {
+      bar.interrupt('this message appears above the progress bar\ncurrent progress is ' + bar.curr + '/' + bar.total);
+  }
+}, 1000);
+```
+
 You can see more examples in the `examples` folder.
 
 ## License

examples/interrupt.js

@@ -0,0 +1,18 @@
+/**
+ * An example to show a progress bar being interrupted,
+ * displaying messages above the bar while keeping the
+ * progress intact
+ */
+
+var ProgressBar = require('progress');
+
+var bar = new ProgressBar(':bar :current/:total', { total: 10 });
+var timer = setInterval(function () {
+    bar.tick();
+    if (bar.complete) {
+        clearInterval(timer);
+    } else if (bar.curr === 5 || bar.curr === 8) {
+        bar.interrupt('interrupt: current progress is ' + bar.curr + '/' + bar.total);
+    }
+}, 1000);
+

lib/node-progress.js

@@ -180,6 +180,25 @@ ProgressBar.prototype.update = function (ratio, tokens) {
   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.
  *
@@ -190,5 +209,7 @@ ProgressBar.prototype.terminate = function () {
   if (this.clear) {
     this.stream.clearLine();
     this.stream.cursorTo(0);
-  } else this.stream.write('\n');
+  } else {
+    this.stream.write('\n');
+  }
 };