Function applyRule

src/compute-engine/boxed-expression/rules.ts:981–1232

(
  rule: Readonly<BoxedRule>,
  expr: Expression,
  substitution: BoxedSubstitution,
  options?: Readonly<Partial<ReplaceOptions>>
)

    if (options.canonical === true) return 'canonical';
    if (options.canonical === false) return 'raw';
    return options.canonical;
  }

  return options?.form;
}

/**
 * Apply a rule to an expression, assuming an incoming substitution
 * @param rule the rule to apply
 * @param expr the expression to apply the rule to
 * @param substitution an incoming substitution
 * @param options
 * @returns A transformed expression, if the rule matched. `null` otherwise.
 */
export function applyRule(
  rule: Readonly<BoxedRule>,
  expr: Expression,
  substitution: BoxedSubstitution,
  options?: Readonly<Partial<ReplaceOptions>>
): RuleStep | null {
  if (!rule) return null;
  const requestedForm = normalizeReplaceForm(options);

  // eslint-disable-next-line prefer-const
  let { match, replace, condition, id, onMatch, onBeforeMatch, purpose } = rule;
  const because = id ?? '';

  const ce = expr.engine;

  const canonicalRequested =
    requestedForm !== undefined &&
    requestedForm !== 'raw' &&
    requestedForm !== 'structural';

  // If the canonical form of the match loses wildcards, this rule cannot match
  // canonical expressions (they would already be simplified). Skip this rule.
  if ((canonicalRequested || expr.isCanonical) && match) {
    if (canonicalMatchLosesWildcards(match)) return null;
  }

  let operandsMatched = false;

  if (isFunction(expr) && options?.recursive) {
    const direction = options?.direction ?? 'left-right';
    let newOps =
      direction === 'left-right' ? expr.ops : [...expr.ops].reverse();

    // Apply the rule to the operands of the expression
    newOps = newOps.map((op) => {
      const subExpr = applyRule(rule, op, {}, options);
      if (!subExpr) return op;
      operandsMatched = true;
      return subExpr.value;
    });

    if (direction === 'right-left') (newOps as Expression[]).reverse();

    // At least one operand (directly or recursively) matched: but continue onwards to match against