pixl-cli 1.0.22 → 1.1.1

package/cli.js

@@ -6,10 +6,14 @@ var fs = require('fs');
 var readline = require('readline');
 var path = require('path');
 var chalk = require('chalk');
-var stringWidth = require('string-width');
-var widestLine = require('widest-line');
-var repeating = require('repeating');
-var wordWrap = require('word-wrap');
+
+var Util = require('./util');
+var Width = require('./width');
+var wordWrap = require('./wrap');
+
+var ansiPattern = Util.ansiPattern;
+var stringWidth = Width.stringWidth;
+var widestLine = Width.widestLine;
 
 var Tools = require('pixl-tools');
 var Args = require('pixl-args');
@@ -20,7 +24,7 @@ var cli = module.exports = {
 	// CLI args hash
 	args: args.get(),
 	
-	// expose some 3rd party utilities
+	// expose some utility functions and third-party modules
 	chalk: chalk,
 	stringWidth: stringWidth,
 	widestLine: widestLine,
@@ -28,10 +32,7 @@ var cli = module.exports = {
 	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'),
+	ansiPattern: ansiPattern,
 	
 	mapArgs: function(aliases) {
 		// apply alias lookup to a set of args
@@ -99,7 +100,7 @@ var cli = module.exports = {
 	repeat: function(text, amount) {
 		// repeat string by specified number of times
 		if (!amount || (amount < 0)) return "";
-		return repeating(amount, ''+text);
+		return (''+text).repeat(amount);
 	},
 	
 	space: function(amount) {
@@ -112,6 +113,12 @@ var cli = module.exports = {
 		return text + this.space(width - stringWidth(text));
 	},
 	
+	emoji: function(emoji) {
+		// Draw the emoji, restore its starting cursor position, then explicitly move
+		// forward two cells.  This overrides each terminal's automatic cursor advance.
+		return '\u001b7' + emoji + '\u001b8\u001b[2C';
+	},
+	
 	center: function(text, width) {
 		// center string horizontally
 		var self = this;
@@ -291,25 +298,12 @@ var cli = module.exports = {
 			max_col_widths[longest_col_idx]--;
 		}
 		
-		// finally prune affected columns, trying to preserve ANSI color inside column value
+		// finally prune affected columns by display width, preserving ANSI and emoji
 		rows.forEach( function(cols, idx) {
 			cols.forEach( function(col, idy) {
 				col = '' + col;
 				if (stringWidth(col) > max_col_widths[idy]) {
-					var suffix = '';
-					var prefix = '';
-					
-					while (col.match(/^(\u001b\[[^m]*?m)/)) {
-						prefix += RegExp.$1;
-						col = col.replace(/^(\u001b\[[^m]*?m)/, '');
-					}
-					
-					while (col.match(/(\u001b\[[^m]*?m)$/)) {
-						suffix = RegExp.$1 + suffix;
-						col = col.replace(/(\u001b\[[^m]*?m)$/, '');
-					}
-					
-					cols[idy] = prefix + col.substring(0, max_col_widths[idy] - 1) + '…' + suffix;
+					cols[idy] = Width.truncate(col, max_col_widths[idy], '…');
 				} // too wide
 			});
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pixl-cli",
-	"version": "1.0.22",
+	"version": "1.1.1",
 	"description": "Tools for building command-line apps for Node.js.",
 	"author": "Joseph Huckaby <jhuckaby@gmail.com>",
 	"homepage": "https://github.com/jhuckaby/pixl-cli",
@@ -22,14 +22,9 @@
 		"table"
 	],
 	"dependencies": {
-		"pixl-class": "^1.0.3",
 		"pixl-args": "^1.0.0",
 		"pixl-tools": "^2.0.2",
-		"chalk": "2.4.1",
-		"string-width": "4.2.0",
-		"widest-line": "3.0.0",
-		"repeating": "3.0.0",
-		"word-wrap": "1.2.4"
+		"chalk": "2.4.1"
 	},
 	"devDependencies": {}
 }

package/util.js

@@ -0,0 +1,39 @@
+// Shared Unicode and terminal utilities for pixl-cli.
+
+// Match ANSI terminal escape sequences so they can be ignored during measurement.
+var 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');
+
+// Split strings into user-perceived characters, including complete emoji sequences.
+var graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+
+function splitAnsiGraphemes(text) {
+	// Split a string into complete ANSI sequences and Unicode grapheme clusters.
+	// ANSI sequences are kept intact so callers can preserve them while editing text.
+	var units = [];
+	var pattern = new RegExp(ansiPattern.source, 'g');
+	var offset = 0;
+	var match = null;
+	
+	var addText = function(value) {
+		for (var item of graphemeSegmenter.segment(value)) {
+			units.push({ text: item.segment, ansi: false });
+		}
+	};
+	
+	while ((match = pattern.exec(text))) {
+		if (match.index > offset) addText( text.substring(offset, match.index) );
+		units.push({ text: match[0], ansi: true });
+		offset = pattern.lastIndex;
+	}
+	if (offset < text.length) addText( text.substring(offset) );
+	return units;
+}
+
+module.exports = {
+	ansiPattern: ansiPattern,
+	graphemeSegmenter: graphemeSegmenter,
+	splitAnsiGraphemes: splitAnsiGraphemes
+};

package/width.js

@@ -0,0 +1,116 @@
+// Terminal display-width measurement for pixl-cli.
+
+var Util = require('./util');
+var ansiPattern = Util.ansiPattern;
+var graphemeSegmenter = Util.graphemeSegmenter;
+
+// These built-in Unicode properties let us identify emoji without carrying a large,
+// generated lookup table.  VS16 changes text-default symbols to emoji presentation.
+var zeroWidthClusterPattern = /^(?:\p{Default_Ignorable_Code_Point}|\p{Control}|\p{Format}|\p{Nonspacing_Mark}|\p{Enclosing_Mark}|\p{Surrogate})+$/u;
+var emojiPattern = /\p{Emoji}/u;
+var emojiPresentationPattern = /\p{Emoji_Presentation}/u;
+var emojiModifierPattern = /\p{Emoji_Modifier}/u;
+var regionalIndicatorPattern = /\p{Regional_Indicator}/gu;
+var extendedPictographicPattern = /\p{Extended_Pictographic}/gu;
+var keycapPattern = /^[\d#*]\uFE0F?\u20E3$/;
+var keycapBaseWithVs16Pattern = /^[\d#*]\uFE0F$/;
+
+function stringWidth(text) {
+	// Measure Western Unicode and emoji terminal columns, ignoring ANSI styling.
+	if ((typeof(text) != 'string') || !text.length) return 0;
+	text = text.replace(ansiPattern, '');
+	if (!text.length) return 0;
+	
+	// Printable ASCII needs no Unicode segmentation and is by far the common case.
+	if (text.match(/^[\u0020-\u007E]*$/)) return text.length;
+	
+	var width = 0;
+	var segments = graphemeSegmenter.segment(text);
+	for (var item of segments) {
+		var segment = item.segment;
+		if (zeroWidthClusterPattern.test(segment)) continue;
+		
+		// Native emoji generally occupy two terminal columns.  The extra checks cover
+		// text-default emoji switched by VS16, flags, keycaps and unqualified sequences.
+		var regionalIndicators = segment.match(regionalIndicatorPattern);
+		var pictographs = segment.match(extendedPictographicPattern);
+		var isEmoji = false;
+		
+		if (segment.includes('\u20E3')) {
+			isEmoji = keycapPattern.test(segment);
+		}
+		else if (regionalIndicators) {
+			isEmoji = (regionalIndicators.length >= 2);
+		}
+		else {
+			isEmoji = emojiPresentationPattern.test(segment) ||
+				(emojiPattern.test(segment) && segment.includes('\uFE0F') &&
+					!keycapBaseWithVs16Pattern.test(segment)) ||
+				(emojiPattern.test(segment) && emojiModifierPattern.test(segment)) ||
+				(segment.includes('\u200D') && pictographs && (pictographs.length >= 2));
+		}
+		
+		width += isEmoji ? 2 : 1;
+	}
+	
+	return width;
+}
+
+function widestLine(text) {
+	// Return the visual width of the widest line in a multi-line string.
+	var width = 0;
+	text.split(/\n/).forEach( function(line) {
+		width = Math.max( width, stringWidth(line) );
+	} );
+	return width;
+}
+
+function truncate(text, width, suffix) {
+	// Truncate a string to an exact terminal display width.  Preserve complete ANSI
+	// sequences and grapheme clusters, and retain trailing SGR codes to reset styles.
+	if (typeof(text) != 'string') text = '' + text;
+	if (suffix == null) suffix = '';
+	if (stringWidth(text) <= width) return text;
+	
+	var suffixWidth = stringWidth(suffix);
+	var contentWidth = Math.max(0, width - suffixWidth);
+	var outputWidth = 0;
+	var output = '';
+	var units = Util.splitAnsiGraphemes(text);
+	var trailingAnsi = [];
+	
+	for (var idx = units.length - 1; idx >= 0; idx--) {
+		if (!units[idx].ansi) break;
+		if (units[idx].text.match(/^(?:\u001B\[|\u009B)[^m]*m$/)) {
+			trailingAnsi.unshift(units[idx].text);
+		}
+	}
+	
+	for (var idx = 0, len = units.length; idx < len; idx++) {
+		var unit = units[idx];
+		if (unit.ansi) {
+			output += unit.text;
+			continue;
+		}
+		
+		var unitWidth = stringWidth(unit.text);
+		if ((outputWidth + unitWidth) > contentWidth) break;
+		output += unit.text;
+		outputWidth += unitWidth;
+	}
+	
+	// A wide grapheme may not fit the final available cell.  Pad that cell so the
+	// ellipsis still lands at the exact requested width and tables remain aligned.
+	if (outputWidth < contentWidth) output += ' '.repeat(contentWidth - outputWidth);
+	return output + suffix + trailingAnsi.join('');
+}
+
+// Preserve the compatibility aliases provided by the old CommonJS dependencies.
+stringWidth.default = stringWidth;
+widestLine.default = widestLine;
+
+module.exports = {
+	stringWidth: stringWidth,
+	widestLine: widestLine,
+	truncate: truncate
+};

package/wrap.js

@@ -0,0 +1,122 @@
+// Display-width-aware word wrapping for pixl-cli.
+
+var Util = require('./util');
+var stringWidth = require('./width').stringWidth;
+
+function getWrapTokens(text) {
+	// Split text into alternating words and breakable whitespace, while preserving
+	// ANSI sequences as zero-width units in their original positions.
+	var units = Util.splitAnsiGraphemes(text);
+	units.forEach( function(unit) {
+		unit.width = unit.ansi ? 0 : stringWidth(unit.text);
+		unit.breakable = !unit.ansi && !!unit.text.match(/^(?:\s|\u200B)+$/u);
+	} );
+	
+	var tokens = [];
+	var token = null;
+	var pending = [];
+	units.forEach( function(unit) {
+		// ANSI codes do not determine whether a token is a word or whitespace.
+		if (unit.ansi) {
+			if (token) token.units.push(unit);
+			else pending.push(unit);
+			return;
+		}
+		
+		var type = unit.breakable ? 'break' : 'word';
+		if (!token || (token.type != type)) {
+			if (token) tokens.push(token);
+			token = { type: type, units: pending.concat([unit]) };
+			pending = [];
+		}
+		else token.units.push(unit);
+	} );
+	
+	if (token) tokens.push(token);
+	else if (pending.length) tokens.push({ type: 'word', units: pending });
+	return tokens;
+}
+
+function joinWrapUnits(units) {
+	// Join tokenized graphemes and ANSI sequences back into their original string.
+	return units.map( function(unit) { return unit.text; } ).join('');
+}
+
+function trimWrapLines(text) {
+	// Trim spaces and tabs from each line without removing the initial indentation.
+	return text.split('\n').map( function(line) {
+		return line.replace(/[ \t]+$/, '');
+	} ).join('\n');
+}
+
+function wordWrap(text, options) {
+	// Wrap text using terminal display columns instead of JavaScript string length.
+	options = options || {};
+	if (text == null) return text;
+	
+	var width = options.width || 50;
+	var indent = (typeof(options.indent) == 'string') ? options.indent : '  ';
+	var newline = options.newline || ('\n' + indent);
+	var escape = (typeof(options.escape) == 'function') ? options.escape : function(value) {
+		return value;
+	};
+	var tokens = getWrapTokens(text);
+	var lines = [];
+	var lineUnits = [];
+	
+	var flushLine = function() {
+		var line = joinWrapUnits(lineUnits);
+		if (line.slice(-1) == '\n') line = line.slice(0, -1);
+		lines.push( escape(line) );
+		lineUnits = [];
+	};
+	
+	if (options.cut === true) {
+		// Cut mode fills every line to the requested display width, even when that
+		// means breaking a word.  Complete grapheme clusters always stay together.
+		var lineWidth = 0;
+		tokens.forEach( function(token) {
+			token.units.forEach( function(unit) {
+				if (unit.text.includes('\n')) {
+					if (stringWidth(joinWrapUnits(lineUnits))) flushLine();
+					else lineUnits = [];
+					lineWidth = 0;
+					return;
+				}
+				
+				if (!unit.ansi && lineWidth && ((lineWidth + unit.width) > width)) {
+					flushLine();
+					lineWidth = 0;
+				}
+				lineUnits.push(unit);
+				lineWidth += unit.width;
+			} );
+		} );
+	}
+	else {
+		tokens.forEach( function(token) {
+			var tokenText = joinWrapUnits(token.units);
+			
+			if (token.type == 'break') {
+				lineUnits = lineUnits.concat(token.units);
+				if (tokenText.includes('\n')) {
+					if (stringWidth(joinWrapUnits(lineUnits))) flushLine();
+					else lineUnits = [];
+				}
+				return;
+			}
+			
+			var lineText = joinWrapUnits(lineUnits);
+			var candidateWidth = stringWidth(lineText + tokenText);
+			if (lineUnits.length && (candidateWidth > width)) flushLine();
+			lineUnits = lineUnits.concat(token.units);
+		} );
+	}
+	
+	if (lineUnits.length) flushLine();
+	var result = indent + lines.join(newline);
+	if (options.trim === true) result = trimWrapLines(result);
+	return result;
+}
+
+module.exports = wordWrap;