pixl-cli 1.0.9 → 1.0.13

package/README.md

@@ -1,3 +1,40 @@
+<details><summary>Table of Contents</summary>
+
+<!-- toc -->
+- [Overview](#overview)
+- [Usage](#usage)
+	* [Basic Tools](#basic-tools)
+		+ [Printing](#printing)
+			- [STDERR](#stderr)
+			- [Dying](#dying)
+		+ [Logging](#logging)
+		+ [Loading and Saving Files](#loading-and-saving-files)
+		+ [TTY Detection](#tty-detection)
+		+ [Other Tools](#other-tools)
+	* [Command-Line Arguments](#command-line-arguments)
+		+ [Verbose Mode](#verbose-mode)
+		+ [Quiet Mode](#quiet-mode)
+	* [Prompting The User](#prompting-the-user)
+		+ [Yes/No Questions](#yesno-questions)
+	* [Displaying Info Boxes](#displaying-info-boxes)
+		+ [Centering Text](#centering-text)
+		+ [Word-Wrapping Text](#word-wrapping-text)
+	* [Displaying Tables](#displaying-tables)
+	* [Graphical Progress Bars](#graphical-progress-bars)
+		+ [Configuration](#configuration)
+		+ [Temporarily Erasing The Bar](#temporarily-erasing-the-bar)
+		+ [Customizing the Look](#customizing-the-look)
+		+ [Changing Color Styles](#changing-color-styles)
+		+ [Automatic Width](#automatic-width)
+		+ [Keep progress bar visible](#keep-progress-bar-visible)
+		+ [Unicode or ASCII](#unicode-or-ascii)
+		+ [Hiding the Cursor](#hiding-the-cursor)
+	* [Chalk](#chalk)
+	* [Importing Into Global](#importing-into-global)
+- [License](#license)
+
+</details>
+
 # Overview
 
 This module provides utilities for creating command-line Node.js apps.  Features include automatic parsing of command-line args into simple key/value pairs, prompting the user for information, and displaying graphical info boxes and progress bars.
@@ -31,7 +68,7 @@ cli.global();
 print("Hello world!\n");
 ```
 
-Unlike `console.log()` this does not add an EOL at the end of each string.  It works just like the standard `print()` function from other languages.
+Unlike `console.log()` this does not add an EOL at the end of each string.  It works just like the standard `print()` function from other languages.  However, a `println()` method is also provided which *does* add an EOL.
 
 Note that `print()` will be silent if `--quiet` mode is enabled.  See [Quiet Mode](#quiet-mode) below.
 
@@ -68,6 +105,25 @@ cli.global();
 die("A fatal error occurred.\n");
 ```
 
+### Logging
+
+To enable logging mode, so all calls to `print()`, `verbose()`, `warn()` and `die()` also get logged to a file, call `cli.setLogFile()` and pass in a path.  The file need not exist, but the directory should.  Example:
+
+```js
+cli.setLogFile( "/var/log/myscript.log" );
+```
+
+Note that once the log file is set, everything printed is logged, even if quiet mode is enabled.  Additionally, all calls to `cli.verbose()` are also logged, even if `--verbose` mode is not enabled.
+
+The log file format is simply a date/time surrounded by square brackets, followed by a single space, followed by the raw text printed.  All color is automatically stripped.  Example log snippet:
+
+```
+[2019/05/18 18:49:12] Hello there!
+[2019/05/18 18:49:13] Good bye!
+```
+
+You can also call `cli.log()` to log something directly without also printing it to the console.  If you pass an object to `cli.log()` it is serialized to JSON.
+
 ### Loading and Saving Files
 
 Simple methods are provided to load and save files to/from strings.  These are both synchronous calls.  They are `loadFile()` which accepts a file path and returns the contents as a string, and `saveFile()` which accepts a file path and contents as a string.  `saveFile()` writes to the specified file, replacing any existing content, and creating the file if necessary.  Example of both functions:
@@ -126,6 +182,8 @@ The following utility functions from the [pixl-tools](https://www.npmjs.com/pack
 | [cli.pluralize()](https://www.npmjs.com/package/pixl-tools#pluralize) | Apply English language pluralization to a word, based on a specified value. |
 | [cli.ucfirst()](https://www.npmjs.com/package/pixl-tools#ucfirst) | Upper-case the first character of a string, lower-case the rest. |
 
+In fact, the entire [pixl-tools](https://www.npmjs.com/package/pixl-tools) module is made available to you as `cli.Tools`, so you don't have to import it separately.
+
 ## Command-Line Arguments
 
 Any arguments passed to your script on the command-line are parsed using the [pixl-args](https://www.npmjs.com/package/pixl-args) module, and provided as simple key/value pairs in `cli.args`.  Example:
@@ -475,7 +533,7 @@ If you switch to [plain ASCII mode](#unicode-or-ascii) by setting the `unicode`
 ```js
 cli.progress.start({
 	spinner: ['|', '/', '-', "\\"],
-	braces: ['[', ']']
+	braces: ['[', ']'],
 	filling: [' ', '.', ':'],
 	filled: '#'
 });
@@ -519,7 +577,7 @@ cli.progress.update({
 });
 ```
 
-### Keep progress bar visible after it ends
+### Keep progress bar visible
 
 To keep the progress bar visible after it reaches 100%, just pass the value `false` to the 
 `cli.progress.end()` function. This will prevent it from being erased from the screen.
@@ -591,6 +649,7 @@ print( box( bold.red("This is bold, red and in a box!") ) + "\n" );
 The full list of methods and objects that are imported are:
 
 - `print()`
+- `println()`
 - `verbose()`
 - `warn()`
 - `die()`
@@ -613,9 +672,9 @@ The full list of methods and objects that are imported are:
 
 # License
 
-The MIT License
+**The MIT License**
 
-Copyright (c) 2016 Joseph Huckaby.
+*Copyright (c) 2016 - 2019 Joseph Huckaby.*
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/cli.js

@@ -27,6 +27,12 @@ var cli = module.exports = {
 	wordWrap: wordWrap,
 	Tools: Tools,
 	
+	// for stripping colors:
+	ansiPattern: new RegExp([
+		'[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)',
+		'(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))'
+	].join('|'), 'g'),
+	
 	tty: function() {
 		// return true if stdout is connected to a TTY, 
 		// i.e. so we can ask the user things
@@ -245,7 +251,7 @@ var cli = module.exports = {
 		var widestCols = [];
 		rows.forEach( function(cols, idx) {
 			cols.forEach( function(col, idy) {
-				widestCols[idy] = Math.max( widestCols[idy] || 0, stringWidth(col) + 2 );
+				widestCols[idy] = Math.max( widestCols[idy] || 0, stringWidth(''+col) + 2 );
 			} );
 		} );
 		
@@ -320,19 +326,58 @@ var cli = module.exports = {
 		return JSON.stringify( mixed, null, "\t" );
 	},
 	
+	stripColor: function(text) {
+		// strip ANSI colors from text
+		return text.replace( this.ansiPattern, '' );
+	},
+	
+	setLogFile: function(file) {
+		// log all output from our print methods to file
+		this.logFile = file;
+	},
+	
+	log: function(msg) {
+		// log something (if log file is configured)
+		if (this.logFile) {
+			if (typeof(msg) == 'object') msg = JSON.stringify(msg);
+			else if (!msg.match(/\S/)) return; // skip whitespace
+			var dargs = Tools.getDateArgs( Tools.timeNow() );
+			var line = '[' + dargs.yyyy_mm_dd + ' ' + dargs.hh_mi_ss + '] ' + this.stripColor(msg.trim()).trim() + "\n";
+			fs.appendFileSync( this.logFile, line );
+		}
+	},
+	
 	print: function(msg) {
 		// print message to console
 		if (!this.args.quiet) process.stdout.write(msg);
+		this.log(msg);
+	},
+	
+	println: function(msg) {
+		// print plus EOL
+		this.print( msg + "\n" );
 	},
 	
 	verbose: function(msg) {
 		// print only in verbose mode
 		if (this.args.verbose) this.print(msg);
+		else this.log(msg);
+	},
+	
+	verboseln: function(msg) {
+		// verbose print plus EOL
+		this.verbose( msg + "\n" );
 	},
 	
 	warn: function(msg) {
 		// print to stderr
 		if (!this.args.quiet) process.stderr.write(msg);
+		this.log(msg);
+	},
+	
+	warnln: function(msg) {
+		// warn plus EOL
+		this.warn( msg + "\n" );
 	},
 	
 	die: function(msg) {
@@ -341,6 +386,11 @@ var cli = module.exports = {
 		process.exit(1);
 	},
 	
+	dieln: function(msg) {
+		// die plus EOL
+		this.die( msg + "\n" );
+	},
+	
 	global: function() {
 		// pollute global namespace with our wares
 		var self = this;
@@ -351,7 +401,7 @@ var cli = module.exports = {
 		global.Tools = Tools;
 		
 		// bind wrap functions
-		["prompt", "yesno", "table", "box", "wrap", "center", "print", "verbose", "warn", "die", "loadFile", "saveFile", "appendFile"].forEach( function(func) {
+		["prompt", "yesno", "table", "box", "wrap", "center", "print", "println", "verbose", "verboseln", "warn", "warnln", "die", "dieln", "loadFile", "saveFile", "appendFile"].forEach( function(func) {
 			global[func] = self[func].bind(self);
 		} );
 		
@@ -435,7 +485,7 @@ var cli = module.exports = {
 			this.timer = setInterval( this.draw.bind(this), args.freq );
 			
 			// hide CLI cursor
-			cli.print('\u001b[?25l');
+			if (!this.args.quiet) process.stdout.write('\u001b[?25l');
 			
 			// just in case
 			process.once('exit', function() {
@@ -522,7 +572,7 @@ var cli = module.exports = {
 				}
 			}
 			
-			cli.print( line + "\r" );
+			if (!this.args.quiet) process.stdout.write( line + "\r" );
 			this.lastLine = line;
 		},
 		
@@ -546,8 +596,8 @@ var cli = module.exports = {
 		erase: function() {
 			// erase progress
 			if (!cli.tty()) return;
-			if (this.lastLine) {
-				cli.print( cli.space( stringWidth(this.lastLine) ) + "\r" );
+			if (this.lastLine && !this.args.quiet) {
+				process.stdout.write( cli.space( stringWidth(this.lastLine) ) + "\r" );
 			}
 		},
 		
@@ -564,7 +614,7 @@ var cli = module.exports = {
 			this.args = {};
 			
 			// restore CLI cursor
-			cli.print('\u001b[?25h');
+			if (!this.args.quiet) process.stdout.write('\u001b[?25h');
 		}
 	} // progress
 	

package/package.json

@@ -1,35 +1,35 @@
 {
-  "name": "pixl-cli",
-  "version": "1.0.9",
-  "description": "Tools for building command-line apps for Node.js.",
-  "author": "Joseph Huckaby <jhuckaby@gmail.com>",
-  "homepage": "https://github.com/jhuckaby/pixl-cli",
-  "license": "MIT",
-  "main": "cli.js",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/jhuckaby/pixl-cli"
-  },
-  "bugs": {
-    "url": "https://github.com/jhuckaby/pixl-cli/issues"
-  },
-  "keywords": [
-    "cli",
-    "commandline",
-    "prompt",
-    "progress",
-    "progressbar",
-    "table"
-  ],
-  "dependencies": {
-    "pixl-class": "^1.0.0",
-    "pixl-args": "^1.0.0",
-    "pixl-tools": "^1.0.0",
-    "chalk": "2.4.1",
-    "string-width": "2.1.1",
-    "widest-line": "2.0.0",
-    "repeating": "3.0.0",
-    "word-wrap": "1.2.3"
-  },
-  "devDependencies": {}
+	"name": "pixl-cli",
+	"version": "1.0.13",
+	"description": "Tools for building command-line apps for Node.js.",
+	"author": "Joseph Huckaby <jhuckaby@gmail.com>",
+	"homepage": "https://github.com/jhuckaby/pixl-cli",
+	"license": "MIT",
+	"main": "cli.js",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/jhuckaby/pixl-cli"
+	},
+	"bugs": {
+		"url": "https://github.com/jhuckaby/pixl-cli/issues"
+	},
+	"keywords": [
+		"cli",
+		"commandline",
+		"prompt",
+		"progress",
+		"progressbar",
+		"table"
+	],
+	"dependencies": {
+		"pixl-class": "^1.0.0",
+		"pixl-args": "^1.0.0",
+		"pixl-tools": "^1.0.0",
+		"chalk": "2.4.1",
+		"string-width": "4.2.0",
+		"widest-line": "3.0.0",
+		"repeating": "3.0.0",
+		"word-wrap": "1.2.3"
+	},
+	"devDependencies": {}
 }