nerdamer 1.1.13 → 2.0.0-rc.1

package/output/core/converters/BaseConverter.js

@@ -0,0 +1,405 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseConverter = void 0;
+const Expression_1 = require("../classes/expression/Expression");
+const constants_1 = require("../classes/parser/constants");
+const errors_1 = require("../errors");
+const modes = {
+    TeX: 'TeX',
+    TEXT: 'text',
+};
+/**
+ * Shared formatting pipeline for Nerdamer converters.
+ *
+ * @remarks
+ * This is an implementation base class. Public callers should construct `Converter`
+ * through `nerdamer.classes.Converter`; subclasses provide the
+ * expression-specific formatting hooks used by {@link BaseConverter.convert}.
+ *
+ * Conversion separates every expression into multiplier, value, and power fragments,
+ * each with numerator and denominator slots. Keeping those fragments separate lets the
+ * final formatting step place negative powers and rational multipliers into one
+ * denominator without algebraically rewriting the caller's symbolic value.
+ */
+class BaseConverter {
+    static GREEK_LETTERS = [
+        'alpha',
+        'beta',
+        'gamma',
+        'delta',
+        'epsilon',
+        'zeta',
+        'eta',
+        'theta',
+        'iota',
+        'kappa',
+        'lambda',
+        'mu',
+        'nu',
+        'xi',
+        'omnikron',
+        'pi',
+        'rho',
+        'sigma',
+        'tau',
+        'upsilon',
+        'phi',
+        'chi',
+        'psi',
+        'omega',
+        'Gamma',
+        'Delta',
+        'Epsilon',
+        'Theta',
+        'Lambda',
+        'Xi',
+        'Pi',
+        'Sigma',
+        'Phi',
+        'Psi',
+        'Omega',
+    ];
+    static modes = modes;
+    greek = BaseConverter.GREEK_LETTERS;
+    modes = [modes.TeX, modes.TEXT];
+    mode = this.modes[0];
+    static convertNtRoot(input, root) {
+        return Expression_1.Expression.toFunction(constants_1.NTHROOT, [BaseConverter.strip(input), root]);
+    }
+    static convertSQRT(input) {
+        return Expression_1.Expression.toFunction(constants_1.SQRT, [BaseConverter.strip(input)]);
+    }
+    static join(n, d, glue) {
+        if (!n && !d) {
+            return '';
+        }
+        if (n && !d) {
+            return n;
+        }
+        if (d && !n) {
+            return d;
+        }
+        return n + glue + d;
+    }
+    static merge(a, b) {
+        return [a[0] + b[0], a[1] + b[1]];
+    }
+    static strip(input) {
+        const arg = new Expression_1.Expression(input);
+        delete arg.power;
+        delete arg.multiplier;
+        return arg;
+    }
+    cleanup() {
+        // Override in subclasses if needed
+    }
+    convertPower(input, power, options) {
+        return power.isOne() || (input.isNUM() && power.isZero())
+            ? ''
+            : this.convert(power, options);
+    }
+    finalizePowerAndInput(power, input, _options) {
+        return [power, input];
+    }
+    formatPowerOutput(pArray, requiresBrackets) {
+        const retval = ['', ''];
+        for (let i = 0; i < pArray.length; i++) {
+            const p = pArray[i];
+            if (p === '') {
+                retval[i] = '';
+                continue;
+            }
+            const formatted = this.mode === BaseConverter.modes.TEXT && requiresBrackets
+                ? this.inBrackets(p)
+                : this.inBraces(p);
+            retval[i] = '^' + formatted;
+        }
+        return retval;
+    }
+    formatSubscripts(value) {
+        const parts = value.split('_');
+        let formatted = '';
+        while (parts.length > 1) {
+            formatted = '_' + this.inBraces(parts.pop() + formatted);
+        }
+        return parts[0] + formatted;
+    }
+    getMultiplicationSymbol() {
+        return this.mode === 'TeX' ? ' \\cdot ' : '*';
+    }
+    inBraces(value) {
+        return this.mode === BaseConverter.modes.TEXT ? value : `{${value}}`;
+    }
+    inBrackets(value, type = 'parens') {
+        const bracketTypes = {
+            parens: ['(', ')'],
+            square: ['[', ']'],
+            brace: ['{', '}'],
+            abs: ['|', '|'],
+        };
+        const [L, R] = bracketTypes[type];
+        if (this.mode === BaseConverter.modes.TEXT) {
+            return `${L}${value}${R}`;
+        }
+        if (type === 'brace') {
+            return `\\left\\{${value}\\right\\}`;
+        }
+        return `\\left${L}${value}\\right${R}`;
+    }
+    initInput(input) {
+        return input;
+    }
+    isBracketed(v) {
+        return /^\\left\(.+\\right\)$/.test(v);
+    }
+    requiresMultiplicationSymbol(input) {
+        return input.isSum();
+    }
+    set(m, v, p, input) {
+        const mul = this.getMultiplicationSymbol();
+        const combinePower = input.isProduct();
+        // Format power
+        let tp;
+        if (p) {
+            const power = input.getPower();
+            const requiresBrackets = ((power.isSum() || power.isProduct()) && power.isLinear()) ||
+                (power.isNUM() && !power.isInteger()) ||
+                power.getPower().sign() === -1;
+            p = this.formatPowerOutput(p, requiresBrackets);
+        }
+        if (combinePower) {
+            tp = p[0];
+            p[0] = '';
+        }
+        // Merge v and p
+        v = BaseConverter.merge(v, p);
+        let [mn, md] = m;
+        const [vn, vd] = v;
+        // Filter out unnecessary ones
+        if (vn && Number(mn) === 1) {
+            mn = '';
+        }
+        if (Number(md) === 1) {
+            md = '';
+        }
+        const addMultiplication = this.requiresMultiplicationSymbol(input);
+        const alwaysMul = this.mode === BaseConverter.modes.TeX;
+        const top = BaseConverter.join(mn, vn, alwaysMul || !this.isBracketed(vn) || addMultiplication ? mul : '');
+        let bottom = BaseConverter.join(md, vd, alwaysMul || !this.isBracketed(vd) || addMultiplication ? mul : '');
+        if (md && vd && this.mode === BaseConverter.modes.TEXT) {
+            bottom = this.inBrackets(bottom);
+        }
+        if (top && bottom) {
+            let frac = this.toFraction(top, bottom);
+            if (combinePower && tp) {
+                frac = this.inBrackets(frac) + tp;
+            }
+            return frac;
+        }
+        return top;
+    }
+    setMultiplier(m, multiplierArray, _input, options) {
+        if (options?.decimal) {
+            multiplierArray[0] = m.isInteger() ? String(m.numerator) : m.text(options);
+        }
+        else {
+            multiplierArray[0] = String(m.numerator);
+            multiplierArray[1] = String(m.denominator);
+        }
+    }
+    toFraction(n, d) {
+        if (this.mode === 'TeX') {
+            return ('\\frac' +
+                this.inBraces(this.stripOuterBrackets(n)) +
+                this.inBraces(this.stripOuterBrackets(d)));
+        }
+        return `${n}/${d}`;
+    }
+    value(_input, _isInverted, _isNegative, _options) {
+        return ['', ''];
+    }
+    convertCollection(input, options) {
+        const elements = input.elements.map(e => this.convert(e, options));
+        const inner = elements.join(this.mode === BaseConverter.modes.TeX ? ', \\, ' : ', ');
+        return this.inBrackets(inner);
+    }
+    convertDictionary(input, options) {
+        const pairs = input.entries().map(([key, value]) => {
+            const convertedValue = this.convert(value, options);
+            if (this.mode === BaseConverter.modes.TeX) {
+                return `${key} \\mapsto ${convertedValue}`;
+            }
+            return `${key} => ${convertedValue}`;
+        });
+        const inner = pairs.join(this.mode === BaseConverter.modes.TeX ? ', \\, ' : ', ');
+        if (this.mode === BaseConverter.modes.TeX) {
+            return `\\left\\{${inner}\\right\\}`;
+        }
+        return `{${inner}}`;
+    }
+    convertEquation(input, options) {
+        return `${this.convert(input.LHS, options)}=${this.convert(input.RHS, options)}`;
+    }
+    convertExpression(input, options) {
+        input = this.initInput(input);
+        const pExpr = input.getPower();
+        // Complex exponents are not ordered, and signFree() would replace them with their modulus.
+        // Preserve them verbatim instead of trying to move them into the denominator.
+        const isComplexPower = pExpr.isComplex();
+        const power = isComplexPower ? pExpr : pExpr.signFree();
+        const isInverted = !isComplexPower && (pExpr.lt(0) || pExpr.sign() === -1);
+        const isNegative = input.getMultiplier().isNegative();
+        const m = input.getMultiplier().abs();
+        const multiplierArray = ['', ''];
+        if (!options.ignoreMultiplier) {
+            this.setMultiplier(m, multiplierArray, input, options);
+        }
+        const [finalPower, finalInput] = this.finalizePowerAndInput(power, input, options);
+        const valueArray = this.value(finalInput, isInverted, isNegative, options);
+        const p = this.convertPower(finalInput, finalPower, options);
+        const powerArray = ['', ''];
+        powerArray[isInverted ? 1 : 0] = p;
+        const result = (isNegative ? '-' : '') + this.set(multiplierArray, valueArray, powerArray, finalInput);
+        this.cleanup();
+        return result.replace(/\+-/g, '-');
+    }
+    convertMatrix(input, options) {
+        let retval;
+        if (this.mode === BaseConverter.modes.TEXT) {
+            const rows = input.elements.map(row => {
+                return `[${row.map(e => this.convert(e, options)).join(', ')}]`;
+            });
+            retval = `matrix(${rows.join(', ')})`;
+        }
+        else {
+            const style = options.matrixStyle || '';
+            const matrixOptions = { ...options, insideMatrix: true };
+            const rows = input.elements.map(row => row.map(e => this.convert(e, matrixOptions)).join(' & '));
+            retval = `\\begin{${style}matrix} ${rows.join(' \\\\ ')} \\end{${style}matrix}`;
+        }
+        return retval;
+    }
+    convertValuesSet(input, options) {
+        const elements = input.elements.map(e => this.convert(e, options));
+        const inner = elements.join(this.mode === BaseConverter.modes.TeX ? ', \\, ' : ', ');
+        if (this.mode === BaseConverter.modes.TeX) {
+            return `\\left\\{${inner}\\right\\}`;
+        }
+        return `{${inner}}`;
+    }
+    /**
+     * Removes a single outer \left(...\right) wrapper when the contents
+     * will already be visually grouped (e.g. inside \frac{}{}).
+     */
+    stripOuterBrackets(s) {
+        const left = '\\left(';
+        const right = '\\right)';
+        let retval = s;
+        if (s.startsWith(left) && s.endsWith(right)) {
+            let depth = 0;
+            let isOuterWrapper = true;
+            for (let i = 0; i < s.length && isOuterWrapper;) {
+                if (s.startsWith(left, i)) {
+                    depth++;
+                    i += left.length;
+                }
+                else if (s.startsWith(right, i)) {
+                    depth--;
+                    i += right.length;
+                    if (depth === 0 && i < s.length) {
+                        isOuterWrapper = false;
+                    }
+                    else if (depth < 0) {
+                        isOuterWrapper = false;
+                    }
+                }
+                else {
+                    i++;
+                }
+            }
+            if (isOuterWrapper && depth === 0) {
+                retval = s.slice(left.length, -right.length);
+            }
+        }
+        return retval;
+    }
+    /**
+     * Formats a supported Nerdamer value in the converter's current mode.
+     *
+     * @remarks
+     * String input is parsed before formatting, so current parser settings, constants,
+     * and known values apply. Numbers are converted with JavaScript's string conversion.
+     * Expressions, equations, collections, vectors, matrices, solution sets, value sets,
+     * and dictionaries use their structured representations rather than being reparsed
+     * from display text.
+     * Reading an expression can initialize its lazily stored multiplier or power fields,
+     * but conversion does not change the expression's mathematical value.
+     *
+     * `convertRoots` defaults to `true`, rendering reciprocal integer powers as roots
+     * where the active mode supports that form. `decimal` requests decimal rational
+     * multipliers, `precision` is forwarded to rational formatting, `matrixStyle`
+     * selects the TeX matrix environment prefix, and `ignoreMultiplier` omits an
+     * expression's top-level multiplier. `insideMatrix` is used while formatting matrix
+     * elements and is normally managed by the converter itself.
+     *
+     * @param input - The parser entity, expression string, or number to format.
+     * @param options - Formatting options for this conversion and recursive child conversions.
+     * @returns The formatted text or TeX string for `input`.
+     * @throws Error When `input` is not one of the supported parser entity types.
+     */
+    convert(input, options) {
+        options = { convertRoots: true, ...options };
+        if (typeof input === 'number') {
+            return String(input);
+        }
+        if (typeof input === 'string' || Expression_1.Expression.isExpression(input)) {
+            return this.convertExpression(Expression_1.Expression.create(input), options);
+        }
+        if (input.dataType === constants_1.COLLECTION) {
+            return this.convertCollection(input, options);
+        }
+        if (input.dataType === constants_1.EQUATION) {
+            return this.convertEquation(input, options);
+        }
+        if (input.dataType === constants_1.VECTOR) {
+            const vector = input;
+            const separator = options.insideMatrix
+                ? ' & '
+                : this.mode === BaseConverter.modes.TeX
+                    ? ', \\, '
+                    : ', ';
+            const inner = vector.arrayMap(e => this.convert(e, options)).join(separator);
+            return options.insideMatrix ? inner : this.inBrackets(inner, 'square');
+        }
+        if (input.dataType === constants_1.MATRIX) {
+            return this.convertMatrix(input, options);
+        }
+        if (input.dataType === constants_1.SOLUTIONS_SET) {
+            return this.convertValuesSet(input, options);
+        }
+        if (input.dataType === constants_1.SET) {
+            return this.convertValuesSet(input, options);
+        }
+        if (input.dataType === constants_1.DICTIONARY) {
+            return this.convertDictionary(input, options);
+        }
+        throw new Error((0, errors_1.message)('unsupportedType', { type: constants_1.dataTypes[input.dataType] || typeof input }));
+    }
+    /**
+     * Selects the output syntax used by subsequent conversions.
+     *
+     * @remarks
+     * The mode is mutable converter state. Supported values are `"TeX"` and `"text"`;
+     * changing the mode does not alter parser settings or previously returned strings.
+     *
+     * @param mode - The output mode to activate.
+     * @throws Error When `mode` is not `"TeX"` or `"text"`.
+     */
+    setMode(mode) {
+        if (!this.modes.includes(mode)) {
+            throw new Error((0, errors_1.message)('unrecognizedMode', { mode }));
+        }
+        this.mode = mode;
+    }
+}
+exports.BaseConverter = BaseConverter;

