nerdamer 1.1.13 → 2.0.0-rc.1

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

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assign = assign;
+exports.normalizeLetArguments = normalizeLetArguments;
+exports.LET = LET;
+exports.unassign = unassign;
+const Scope_1 = require("../../../common/classes/Scope");
+const errors_1 = require("../../../errors");
+const Settings_1 = require("../../../Settings");
+const Expression_1 = require("../../expression/Expression");
+const utils_1 = require("../../expression/utils");
+const constants_1 = require("../constants");
+const Parser_1 = require("../Parser");
+const Token_1 = require("../Token");
+/**
+ * Adds a known value to a variable in the parser
+ * @param a
+ * @param b
+ */
+function assign(a, b) {
+    a = Expression_1.Expression.create(a);
+    if (typeof b === 'string') {
+        b = Parser_1.Parser.parse(b);
+    }
+    // We can only assign to plain variables
+    if (Expression_1.Expression.isExpression(a) && !a.isPlainVariable()) {
+        throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: String(a) }));
+    }
+    // We cannot assign to restricted values
+    if (Settings_1.RESTRICTED.includes(a.value)) {
+        throw new errors_1.AssignmentError((0, errors_1.message)('restrictedVariableName', { name: a.value }));
+    }
+    Parser_1.Parser.KNOWN_VALUES[a.value] = b;
+    return b;
+}
+/**
+ * Converts colon-style LET bindings into the alternating name/value scopes consumed by LET.
+ */
+function normalizeLetArguments(argumentScopes) {
+    const normalizedScopes = [];
+    for (let i = 0; i < argumentScopes.length; i++) {
+        const argumentScope = argumentScopes[i];
+        let assignmentIndex = -1;
+        if (i < argumentScopes.length - 1) {
+            for (let j = 0; j < argumentScope.length; j++) {
+                const argumentToken = argumentScope[j];
+                if (Token_1.Token.isToken(argumentToken) &&
+                    argumentToken.type === Token_1.Token.OPERATOR &&
+                    argumentToken.value === constants_1.ASSIGN) {
+                    assignmentIndex = j;
+                    break;
+                }
+            }
+        }
+        if (assignmentIndex > 0 && assignmentIndex < argumentScope.length - 1) {
+            const nameScope = new Scope_1.Scope(argumentScope.type, argumentScope.column);
+            const valueScope = new Scope_1.Scope(argumentScope.type, argumentScope.column);
+            for (let j = 0; j < assignmentIndex; j++) {
+                nameScope.push(argumentScope[j]);
+            }
+            for (let j = assignmentIndex + 1; j < argumentScope.length; j++) {
+                valueScope.push(argumentScope[j]);
+            }
+            normalizedScopes.push(nameScope, valueScope);
+        }
+        else {
+            normalizedScopes.push(argumentScope);
+        }
+    }
+    return normalizedScopes;
+}
+/**
+ * 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.
+ */
+function LET(...args) {
+    if (args.length < 3 || args.length % 2 === 0) {
+        throw new errors_1.ParserError((0, errors_1.message)('letRequiresBindingsAndBody'));
+    }
+    const previousValues = new Map();
+    const previouslyUndefined = new Set();
+    const localNames = [];
+    let retval;
+    try {
+        for (let i = 0; i < args.length - 1; i += 2) {
+            // Binding names are syntax, not values. Suppress both call-scoped and known-value
+            // substitution while resolving the plain variable name.
+            const nameExpression = args[i]({ inheritValues: false, substitute: false });
+            if (!Expression_1.Expression.isExpression(nameExpression)) {
+                throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: nameExpression.text() }));
+            }
+            const name = (0, utils_1.assertPlainVariableAndGetString)(nameExpression);
+            const value = args[i + 1]({ excludeValues: localNames });
+            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);
+                }
+            }
+            assign(nameExpression, value);
+            if (!localNames.includes(name)) {
+                localNames.push(name);
+            }
+        }
+        retval = args[args.length - 1]({ excludeValues: localNames });
+    }
+    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;
+}
+/**
+ * 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.
+ */
+function unassign(x) {
+    let variable;
+    let name;
+    if (typeof x === 'function') {
+        const parsed = x({ inheritValues: false, substitute: false });
+        if (!Expression_1.Expression.isExpression(parsed)) {
+            throw new errors_1.UnexpectedInputError((0, errors_1.message)('plainVariableExpected', { input: parsed.text() }));
+        }
+        variable = parsed;
+    }
+    else {
+        variable = x;
+    }
+    if (Expression_1.Expression.isExpression(variable)) {
+        name = (0, utils_1.assertPlainVariableAndGetString)(variable);
+    }
+    else {
+        name = variable;
+    }
+    delete Parser_1.Parser.KNOWN_VALUES[name];
+    return Expression_1.Expression.create(variable);
+}

