nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/classes/parser/scripting/controlFlow.js

@@ -0,0 +1,355 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContinueSignal = exports.BreakSignal = exports.ReturnSignal = exports.ControlFlowSignal = exports.CONTINUE_SIGNAL = exports.BREAK_SIGNAL = exports.RETURN_SIGNAL = void 0;
+exports.functionBoundary = functionBoundary;
+exports.RETURN = RETURN;
+exports.BREAK = BREAK;
+exports.CONTINUE = CONTINUE;
+exports.AND = AND;
+exports.OR = OR;
+exports.NOT = NOT;
+exports.XOR = XOR;
+exports.IFERROR = IFERROR;
+exports.ISERROR = ISERROR;
+exports.IF = IF;
+exports.WHILE = WHILE;
+exports.FOR = FOR;
+exports.BLOCK = BLOCK;
+exports.parserReturnBoundary = parserReturnBoundary;
+exports.parserBlock = parserBlock;
+const common_1 = require("../../../common/common");
+const errors_1 = require("../../../errors");
+const Settings_1 = require("../../../Settings");
+const Expression_1 = require("../../expression/Expression");
+const shortcuts_1 = require("../../expression/shortcuts");
+const Vector_1 = require("../../vector/Vector");
+const constants_1 = require("../constants");
+// Internal runtime tags for parser control-flow signals. These are not ParserEntity data types.
+exports.RETURN_SIGNAL = 'RETURN_SIGNAL';
+exports.BREAK_SIGNAL = 'BREAK_SIGNAL';
+exports.CONTINUE_SIGNAL = 'CONTINUE_SIGNAL';
+/** Base class for internal parser control transfers. These signals are not parser errors. */
+class ControlFlowSignal extends Error {
+    constructor() {
+        super();
+        this.name = new.target.name;
+    }
+}
+exports.ControlFlowSignal = ControlFlowSignal;
+/**
+ * Internal control-flow signal used to carry a symbolic function's return value to its
+ * function boundary. It is not a mathematical parser result.
+ */
+class ReturnSignal extends ControlFlowSignal {
+    value;
+    dataType = exports.RETURN_SIGNAL;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+    static isReturnSignal(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, exports.RETURN_SIGNAL);
+    }
+}
+exports.ReturnSignal = ReturnSignal;
+/** Internal control-flow signal consumed by the nearest parser loop. */
+class BreakSignal extends ControlFlowSignal {
+    dataType = exports.BREAK_SIGNAL;
+    static isBreakSignal(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, exports.BREAK_SIGNAL);
+    }
+}
+exports.BreakSignal = BreakSignal;
+/** Internal control-flow signal consumed by the nearest parser loop. */
+class ContinueSignal extends ControlFlowSignal {
+    dataType = exports.CONTINUE_SIGNAL;
+    static isContinueSignal(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, exports.CONTINUE_SIGNAL);
+    }
+}
+exports.ContinueSignal = ContinueSignal;
+// BREAK and CONTINUE carry no data, so reuse their signals instead of allocating an Error
+// on every control transfer. RETURN carries a value and therefore remains per invocation.
+const BREAK_SIGNAL_INSTANCE = new BreakSignal();
+const CONTINUE_SIGNAL_INSTANCE = new ContinueSignal();
+// Parser control flow is synchronous. Track active execution boundaries so internal signals
+// are consumed by the correct parser construct without leaking across function calls.
+let loopBodyDepth = 0;
+let parserReturnBoundaryDepth = 0;
+let symbolicFunctionDepth = 0;
+/** Returns the parser's boolean interpretation of one evaluated condition. */
+function isTruthy(value) {
+    if (!Expression_1.Expression.isExpression(value)) {
+        throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: constants_1.dataTypes[value.dataType] }));
+    }
+    return !value.isZero();
+}
+/**
+ * Evaluates one symbolic-function body and consumes control flow at the function boundary.
+ * RETURN becomes the function result, while BREAK and CONTINUE cannot escape a function call.
+ */
+function functionBoundary(evaluate) {
+    let retval;
+    symbolicFunctionDepth++;
+    try {
+        retval = evaluate();
+    }
+    catch (error) {
+        if (ReturnSignal.isReturnSignal(error)) {
+            retval = error.value;
+        }
+        else if (BreakSignal.isBreakSignal(error)) {
+            throw new errors_1.ParserError((0, errors_1.message)('breakOutsideLoop'));
+        }
+        else if (ContinueSignal.isContinueSignal(error)) {
+            throw new errors_1.ParserError((0, errors_1.message)('continueOutsideLoop'));
+        }
+        else {
+            throw error;
+        }
+    }
+    finally {
+        symbolicFunctionDepth--;
+    }
+    return retval;
+}
+/**
+ * Returns a value from the current symbolic function.
+ * @param x
+ * @returns
+ */
+function RETURN(x) {
+    throw new ReturnSignal(x);
+}
+/** Exits the nearest parser control-flow loop. */
+function BREAK() {
+    if (loopBodyDepth === 0) {
+        throw new errors_1.ParserError((0, errors_1.message)('breakOutsideLoop'));
+    }
+    throw BREAK_SIGNAL_INSTANCE;
+}
+/** Skips to the next iteration of the nearest parser control-flow loop. */
+function CONTINUE() {
+    if (loopBodyDepth === 0) {
+        throw new errors_1.ParserError((0, errors_1.message)('continueOutsideLoop'));
+    }
+    throw CONTINUE_SIGNAL_INSTANCE;
+}
+/**
+ * Returns 1 when every deferred argument is nonzero, otherwise 0.
+ * Evaluation stops as soon as a false argument is found.
+ */
+function AND(...args) {
+    let retval = (0, shortcuts_1.one)();
+    for (const arg of args) {
+        if (!isTruthy(arg())) {
+            retval = (0, shortcuts_1.zero)();
+            break;
+        }
+    }
+    return retval;
+}
+/**
+ * Returns 1 when at least one deferred argument is nonzero, otherwise 0.
+ * Evaluation stops as soon as a true argument is found.
+ */
+function OR(...args) {
+    let retval = (0, shortcuts_1.zero)();
+    for (const arg of args) {
+        if (isTruthy(arg())) {
+            retval = (0, shortcuts_1.one)();
+            break;
+        }
+    }
+    return retval;
+}
+/** Returns 1 when the argument is zero and 0 otherwise. */
+function NOT(value) {
+    const retval = isTruthy(value) ? (0, shortcuts_1.zero)() : (0, shortcuts_1.one)();
+    return retval;
+}
+/** Returns 1 when an odd number of arguments are nonzero, otherwise 0. */
+function XOR(...args) {
+    let odd = false;
+    for (const arg of args) {
+        if (isTruthy(arg)) {
+            odd = !odd;
+        }
+    }
+    const retval = odd ? (0, shortcuts_1.one)() : (0, shortcuts_1.zero)();
+    return retval;
+}
+/**
+ * Evaluates an expression and returns its result unless evaluation throws an ordinary error.
+ * The fallback is evaluated only after an error. Internal parser control-flow signals continue
+ * unwinding to their enclosing function or loop boundary.
+ */
+function IFERROR(expression, fallback) {
+    let retval;
+    try {
+        retval = expression();
+    }
+    catch (error) {
+        if (error instanceof ControlFlowSignal) {
+            throw error;
+        }
+        retval = fallback();
+    }
+    return retval;
+}
+/**
+ * Returns 1 when deferred evaluation throws an ordinary error and 0 otherwise.
+ * Internal parser control-flow signals are not errors and continue unwinding normally.
+ */
+function ISERROR(expression) {
+    let retval = (0, shortcuts_1.zero)();
+    try {
+        expression();
+    }
+    catch (error) {
+        if (error instanceof ControlFlowSignal) {
+            throw error;
+        }
+        retval = (0, shortcuts_1.one)();
+    }
+    return retval;
+}
+/**
+ * A branching function. Its arguments are deferred so only the selected branch is evaluated.
+ * When the false branch is omitted, a false condition produces the parser's empty result.
+ * @param condition
+ * @param branch1
+ * @param branch2
+ * @returns
+ */
+function IF(condition, branch1, branch2) {
+    const evaluatedCondition = condition();
+    let retval;
+    if (isTruthy(evaluatedCondition)) {
+        retval = branch1();
+    }
+    else {
+        retval = branch2 ? branch2() : new Vector_1.Vector();
+    }
+    return retval;
+}
+/**
+ * Repeatedly evaluates a deferred body while a deferred condition is nonzero.
+ * The condition is reevaluated before every iteration. BREAK and CONTINUE are consumed here so
+ * they apply only to the nearest loop; other control-flow signals continue to unwind outward.
+ * The final completed body result is returned; if the body never completes, an empty Vector is
+ * returned.
+ * @param condition
+ * @param body
+ * @returns
+ */
+function WHILE(condition, body) {
+    let retval = new Vector_1.Vector();
+    let continueLoop = true;
+    let iterations = 0;
+    while (continueLoop) {
+        const evaluatedCondition = condition();
+        if (!isTruthy(evaluatedCondition)) {
+            continueLoop = false;
+        }
+        else {
+            if (iterations >= Settings_1.Settings.MAX_LOOP_ITERATIONS) {
+                throw new errors_1.ParserError((0, errors_1.message)('loopIterationLimitExceeded', {
+                    max: String(Settings_1.Settings.MAX_LOOP_ITERATIONS),
+                }));
+            }
+            loopBodyDepth++;
+            try {
+                retval = body();
+            }
+            catch (error) {
+                if (BreakSignal.isBreakSignal(error)) {
+                    continueLoop = false;
+                }
+                else if (!ContinueSignal.isContinueSignal(error)) {
+                    throw error;
+                }
+            }
+            finally {
+                loopBodyDepth--;
+            }
+            iterations++;
+        }
+    }
+    return retval;
+}
+/**
+ * Evaluates a deferred initializer once, then delegates repeated condition and body evaluation
+ * to WHILE. The update runs after each completed body evaluation and also before a CONTINUE
+ * advances to the next condition check. BREAK and RETURN skip the pending update. The final
+ * completed body result is returned; if the body never completes, WHILE's empty-Vector result
+ * is preserved.
+ * @param initializer
+ * @param condition
+ * @param update
+ * @param body
+ * @returns
+ */
+function FOR(initializer, condition, update, body) {
+    initializer();
+    const retval = WHILE(condition, () => {
+        let bodyResult;
+        try {
+            bodyResult = body();
+        }
+        catch (error) {
+            if (ContinueSignal.isContinueSignal(error)) {
+                update();
+            }
+            throw error;
+        }
+        update();
+        return bodyResult;
+    });
+    return retval;
+}
+/**
+ * Evaluates a sequence of deferred parser commands in order.
+ * The final command's result is returned. Control-flow signals are not consumed here, allowing
+ * RETURN, BREAK, and CONTINUE to unwind to their enclosing function or loop boundary. An empty
+ * block retains the historical empty-vector result.
+ * @param args
+ * @returns
+ */
+function BLOCK(...args) {
+    let retval = new Vector_1.Vector();
+    for (const arg of args) {
+        retval = arg();
+    }
+    return retval;
+}
+/**
+ * Evaluates one parser-dispatched function through the outer return boundary.
+ *
+ * Nested parser calls keep propagating RETURN. The outermost parser call consumes it when
+ * execution is not already inside a symbolic function.
+ */
+function parserReturnBoundary(evaluate) {
+    const consumesReturn = symbolicFunctionDepth === 0 && parserReturnBoundaryDepth === 0;
+    let retval;
+    parserReturnBoundaryDepth++;
+    try {
+        retval = evaluate();
+    }
+    catch (error) {
+        if (consumesReturn && ReturnSignal.isReturnSignal(error)) {
+            retval = error.value;
+        }
+        else {
+            throw error;
+        }
+    }
+    finally {
+        parserReturnBoundaryDepth--;
+    }
+    return retval;
+}
+/** Evaluates BLOCK through the parser return boundary. */
+function parserBlock(...args) {
+    return parserReturnBoundary(() => BLOCK(...args));
+}

