documents.js 1.63.0 → 1.64.0

package/dist/odb/formula/evaluate.js

@@ -0,0 +1,281 @@
+import { CELL_NULL, aggregateCellValues, cellComparisonKey, cellValuesEqual } from "../values.js";
+import { RptFormulaEvaluationError } from "./errors.js";
+import { parseRptFormula } from "./parser.js";
+//#region src/odb/formula/evaluate.ts
+function fail(message, formula) {
+	throw new RptFormulaEvaluationError(message, formula);
+}
+function matchNamed(candidates, nameOf, name) {
+	const exact = candidates.filter((candidate) => nameOf(candidate) === name);
+	return exact.length > 0 ? exact : candidates.filter((candidate) => nameOf(candidate).toUpperCase() === name.toUpperCase());
+}
+function identity(name) {
+	return name;
+}
+function prepareBandFormulas(band) {
+	return band.formulas.map((formula) => formula === void 0 ? void 0 : parseRptFormula(formula));
+}
+function prepareBand(band) {
+	return band === void 0 ? void 0 : prepareBandFormulas(band);
+}
+var PreparedReport = class {
+	resultSet;
+	namedFunctions;
+	groupExpressions;
+	bands;
+	columnNames;
+	resolutions = /* @__PURE__ */ new Map();
+	constructor(definition, resultSet) {
+		this.resultSet = resultSet;
+		this.columnNames = resultSet.columns;
+		const named = /* @__PURE__ */ new Map();
+		const declare = (functions, scope) => {
+			for (const declaration of functions) {
+				if (named.has(declaration.name)) fail(`rpt:function "${declaration.name}" is declared more than once in this report`, declaration.formula);
+				named.set(declaration.name, {
+					name: declaration.name,
+					formula: parseRptFormula(declaration.formula),
+					scope
+				});
+			}
+		};
+		declare(definition.functions, { kind: "report" });
+		for (const [level, group] of definition.groups.entries()) declare(group.functions, {
+			kind: "group",
+			level
+		});
+		this.namedFunctions = named;
+		this.groupExpressions = definition.groups.map((group) => parseRptFormula(group.groupExpression));
+		this.bands = {
+			reportHeader: prepareBand(definition.reportHeader),
+			detail: prepareBand(definition.detail),
+			reportFooter: prepareBand(definition.reportFooter),
+			groups: definition.groups.map((group) => ({
+				header: prepareBand(group.header),
+				footer: prepareBand(group.footer)
+			}))
+		};
+		for (const expression of this.groupExpressions) this.rejectAggregateDependency(expression, expression, /* @__PURE__ */ new Set());
+	}
+	rejectAggregateDependency(formula, expression, visiting) {
+		if (formula.kind === "aggregate") fail(`a group expression cannot depend on the aggregate rpt:${formula.aggregate}(${formula.reference.name}) -- an aggregate's own rows are defined by the very group boundaries this expression decides`, expression.text);
+		const resolved = matchNamed([...this.namedFunctions.values()], (candidate) => candidate.name, formula.reference.name)[0];
+		if (resolved === void 0) return;
+		if (visiting.has(resolved.name)) fail(`rpt:function "${resolved.name}" refers to itself, directly or through another function`, expression.text);
+		this.rejectAggregateDependency(resolved.formula, expression, /* @__PURE__ */ new Set([...visiting, resolved.name]));
+	}
+	resolveReference(reference, formula) {
+		const cached = this.resolutions.get(reference);
+		if (cached !== void 0) return cached;
+		const functionMatches = matchNamed([...this.namedFunctions.values()], (candidate) => candidate.name, reference.name);
+		const columnMatches = matchNamed(this.columnNames, identity, reference.name);
+		if (functionMatches.length + columnMatches.length > 1) fail(`reference "${reference.name}" is ambiguous -- it matches ${[...functionMatches.map((match) => `rpt:function ${match.name}`), ...columnMatches.map((match) => `column ${match}`)].join(", ")}`, formula);
+		const resolved = this.resolveSingleMatch(reference, functionMatches[0], columnMatches[0], formula);
+		this.resolutions.set(reference, resolved);
+		return resolved;
+	}
+	resolveSingleMatch(reference, named, columnName, formula) {
+		if (named !== void 0) return {
+			kind: "function",
+			resolved: named
+		};
+		if (columnName === void 0) fail(`reference "${reference.name}" names neither a declared rpt:function nor a column of the report's own data -- functions: ${this.namedFunctions.size === 0 ? "(none)" : [...this.namedFunctions.keys()].join(", ")}; columns: ${this.columnNames.length === 0 ? "(none)" : this.columnNames.join(", ")}`, formula);
+		return {
+			kind: "column",
+			index: this.columnNames.indexOf(columnName)
+		};
+	}
+	valueAt(columnIndex, rowIndex, formula) {
+		const value = this.resultSet.rows[rowIndex]?.[columnIndex];
+		if (value === void 0) fail(`the report's own data has no value at row ${String(rowIndex)}, column ${String(columnIndex)}`, formula);
+		return value;
+	}
+};
+var RunState = class {
+	rowCount;
+	openInstances;
+	constructor(levels, rowCount) {
+		this.rowCount = rowCount;
+		this.openInstances = Array.from({ length: levels }, () => void 0);
+	}
+	open(level, range) {
+		this.openInstances[level] = range;
+	}
+	openAt(level) {
+		return this.openInstances[level];
+	}
+	close(level) {
+		this.openInstances[level] = void 0;
+	}
+	rangeFor(scope, formula) {
+		if (scope.kind === "report") return {
+			startRow: 0,
+			endRowExclusive: this.rowCount
+		};
+		const open = this.openInstances[scope.level];
+		if (open === void 0) fail(`an aggregate scoped to group level ${String(scope.level)} was evaluated while no instance of that group was open`, formula);
+		return open;
+	}
+};
+function textOf(value, formula, what) {
+	if (value.kind === "empty") return;
+	const key = cellComparisonKey(value);
+	if (key?.valueClass !== "text") fail(`${what} requires a text value, but found a ${value.kind} value -- this engine does not format a number or a boolean into text, since a report's own number format lives in its band styles rather than in the formula`, formula);
+	return key.text;
+}
+var FormulaEvaluator = class {
+	prepared;
+	state;
+	constructor(prepared, state) {
+		this.prepared = prepared;
+		this.state = state;
+	}
+	evaluate(formula, rowIndex, scope, visiting = /* @__PURE__ */ new Set()) {
+		switch (formula.kind) {
+			case "field": return this.referenceValue(formula.reference, this.requireRow(rowIndex, formula.text, "a field: reference"), formula.text, visiting);
+			case "hasChanged": {
+				const rowOfChange = this.requireRow(rowIndex, formula.text, "rpt:HASCHANGED");
+				const current = this.referenceValue(formula.reference, rowOfChange, formula.text, visiting);
+				if (rowOfChange === 0) return {
+					kind: "boolean",
+					value: true
+				};
+				const previous = this.referenceValue(formula.reference, rowOfChange - 1, formula.text, visiting);
+				return {
+					kind: "boolean",
+					value: !cellValuesEqual(current, previous)
+				};
+			}
+			case "left": {
+				const text = textOf(this.referenceValue(formula.reference, this.requireRow(rowIndex, formula.text, "rpt:LEFT"), formula.text, visiting), formula.text, "rpt:LEFT");
+				return text === void 0 ? CELL_NULL : {
+					kind: "string",
+					value: [...text].slice(0, formula.length).join("")
+				};
+			}
+			case "aggregate": {
+				const range = this.state.rangeFor(scope, formula.text);
+				const values = [];
+				for (let row = range.startRow; row < range.endRowExclusive; row += 1) values.push(this.referenceValue(formula.reference, row, formula.text, visiting));
+				return aggregateCellValues(formula.aggregate, values, (message) => new RptFormulaEvaluationError(message, formula.text));
+			}
+		}
+	}
+	requireRow(rowIndex, formula, what) {
+		if (rowIndex === void 0) fail(`${what} needs a data row, but the band it appears in belongs to no row (the report header and footer print outside the data)`, formula);
+		return rowIndex;
+	}
+	referenceValue(reference, rowIndex, formula, visiting) {
+		const resolved = this.prepared.resolveReference(reference, formula);
+		if (resolved.kind === "column") return this.prepared.valueAt(resolved.index, rowIndex, formula);
+		if (visiting.has(resolved.resolved.name)) fail(`rpt:function "${resolved.resolved.name}" refers to itself, directly or through another function`, formula);
+		return this.evaluate(resolved.resolved.formula, rowIndex, resolved.resolved.scope, /* @__PURE__ */ new Set([...visiting, resolved.resolved.name]));
+	}
+};
+function resolveOwnBreak(value, formula) {
+	if (value.kind !== "boolean") fail(`a group expression must evaluate to a boolean break test (rpt:HASCHANGED(...)), but this one produced a ${value.kind} value`, formula);
+	return value.value;
+}
+var GroupBreaks = class {
+	rowCount;
+	rows;
+	constructor(prepared, evaluator, rowCount) {
+		this.rowCount = rowCount;
+		const rows = [];
+		for (let rowIndex = 0; rowIndex < rowCount; rowIndex += 1) {
+			const flags = [];
+			let enclosingBroke = false;
+			for (const [level, expression] of prepared.groupExpressions.entries()) {
+				const ownBreak = resolveOwnBreak(evaluator.evaluate(expression, rowIndex, {
+					kind: "group",
+					level
+				}), expression.text);
+				const broke = enclosingBroke || rowIndex === 0 || ownBreak;
+				flags.push(broke);
+				enclosingBroke = broke;
+			}
+			rows.push(flags);
+		}
+		this.rows = rows;
+	}
+	flagsAt(rowIndex) {
+		const flags = this.rows[rowIndex];
+		if (flags === void 0) throw new Error(`rpt report run: row ${String(rowIndex)} is outside the ${String(this.rowCount)} rows its group breaks were computed for`);
+		return flags;
+	}
+	outermostBreakAt(rowIndex) {
+		return this.flagsAt(rowIndex).indexOf(true);
+	}
+	breaksAt(rowIndex, level) {
+		return this.flagsAt(rowIndex)[level] === true;
+	}
+	instanceContaining(level, rowIndex) {
+		let startRow = rowIndex;
+		while (startRow > 0 && !this.breaksAt(startRow, level)) startRow -= 1;
+		let endRowExclusive = rowIndex + 1;
+		while (endRowExclusive < this.rowCount && !this.breaksAt(endRowExclusive, level)) endRowExclusive += 1;
+		return {
+			startRow,
+			endRowExclusive
+		};
+	}
+};
+function detailScope(groupCount) {
+	return groupCount === 0 ? { kind: "report" } : {
+		kind: "group",
+		level: groupCount - 1
+	};
+}
+function runRptReport(definition, resultSet) {
+	const rowCount = resultSet.rows.length;
+	const levels = definition.groups.length;
+	const prepared = new PreparedReport(definition, resultSet);
+	const state = new RunState(levels, rowCount);
+	const evaluator = new FormulaEvaluator(prepared, state);
+	const bands = [];
+	const emit = (band, kind, groupLevel, rowIndex, scope) => {
+		if (band === void 0) return;
+		bands.push({
+			kind,
+			groupLevel,
+			rowIndex,
+			values: band.map((formula) => formula === void 0 ? void 0 : evaluator.evaluate(formula, rowIndex, scope))
+		});
+	};
+	emit(prepared.bands.reportHeader, "report-header", void 0, void 0, { kind: "report" });
+	const breaks = new GroupBreaks(prepared, evaluator, rowCount);
+	const closeFrom = (level) => {
+		for (let openLevel = levels - 1; openLevel >= level; openLevel -= 1) {
+			const open = state.openAt(openLevel);
+			if (open === void 0) continue;
+			emit(prepared.bands.groups[openLevel]?.footer, "group-footer", openLevel, open.endRowExclusive - 1, {
+				kind: "group",
+				level: openLevel
+			});
+			state.close(openLevel);
+		}
+	};
+	for (let rowIndex = 0; rowIndex < rowCount; rowIndex += 1) {
+		const outermostBroken = breaks.outermostBreakAt(rowIndex);
+		if (outermostBroken >= 0) {
+			closeFrom(outermostBroken);
+			for (let level = outermostBroken; level < levels; level += 1) {
+				state.open(level, breaks.instanceContaining(level, rowIndex));
+				emit(prepared.bands.groups[level]?.header, "group-header", level, rowIndex, {
+					kind: "group",
+					level
+				});
+			}
+		}
+		emit(prepared.bands.detail, "detail", void 0, rowIndex, detailScope(levels));
+	}
+	closeFrom(0);
+	emit(prepared.bands.reportFooter, "report-footer", void 0, void 0, { kind: "report" });
+	return { bands };
+}
+function evaluateRptBandOutsideData(definition, band, resultSet) {
+	const evaluator = new FormulaEvaluator(new PreparedReport(definition, resultSet), new RunState(definition.groups.length, resultSet.rows.length));
+	return prepareBandFormulas(band).map((formula) => formula === void 0 ? void 0 : evaluator.evaluate(formula, void 0, { kind: "report" }));
+}
+//#endregion
+export { evaluateRptBandOutsideData, runRptReport };

