pixl-cli 1.0.18 → 1.0.20

package/README.md

@@ -512,13 +512,13 @@ If you call `cli.progress.update()` and pass in a number, the library assumes yo
 
 ### Temporarily Erasing The Bar
 
-If you need to temporarily erase the progress bar, presumably to write some lines of output to the console, you can call the `cli.progress.erase()` method.  Just note that after `freq` milliseconds (or less), the bar will be redrawn.
+If you need to temporarily erase the progress bar, presumably to write some lines of output to the console, you can call the `cli.progress.erase()` method.  To reduce flickering, you can force a redraw just after outputting your lines by calling `cli.progress.draw()`.
 
-To reduce flickering, you can force a redraw just after outputting your lines by calling `cli.progress.draw()`.  Example:
+However, if you use the built-in CLI `print()`, `println()`, `verbose()` or `verboseln()` functions, the progress bar is automatically hidden and redrawn for you.  You should only need to manually erase and redraw it if you are calling some other code that outputs to STDOUT or STDERR.  Example:
 
 ```js
 cli.progress.erase();
-cli.print("We're now in phase 2 of 3: Updating DB indexes...\n\n");
+console.log( some_large_object );
 cli.progress.draw();
 ```
 
@@ -564,6 +564,7 @@ cli.progress.start({
 		spinner: ['bold', 'green'],
 		braces: ['gray'],
 		bar: ['bold', 'cyan'],
+		indeterminate: ['gray'],
 		pct: ['bold', 'yellow'],
 		remain: ['green'],
 		text: [function( text ) { return text.toUpperCase() }]
@@ -573,6 +574,8 @@ cli.progress.start({
 
 Each key should be set to an array of styles supported by the [chalk](https://www.npmjs.com/package/chalk) module or a function.  These are arrays because each component may contain multiple styles.  For example, by default the `spinner`, `bar` and `pct` are styled with both a color and `bold`.
 
+The `indeterminate` style is applied to the filled portion of the bar when the `amount` is exactly equal to the `max`.  This is to handle cases where a job "sits at 100%" but isn't quite complete, and also handle deliberate intermintate jobs (i.e. your code can just set the `amount` to the `max` to show an interminate bar).  This also hides the time remaining.
+
 ### Automatic Width
 
 To set the progress bar size automatically to take up the full width of your Terminal window, you can use the `cli.width()` function.  Just subtract 27 characters from it (possibly more if you use `indent` or `text`) to account for the spinner, braces, percentage and remaining time:

package/cli.js

@@ -432,7 +432,11 @@ var cli = module.exports = {
 	
 	print: function(msg) {
 		// print message to console
-		if (!this.args.quiet) process.stdout.write(msg);
+		if (!this.args.quiet) {
+			if (this.progress.running) this.progress.erase();
+			process.stdout.write(msg);
+			if (this.progress.running) this.progress.draw();
+		}
 		this.log(msg);
 	},
 	
@@ -454,7 +458,11 @@ var cli = module.exports = {
 	
 	warn: function(msg) {
 		// print to stderr
-		if (!this.args.quiet) process.stderr.write(msg);
+		if (!this.args.quiet) {
+			if (this.progress.running) this.progress.erase();
+			process.stderr.write(msg);
+			if (this.progress.running) this.progress.draw();
+		}
 		this.log(msg);
 	},
 	
@@ -465,6 +473,7 @@ var cli = module.exports = {
 	
 	die: function(msg) {
 		// print to stderr and exit with non-zero code
+		if (this.progress.running) this.progress.end();
 		this.warn(msg);
 		process.exit(1);
 	},
@@ -512,6 +521,7 @@ var cli = module.exports = {
 				spinner: ['bold', 'green'],
 				braces: ['gray'],
 				bar: ['bold', 'cyan'],
+				indeterminate: ['gray'],
 				pct: ['bold', 'yellow'],
 				remain: ['green'],
 				text: []
@@ -596,8 +606,8 @@ var cli = module.exports = {
 		
 		draw: function() {
 			// draw progress bar, spinner
-			if (!cli.tty()) return;
 			if (!this.running) return;
+			if (!cli.tty()) return;
 			
 			var args = this.args;
 			var line = args.indent;
@@ -618,7 +628,7 @@ var cli = module.exports = {
 			}
 			bar += cli.space(args.width - stringWidth(bar));
 			
-			line += cli.applyStyles( bar, args.styles.bar );
+			line += cli.applyStyles( bar, (args.amount === args.max) ? args.styles.indeterminate : args.styles.bar );
 			line += cli.applyStyles( args.braces[1], args.styles.braces );
 			line += " ";
 			
@@ -660,8 +670,8 @@ var cli = module.exports = {
 		},
 		
 		update: function(args) {
-			if (!cli.tty()) return;
 			if (!this.running) return;
+			if (!cli.tty()) return;
 			
 			if (typeof(args) == 'number') {
 				// just updating the amount
@@ -678,6 +688,7 @@ var cli = module.exports = {
 		
 		erase: function() {
 			// erase progress
+			if (!this.running) return;
 			if (!cli.tty()) return;
 			if (this.lastLine && !this.args.quiet) {
 				process.stdout.write( cli.space( stringWidth(this.lastLine) ) + "\r" );
@@ -686,8 +697,8 @@ var cli = module.exports = {
 		
 		end: function(erase) {
 			// end of progress session
-			if (!cli.tty()) return;
 			if (!this.running) return;
+			if (!cli.tty()) return;
 			
 			if (erase !== false) {
 			  this.erase();
@@ -695,6 +706,7 @@ var cli = module.exports = {
 			clearTimeout( this.timer );
 			this.running = false;
 			this.args = {};
+			this.lastLine = '';
 			
 			// restore CLI cursor
 			if (!this.args.quiet) process.stdout.write('\u001b[?25h');

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pixl-cli",
-	"version": "1.0.18",
+	"version": "1.0.20",
 	"description": "Tools for building command-line apps for Node.js.",
 	"author": "Joseph Huckaby <jhuckaby@gmail.com>",
 	"homepage": "https://github.com/jhuckaby/pixl-cli",