package/output/core/classes/parser/scripting/evaluate.d.ts

@@ -0,0 +1,10 @@
+import type { ParserEntity } from '../../../types';
+import type { DeferredFunctionArgument } from '../types';
+/**
+ * Evaluates a deferred parser value and returns the resolved input if evaluation cannot complete.
+ */
+export declare function evaluate(value: DeferredFunctionArgument, substitutions?: DeferredFunctionArgument, point?: DeferredFunctionArgument): ParserEntity;
+/**
+ * Evaluates a parser value numerically at a finite significant-digit precision.
+ */
+export declare function numeric(value: DeferredFunctionArgument, precision?: DeferredFunctionArgument): ParserEntity;

package/output/core/classes/parser/scripting/evaluate.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluate = evaluate;
+exports.numeric = numeric;
+const math_1 = require("../../../../math/math");
+const errors_1 = require("../../../errors");
+const Collection_1 = require("../../collection/Collection");
+const Dictionary_1 = require("../../dictionary/Dictionary");
+const Equation_1 = require("../../equation/Equation");
+const Expression_1 = require("../../expression/Expression");
+const utils_1 = require("../../expression/utils");
+const Matrix_1 = require("../../matrix/Matrix");
+const ValuesSet_1 = require("../../valuesSet/ValuesSet");
+const Vector_1 = require("../../vector/Vector");
+const constants_1 = require("../constants");
+const EVALUATE_FUNCTION = 'evaluate';
+/**
+ * Evaluates a deferred parser value and returns the resolved input if evaluation cannot complete.
+ */
+function evaluate(value, substitutions, point) {
+    const input = value();
+    let values;
+    if (substitutions) {
+        const resolved = substitutions();
+        values = {};
+        if (point) {
+            const resolvedPoint = point();
+            if (!Vector_1.Vector.isVector(resolved)) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('vectorExpected', { type: constants_1.dataTypes[resolved.dataType] }));
+            }
+            if (!Vector_1.Vector.isVector(resolvedPoint)) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('vectorExpected', { type: constants_1.dataTypes[resolvedPoint.dataType] }));
+            }
+            if (resolved.count() !== resolvedPoint.count()) {
+                throw new errors_1.DimensionError((0, errors_1.message)('mismatchedDimensions', { function: EVALUATE_FUNCTION }));
+            }
+            for (let i = 0; i < resolved.count(); i++) {
+                const variable = resolved.elements[i];
+                if (!Expression_1.Expression.isExpression(variable)) {
+                    throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: constants_1.dataTypes[variable.dataType] }));
+                }
+                values[(0, utils_1.assertPlainVariableAndGetString)(variable)] = resolvedPoint.elements[i];
+            }
+        }
+        else {
+            if (!Dictionary_1.Dictionary.isDictionary(resolved)) {
+                throw new errors_1.UnexpectedDataType((0, errors_1.message)('unsupportedType', { type: constants_1.dataTypes[resolved.dataType] }));
+            }
+            for (const [name, substitution] of resolved) {
+                values[name] = substitution;
+            }
+        }
+    }
+    let retval = input;
+    try {
+        if (values &&
+            (Expression_1.Expression.isExpression(input) || Vector_1.Vector.isVector(input) || Matrix_1.Matrix.isMatrix(input))) {
+            retval = input.evaluate(values);
+        }
+        else {
+            retval = input.evaluate();
+        }
+    }
+    catch {
+        retval = input;
+    }
+    return retval;
+}
+function applyNumeric(value, precision) {
+    let retval;
+    if (Expression_1.Expression.isExpression(value)) {
+        retval = (0, math_1.numeric)(value, precision);
+    }
+    else if (Equation_1.Equation.isEquation(value)) {
+        retval = value.copy().each(e => Expression_1.Expression.isExpression(e) ? (0, math_1.numeric)(e, precision) : e);
+    }
+    else if (Vector_1.Vector.isVector(value)) {
+        retval = value.copy().each(e => applyNumeric(e, precision));
+    }
+    else if (Matrix_1.Matrix.isMatrix(value)) {
+        retval = value.copy().each(e => (0, math_1.numeric)(e, precision));
+    }
+    else if (Collection_1.Collection.isCollection(value)) {
+        retval = value.copy().each(e => applyNumeric(e, precision));
+    }
+    else if (Dictionary_1.Dictionary.isDictionary(value)) {
+        retval = value.copy().each(e => applyNumeric(e, precision));
+    }
+    else if (ValuesSet_1.ValuesSet.isValuesSet(value)) {
+        retval = value.copy().each(e => applyNumeric(e, precision));
+    }
+    else {
+        retval = value;
+    }
+    return retval;
+}
+/**
+ * Evaluates a parser value numerically at a finite significant-digit precision.
+ */
+function numeric(value, precision) {
+    const input = value();
+    let digits;
+    if (precision) {
+        const resolved = precision();
+        if (!Expression_1.Expression.isExpression(resolved)) {
+            throw new errors_1.UnexpectedDataType((0, errors_1.message)('expressionExpected', { type: constants_1.dataTypes[resolved.dataType] }));
+        }
+        digits = resolved;
+    }
+    const retval = applyNumeric(input, digits);
+    return retval;
+}