package/dist/odb/formula/parser.cjs

@@ -0,0 +1,198 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_odb_formula_errors = require("./errors.cjs");
+//#region src/odb/formula/parser.ts
+const AGGREGATE_FUNCTIONS = /* @__PURE__ */ new Set([
+	"COUNT",
+	"SUM",
+	"AVG",
+	"MIN",
+	"MAX"
+]);
+function isAggregateFunction(name) {
+	return AGGREGATE_FUNCTIONS.has(name);
+}
+const FIELD_PREFIX = "field:";
+const RPT_PREFIX = "rpt:";
+function isNameCharacter(character) {
+	return character >= "A" && character <= "Z" || character >= "a" && character <= "z" || character >= "0" && character <= "9" || character === "_";
+}
+var FormulaScanner = class {
+	formula;
+	offset = 0;
+	constructor(formula) {
+		this.formula = formula;
+	}
+	get position() {
+		return this.offset;
+	}
+	fail(message) {
+		throw new require_odb_formula_errors.RptFormulaParseError(message, this.formula, this.offset);
+	}
+	skipWhitespace() {
+		while (this.offset < this.formula.length && /\s/.test(this.formula.charAt(this.offset))) this.offset += 1;
+	}
+	atEnd() {
+		this.skipWhitespace();
+		return this.offset >= this.formula.length;
+	}
+	peek() {
+		this.skipWhitespace();
+		return this.formula.charAt(this.offset);
+	}
+	tryConsume(text) {
+		this.skipWhitespace();
+		if (!this.formula.startsWith(text, this.offset)) return false;
+		this.offset += text.length;
+		return true;
+	}
+	expect(character, what) {
+		this.skipWhitespace();
+		if (this.formula.charAt(this.offset) !== character) this.fail(`expected ${what} ("${character}") but found ${this.offset >= this.formula.length ? "the end of the formula" : `"${this.formula.charAt(this.offset)}"`}`);
+		this.offset += 1;
+	}
+	readName(what) {
+		this.skipWhitespace();
+		const start = this.offset;
+		while (this.offset < this.formula.length && isNameCharacter(this.formula.charAt(this.offset))) this.offset += 1;
+		if (this.offset === start) this.fail(`expected ${what}`);
+		return this.formula.slice(start, this.offset);
+	}
+	readBracketReference() {
+		this.expect("[", "the opening bracket of a column reference");
+		const start = this.offset;
+		const close = this.formula.indexOf("]", this.offset);
+		if (close < 0) {
+			this.offset = this.formula.length;
+			this.fail("unterminated column reference -- no closing \"]\"");
+		}
+		this.offset = close + 1;
+		return {
+			name: this.formula.slice(start, close),
+			spelling: "bracket"
+		};
+	}
+	readQuotedReference() {
+		this.expect("\"", "the opening quote of a name reference");
+		let name = "";
+		for (;;) {
+			if (this.offset >= this.formula.length) this.fail("unterminated name reference -- no closing double quote");
+			const character = this.formula.charAt(this.offset);
+			this.offset += 1;
+			if (character !== "\"") {
+				name += character;
+				continue;
+			}
+			if (this.formula.charAt(this.offset) === "\"") {
+				name += "\"";
+				this.offset += 1;
+				continue;
+			}
+			return {
+				name,
+				spelling: "quote"
+			};
+		}
+	}
+	readNumber() {
+		this.skipWhitespace();
+		const start = this.offset;
+		if (this.formula.charAt(this.offset) === "-") this.offset += 1;
+		while (this.offset < this.formula.length && this.formula.charAt(this.offset) >= "0" && this.formula.charAt(this.offset) <= "9") this.offset += 1;
+		if (this.formula.charAt(this.offset) === ".") {
+			this.offset += 1;
+			while (this.offset < this.formula.length && this.formula.charAt(this.offset) >= "0" && this.formula.charAt(this.offset) <= "9") this.offset += 1;
+		}
+		const text = this.formula.slice(start, this.offset);
+		const value = Number(text);
+		if (text === "" || text === "-" || !Number.isFinite(value)) {
+			this.offset = start;
+			this.fail("expected a number");
+		}
+		return value;
+	}
+	readArgument() {
+		const next = this.peek();
+		if (next === "") this.fail("expected an argument but found the end of the formula");
+		if (next === "[") return {
+			kind: "reference",
+			reference: this.readBracketReference()
+		};
+		if (next === "\"") return {
+			kind: "reference",
+			reference: this.readQuotedReference()
+		};
+		return {
+			kind: "number",
+			value: this.readNumber()
+		};
+	}
+};
+function referenceArgument(argument, functionName, ordinal, scanner) {
+	if (argument?.kind !== "reference") scanner.fail(`rpt:${functionName}'s ${ordinal} argument must be a column or function reference ([NAME] or "NAME")`);
+	return argument.reference;
+}
+function expectArgumentCount(argumentValues, expected, functionName, scanner) {
+	if (argumentValues.length !== expected) scanner.fail(`rpt:${functionName} takes exactly ${String(expected)} argument${expected === 1 ? "" : "s"}, but ${String(argumentValues.length)} ${argumentValues.length === 1 ? "was" : "were"} given`);
+}
+function buildCall(functionName, argumentValues, formula, scanner) {
+	const canonical = functionName.toUpperCase();
+	if (canonical === "HASCHANGED") {
+		expectArgumentCount(argumentValues, 1, functionName, scanner);
+		return {
+			kind: "hasChanged",
+			reference: referenceArgument(argumentValues[0], functionName, "first", scanner),
+			text: formula
+		};
+	}
+	if (canonical === "LEFT") {
+		expectArgumentCount(argumentValues, 2, functionName, scanner);
+		const reference = referenceArgument(argumentValues[0], functionName, "first", scanner);
+		const lengthArgument = argumentValues[1];
+		if (lengthArgument?.kind !== "number") scanner.fail(`rpt:${functionName}'s second argument must be a number of characters`);
+		if (!Number.isInteger(lengthArgument.value) || lengthArgument.value < 0) scanner.fail(`rpt:${functionName}'s second argument must be a non-negative whole number of characters, but was ${String(lengthArgument.value)}`);
+		return {
+			kind: "left",
+			reference,
+			length: lengthArgument.value,
+			text: formula
+		};
+	}
+	if (isAggregateFunction(canonical)) {
+		expectArgumentCount(argumentValues, 1, functionName, scanner);
+		return {
+			kind: "aggregate",
+			aggregate: canonical,
+			reference: referenceArgument(argumentValues[0], functionName, "first", scanner),
+			text: formula
+		};
+	}
+	throw new require_odb_formula_errors.RptFormulaUnsupportedError(functionName, formula);
+}
+function parseRptFormula(formula) {
+	const scanner = new FormulaScanner(formula);
+	if (scanner.tryConsume(FIELD_PREFIX)) {
+		const reference = scanner.readBracketReference();
+		if (!scanner.atEnd()) scanner.fail("unexpected trailing text after a field: reference");
+		return {
+			kind: "field",
+			reference,
+			text: formula
+		};
+	}
+	if (!scanner.tryConsume(RPT_PREFIX)) scanner.fail(`expected a formula beginning "${FIELD_PREFIX}" or "${RPT_PREFIX}"`);
+	const functionName = scanner.readName("an rpt: function name");
+	scanner.expect("(", "the opening parenthesis of a function's argument list");
+	const argumentValues = [];
+	if (scanner.peek() !== ")") {
+		argumentValues.push(scanner.readArgument());
+		while (scanner.peek() === ";") {
+			scanner.expect(";", "an argument separator");
+			argumentValues.push(scanner.readArgument());
+		}
+	}
+	scanner.expect(")", "the closing parenthesis of a function's argument list");
+	if (!scanner.atEnd()) scanner.fail("unexpected trailing text after a function call");
+	return buildCall(functionName, argumentValues, formula, scanner);
+}
+//#endregion
+exports.parseRptFormula = parseRptFormula;

