@ansi-tools/parser 0.0.0

package/dist/parse-ClmKWMZx.js

@@ -0,0 +1,485 @@
+//#region src/constants.ts
+const BELL = String.fromCharCode(7);
+const ESC = String.fromCharCode(27);
+const BACKSLASH = String.fromCharCode(92);
+const DCS = String.fromCharCode(144);
+const SOS = String.fromCharCode(152);
+const CSI = String.fromCharCode(155);
+const ST = String.fromCharCode(156);
+const OSC = String.fromCharCode(157);
+const PM = String.fromCharCode(158);
+const APC = String.fromCharCode(159);
+const CSI_OPEN = "[";
+const OSC_OPEN = "]";
+const DEC_OPEN = "?";
+const PRIVATE_OPENERS = new Set([
+	"<",
+	"=",
+	">"
+]);
+const DCS_OPEN = "P";
+const APC_OPEN = "_";
+const SOS_OPEN = "^";
+const PM_OPEN = "X";
+const STRING_OPENERS = new Set([
+	DCS_OPEN,
+	APC_OPEN,
+	SOS_OPEN,
+	PM_OPEN
+]);
+const TOKEN_TYPES = {
+	TEXT: "TEXT",
+	INTRODUCER: "INTRODUCER",
+	DATA: "DATA",
+	FINAL: "FINAL"
+};
+const CODE_TYPES = {
+	CSI: "CSI",
+	DCS: "DCS",
+	DEC: "DEC",
+	ESC: "ESC",
+	OSC: "OSC",
+	PRIVATE: "PRIVATE",
+	SGR: "SGR",
+	STRING: "STRING",
+	TEXT: "TEXT"
+};
+
+//#endregion
+//#region src/parsers/csi.ts
+function parseCSI(pos, raw, data, final) {
+	const params = [];
+	let intermediates = "";
+	if (data) {
+		let i = 0;
+		let paramSection = "";
+		while (i < data.length && data.charCodeAt(i) >= 48 && data.charCodeAt(i) <= 63) {
+			paramSection += data[i];
+			i++;
+		}
+		intermediates = data.slice(i);
+		if (paramSection) {
+			let current = "";
+			for (let j = 0; j < paramSection.length; j++) if (paramSection[j] === ";") {
+				params.push(current || "-1");
+				current = "";
+			} else current += paramSection[j];
+			params.push(current || "-1");
+		}
+	}
+	const command = intermediates + final;
+	return {
+		type: CODE_TYPES.CSI,
+		pos,
+		raw,
+		command,
+		params
+	};
+}
+function parsePrivateCSI(pos, raw, data, final) {
+	const privateIndicator = data[0];
+	const withoutIndicator = data.slice(1);
+	const match = withoutIndicator.match(/^([\d;]*)(.*)/);
+	const paramsRaw = match?.[1] ?? "";
+	const intermediates = match?.[2] ?? "";
+	const command = `${privateIndicator}${intermediates}${final}`;
+	const params = [];
+	if (paramsRaw) {
+		let current = "";
+		for (let i = 0; i < paramsRaw.length; i++) if (paramsRaw[i] === ";") {
+			params.push(current || "-1");
+			current = "";
+		} else current += paramsRaw[i];
+		params.push(current || "-1");
+	}
+	return {
+		type: CODE_TYPES.PRIVATE,
+		pos,
+		raw,
+		command,
+		params
+	};
+}
+
+//#endregion
+//#region src/parsers/dcs.ts
+const DCS_PATTERNS = new Map([
+	["$q", 2],
+	["+q", 2],
+	["+p", 2],
+	["|", 1],
+	["{", 1]
+]);
+function parseDCS(pos, raw, data) {
+	if (!data) return {
+		type: CODE_TYPES.DCS,
+		pos,
+		raw,
+		command: "",
+		params: []
+	};
+	for (const [pattern, length] of DCS_PATTERNS) if (data.startsWith(pattern)) {
+		const remainder = data.slice(length);
+		const params = [];
+		if (remainder) {
+			let current = "";
+			for (let i = 0; i < remainder.length; i++) if (remainder[i] === ";") {
+				params.push(current || "-1");
+				current = "";
+			} else current += remainder[i];
+			params.push(current || "-1");
+		}
+		return {
+			type: CODE_TYPES.DCS,
+			pos,
+			raw,
+			command: pattern,
+			params
+		};
+	}
+	return {
+		type: CODE_TYPES.DCS,
+		pos,
+		raw,
+		command: "",
+		params: [data]
+	};
+}
+
+//#endregion
+//#region src/parsers/dec.ts
+function parseDEC(pos, raw, data, final) {
+	const withoutPrefix = data.slice(1);
+	let i = 0;
+	let paramsRaw = "";
+	while (i < withoutPrefix.length && (withoutPrefix.charCodeAt(i) >= 48 && withoutPrefix.charCodeAt(i) <= 57 || withoutPrefix[i] === ";")) {
+		paramsRaw += withoutPrefix[i];
+		i++;
+	}
+	const command = withoutPrefix.slice(i) + final;
+	const params = [];
+	if (paramsRaw) {
+		let current = "";
+		for (let j = 0; j < paramsRaw.length; j++) if (paramsRaw[j] === ";") {
+			params.push(current || "-1");
+			current = "";
+		} else current += paramsRaw[j];
+		params.push(current || "-1");
+	}
+	return {
+		type: CODE_TYPES.DEC,
+		pos,
+		raw,
+		command,
+		params
+	};
+}
+
+//#endregion
+//#region src/parsers/esc.ts
+function parseESC(pos, raw, command, data) {
+	return {
+		type: CODE_TYPES.ESC,
+		pos,
+		raw,
+		command,
+		params: data ? [data] : []
+	};
+}
+
+//#endregion
+//#region src/parsers/osc.ts
+function parseOSC(pos, raw, data) {
+	const semicolonIndex = data.indexOf(";");
+	if (semicolonIndex === -1) return {
+		type: CODE_TYPES.OSC,
+		pos,
+		raw,
+		command: data,
+		params: []
+	};
+	const command = data.slice(0, semicolonIndex);
+	const remainder = data.slice(semicolonIndex + 1);
+	if (command === "1337") return {
+		type: CODE_TYPES.OSC,
+		pos,
+		raw,
+		command,
+		params: [remainder]
+	};
+	const params = [];
+	if (remainder) {
+		let current = "";
+		for (let i = 0; i < remainder.length; i++) if (remainder[i] === ";") {
+			params.push(current);
+			current = "";
+		} else current += remainder[i];
+		params.push(current);
+	}
+	return {
+		type: CODE_TYPES.OSC,
+		pos,
+		raw,
+		command,
+		params
+	};
+}
+
+//#endregion
+//#region src/tokenize.ts
+const INTRODUCERS = new Set([
+	ESC,
+	CSI,
+	OSC,
+	DCS,
+	APC,
+	PM,
+	SOS
+]);
+function emit$1(token) {
+	return token;
+}
+function* tokenizer(input) {
+	let i = 0;
+	let state = "GROUND";
+	let currentCode;
+	function setState(next, code) {
+		state = next;
+		currentCode = code;
+	}
+	while (i < input.length) if (state === "GROUND") {
+		const textStart = i;
+		while (i < input.length) {
+			const char = input[i];
+			if (INTRODUCERS.has(char)) break;
+			i++;
+		}
+		if (i > textStart) yield emit$1({
+			type: TOKEN_TYPES.TEXT,
+			pos: textStart,
+			raw: input.substring(textStart, i)
+		});
+		if (i < input.length) {
+			const char = input[i];
+			if (char === CSI || char === OSC || char === DCS || char === APC || char === PM || char === SOS) {
+				yield emit$1({
+					type: TOKEN_TYPES.INTRODUCER,
+					pos: i,
+					raw: char,
+					code: char
+				});
+				i++;
+				setState("SEQUENCE", char);
+			} else if (char === ESC) {
+				const next = input[i + 1];
+				if (next === CSI_OPEN) {
+					yield emit$1({
+						type: TOKEN_TYPES.INTRODUCER,
+						pos: i,
+						raw: char + next,
+						code: CSI
+					});
+					i += 2;
+					setState("SEQUENCE", CSI);
+				} else if (next === OSC_OPEN) {
+					yield emit$1({
+						type: TOKEN_TYPES.INTRODUCER,
+						pos: i,
+						raw: char + next,
+						code: OSC
+					});
+					i += 2;
+					setState("SEQUENCE", OSC);
+				} else if (STRING_OPENERS.has(next)) {
+					yield emit$1({
+						type: TOKEN_TYPES.INTRODUCER,
+						pos: i,
+						raw: char + next,
+						code: next
+					});
+					i += 2;
+					setState("SEQUENCE", next);
+				} else if (next && next.charCodeAt(0) >= 32 && next.charCodeAt(0) <= 47) {
+					yield emit$1({
+						type: TOKEN_TYPES.INTRODUCER,
+						pos: i,
+						raw: char,
+						code: ESC
+					});
+					i += 1;
+					yield emit$1({
+						type: TOKEN_TYPES.FINAL,
+						pos: i,
+						raw: next
+					});
+					i++;
+				} else if (next) {
+					yield emit$1({
+						type: TOKEN_TYPES.INTRODUCER,
+						pos: i,
+						raw: char,
+						code: ESC
+					});
+					yield emit$1({
+						type: TOKEN_TYPES.FINAL,
+						pos: i + 1,
+						raw: next
+					});
+					i += 2;
+				} else {
+					yield emit$1({
+						type: TOKEN_TYPES.INTRODUCER,
+						pos: i,
+						raw: char,
+						code: ESC
+					});
+					i++;
+				}
+			}
+		}
+	} else {
+		const pos = i;
+		const code = currentCode;
+		let data = "";
+		if (code === CSI) while (i < input.length) {
+			const char = input[i];
+			const charCode = char.charCodeAt(0);
+			if (charCode >= 64 && charCode < 126) {
+				if (data) yield emit$1({
+					type: TOKEN_TYPES.DATA,
+					pos,
+					raw: data
+				});
+				yield emit$1({
+					type: TOKEN_TYPES.FINAL,
+					pos: i,
+					raw: char
+				});
+				i++;
+				break;
+			}
+			data += char;
+			i++;
+		}
+		else if (code) while (i < input.length) {
+			const char = input[i];
+			let terminator;
+			if (char === ST) terminator = ST;
+			else if (char === BELL && code === OSC) terminator = BELL;
+			else if (char === ESC && input[i + 1] === BACKSLASH) terminator = ESC + BACKSLASH;
+			if (terminator) {
+				if (data) yield emit$1({
+					type: TOKEN_TYPES.DATA,
+					pos,
+					raw: data
+				});
+				yield emit$1({
+					type: TOKEN_TYPES.FINAL,
+					pos: i,
+					raw: terminator
+				});
+				i += terminator.length;
+				break;
+			}
+			data += char;
+			i++;
+		}
+		setState("GROUND");
+	}
+}
+function tokenize(input) {
+	return Array.from(tokenizer(input));
+}
+
+//#endregion
+//#region src/parse.ts
+function emit(token) {
+	return token;
+}
+function* parser(tokens) {
+	let current = tokens.next();
+	while (!current.done) {
+		const token = current.value;
+		if (token.type === TOKEN_TYPES.TEXT) {
+			yield emit({
+				type: CODE_TYPES.TEXT,
+				pos: token.pos,
+				raw: token.raw
+			});
+			current = tokens.next();
+			continue;
+		}
+		if (token.type === TOKEN_TYPES.INTRODUCER) {
+			const pos = token.pos;
+			let raw = token.raw;
+			let data = "";
+			let finalToken;
+			current = tokens.next();
+			while (!current.done && !finalToken) {
+				const nextToken = current.value;
+				if (nextToken.type === TOKEN_TYPES.DATA) {
+					data += nextToken.raw;
+					raw += nextToken.raw;
+				} else if (nextToken.type === TOKEN_TYPES.FINAL) {
+					finalToken = nextToken;
+					raw += nextToken.raw;
+				}
+				current = tokens.next();
+			}
+			if (finalToken) switch (token.code) {
+				case CSI:
+					if (data.startsWith(DEC_OPEN)) yield emit(parseDEC(pos, raw, data, finalToken.raw));
+					else if (PRIVATE_OPENERS.has(data[0])) yield emit(parsePrivateCSI(pos, raw, data, finalToken.raw));
+					else yield emit(parseCSI(pos, raw, data, finalToken.raw));
+					break;
+				case OSC:
+					yield emit(parseOSC(pos, raw, data));
+					break;
+				case DCS:
+				case DCS_OPEN:
+					yield emit(parseDCS(pos, raw, data));
+					break;
+				case APC:
+				case APC_OPEN:
+					yield emit({
+						type: CODE_TYPES.STRING,
+						pos,
+						raw,
+						command: "APC",
+						params: data ? [data] : []
+					});
+					break;
+				case PM:
+				case PM_OPEN:
+					yield emit({
+						type: CODE_TYPES.STRING,
+						pos,
+						raw,
+						command: "PM",
+						params: data ? [data] : []
+					});
+					break;
+				case SOS:
+				case SOS_OPEN:
+					yield emit({
+						type: CODE_TYPES.STRING,
+						pos,
+						raw,
+						command: "SOS",
+						params: data ? [data] : []
+					});
+					break;
+				case ESC:
+					yield emit(parseESC(pos, raw, finalToken.raw, data));
+					break;
+			}
+			else if (token.code === ESC) yield emit(parseESC(pos, raw, "", ""));
+		} else current = tokens.next();
+	}
+}
+function parse(input) {
+	return Array.from(parser(tokenizer(input)));
+}
+
+//#endregion
+export { APC, APC_OPEN, BACKSLASH, BELL, CODE_TYPES, CSI, CSI_OPEN, DCS, DCS_OPEN, DEC_OPEN, ESC, OSC, OSC_OPEN, PM, PM_OPEN, PRIVATE_OPENERS, SOS, SOS_OPEN, ST, STRING_OPENERS, TOKEN_TYPES, parse, parser, tokenize, tokenizer };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ansi-tools/parser",
+  "version": "0.0.0",
+  "description": "Tokenize and parse strings containing ANSI escape sequences and control codes",
+  "main": "./dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./escaped": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/escaped.js",
+      "default": "./dist/escaped.js"
+    }
+  },
+  "keywords": [
+    "ansi",
+    "escape codes",
+    "web application"
+  ],
+  "author": "Lars Kappert <lars@webpro.nl>",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.13",
+    "tsdown": "^0.12.9",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "prebuild": "pnpm type-check && pnpm test",
+    "build": "tsdown --dts src/index.ts src/escaped.ts",
+    "test": "node --test",
+    "type-check": "tsc"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,40 @@
+export const BELL = String.fromCharCode(7);
+export const ESC = String.fromCharCode(27);
+export const BACKSLASH = String.fromCharCode(92);
+export const DCS = String.fromCharCode(144);
+export const SOS = String.fromCharCode(152);
+export const CSI = String.fromCharCode(155);
+export const ST = String.fromCharCode(156);
+export const OSC = String.fromCharCode(157);
+export const PM = String.fromCharCode(158);
+export const APC = String.fromCharCode(159);
+
+export const CSI_OPEN = "[";
+export const OSC_OPEN = "]";
+export const DEC_OPEN = "?";
+export const PRIVATE_OPENERS = new Set(["<", "=", ">"]);
+
+export const DCS_OPEN = "P";
+export const APC_OPEN = "_";
+export const SOS_OPEN = "^";
+export const PM_OPEN = "X";
+export const STRING_OPENERS = new Set([DCS_OPEN, APC_OPEN, SOS_OPEN, PM_OPEN]);
+
+export const TOKEN_TYPES = {
+  TEXT: "TEXT",
+  INTRODUCER: "INTRODUCER",
+  DATA: "DATA",
+  FINAL: "FINAL",
+} as const;
+
+export const CODE_TYPES = {
+  CSI: "CSI",
+  DCS: "DCS",
+  DEC: "DEC",
+  ESC: "ESC",
+  OSC: "OSC",
+  PRIVATE: "PRIVATE",
+  SGR: "SGR",
+  STRING: "STRING",
+  TEXT: "TEXT",
+} as const;