package/output/core/classes/parser/scripting/functions.d.ts

@@ -0,0 +1,14 @@
+import type { ParserEntity } from '../../../types';
+import type { DeferredFunctionArgument } from '../types';
+/**
+ * Evaluates a symbolic user-function body with call-scoped argument bindings.
+ *
+ * Arguments temporarily shadow parser known values so ordinary assignment can update a
+ * function parameter during the call. Previous bindings are restored afterward, including
+ * when RETURN or another error unwinds evaluation. A string body is parsed per invocation;
+ * a deferred parser body reuses its compiled RPN while still resolving current parameter and
+ * known-value state. RETURN is consumed at the function boundary so its parser entity becomes
+ * the function result and cannot escape into the caller. BREAK and CONTINUE are also rejected
+ * at that boundary so loop control cannot cross a function call.
+ */
+export declare function wrappedFunction(expression: string | DeferredFunctionArgument, argList: string[]): (...inputs: ParserEntity[]) => ParserEntity;

package/output/core/classes/parser/scripting/functions.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrappedFunction = wrappedFunction;
+const Parser_1 = require("../Parser");
+const controlFlow_1 = require("./controlFlow");
+/**
+ * Evaluates a symbolic user-function body with call-scoped argument bindings.
+ *
+ * Arguments temporarily shadow parser known values so ordinary assignment can update a
+ * function parameter during the call. Previous bindings are restored afterward, including
+ * when RETURN or another error unwinds evaluation. A string body is parsed per invocation;
+ * a deferred parser body reuses its compiled RPN while still resolving current parameter and
+ * known-value state. RETURN is consumed at the function boundary so its parser entity becomes
+ * the function result and cannot escape into the caller. BREAK and CONTINUE are also rejected
+ * at that boundary so loop control cannot cross a function call.
+ */
+function wrappedFunction(expression, argList) {
+    return (...inputs) => {
+        const previousValues = new Map();
+        const previouslyUndefined = new Set();
+        for (let i = 0; i < argList.length; i++) {
+            const name = argList[i];
+            if (!previousValues.has(name) && !previouslyUndefined.has(name)) {
+                if (Object.prototype.hasOwnProperty.call(Parser_1.Parser.KNOWN_VALUES, name)) {
+                    previousValues.set(name, Parser_1.Parser.KNOWN_VALUES[name]);
+                }
+                else {
+                    previouslyUndefined.add(name);
+                }
+            }
+            Parser_1.Parser.KNOWN_VALUES[name] = inputs[i];
+        }
+        let retval;
+        try {
+            retval = (0, controlFlow_1.functionBoundary)(() => {
+                let result;
+                if (typeof expression === 'string') {
+                    result = Parser_1.Parser.parse(expression);
+                }
+                else {
+                    // Function declarations should not capture temporary Parser.parse(..., values)
+                    // substitutions from registration. Parameter and persistent known values are
+                    // resolved from the current call instead.
+                    result = expression({ inheritValues: false });
+                }
+                return result;
+            });
+        }
+        finally {
+            for (const [name, value] of previousValues) {
+                Parser_1.Parser.KNOWN_VALUES[name] = value;
+            }
+            for (const name of previouslyUndefined) {
+                delete Parser_1.Parser.KNOWN_VALUES[name];
+            }
+        }
+        return retval;
+    };
+}