package/dist/odb/formula/parser.d.cts

@@ -0,0 +1,29 @@
+import { n as CellAggregateFunction } from "../../values-BetetbaH.cjs";
+//#region src/odb/formula/parser.d.ts
+type RptAggregateFunction = CellAggregateFunction;
+interface RptReference {
+  readonly name: string;
+  readonly spelling: 'bracket' | 'quote';
+}
+type RptFormula = {
+  readonly kind: 'field';
+  readonly reference: RptReference;
+  readonly text: string;
+} | {
+  readonly kind: 'hasChanged';
+  readonly reference: RptReference;
+  readonly text: string;
+} | {
+  readonly kind: 'left';
+  readonly reference: RptReference;
+  readonly length: number;
+  readonly text: string;
+} | {
+  readonly kind: 'aggregate';
+  readonly aggregate: RptAggregateFunction;
+  readonly reference: RptReference;
+  readonly text: string;
+};
+declare function parseRptFormula(formula: string): RptFormula;
+//#endregion
+export { RptAggregateFunction, RptFormula, RptReference, parseRptFormula };

package/dist/odb/formula/parser.d.ts

@@ -0,0 +1,29 @@
+import { n as CellAggregateFunction } from "../../values-BetetbaH.js";
+//#region src/odb/formula/parser.d.ts
+type RptAggregateFunction = CellAggregateFunction;
+interface RptReference {
+  readonly name: string;
+  readonly spelling: 'bracket' | 'quote';
+}
+type RptFormula = {
+  readonly kind: 'field';
+  readonly reference: RptReference;
+  readonly text: string;
+} | {
+  readonly kind: 'hasChanged';
+  readonly reference: RptReference;
+  readonly text: string;
+} | {
+  readonly kind: 'left';
+  readonly reference: RptReference;
+  readonly length: number;
+  readonly text: string;
+} | {
+  readonly kind: 'aggregate';
+  readonly aggregate: RptAggregateFunction;
+  readonly reference: RptReference;
+  readonly text: string;
+};
+declare function parseRptFormula(formula: string): RptFormula;
+//#endregion
+export { RptAggregateFunction, RptFormula, RptReference, parseRptFormula };