Files
marqdo-cli/crates/marqdo-math/src/ast.rs
T
cflmy f6c3efa849 feat(math,foreign): native formula kernel and isolated Python/Node kernels
Marqdo-math: limited, documented LaTeX-subset kernel (blueprint section 5).
- Exact BigRational arithmetic, structured Float only for irrational results;
  Int result when exact; bounds on exponents, source size, AST nodes and result
  bits so hostile input cannot hang or exhaust memory.
- Supports numbers, Unicode identifiers, \pi/\e, + - * / ^, \frac, \sqrt,
  \cdot/\times, braces, parentheses, one '=' equation, and linear solving for a
  target variable (F=ma solved for F/m/a).
- Unsupported constructs are structured errors; the kernel never claims any
  mathematical proof.

Marqdo-foreign: explicit kernels (blueprint section 6).
- run/call/detect only; reading a document never spawns a process.
- Direct exec of python3/python/node with a temp program file, clear env,
  private cwd, JSON request envelope on stdin, captured bounded stdout/stderr,
  wall-clock timeout with kill, typed wire decoding for call, structured
  ForeignError for spawn/protocol/timeout/oversized output.
- Process isolation only: crate docs state this is not a strict OS sandbox.
2026-11-20 10:43:50 +08:00

395 lines
13 KiB
Rust