package/output/core/classes/parser/scripting/scope.d.ts

@@ -0,0 +1,35 @@
+import { Scope } from '../../../common/classes/Scope';
+import { Expression } from '../../expression/Expression';
+import type { ExpressionInput, ParserEntity } from '../../../types';
+import type { DeferredFunctionArgument } from '../types';
+/**
+ * Adds a known value to a variable in the parser
+ * @param a
+ * @param b
+ */
+export declare function assign(a: ExpressionInput, b: ParserEntity | string): ParserEntity;
+/**
+ * Converts colon-style LET bindings into the alternating name/value scopes consumed by LET.
+ */
+export declare function normalizeLetArguments(argumentScopes: Scope[]): Scope[];
+/**
+ * Evaluates sequential local bindings and restores only those bindings after the body.
+ *
+ * Arguments are alternating variable/value pairs followed by a body expression. Each value
+ * is evaluated after earlier bindings have been installed, so later initializers can reference
+ * earlier locals. Ordinary assignment is reused for validation and storage. Any assignment to
+ * a name not declared by LET keeps its normal parser behavior.
+ *
+ * @param args Deferred variable/value pairs followed by the deferred body.
+ * @returns The body's result.
+ */
+export declare function LET(...args: DeferredFunctionArgument[]): ParserEntity;
+/**
+ * Removes a known parser value by variable name.
+ *
+ * Parser calls defer the argument so an assigned variable can be read as its name rather than
+ * substituted value. Direct callers may still pass an Expression or string.
+ *
+ * @param x Variable name or deferred variable-name expression.
+ */
+export declare function unassign(x: Expression | string | DeferredFunctionArgument): Expression;