package/src/escaped.ts

@@ -0,0 +1,4 @@
+export * from "./constants.ts";
+export { parse, parser } from "./parse.ts";
+export { tokenize, tokenizer } from "./tokenize.escaped.ts";
+export type { CODE, CONTROL_CODE, CONTROL_CODE_TEXT, TOKEN } from "./types.ts";

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./constants.ts";
+export { parse, parser } from "./parse.ts";
+export { tokenize, tokenizer } from "./tokenize.ts";
+export type { CODE, CONTROL_CODE, CONTROL_CODE_TEXT, TOKEN } from "./types.ts";

package/src/parse.escaped.test.ts

@@ -0,0 +1,86 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { tokenizer } from "./tokenize.escaped.ts";
+import { parser } from "./parse.ts";
+import { CODE_TYPES } from "./constants.ts";
+
+test("parse simple text", () => {
+  const input = "hello world";
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [{ type: CODE_TYPES.TEXT, pos: 0, raw: "hello world" }]);
+});
+
+test("parse mixed text and csi", () => {
+  const input = String.raw`hello \e[31mworld\e[0m`;
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [
+    { type: CODE_TYPES.TEXT, pos: 0, raw: "hello " },
+    { type: CODE_TYPES.CSI, pos: 6, raw: "\\e[31m", params: ["31"], command: "m" },
+    { type: CODE_TYPES.TEXT, pos: 12, raw: "world" },
+    { type: CODE_TYPES.CSI, pos: 17, raw: "\\e[0m", params: ["0"], command: "m" },
+  ]);
+});
+
+test("subsequent escape sequences", () => {
+  const input = String.raw`\e[31m\e[32m\e[33m`;
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [
+    { type: CODE_TYPES.CSI, pos: 0, raw: "\\e[31m", params: ["31"], command: "m" },
+    { type: CODE_TYPES.CSI, pos: 6, raw: "\\e[32m", params: ["32"], command: "m" },
+    { type: CODE_TYPES.CSI, pos: 12, raw: "\\e[33m", params: ["33"], command: "m" },
+  ]);
+});
+
+test("parse multiple different sequence types", () => {
+  const input = String.raw`\e[1;32m\e]0;title\a\e=\ePdata\e\\`;
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [
+    { type: CODE_TYPES.CSI, pos: 0, raw: "\\e[1;32m", params: ["1", "32"], command: "m" },
+    { type: CODE_TYPES.OSC, pos: 8, raw: "\\e]0;title\\a", params: ["title"], command: "0" },
+    { type: CODE_TYPES.ESC, pos: 20, raw: "\\e=", command: "=", params: [] },
+    { type: CODE_TYPES.DCS, pos: 23, raw: "\\ePdata\\e\\\\", params: ["data"], command: "" },
+  ]);
+});
+
+test("parse mixed standard and private sequences", () => {
+  const input = String.raw`\e[31m\e[<5h\e[?25l\e[>c`;
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [
+    { type: CODE_TYPES.CSI, pos: 0, raw: "\\e[31m", params: ["31"], command: "m" },
+    { type: CODE_TYPES.PRIVATE, pos: 6, raw: "\\e[<5h", params: ["5"], command: "<h" },
+    { type: CODE_TYPES.DEC, pos: 12, raw: "\\e[?25l", params: ["25"], command: "l" },
+    { type: CODE_TYPES.PRIVATE, pos: 19, raw: "\\e[>c", params: [], command: ">c" },
+  ]);
+});
+
+test("parse complex missing parameter scenarios", () => {
+  const input = String.raw`\e[;5;m\e[?;h\eP$q;;\e\\`;
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [
+    { type: CODE_TYPES.CSI, pos: 0, raw: "\\e[;5;m", params: ["-1", "5", "-1"], command: "m" },
+    { type: CODE_TYPES.DEC, pos: 7, raw: "\\e[?;h", params: ["-1", "-1"], command: "h" },
+    { type: CODE_TYPES.DCS, pos: 13, raw: "\\eP$q;;\\e\\\\", params: ["-1", "-1", "-1"], command: "$q" },
+  ]);
+});
+
+test("parse iTerm2 image sequence", () => {
+  const input = String.raw`\e]1337;File=inline=1;width=1;height=1:R0lG=\a`;
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [
+    { type: CODE_TYPES.OSC, pos: 0, raw: input, command: "1337", params: ["File=inline=1;width=1;height=1:R0lG="] },
+  ]);
+});
+
+test("parse DECUDK sequence", () => {
+  const input = String.raw`\eP0|23/68656c6c6f\e\\`;
+  const tokens = tokenizer(input);
+  const codes = [...parser(tokens)];
+  assert.deepEqual(codes, [{ type: CODE_TYPES.DCS, pos: 0, raw: input, command: "", params: ["0|23/68656c6c6f"] }]);
+});