xls-codec 4.9.0 → 4.11.0

package/dist/biff/ptg-writer.cjs

@@ -0,0 +1,546 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_errors = require("./errors.cjs");
+const require_biff_write_errors = require("./write-errors.cjs");
+const require_biff_ptg_functions = require("./ptg-functions.cjs");
+const require_biff_string_writer = require("./string-writer.cjs");
+let document_schema_js = require("document-schema.js");
+//#region src/biff/ptg-writer.ts
+const PTG_ADD = 3;
+const PTG_SUB = 4;
+const PTG_MUL = 5;
+const PTG_DIV = 6;
+const PTG_POWER = 7;
+const PTG_CONCAT = 8;
+const PTG_LT = 9;
+const PTG_LE = 10;
+const PTG_EQ = 11;
+const PTG_GE = 12;
+const PTG_GT = 13;
+const PTG_NE = 14;
+const PTG_UPLUS = 18;
+const PTG_UMINUS = 19;
+const PTG_PERCENT = 20;
+const PTG_PAREN = 21;
+const PTG_MISSARG = 22;
+const PTG_STR = 23;
+const PTG_ERR = 28;
+const PTG_BOOL = 29;
+const PTG_INT = 30;
+const PTG_NUM = 31;
+/** The "value" class of the reference/function token family -- see biff/ptg.ts's own top comment for why REF/VALUE/ARRAY share one on-disk field layout and this writer, like every other real minimal BIFF8 writer, does not need to distinguish them for an ordinary (non-array) formula. */
+const PTG_REF_VALUE = 68;
+const PTG_AREA_VALUE = 69;
+const PTG_FUNC_VALUE = 65;
+const PTG_FUNCVAR_VALUE = 66;
+const COLUMN_RELATIVE_BIT = 16384;
+const ROW_RELATIVE_BIT = 32768;
+/** BIFF8's own 16-bit row index and 8-bit column index ceilings ([MS-XLS] 2.4.221's Rw structure and 2.4.53's Col256U structure) -- the identical grid workbook/sheet-writer.ts's own checkedCellPosition enforces for a cell record's own row/column. */
+const MAX_ROW_INDEX = 65535;
+const MAX_COLUMN_INDEX = 255;
+/** PtgInt's own ceiling ([MS-XLS] 2.5.198.28): an unsigned 16-bit integer. A plain non-negative integer literal above this, or one carrying a decimal point or exponent in its own source text, is written as PtgNum instead, so the reader's own String(cursor.u16())/String(cursor.f64()) reconstructs the identical text. */
+const PTG_INT_MAX = 65535;
+var RgceBuilder = class {
+	parts = [];
+	push(...bytes) {
+		this.parts.push(bytes);
+		return this;
+	}
+	u16(value) {
+		const bits = value & 65535;
+		return this.push(bits & 255, bits >>> 8 & 255);
+	}
+	f64(value) {
+		const buffer = /* @__PURE__ */ new ArrayBuffer(8);
+		new DataView(buffer).setFloat64(0, value, true);
+		return this.push(...new Uint8Array(buffer));
+	}
+	concat(bytes) {
+		this.parts.push(Array.from(bytes));
+		return this;
+	}
+	build() {
+		const flat = this.parts.flat();
+		return new Uint8Array(flat);
+	}
+};
+const NUMBER_RE = /^[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?/;
+const WORD_RE = /^[A-Za-z][A-Za-z0-9_.]*/;
+const ERROR_RE = /^#[A-Za-z0-9/?!_]+/;
+const OPERATORS = [
+	"<=",
+	">=",
+	"<>",
+	"+",
+	"-",
+	"*",
+	"/",
+	"^",
+	"&",
+	"<",
+	">",
+	"=",
+	"%"
+];
+function tokenize(text) {
+	const tokens = [];
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index];
+		if (char === " " || char === "	" || char === "\n" || char === "\r") {
+			index += 1;
+			continue;
+		}
+		if (char === "$") {
+			tokens.push({
+				type: "dollar",
+				text: "$"
+			});
+			index += 1;
+			continue;
+		}
+		if (char === ":") {
+			tokens.push({
+				type: "colon",
+				text: ":"
+			});
+			index += 1;
+			continue;
+		}
+		if (char === ",") {
+			tokens.push({
+				type: "comma",
+				text: ","
+			});
+			index += 1;
+			continue;
+		}
+		if (char === "(") {
+			tokens.push({
+				type: "lparen",
+				text: "("
+			});
+			index += 1;
+			continue;
+		}
+		if (char === ")") {
+			tokens.push({
+				type: "rparen",
+				text: ")"
+			});
+			index += 1;
+			continue;
+		}
+		if (char === "\"") {
+			let value = "";
+			let cursor = index + 1;
+			for (;;) {
+				if (cursor >= text.length) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(text)} carries an unterminated string literal starting at offset ${index}`);
+				const current = text.charAt(cursor);
+				if (current === "\"") {
+					if (text.charAt(cursor + 1) === "\"") {
+						value += "\"";
+						cursor += 2;
+						continue;
+					}
+					cursor += 1;
+					break;
+				}
+				value += current;
+				cursor += 1;
+			}
+			tokens.push({
+				type: "string",
+				text: value
+			});
+			index = cursor;
+			continue;
+		}
+		if (char === "#") {
+			const match = ERROR_RE.exec(text.slice(index));
+			if (match?.[0] === void 0) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(text)} carries an unrecognised error literal starting at offset ${index}`);
+			tokens.push({
+				type: "error",
+				text: match[0]
+			});
+			index += match[0].length;
+			continue;
+		}
+		const numberMatch = NUMBER_RE.exec(text.slice(index));
+		if (numberMatch?.[0] !== void 0) {
+			tokens.push({
+				type: "number",
+				text: numberMatch[0]
+			});
+			index += numberMatch[0].length;
+			continue;
+		}
+		const wordMatch = WORD_RE.exec(text.slice(index));
+		if (wordMatch?.[0] !== void 0) {
+			tokens.push({
+				type: "word",
+				text: wordMatch[0]
+			});
+			index += wordMatch[0].length;
+			continue;
+		}
+		const op = OPERATORS.find((candidate) => text.startsWith(candidate, index));
+		if (op !== void 0) {
+			tokens.push({
+				type: "op",
+				text: op
+			});
+			index += op.length;
+			continue;
+		}
+		throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(text)} carries an unrecognised character ${JSON.stringify(char)} at offset ${index}`);
+	}
+	tokens.push({
+		type: "eof",
+		text: ""
+	});
+	return tokens;
+}
+var FormulaParser = class {
+	tokens;
+	position = 0;
+	sourceText;
+	constructor(tokens, sourceText) {
+		this.tokens = tokens;
+		this.sourceText = sourceText;
+	}
+	peek(offset = 0) {
+		const token = this.tokens[this.position + offset];
+		if (token === void 0) throw new require_biff_write_errors.BiffWriteError(`internal error: formula token stream for ${JSON.stringify(this.sourceText)} ran past its own end`);
+		return token;
+	}
+	advance() {
+		const token = this.peek();
+		this.position += 1;
+		return token;
+	}
+	expect(type) {
+		const token = this.peek();
+		if (token.type !== type) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} expected a ${type} but found ${JSON.stringify(token.text)}`);
+		return this.advance();
+	}
+	parseFormula() {
+		const node = this.parseComparison();
+		this.expect("eof");
+		return node;
+	}
+	parseComparison() {
+		let node = this.parseConcat();
+		for (;;) {
+			const token = this.peek();
+			const opcode = this.comparisonOpcode(token);
+			if (opcode === void 0) return node;
+			this.advance();
+			const right = this.parseConcat();
+			node = {
+				kind: "binary",
+				opcode,
+				left: node,
+				right
+			};
+		}
+	}
+	comparisonOpcode(token) {
+		if (token.type !== "op") return void 0;
+		switch (token.text) {
+			case "<": return PTG_LT;
+			case "<=": return PTG_LE;
+			case "=": return PTG_EQ;
+			case ">=": return PTG_GE;
+			case ">": return PTG_GT;
+			case "<>": return PTG_NE;
+			default: return;
+		}
+	}
+	parseConcat() {
+		let node = this.parseAdditive();
+		while (this.peek().type === "op" && this.peek().text === "&") {
+			this.advance();
+			const right = this.parseAdditive();
+			node = {
+				kind: "binary",
+				opcode: PTG_CONCAT,
+				left: node,
+				right
+			};
+		}
+		return node;
+	}
+	parseAdditive() {
+		let node = this.parseMultiplicative();
+		for (;;) {
+			const token = this.peek();
+			if (token.type !== "op" || token.text !== "+" && token.text !== "-") return node;
+			this.advance();
+			const right = this.parseMultiplicative();
+			node = {
+				kind: "binary",
+				opcode: token.text === "+" ? PTG_ADD : PTG_SUB,
+				left: node,
+				right
+			};
+		}
+	}
+	parseMultiplicative() {
+		let node = this.parsePower();
+		for (;;) {
+			const token = this.peek();
+			if (token.type !== "op" || token.text !== "*" && token.text !== "/") return node;
+			this.advance();
+			const right = this.parsePower();
+			node = {
+				kind: "binary",
+				opcode: token.text === "*" ? PTG_MUL : PTG_DIV,
+				left: node,
+				right
+			};
+		}
+	}
+	parsePower() {
+		let node = this.parsePercent();
+		while (this.peek().type === "op" && this.peek().text === "^") {
+			this.advance();
+			const right = this.parsePercent();
+			node = {
+				kind: "binary",
+				opcode: PTG_POWER,
+				left: node,
+				right
+			};
+		}
+		return node;
+	}
+	parsePercent() {
+		let node = this.parseUnary();
+		while (this.peek().type === "op" && this.peek().text === "%") {
+			this.advance();
+			node = {
+				kind: "percent",
+				operand: node
+			};
+		}
+		return node;
+	}
+	parseUnary() {
+		const token = this.peek();
+		if (token.type === "op" && (token.text === "+" || token.text === "-")) {
+			this.advance();
+			const operand = this.parseUnary();
+			return {
+				kind: "unary",
+				opcode: token.text === "+" ? PTG_UPLUS : PTG_UMINUS,
+				operand
+			};
+		}
+		return this.parsePrimary();
+	}
+	parsePrimary() {
+		const token = this.peek();
+		if (token.type === "number") {
+			this.advance();
+			return this.numberNode(token.text);
+		}
+		if (token.type === "string") {
+			this.advance();
+			return {
+				kind: "str",
+				value: token.text
+			};
+		}
+		if (token.type === "error") {
+			this.advance();
+			const code = require_biff_errors.errorCodeOf(token.text);
+			if (code === void 0) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} carries error literal ${token.text}, which is not one of the eight error values [MS-XLS] 2.5.10 defines`);
+			return {
+				kind: "err",
+				code
+			};
+		}
+		if (token.type === "lparen") {
+			this.advance();
+			const inner = this.parseComparison();
+			this.expect("rparen");
+			return {
+				kind: "paren",
+				inner
+			};
+		}
+		if (token.type === "dollar") return this.parseRefOrArea();
+		if (token.type === "word") {
+			if (this.peek(1).type === "lparen") return this.parseCall();
+			if (token.text === "TRUE" || token.text === "FALSE") {
+				this.advance();
+				return {
+					kind: "bool",
+					value: token.text === "TRUE"
+				};
+			}
+			return this.parseRefOrArea();
+		}
+		throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} carries an unexpected token ${JSON.stringify(token.text)}`);
+	}
+	numberNode(text) {
+		const value = Number.parseFloat(text);
+		if (/^[0-9]+$/.test(text) && Number.isInteger(value) && value >= 0 && value <= PTG_INT_MAX) return {
+			kind: "int",
+			value
+		};
+		return {
+			kind: "num",
+			value
+		};
+	}
+	parseCall() {
+		const nameToken = this.expect("word");
+		this.expect("lparen");
+		const args = [];
+		if (this.peek().type !== "rparen") {
+			args.push(this.parseArgument());
+			while (this.peek().type === "comma") {
+				this.advance();
+				args.push(this.parseArgument());
+			}
+		}
+		this.expect("rparen");
+		const iftab = require_biff_ptg_functions.FTAB_IFTAB_BY_NAME.get(nameToken.text);
+		if (iftab === void 0) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} calls ${nameToken.text}(), which is not one of the built-in functions [MS-XLS] 2.5.198.17's own Ftab enumerates`);
+		const fixedArity = require_biff_ptg_functions.FTAB_FIXED_ARITY.get(iftab);
+		if (fixedArity !== void 0 && fixedArity !== args.length) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} calls ${nameToken.text}() with ${args.length} argument(s), but [MS-XLS]'s own Ftab grammar fixes its arity at ${fixedArity}`);
+		return {
+			kind: "call",
+			iftab,
+			variable: fixedArity === void 0,
+			args
+		};
+	}
+	parseArgument() {
+		const token = this.peek();
+		if (token.type === "comma" || token.type === "rparen") return { kind: "missarg" };
+		return this.parseComparison();
+	}
+	parseRefOrArea() {
+		const start = this.parseCellPoint();
+		if (this.peek().type === "colon") {
+			this.advance();
+			return {
+				kind: "area",
+				start,
+				end: this.parseCellPoint()
+			};
+		}
+		return {
+			kind: "ref",
+			point: start
+		};
+	}
+	/** One cell reference's own point, per its own leading `$` (column-absolute) and, for a column-only word, a trailing `$` (row-absolute) -- see this module's own top comment for why a plain (non-`$`-prefixed) reference always lexes as one combined letters-then-digits word token, while a `$`-separated one splits across a dollar/word/dollar/number sequence instead. */
+	parseCellPoint() {
+		let columnAbsolute = false;
+		if (this.peek().type === "dollar") {
+			this.advance();
+			columnAbsolute = true;
+		}
+		const word = this.expect("word");
+		const combined = /^([A-Za-z]{1,3})([0-9]+)$/.exec(word.text);
+		let columnLetters;
+		let rowDigits;
+		let rowAbsolute = false;
+		if (combined?.[1] !== void 0 && combined[2] !== void 0) {
+			columnLetters = combined[1];
+			rowDigits = combined[2];
+		} else {
+			if (!/^[A-Za-z]{1,3}$/.test(word.text)) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} carries ${JSON.stringify(word.text)}, which is not a valid cell reference`);
+			columnLetters = word.text;
+			if (this.peek().type === "dollar") {
+				this.advance();
+				rowAbsolute = true;
+			}
+			const rowToken = this.expect("number");
+			if (!/^[0-9]+$/.test(rowToken.text)) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} carries ${JSON.stringify(word.text + rowToken.text)}, which is not a valid cell reference`);
+			rowDigits = rowToken.text;
+		}
+		const column = (0, document_schema_js.columnLettersToIndex)(columnLetters);
+		const row = Number.parseInt(rowDigits, 10) - 1;
+		if (column === void 0 || column > MAX_COLUMN_INDEX || row < 0 || row > MAX_ROW_INDEX) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(this.sourceText)} references ${columnLetters}${rowDigits}, which is outside BIFF8's own grid (rows 1-65536, columns A-IV)`);
+		return {
+			row,
+			column,
+			columnAbsolute,
+			rowAbsolute
+		};
+	}
+};
+function columnField(point) {
+	return point.column | (point.columnAbsolute ? 0 : COLUMN_RELATIVE_BIT) | (point.rowAbsolute ? 0 : ROW_RELATIVE_BIT);
+}
+function compileNode(builder, node) {
+	switch (node.kind) {
+		case "int":
+			builder.push(PTG_INT).u16(node.value);
+			return;
+		case "num":
+			builder.push(PTG_NUM).f64(node.value);
+			return;
+		case "str":
+			builder.push(PTG_STR).concat(require_biff_string_writer.writeShortXLUnicodeString(node.value));
+			return;
+		case "bool":
+			builder.push(PTG_BOOL, node.value ? 1 : 0);
+			return;
+		case "err":
+			builder.push(PTG_ERR, node.code);
+			return;
+		case "missarg":
+			builder.push(PTG_MISSARG);
+			return;
+		case "ref":
+			builder.push(PTG_REF_VALUE).u16(node.point.row).u16(columnField(node.point));
+			return;
+		case "area":
+			builder.push(PTG_AREA_VALUE).u16(node.start.row).u16(node.end.row).u16(columnField(node.start)).u16(columnField(node.end));
+			return;
+		case "binary":
+			compileNode(builder, node.left);
+			compileNode(builder, node.right);
+			builder.push(node.opcode);
+			return;
+		case "unary":
+			compileNode(builder, node.operand);
+			builder.push(node.opcode);
+			return;
+		case "percent":
+			compileNode(builder, node.operand);
+			builder.push(PTG_PERCENT);
+			return;
+		case "paren":
+			compileNode(builder, node.inner);
+			builder.push(PTG_PAREN);
+			return;
+		case "call":
+			for (const arg of node.args) compileNode(builder, arg);
+			if (node.variable) {
+				if (node.args.length > 255) throw new require_biff_write_errors.BiffWriteError(`a function call with ${node.args.length} arguments cannot be written: PtgFuncVar's own cparams field ([MS-XLS] 2.5.198.25) is a single byte, so it cannot exceed 255`);
+				builder.push(PTG_FUNCVAR_VALUE, node.args.length).u16(node.iftab);
+			} else builder.push(PTG_FUNC_VALUE).u16(node.iftab);
+			return;
+	}
+}
+/** [MS-XLS] 2.5.198.3's own cce ceiling: a two-byte length field, so rgce itself can never exceed this regardless of the 8224-byte whole-record limit biff/record-writer.ts already enforces. */
+const MAX_RGCE_LENGTH = 65535;
+/**
+* Compiles same-sheet formula text into a Formula record's own rgce token stream -- the write-side counterpart of biff/ptg.ts's parseFormulaText, scoped to the subset this module's own top comment describes. Throws BiffWriteError, naming the construct, for anything outside that scope rather than emitting a token stream this package's own reader could not read back.
+*/
+function compileFormulaText(text) {
+	const node = new FormulaParser(tokenize(text), text).parseFormula();
+	const builder = new RgceBuilder();
+	compileNode(builder, node);
+	const rgce = builder.build();
+	if (rgce.length > MAX_RGCE_LENGTH) throw new require_biff_write_errors.BiffWriteError(`formula text ${JSON.stringify(text)} compiles to ${rgce.length} bytes of rgce, above the ${MAX_RGCE_LENGTH}-byte ceiling its own cce field can hold`);
+	return rgce;
+}
+//#endregion
+exports.compileFormulaText = compileFormulaText;

package/dist/biff/ptg-writer.d.cts

@@ -0,0 +1,7 @@
+//#region src/biff/ptg-writer.d.ts
+/**
+ * Compiles same-sheet formula text into a Formula record's own rgce token stream -- the write-side counterpart of biff/ptg.ts's parseFormulaText, scoped to the subset this module's own top comment describes. Throws BiffWriteError, naming the construct, for anything outside that scope rather than emitting a token stream this package's own reader could not read back.
+ */
+declare function compileFormulaText(text: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { compileFormulaText };

package/dist/biff/ptg-writer.d.ts

@@ -0,0 +1,7 @@
+//#region src/biff/ptg-writer.d.ts
+/**
+ * Compiles same-sheet formula text into a Formula record's own rgce token stream -- the write-side counterpart of biff/ptg.ts's parseFormulaText, scoped to the subset this module's own top comment describes. Throws BiffWriteError, naming the construct, for anything outside that scope rather than emitting a token stream this package's own reader could not read back.
+ */
+declare function compileFormulaText(text: string): Uint8Array<ArrayBuffer>;
+//#endregion
+export { compileFormulaText };