package/output/core/converters/Converter.d.ts

@@ -0,0 +1,111 @@
+import { Expression } from '../classes/expression/Expression';
+import { BaseConverter } from './BaseConverter';
+import type { OptionsObject } from '../classes/parser/types';
+import type { FracArray } from '../classes/parser/types';
+import type { ParserEntity } from '../types';
+/**
+ * Formats Nerdamer values as TeX or normalized text and imports supported TeX input.
+ *
+ * @remarks
+ * A converter retains its output mode between calls. The default mode is `"TeX"`;
+ * construct a separate `"text"` converter when both representations are needed.
+ * Formatting a string parses it with the process-wide parser, so registered functions,
+ * constants, settings, and known values can affect the result.
+ *
+ * {@link Converter.fromTeX} recognizes the TeX forms emitted by this converter and a
+ * practical subset of common mathematical notation. It is not a general TeX parser:
+ * unsupported macros, ambiguous implicit notation, or nesting outside the recognized
+ * forms can produce parser errors or a different symbolic interpretation.
+ *
+ * @example
+ * ```ts
+ * import nerdamer from 'nerdamer';
+ *
+ * const text = new nerdamer.classes.Converter('text');
+ * const tex = new nerdamer.classes.Converter();
+ *
+ * text.convert('x^2 + 2*x + 1'); // "1+2*x+x^2"
+ * tex.convert('sqrt(x)');        // "\\sqrt{x}"
+ * ```
+ */
+export declare class Converter extends BaseConverter {
+    private static readonly TEX_FUNCTION_MAP;
+    /**
+     * Reverse map for fromTeX: maps TeX command names back to internal function names.
+     */
+    private static readonly TEX_REVERSE_MAP;
+    /**
+     * Creates a converter with persistent output mode.
+     *
+     * @param mode - `"TeX"` (the default) or `"text"`.
+     */
+    constructor(mode?: 'TeX' | 'text');
+    private static clearOnes;
+    private static wrapRoot;
+    protected finalizePowerAndInput(power: Expression, input: Expression, options?: OptionsObject): [Expression, Expression];
+    protected functionString(input: Expression, options?: OptionsObject): string;
+    protected value(input: Expression, isInverted: boolean, isNegative: boolean, options?: OptionsObject): FracArray;
+    private convertSourceRPN;
+    private formatFactorial;
+    private formatSumOrProduct;
+    private formatTeXFunction;
+    private formatVariable;
+    private getFunctionName;
+    private handleExp;
+    private handleProduct;
+    private handleSum;
+    /** Parses a top-level TeX matrix environment into a scalar-valued Matrix. */
+    private parseTeXMatrix;
+    private parseTeXSetOrDictionary;
+    private parseTeXVector;
+    /**
+     * Rewrites the supported TeX subset into parser syntax in an ordered pass.
+     *
+     * Structure-dependent forms such as transforms, derivatives, integrals, limits, and
+     * indexed sums must be recognized before generic braces and commands are removed.
+     * This is a compatibility preprocessor rather than a TeX grammar, so each rewrite is
+     * limited to the forms that can be mapped unambiguously to parser calls.
+     */
+    private preprocessTeXClean;
+    /**
+     * Rewrites one TeX command whose argument is carried in balanced braces.
+     *
+     * The converter emits some commands around expressions that can themselves contain
+     * nested TeX groups. A flat regular expression cannot safely recover those arguments,
+     * so this keeps the brace matching local to the TeX conversion pipeline.
+     */
+    private replaceBracedTeXCommand;
+    private splitTeXTopLevel;
+    /**
+     * Formats supported values while retaining ordinary Converter semantics by default.
+     * Source preservation is an internal compatibility option used by convertToLaTeX.
+     */
+    convert(input: ParserEntity | string | number, options?: OptionsObject): string;
+    /**
+     * Parses a supported TeX subset into a Nerdamer parser entity.
+     *
+     * @remarks
+     * Set notation is recognized before ordinary expression preprocessing and produces a
+     * value set or dictionary when appropriate. Other input is rewritten to Nerdamer
+     * parser syntax, tokenized in pure mode, and evaluated through the process-wide parser.
+     * Consequently, parser settings or registered functions can affect the result.
+     *
+     * The importer supports the converter's common function forms, roots, arbitrary-base
+     * logarithms, transforms, derivatives, integrals, limits, sums, products, floor and
+     * ceiling notation, equations, vectors, matrices, finite sets, and dictionaries. It does
+     * not promise round-tripping arbitrary third-party TeX.
+     *
+     * @param input - TeX text in the supported conversion subset.
+     * @returns The parser entity represented by the supported TeX input.
+     * @throws Error When preprocessing leaves syntax that the parser cannot interpret.
+     *
+     * @example
+     * ```ts
+     * import nerdamer from 'nerdamer';
+     *
+     * const converter = new nerdamer.classes.Converter();
+     * nerdamer.pretty(converter.fromTeX('\\log_{2}{256}'), 'text'); // "8"
+     * ```
+     */
+    fromTeX(input: string): ParserEntity;
+}