package/output/core/classes/parser/types.d.ts

@@ -0,0 +1,125 @@
+import { type Equation } from '../equation/Equation';
+import { type Expression } from '../expression/Expression';
+import type { NerdamerInput, ParserEntity } from '../../types';
+import type { IndexedReference } from './wrappers/IndexedReference';
+import type { KeyValuePair } from './wrappers/KeyValuePair';
+import type Decimal from 'decimal.js';
+/**
+ * The type used to defined a operation function for the parser
+ */
+export type Operation = (a: ParserEntity, b?: ParserEntity) => ParserEntity;
+/**
+ * The comma operation returns both operands so the parser can place them back
+ * on the output stack as separate values.
+ */
+export type CommaOperation = (a: ParserStackValue, b: ParserStackValue) => ParserStackValue[];
+/**
+ * The type used to defined a prefix for the parser
+ */
+export type PreFixFunction = (a: ParserEntity) => ParserEntity;
+/**
+ * The type used to defined a prefix for the parser
+ */
+export type PostFixFunction = (b: ParserEntity) => ParserEntity;
+/**
+ * The call used to construct an equation
+ */
+export type EquationConstructorCall = (a: ParserEntity, b: ParserEntity) => Equation;
+/** Controls the parser context used when a deferred function evaluates one argument. */
+export interface DeferredArgumentOptions {
+    /** Call-scoped substitution names to omit while evaluating this argument. */
+    excludeValues?: readonly string[];
+    /** Whether this argument should inherit the enclosing call-scoped substitutions. */
+    inheritValues?: boolean;
+    /** Optional temporary override for known-value substitution. */
+    substitute?: boolean;
+}
+/**
+ * A parser argument whose evaluation is delayed until the receiving function decides to
+ * execute it. The callback may be invoked once or repeatedly, and may narrow the inherited
+ * substitution context for lexical control functions.
+ */
+export type DeferredFunctionArgument = (options?: DeferredArgumentOptions) => ParserEntity;
+/** An operator action whose right-hand operand is deferred. */
+export type DeferredOperation = (a: ParserEntity, b: DeferredFunctionArgument) => ParserEntity;
+/**
+ * Named values substituted while parsing or evaluating an input expression.
+ *
+ * Keys are parser variable names. This compatibility type accepts the same broad value
+ * union as the root API, but not every substitution path can consume every structured
+ * entity. The receiving operation's documentation defines the narrower requirements when
+ * one applies.
+ */
+export type ParserValuesObject = Record<string, NerdamerInput>;
+/**
+ * Constant definitions accepted by the parser's constant registry.
+ *
+ * String definitions are parsed when the constant is encountered. Function
+ * definitions are deferred factories that return parser text, allowing constants such
+ * as `pi` and `e` to reflect the active numerical precision. The registry itself is
+ * process-wide; this type does not imply isolated parser state.
+ */
+export type ParserConstants = Record<string, (() => string) | string>;
+/**
+ * Values currently accepted by Nerdamer's broad settings objects.
+ *
+ * @remarks
+ * Parser and formatting settings share this recursive value type. Each API still decides
+ * which setting names and value shapes it understands.
+ */
+export type OptionValue = string | boolean | number | string[] | OptionsObject;
+/**
+ * Compatibility settings bag used by several parser and formatter entry points.
+ *
+ * The index signature reflects the values that settings APIs currently pass around. It
+ * does not make arbitrary setting names part of the supported public method.
+ */
+export interface OptionsObject {
+    [key: string]: OptionValue;
+}
+/**
+ * Formatting options accepted by {@link Expression.text}.
+ *
+ * These options affect only the returned string. They do not change the expression or
+ * Nerdamer's process-wide settings.
+ */
+export type TextOptions = {
+    /** Render rational values as decimals instead of exact fractions. */
+    decimal?: boolean;
+    /** Significant-digit precision used when decimal output is requested. */
+    precision?: number;
+    /** Sort sum and product elements with {@link Expression.sortFunction} before rendering. */
+    sort?: boolean;
+    /** Parenthesize powers for output that will be embedded in JavaScript-style expressions. */
+    wrapPow?: boolean;
+};
+/**
+ * The type used when passing settings
+ */
+export type SimpleOptionsObject = Record<string, string | number | Expression>;
+/**
+ * The type supported by Decimal implementations of algorithms
+ */
+export type DecimalType = Decimal | number | string;
+/**
+ * Native JavaScript function produced or consumed by numerical compilation APIs.
+ *
+ * Arguments and numeric results use JavaScript `number` arithmetic rather than
+ * Nerdamer's exact rational or arbitrary-precision symbolic representation. Boolean
+ * results support compiled comparison expressions.
+ */
+export type JsFunction = (...args: number[]) => number | boolean;
+/**
+ * A simple expression function call
+ */
+export type ExpressionFunction = (...args: Expression[]) => Expression;
+/**
+ * Internal values that may temporarily exist on the parser output stack.
+ * IndexedReference and KeyValuePair are resolved or consumed before parseRPN returns.
+ * Deferred callbacks are consumed only by operators that explicitly request them.
+ */
+export type ParserStackValue = ParserEntity | IndexedReference | KeyValuePair | DeferredFunctionArgument;
+/**
+ * An array containing numerator and denominator
+ */
+export type FracArray = [string, string];

