@peteanderson/ansi 0.2.4 → 0.3.0

package/src/slice.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const {rxCSI, rxSGR}  = require("./patterns");
+const {simplify}      = require("./simplify");
+const {visibleLength} = require("./strip");
+
+/**
+@type {
+	(
+		text            : string,
+		fromStringIndex : number,
+		visibleCount    : number,
+	) => {index: number, length: number}
+}
+*/
+function scanCSI(text, fromStringIndex, visibleCount) {
+	// We intentionally mutate `lastIndex` here, so we need a clone.
+	const rx = new RegExp(rxCSI);
+
+	let length = 0;
+	let index  = fromStringIndex;
+
+	while (index < text.length && length < visibleCount) {
+		if (text[index] === "\x1b") {
+			rx.lastIndex = index;
+			const match = rx.exec(text);
+			if (match?.index === index) {
+				index += match[0].length;
+				continue;
+			}
+		}
+
+		index++;
+		length++;
+	}
+
+	return {index, length};
+}
+
+/** @type {(text: string, start: number, end?: number) => string} */
+function skippedSequences(text, start, end) {
+	const sequences = text.slice(start, end).match(new RegExp(rxSGR));
+	return sequences ? simplify(sequences.join("")) : "";
+}
+
+/**
+ * Return a slice of the given text, counting only visible characters (i.e. ignoring ANSI escape
+ * codes). The returned slice will include any ANSI escape codes from within the slice. In addition,
+ * SGR codes (m) from before and after the slice will be combined, simplified, and included so that
+ * the terminal state before and after the slice will be the same as if the whole string were
+ * printed. If you compose two or more slices together, there may be redundant SGR sequences at the
+ * boundaries, but the result will be correct. You can use `simplify` to remove the redundancies.
+ *
+ * Note the following caveats:
+ *
+ *   * Any non-SGR ANSI codes prior to or after the slice will be ignored.
+ *   * Control characters (such as newlines and backspaces) both outside and inside the slice are
+ *     counted as visible characters.
+ *
+ * These caveats mean that text may not appear on screen to be the same number of characters as the
+ * length of the slice, and that the terminal state may not be exactly the same at the start and end
+ * of the slice as it would be if the whole string were printed. This function is intended mostly
+ * for text that contains SGR codes, but no other ANSI codes or control characters.
+ *
+ * @type {(text: string, start: number, end: number) => string}
+ */
+function slice(text, start, end) {
+	/** @type {number | undefined} */
+	let textVisibleLength;
+	const getVisibleLength = () => textVisibleLength ??= visibleLength(text);
+
+	if (start < 0 || end < 0) {
+		textVisibleLength = getVisibleLength();
+		if (start < 0)
+			start = Math.max(0, textVisibleLength + start);
+		if (end < 0)
+			end = Math.max(0, textVisibleLength + end);
+	}
+	if (start > end)
+		return "";
+
+	if (start === 0 && (end >= text.length || end >= getVisibleLength()))
+		return text;
+
+	const {index: startIndex, length: visibleSkipped} = scanCSI(text, 0, start);
+
+	const endIndex =
+		startIndex < text.length && visibleSkipped < end
+			? scanCSI(text, startIndex, end - visibleSkipped).index
+			: text.length;
+
+	// Start and end the string in the same terminal state it would be in if the string weren't sliced.
+	const leadingSequences  = skippedSequences(text, 0, startIndex);
+	const trailingSequences = skippedSequences(text, endIndex);
+
+	return leadingSequences + text.slice(startIndex, endIndex) + trailingSequences;
+}
+
+module.exports = {slice};

package/src/strip.js

@@ -0,0 +1,23 @@
+"use strict";
+
+const {rxCSI, rxUnsafe} = require("./patterns");
+
+/**
+ * Remove all ANSI escape codes from the given text.
+ * @type {(text: string) => string}
+ */
+const strip = text => text.replace(new RegExp(rxCSI), "");
+
+/**
+ * Calculate the visible length of a string with ANSI escape codes stripped.
+ * @type {(text: string) => number}
+ */
+const visibleLength = text => strip(text).length;
+
+/**
+ * Remove all ANSI escape codes except SGR codes (m), which are used for color and styling.
+ * @type {(text: string) => string}
+ */
+const sanitize = text => text.replace(new RegExp(rxUnsafe), "");
+
+module.exports = {strip, visibleLength, sanitize};

package/ansi.js

@@ -1,28 +0,0 @@
-"use strict";
-
-const caret                            = require("./caret");
-const erase                            = require("./erase");
-const scroll                           = require("./scroll");
-const {bg, fg, reset, style}           = require("./sgr");
-const {simplify}                       = require("./simplify");
-const {slice}                          = require("./slice");
-const {sanitize, strip, visibleLength} = require("./strip");
-
-const ansi = {
-	caret,
-	erase,
-	scroll,
-
-	reset,
-	style,
-	fg,
-	bg,
-
-	strip,
-	visibleLength,
-	sanitize,
-	slice,
-	simplify,
-};
-
-module.exports = ansi;