//! Formula AST, exact-number representation and deterministic rendering.
//!
//! The AST is public so that `math.inspect` and tests can observe the parsed
//! structure instead of re-parsing the source string. [`Formula::source`] keeps
//! the original LaTeX exactly as supplied to [`crate::parse`]; rendering is only
//! used when an operation (currently [`crate::substitute`]) produces a new
//! formula.
use std::collections::BTreeSet;
use num_bigint::BigInt;
use num_rational::Ratio;
use num_traits::{One, Signed, Zero};
/// Exact rational number used internally by the kernel.
///
/// This is `num-rational`'s generic `Ratio` instantiated over the same
/// `num-bigint` `BigInt` type used by [`marqdo_value::Value::Int`], so values can
/// cross the kernel boundary without a lossy or string round-trip.
pub type Rational = Ratio<BigInt>;
/// Named mathematical constants supported by the subset.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Constant {
/// The circle ratio, written `\pi` or `pi`.
Pi,
/// Euler's number, written `\e` or `e`.
E,
}
impl Constant {
/// The approximate `f64` value of this constant.
pub fn value(self) -> f64 {
match self {
Constant::Pi => std::f64::consts::PI,
Constant::E => std::f64::consts::E,
}
}
}
/// A node of the supported expression grammar.
#[derive(Debug, Clone, PartialEq)]
pub enum Expr {
/// An exact numeric literal. Decimal literals are reduced to exact
/// rationals (for example `0.25` becomes `1/4`).
Number(Rational),
/// A free variable resolved from the binding map at evaluation time.
Variable(String),
/// A named constant (`\pi`, `pi`, `\e`, `e`).
Constant(Constant),
/// Unary negation.
Neg(Box<Expr>),
/// Addition.
Add(Box<Expr>, Box<Expr>),
/// Subtraction.
Sub(Box<Expr>, Box<Expr>),
/// Multiplication.
Mul(Box<Expr>, Box<Expr>),
/// Division. `\frac{a}{b}` is parsed as `Div(a, b)`.
Div(Box<Expr>, Box<Expr>),
/// Exponentiation. The exponent must evaluate to an integer.
Pow(Box<Expr>, Box<Expr>),
/// Square root. `\sqrt{x}` is a dedicated node so that perfect squares can
/// stay exact.
Sqrt(Box<Expr>),
}
impl Expr {
/// Collect every free variable name (constants are not variables).
pub fn variables(&self) -> BTreeSet<String> {
let mut names = BTreeSet::new();
self.collect_variables(&mut names);
names
}
fn collect_variables(&self, names: &mut BTreeSet<String>) {
match self {
Expr::Number(_) | Expr::Constant(_) => {}
Expr::Variable(name) => {
names.insert(name.clone());
}
Expr::Neg(inner) | Expr::Sqrt(inner) => inner.collect_variables(names),
Expr::Add(left, right)
| Expr::Sub(left, right)
| Expr::Mul(left, right)
| Expr::Div(left, right)
| Expr::Pow(left, right) => {
left.collect_variables(names);
right.collect_variables(names);
}
}
}
/// Number of syntactic occurrences of `name`.
pub fn occurrences(&self, name: &str) -> usize {
match self {
Expr::Number(_) | Expr::Constant(_) => 0,
Expr::Variable(variable) => usize::from(variable == name),
Expr::Neg(inner) | Expr::Sqrt(inner) => inner.occurrences(name),
Expr::Add(left, right)
| Expr::Sub(left, right)
| Expr::Mul(left, right)
| Expr::Div(left, right)
| Expr::Pow(left, right) => left.occurrences(name) + right.occurrences(name),
}
}
}
/// Top level shape of a parsed formula: an expression or a single equation.
///
/// A formula with one `=` is an [`FormulaKind::Equation`]; it is never an
/// assignment. More than one `=` is a parse error.
#[derive(Debug, Clone, PartialEq)]
pub enum FormulaKind {
/// A standalone arithmetic expression.
Expression(Expr),
/// `left = right`.
Equation {
/// Left-hand side.
left: Expr,
/// Right-hand side.
right: Expr,
},
}
/// A parsed formula plus the original source text.
#[derive(Debug, Clone, PartialEq)]
pub struct Formula {
/// Original LaTeX source exactly as supplied to [`crate::parse`], or the
/// canonical rendering produced by [`crate::substitute`].
pub source: String,
/// Parsed structure.
pub kind: FormulaKind,
}
impl Formula {
/// Whether this formula is an equation.
pub fn is_equation(&self) -> bool {
matches!(self.kind, FormulaKind::Equation { .. })
}
/// Borrow the expression when this formula is not an equation.
pub fn expression(&self) -> Option<&Expr> {
match &self.kind {
FormulaKind::Expression(expr) => Some(expr),
FormulaKind::Equation { .. } => None,
}
}
/// Borrow both sides when this formula is an equation.
pub fn equation(&self) -> Option<(&Expr, &Expr)> {
match &self.kind {
FormulaKind::Expression(_) => None,
FormulaKind::Equation { left, right } => Some((left, right)),
}
}
/// Every free variable appearing in the formula, in sorted order.
pub fn variables(&self) -> BTreeSet<String> {
match &self.kind {
FormulaKind::Expression(expr) => expr.variables(),
FormulaKind::Equation { left, right } => {
let mut names = left.variables();
names.extend(right.variables());
names
}
}
}
/// Render this formula back to the supported LaTeX subset deterministically.
///
/// The result is always re-parseable by [`crate::parse`]. This is used by
/// [`crate::substitute`] to build the new [`Formula::source`].
pub fn render(&self) -> String {
match &self.kind {
FormulaKind::Expression(expr) => render_expr(expr),
FormulaKind::Equation { left, right } => {
format!("{} = {}", render_expr(left), render_expr(right))
}
}
}
}
// Rendering precedence levels, from loosest to tightest.
const PREC_ADD: u8 = 1;
const PREC_MUL: u8 = 2;
const PREC_UNARY: u8 = 3;
const PREC_POW: u8 = 4;
const PREC_ATOM: u8 = 5;
/// Fractional digits beyond which a terminating rational is rendered as
/// `\frac{..}{..}` instead of a long decimal. Chosen so that substituted
/// `f64` values that are exactly representable in a short decimal stay readable,
/// while binary-exact values with long expansions use a compact fraction.
const MAX_RENDERED_DECIMAL_DIGITS: u32 = 32;
/// Render an expression without surrounding parentheses.
pub fn render_expr(expr: &Expr) -> String {
render(expr, 0)
}
fn render(expr: &Expr, parent_precedence: u8) -> String {
match expr {
Expr::Number(value) => {
let (text, precedence) = render_rational(value);
parenthesize(text, precedence, parent_precedence)
}
Expr::Variable(name) => name.clone(),
Expr::Constant(constant) => match constant {
Constant::Pi => "\\pi".to_string(),
Constant::E => "\\e".to_string(),
},
Expr::Neg(inner) => {
let text = format!("-{}", render(inner, PREC_UNARY));
parenthesize(text, PREC_UNARY, parent_precedence)
}
Expr::Add(left, right) => {
let text = format!(
"{} + {}",
render(left, PREC_ADD),
render(right, PREC_ADD + 1)
);
parenthesize(text, PREC_ADD, parent_precedence)
}
Expr::Sub(left, right) => {
let text = format!(
"{} - {}",
render(left, PREC_ADD),
render(right, PREC_ADD + 1)
);
parenthesize(text, PREC_ADD, parent_precedence)
}
Expr::Mul(left, right) => {
let text = format!(
"{} * {}",
render(left, PREC_MUL),
render(right, PREC_MUL + 1)
);
parenthesize(text, PREC_MUL, parent_precedence)
}
Expr::Div(left, right) => {
let text = format!(
"{} / {}",
render(left, PREC_MUL),
render(right, PREC_MUL + 1)
);
parenthesize(text, PREC_MUL, parent_precedence)
}
Expr::Pow(base, exponent) => {
let text = format!(
"{} ^ {}",
render(base, PREC_POW + 1),
render(exponent, PREC_POW)
);
parenthesize(text, PREC_POW, parent_precedence)
}
Expr::Sqrt(inner) => format!("\\sqrt{{{}}}", render(inner, 0)),
}
}
fn parenthesize(text: String, precedence: u8, parent_precedence: u8) -> String {
if precedence < parent_precedence {
format!("({text})")
} else {
text
}
}
/// Render an exact rational, returning the text and its rendering precedence.
///
/// Integral values render as integers. Values with a terminating decimal
/// expansion of at most [`MAX_RENDERED_DECIMAL_DIGITS`] digits render as
/// decimals; everything else renders as `\frac{numerator}{denominator}`.
fn render_rational(value: &Rational) -> (String, u8) {
if value.is_integer() {
let integer = value.to_integer();
let negative = integer.sign() == num_bigint::Sign::Minus;
let precedence = if negative { PREC_UNARY } else { PREC_ATOM };
return (integer.to_string(), precedence);
}
if let Some(places) = decimal_places(value.denom()) {
if places <= MAX_RENDERED_DECIMAL_DIGITS {
let scale = BigInt::from(10_u32).pow(places);
let scaled = value.numer() * &scale / value.denom();
let negative = scaled.sign() == num_bigint::Sign::Minus;
let digits = scaled.abs().to_string();
let places = places as usize;
let decimal = if digits.len() <= places {
format!("0.{}{digits}", "0".repeat(places - digits.len()))
} else {
let split = digits.len() - places;
format!("{}.{}", &digits[..split], &digits[split..])
};
let precedence = if negative { PREC_UNARY } else { PREC_ATOM };
let text = if negative {
format!("-{decimal}")
} else {
decimal
};
return (text, precedence);
}
}
(
format!("\\frac{{{}}}{{{}}}", value.numer(), value.denom()),
PREC_ATOM,
)
}
/// Number of fractional digits needed for the terminating decimal expansion of
/// `denominator`, or `None` when the expansion does not terminate or is longer
/// than [`MAX_RENDERED_DECIMAL_DIGITS`].
fn decimal_places(denominator: &BigInt) -> Option<u32> {
let mut reduced = denominator.clone();
let two = BigInt::from(2_u32);
let five = BigInt::from(5_u32);
let mut twos = 0_u32;
while reduced.is_positive() && (&reduced % &two).is_zero() {
reduced /= &two;
twos += 1;
if twos > MAX_RENDERED_DECIMAL_DIGITS {
return None;
}
}
let mut fives = 0_u32;
while reduced.is_positive() && (&reduced % &five).is_zero() {
reduced /= &five;
fives += 1;
if fives > MAX_RENDERED_DECIMAL_DIGITS {
return None;
}
}
if reduced.is_one() {
Some(twos.max(fives))
} else {
None
}
}
#[cfg(test)]
mod tests {
use super::*;
fn number(numerator: i64, denominator: i64) -> Expr {
Expr::Number(Ratio::new(
BigInt::from(numerator),
BigInt::from(denominator),
))
}
#[test]
fn rendering_round_trips_through_parse() {
// The renderer must always emit text the parser accepts.
for source in [
"1 + 2 * 3",
"(1 + 2) * 3",
"2 ^ (3 + 1)",
"\\frac{1}{3}",
"-4 ^ 2",
"2 ^ (-3)",
"\\sqrt{2}",
"a = 2 * b + 1",
"(2 ^ 3) ^ 2",
"1 - (2 - 3)",
"a / (b * c)",
] {
let formula = crate::parse(source).expect("fixture parses");
let rendered = formula.render();
let reparsed = crate::parse(&rendered)
.unwrap_or_else(|err| panic!("rendered {rendered:?} does not parse: {err}"));
assert_eq!(reparsed.kind, formula.kind, "source {source:?}");
}
}
#[test]
fn decimal_and_fraction_rendering_is_deterministic() {
assert_eq!(render_expr(&number(5, 2)), "2.5");
assert_eq!(render_expr(&number(-5, 2)), "-2.5");
assert_eq!(render_expr(&number(1, 8)), "0.125");
assert_eq!(render_expr(&number(1, 3)), "\\frac{1}{3}");
assert_eq!(render_expr(&number(0, 1)), "0");
}
#[test]
fn variables_are_collected_without_constants() {
let formula = crate::parse("2 * x + y * \\pi").unwrap();
assert_eq!(
formula.variables().into_iter().collect::<Vec<_>>(),
vec!["x".to_string(), "y".to_string()]
);
assert_eq!(formula.expression().unwrap().occurrences("x"), 1);
}
}