Function canonicalForm

src/compute-engine/boxed-expression/canonical.ts:14–85

(
  expr: Expression,
  forms: CanonicalOptions,
  scope?: Scope
)

import { canonicalMultiply, canonicalDivide } from './arithmetic-mul-div.js';
import { canonicalPower } from './arithmetic-power.js';
import { canonicalOrder } from './order.js';
import { declaredBinders, binderShadowAt } from './binding-sites.js';
import { asBigint } from './numerics.js';
import { isOperatorDef, isImaginaryUnit } from './utils.js';
import { isFunction, isNumber, isSymbol } from './type-guards.js';

export function canonicalForm(
  expr: Expression,
  forms: CanonicalOptions,
  scope?: Scope
): Expression {
  // No canonical form?
  if (forms === false) return expr;

  // Full canonical form? Without a scope, `_inScope()` would just call its
  // callback: go straight to the getter. This is on the recursive path of
  // canonicalizing an already-boxed tree (each operand's `.canonical` comes
  // back through here), where every frame per level costs depth.
  if (forms === true)
    return scope === undefined
      ? expr.canonical
      : expr.engine._inScope(scope, () => expr.canonical);

  if (typeof forms === 'string') forms = [forms];

  // A partial form is not fully canonical, so it follows the STRUCTURAL symbol
  // contract: symbols resolve against the scope chain (a `holdUntil: 'never'`
  // constant still substitutes its value, an existing declaration still binds),
  // but a name that resolves to nothing is left unbound instead of being
  // declared into the caller's scope. The suppression wraps the whole pipeline
  // because the forms reach `.canonical` on a symbol through many helpers
  // (`isImaginaryUnit`, `flatten`, `canonicalInvisibleOperator`, …), not just
  // `symbolForm`. See `docs/SCOPING-MODEL.md` A1.
  //
  // The supplied scope is honored on this path too (B1): it steers the lookups
  // the forms perform, exactly as it does on the `forms === true` path above.
  // Without it, `scope` was silently ignored for every partial form.
  const formList = forms;
  return expr.engine._inScope(scope, () =>
    expr.engine._resolveOnly(() => applyForms(expr, formList))
  );
}

/**
 * `expr`'s symbol name, or `''` for anything that is not a symbol — a sentinel
 * no binder can bind, so a shadow-set membership test on it is always false.
 */
function symbolNameOf(expr: Expression): string {
  return isSymbol(expr) ? expr.symbol : '';
}

function applyForms(
  expr: Expression,
  forms: readonly CanonicalForm[]
): Expression {
  // Like for full canonicalization, request the canonical form of symbols.
  // Automatically, this involves the substitution of the symbol with its
  // value, if it is a constant-flagged symbol, with a 'holdUntil' attribute of