package/output/core/classes/parser/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/output/core/classes/parser/wrappers/IndexedReference.d.ts

@@ -0,0 +1,31 @@
+import { INDEXED_REFERENCE } from '../constants';
+import type { ParserEntity } from '../../../types';
+import type { Dictionary } from '../../dictionary/Dictionary';
+/**
+ * A lightweight wrapper that holds a reference to a structured entity and the indices
+ * used to access it. This is pushed onto the output stack during indexing so that
+ * the assign operator can detect it and call setter instead of getter.
+ *
+ * For any non-assign operator, the IndexedReference is resolved to its value via resolve().
+ * The resolved value is cached so that repeated calls don't re-invoke the getter.
+ */
+export declare class IndexedReference {
+    target: ParserEntity;
+    indices: number[] | string;
+    targetName?: string | undefined;
+    private _resolved;
+    dataType: typeof INDEXED_REFERENCE;
+    isEnumerable: boolean;
+    constructor(target: ParserEntity, indices: number[] | string, targetName?: string | undefined);
+    static isIndexedReference(obj: unknown): obj is IndexedReference;
+    copy(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | Dictionary | import("../../equation/Equation").Equation;
+    eq(other: ParserEntity): boolean;
+    evaluate(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | Dictionary | import("../../equation/Equation").Equation;
+    expand(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | Dictionary | import("../../equation/Equation").Equation;
+    gt(other: ParserEntity): boolean;
+    gte(other: ParserEntity): boolean;
+    lt(other: ParserEntity): boolean;
+    lte(other: ParserEntity): boolean;
+    resolve(): ParserEntity;
+    text(): string;
+}

package/output/core/classes/parser/wrappers/IndexedReference.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexedReference = void 0;
+const common_1 = require("../../../common/common");
+const constants_1 = require("../constants");
+/**
+ * A lightweight wrapper that holds a reference to a structured entity and the indices
+ * used to access it. This is pushed onto the output stack during indexing so that
+ * the assign operator can detect it and call setter instead of getter.
+ *
+ * For any non-assign operator, the IndexedReference is resolved to its value via resolve().
+ * The resolved value is cached so that repeated calls don't re-invoke the getter.
+ */
+class IndexedReference {
+    target;
+    indices;
+    targetName;
+    _resolved = null;
+    dataType = constants_1.INDEXED_REFERENCE;
+    isEnumerable = false;
+    constructor(target, indices, targetName) {
+        this.target = target;
+        this.indices = indices;
+        this.targetName = targetName;
+    }
+    static isIndexedReference(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.INDEXED_REFERENCE);
+    }
+    copy() {
+        return this.resolve().copy();
+    }
+    eq(other) {
+        return this.resolve().eq(other);
+    }
+    evaluate() {
+        return this.resolve().evaluate();
+    }
+    expand() {
+        return this.resolve().expand();
+    }
+    gt(other) {
+        return this.resolve().gt(other);
+    }
+    gte(other) {
+        return this.resolve().gte(other);
+    }
+    lt(other) {
+        return this.resolve().lt(other);
+    }
+    lte(other) {
+        return this.resolve().lte(other);
+    }
+    resolve() {
+        if (this._resolved === null) {
+            if (typeof this.indices === 'string') {
+                this._resolved = this.target.__get__(this.indices);
+            }
+            else {
+                this._resolved = this.target.__get__(this.indices);
+            }
+        }
+        return this._resolved;
+    }
+    text() {
+        return this.resolve().text();
+    }
+}
+exports.IndexedReference = IndexedReference;

package/output/core/classes/parser/wrappers/KeyValuePair.d.ts

@@ -0,0 +1,24 @@
+import { KEY_VALUE_PAIR } from '../constants';
+import type { ParserEntity } from '../../../types';
+/**
+ * Internal marker produced by the '=>' (mapTo) operator inside curly braces.
+ * Holds a key-value pair that gets collected into a Dictionary at the end
+ * of curly scope parsing.
+ */
+export declare class KeyValuePair {
+    key: string;
+    value: ParserEntity;
+    dataType: typeof KEY_VALUE_PAIR;
+    isEnumerable: boolean;
+    constructor(key: string, value: ParserEntity);
+    static isKeyValuePair(obj: unknown): obj is KeyValuePair;
+    copy(): KeyValuePair;
+    eq(): boolean;
+    evaluate(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | import("../../dictionary/Dictionary").Dictionary | import("../../equation/Equation").Equation;
+    expand(): import("../../expression/Expression").Expression | import("../../vector/Vector").Vector | import("../../valuesSet/ValuesSet").ValuesSet | import("../../collection/Collection").Collection | import("../../matrix/Matrix").Matrix | import("../../dictionary/Dictionary").Dictionary | import("../../equation/Equation").Equation;
+    gt(): boolean;
+    gte(): boolean;
+    lt(): boolean;
+    lte(): boolean;
+    text(): string;
+}

package/output/core/classes/parser/wrappers/KeyValuePair.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyValuePair = void 0;
+const common_1 = require("../../../common/common");
+const constants_1 = require("../constants");
+/**
+ * Internal marker produced by the '=>' (mapTo) operator inside curly braces.
+ * Holds a key-value pair that gets collected into a Dictionary at the end
+ * of curly scope parsing.
+ */
+class KeyValuePair {
+    key;
+    value;
+    dataType = constants_1.KEY_VALUE_PAIR;
+    isEnumerable = false;
+    constructor(key, value) {
+        this.key = key;
+        this.value = value;
+    }
+    static isKeyValuePair(obj) {
+        return (0, common_1.isNerdamerNativeType)(obj, constants_1.KEY_VALUE_PAIR);
+    }
+    copy() {
+        return new KeyValuePair(this.key, this.value.copy());
+    }
+    eq() {
+        return false;
+    }
+    evaluate() {
+        return this.value.evaluate();
+    }
+    expand() {
+        return this.value.expand();
+    }
+    gt() {
+        return false;
+    }
+    gte() {
+        return false;
+    }
+    lt() {
+        return false;
+    }
+    lte() {
+        return false;
+    }
+    text() {
+        return `${this.key} => ${this.value.text()}`;
+    }
+}
+exports.KeyValuePair = KeyValuePair;