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.
This commit is contained in:
cflmy committed 2026-11-20 10:43:50 +08:00
1 parent 17b68da7f9
commit f6c3efa849
9 files changed
+4032 -2

No files matched your search

+819
View File
@@ -0,0 +1,819 @@
//! Explicit foreign code kernels (Python/Node).
//!
//! A fenced `python` or `javascript` code block is an inert [`Code`] value in
//! Marqdo. Nothing in this crate is ever spawned while reading, parsing or
//! rendering a document: a process is created **only** when the host calls
//! [`run`] or [`call`] after the capability check succeeded.
//!
//! Every execution is one-shot and isolated:
//!
//! * the kernel program is written to a private, uniquely named file under
//! [`std::env::temp_dir`] (`.py` or `.js`), the child is started by direct
//! `argv` exec (no shell, no string interpolation) and its working directory
//! is a fresh private temporary directory so relative writes never touch the
//! project; modern Node performs syntax detection on `.js`, so both ESM
//! `import` and CommonJS `require` kernels are supported;
//! * stdin carries the versioned request envelope
//! `{"wire_version":1,"kind":"request","input":<value or null>}`;
//! * stdout and stderr are always piped and captured, never inherited;
//! * the environment is cleared except for `PATH`, so Marqdo secrets do not
//! leak into the kernel by default;
//! * a wall-clock deadline is enforced by polling `try_wait` and killing the
//! child on expiry, and a shared byte budget aborts output flooding;
//! * the temporary program file and working directory are removed afterwards,
//! including on error paths.
//!
//! [`run`] returns captured output as data. [`call`] additionally requires
//! stdout to be exactly one versioned wire value (see
//! [`marqdo_value::from_wire`]); any stdout pollution or trailing noise is a
//! [`ForeignError::Protocol`] error rather than something silently ignored.
//!
//! This is process isolation, not a security sandbox. The `strict` sandbox
//! mode additionally needs OS-level isolation (namespaces/seccomp/cgroups or
//! platform equivalents) as described in the development blueprint; this crate
//! does not claim to provide it.
//!
//! [`Code`]: marqdo_value::CodeValue
use std::fs;
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use std::process::{Child, Command, ExitStatus, Stdio};
use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex};
use std::thread;
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use marqdo_value::Value;
use serde_json::Value as Json;
/// Value of the `kind` field in the stdin request envelope.
pub const REQUEST_KIND: &str = "request";
/// Timeout applied to `--version` probing in [`detect`].
const DETECT_TIMEOUT: Duration = Duration::from_secs(5);
/// Maximum bytes captured while probing a kernel version.
const DETECT_OUTPUT_LIMIT: usize = 64 * 1024;
/// Polling interval for `try_wait` while supervising a child.
const POLL_INTERVAL: Duration = Duration::from_millis(2);
/// How long to wait for the pipe readers after the child was reaped. A
/// misbehaving kernel that leaves a grandchild holding the pipes must not hang
/// the Marqdo host process.
const READER_GRACE: Duration = Duration::from_secs(2);
static UNIQUE_COUNTER: AtomicU64 = AtomicU64::new(0);
/// Canonical language names supported by this crate.
pub const SUPPORTED_LANGUAGES: [&str; 2] = ["python", "javascript"];
/// Normalize a language alias to its canonical kernel name.
///
/// Recognized aliases are `python`/`python3`/`py` and
/// `javascript`/`js`/`node`/`nodejs`. The comparison is ASCII
/// case-insensitive and surrounding whitespace is ignored. Unknown languages
/// return `None`.
pub fn normalize_language(language: &str) -> Option<&'static str> {
match language.trim().to_ascii_lowercase().as_str() {
"python" | "python3" | "py" => Some("python"),
"javascript" | "js" | "node" | "nodejs" => Some("javascript"),
_ => None,
}
}
/// What the host asks a foreign kernel to do.
#[derive(Debug, Clone, PartialEq)]
pub struct RunRequest {
/// Language name or alias (for example `"python3"` or `"js"`).
pub language: String,
/// Program source executed by the kernel.
pub source: String,
/// Optional input value delivered inside the versioned stdin envelope.
pub input: Option<Json>,
/// Wall-clock budget for the whole child execution.
pub timeout: Duration,
/// Maximum number of bytes captured across stdout and stderr combined.
pub max_output_bytes: usize,
}
impl RunRequest {
/// Create a request with conservative defaults: 30 s timeout and 1 MiB of
/// captured output.
pub fn new(language: impl Into<String>, source: impl Into<String>) -> Self {
Self {
language: language.into(),
source: source.into(),
input: None,
timeout: Duration::from_secs(30),
max_output_bytes: 1024 * 1024,
}
}
}
/// Terminal state of a foreign execution.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum RunStatus {
/// The process exited with status 0 (for [`call`]: and its output decoded).
Success,
/// The process exited non-zero or was terminated by a signal.
Failed,
/// The wall-clock deadline expired and the process was killed.
TimedOut,
}
impl RunStatus {
/// Stable lowercase name for logging and diagnostics.
pub const fn as_str(self) -> &'static str {
match self {
RunStatus::Success => "success",
RunStatus::Failed => "failed",
RunStatus::TimedOut => "timed_out",
}
}
}
/// Outcome of one foreign execution.
#[derive(Debug, Clone, PartialEq)]
pub struct RunResult {
/// Success/failure/timeout classification.
pub status: RunStatus,
/// Captured stdout (lossy UTF-8 for [`run`], validated for [`call`]).
pub stdout: String,
/// Captured stderr; preserved even when the kernel fails.
pub stderr: String,
/// Exit code, or `None` when the child was killed by a signal or timed out.
pub exit_code: Option<i32>,
/// Measured wall-clock duration of the child execution.
pub duration: Duration,
/// Decoded wire value; only [`call`] sets this on success.
pub value: Option<Value>,
}
/// A detected foreign kernel.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct KernelInfo {
/// Canonical language name (`"python"` or `"javascript"`).
pub language: String,
/// Resolved absolute path of the interpreter executable.
pub program: PathBuf,
/// First line of the interpreter's `--version` output.
pub version: String,
}
/// Failure while detecting or executing a foreign kernel.
#[derive(Debug, Clone, thiserror::Error)]
pub enum ForeignError {
/// No usable Python/Node interpreter was found on `PATH`.
#[error("foreign kernel `{language}` is unavailable: {hint}")]
KernelUnavailable {
/// Requested (normalized when known) language name.
language: String,
/// Actionable installation guidance.
hint: String,
},
/// The child process could not be created.
#[error("failed to spawn foreign kernel: {message}")]
Spawn {
/// Operating-system error text.
message: String,
},
/// A pipe, temporary file or wait operation failed.
#[error("foreign kernel I/O error: {message}")]
Io {
/// Operating-system error text.
message: String,
},
/// The wall-clock deadline expired; the child was killed.
#[error("foreign kernel exceeded its wall-clock timeout of {seconds} seconds")]
Timeout {
/// Requested timeout, in seconds.
seconds: f64,
},
/// The kernel violated the stdout wire protocol or sent invalid UTF-8.
#[error("foreign kernel protocol violation: {message}")]
Protocol {
/// What went wrong.
message: String,
},
/// Captured stdout/stderr exceeded `max_output_bytes`; the child was
/// killed and the partial output dropped.
#[error("foreign kernel output exceeded the {limit} byte limit")]
OutputTooLarge {
/// Configured byte budget.
limit: usize,
},
}
/// Detect a kernel for `language` by scanning `PATH`.
///
/// Candidates are `python3`, then `python` for Python, and `node` for
/// JavaScript. The returned [`KernelInfo::version`] is the first line of the
/// interpreter's `--version` output. Returns `None` for an unknown language or
/// when no working interpreter is installed; detection honors the same
/// cleared-environment rule as execution and is bounded by a short timeout.
pub fn detect(language: &str) -> Option<KernelInfo> {
let canonical = normalize_language(language)?;
let path_var = std::env::var_os("PATH")?;
for name in program_candidates(canonical) {
for directory in std::env::split_paths(&path_var) {
let program = directory.join(name);
if !is_executable_file(&program) {
continue;
}
if let Some(version) = probe_version(&program) {
return Some(KernelInfo {
language: canonical.to_string(),
program,
version,
});
}
}
}
None
}
/// One-shot isolated execution of foreign code.
///
/// The source is run in a fresh child process. `request.input` is delivered as
/// the versioned JSON envelope on stdin, stdout/stderr are captured, and the
/// following are enforced: `request.timeout` (wall clock) and
/// `request.max_output_bytes` (stdout + stderr combined).
///
/// A non-zero exit is reported as [`RunStatus::Failed`] with `stderr`
/// preserved, not as an `Err`. Timeouts are reported as
/// [`RunStatus::TimedOut`]. Infrastructure failures (unavailable kernel, spawn
/// failure, exceeding the output budget) are [`ForeignError`]s.
pub fn run(request: &RunRequest) -> Result<RunResult, ForeignError> {
let raw = execute(request)?;
Ok(RunResult {
status: raw.status,
stdout: String::from_utf8_lossy(&raw.stdout).into_owned(),
stderr: String::from_utf8_lossy(&raw.stderr).into_owned(),
exit_code: raw.exit_code,
duration: raw.duration,
value: None,
})
}
/// Typed one-shot call, like [`run`] but with a strict stdout wire protocol.
///
/// On success, stdout must be exactly one versioned wire value object (no
/// log lines, no trailing noise); it is decoded with
/// [`marqdo_value::from_wire`] and stored in [`RunResult::value`]. Any
/// protocol violation is [`ForeignError::Protocol`]. A non-zero exit still
/// returns `Ok` with [`RunStatus::Failed`] and `stderr` preserved so the host
/// can report the kernel's own failure faithfully; a timeout returns
/// [`ForeignError::Timeout`] because no typed value can exist.
pub fn call(request: &RunRequest) -> Result<RunResult, ForeignError> {
let raw = execute(request)?;
match raw.status {
RunStatus::TimedOut => Err(ForeignError::Timeout {
seconds: request.timeout.as_secs_f64(),
}),
RunStatus::Failed => Ok(RunResult {
status: raw.status,
stdout: String::from_utf8_lossy(&raw.stdout).into_owned(),
stderr: String::from_utf8_lossy(&raw.stderr).into_owned(),
exit_code: raw.exit_code,
duration: raw.duration,
value: None,
}),
RunStatus::Success => {
let text =
std::str::from_utf8(&raw.stdout).map_err(|error| ForeignError::Protocol {
message: format!("stdout is not valid UTF-8: {error}"),
})?;
let wire: Json =
serde_json::from_str(text).map_err(|error| ForeignError::Protocol {
message: format!(
"stdout must be exactly one JSON wire value without extra output: {error}"
),
})?;
let value = marqdo_value::from_wire(&wire).map_err(|error| ForeignError::Protocol {
message: format!("stdout is not a valid marqdo wire value: {error}"),
})?;
Ok(RunResult {
status: RunStatus::Success,
stdout: text.to_string(),
stderr: String::from_utf8_lossy(&raw.stderr).into_owned(),
exit_code: raw.exit_code,
duration: raw.duration,
value: Some(value),
})
}
}
}
/// Owned bytes-level result shared by [`run`] and [`call`].
struct RawRun {
status: RunStatus,
stdout: Vec<u8>,
stderr: Vec<u8>,
exit_code: Option<i32>,
duration: Duration,
}
fn execute(request: &RunRequest) -> Result<RawRun, ForeignError> {
let canonical =
normalize_language(&request.language).ok_or_else(|| ForeignError::KernelUnavailable {
language: request.language.clone(),
hint: format!(
"supported languages are `python` (aliases: python3, py) and \
`javascript` (aliases: js, node); `{}` is not a foreign kernel",
request.language
),
})?;
let program = find_program(canonical).ok_or_else(|| ForeignError::KernelUnavailable {
language: canonical.to_string(),
hint: kernel_hint(canonical).to_string(),
})?;
let artifacts = TempArtifacts::create(canonical)?;
artifacts.write_program(&request.source)?;
let payload = request_envelope(request)?;
let mut command = Command::new(&program);
command
.arg(&artifacts.program_path)
.current_dir(&artifacts.work_dir)
.env_clear();
if let Some(path) = std::env::var_os("PATH") {
command.env("PATH", path);
}
let captured = spawn_and_capture(
&mut command,
request.timeout,
request.max_output_bytes,
Some(payload),
)?;
let (status, exit_code) = match captured.outcome {
WaitOutcome::Exited(exit) => {
let status = if exit.success() {
RunStatus::Success
} else {
RunStatus::Failed
};
(status, exit.code())
}
WaitOutcome::TimedOut => (RunStatus::TimedOut, None),
};
Ok(RawRun {
status,
stdout: captured.stdout,
stderr: captured.stderr,
exit_code,
duration: captured.duration,
})
}
fn program_candidates(language: &str) -> &'static [&'static str] {
match language {
"python" => &["python3", "python"],
_ => &["node"],
}
}
fn kernel_hint(language: &str) -> &'static str {
match language {
"python" => {
"install Python 3 (for example `uv python install` or your system package manager) \
and make sure `python3` or `python` is on PATH"
}
_ => "install Node.js and make sure `node` is on PATH",
}
}
fn is_executable_file(path: &Path) -> bool {
match fs::metadata(path) {
Ok(metadata) if metadata.is_file() => {
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
metadata.permissions().mode() & 0o111 != 0
}
#[cfg(not(unix))]
{
true
}
}
_ => false,
}
}
fn find_program(language: &str) -> Option<PathBuf> {
let path_var = std::env::var_os("PATH")?;
for name in program_candidates(language) {
for directory in std::env::split_paths(&path_var) {
let candidate = directory.join(name);
if is_executable_file(&candidate) {
return Some(candidate);
}
}
}
None
}
fn probe_version(program: &Path) -> Option<String> {
let mut command = Command::new(program);
command.arg("--version").env_clear();
if let Some(path) = std::env::var_os("PATH") {
command.env("PATH", path);
}
let captured =
spawn_and_capture(&mut command, DETECT_TIMEOUT, DETECT_OUTPUT_LIMIT, None).ok()?;
let WaitOutcome::Exited(exit) = captured.outcome else {
return None;
};
if !exit.success() {
return None;
}
let stdout = String::from_utf8_lossy(&captured.stdout);
let first = stdout.lines().next().unwrap_or("").trim();
if !first.is_empty() {
return Some(first.to_string());
}
let stderr = String::from_utf8_lossy(&captured.stderr);
let first = stderr.lines().next().unwrap_or("").trim();
if first.is_empty() {
None
} else {
Some(first.to_string())
}
}
fn request_envelope(request: &RunRequest) -> Result<Vec<u8>, ForeignError> {
let envelope = serde_json::json!({
"wire_version": marqdo_value::WIRE_VERSION,
"kind": REQUEST_KIND,
"input": request.input.clone().unwrap_or_default(),
});
serde_json::to_vec(&envelope).map_err(|error| ForeignError::Io {
message: format!("cannot encode the foreign request envelope: {error}"),
})
}
/// Private temporary program file plus a fresh private working directory.
struct TempArtifacts {
program_path: PathBuf,
work_dir: PathBuf,
}
impl TempArtifacts {
fn create(language: &str) -> Result<Self, ForeignError> {
let base = fs::canonicalize(std::env::temp_dir()).unwrap_or_else(|_| std::env::temp_dir());
let extension = if language == "python" { "py" } else { "js" };
let mut last_error: Option<io::Error> = None;
for _ in 0..16 {
let token = unique_token();
let work_dir = base.join(format!("marqdo-foreign-work-{token}"));
match create_private_dir(&work_dir) {
Ok(()) => {
let program_path =
base.join(format!("marqdo-foreign-program-{token}.{extension}"));
return Ok(Self {
program_path,
work_dir,
});
}
Err(error) if error.kind() == io::ErrorKind::AlreadyExists => {
last_error = Some(error);
}
Err(error) => {
return Err(ForeignError::Io {
message: format!(
"cannot create the foreign working directory `{}`: {error}",
work_dir.display()
),
});
}
}
}
Err(ForeignError::Io {
message: format!(
"cannot allocate a unique foreign temporary directory: {}",
last_error
.map(|error| error.to_string())
.unwrap_or_else(|| "name collision".to_string())
),
})
}
fn write_program(&self, source: &str) -> Result<(), ForeignError> {
write_private_file(&self.program_path, source.as_bytes()).map_err(|error| {
ForeignError::Io {
message: format!(
"cannot write the foreign program `{}`: {error}",
self.program_path.display()
),
}
})
}
}
impl Drop for TempArtifacts {
fn drop(&mut self) {
let _ = fs::remove_file(&self.program_path);
let _ = fs::remove_dir_all(&self.work_dir);
}
}
fn create_private_dir(path: &Path) -> io::Result<()> {
let mut builder = fs::DirBuilder::new();
#[cfg(unix)]
{
use std::os::unix::fs::DirBuilderExt;
builder.mode(0o700);
}
builder.create(path)
}
fn write_private_file(path: &Path, bytes: &[u8]) -> io::Result<()> {
let mut options = fs::OpenOptions::new();
options.write(true).create_new(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
options.mode(0o600);
}
let mut file = options.open(path)?;
file.write_all(bytes)?;
file.flush()
}
fn unique_token() -> String {
let counter = UNIQUE_COUNTER.fetch_add(1, Ordering::Relaxed);
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|elapsed| elapsed.as_nanos())
.unwrap_or(0);
format!("{}-{nanos}-{counter}", std::process::id())
}
/// How the supervised child ended.
enum WaitOutcome {
/// The child was reaped normally (exit code or signal).
Exited(ExitStatus),
/// The deadline expired and the child was killed.
TimedOut,
}
struct Captured {
outcome: WaitOutcome,
stdout: Vec<u8>,
stderr: Vec<u8>,
duration: Duration,
}
struct ReaderState {
data: Arc<Mutex<Vec<u8>>>,
done: Arc<AtomicBool>,
handle: Option<thread::JoinHandle<()>>,
}
fn spawn_reader<R: Read + Send + 'static>(
mut stream: R,
total: Arc<AtomicUsize>,
overflow: Arc<AtomicBool>,
limit: usize,
) -> Result<ReaderState, ForeignError> {
let data = Arc::new(Mutex::new(Vec::new()));
let done = Arc::new(AtomicBool::new(false));
let thread_data = Arc::clone(&data);
let thread_done = Arc::clone(&done);
let handle = thread::Builder::new()
.name("marqdo-foreign-output-reader".to_string())
.spawn(move || {
let mut buffer = [0_u8; 8192];
loop {
match stream.read(&mut buffer) {
Ok(0) => break,
Ok(read) => {
let previous = total.fetch_add(read, Ordering::AcqRel);
let allowed = limit.saturating_sub(previous).min(read);
if allowed > 0 {
if let Ok(mut guard) = thread_data.lock() {
guard.extend_from_slice(&buffer[..allowed]);
}
}
if allowed < read {
overflow.store(true, Ordering::Release);
break;
}
}
Err(ref error) if error.kind() == io::ErrorKind::Interrupted => continue,
Err(_) => break,
}
}
thread_done.store(true, Ordering::Release);
})
.map_err(|error| ForeignError::Io {
message: format!("cannot start the foreign output reader: {error}"),
})?;
Ok(ReaderState {
data,
done,
handle: Some(handle),
})
}
/// Spawn `command`, write the optional stdin payload, capture both output
/// streams within `max_output_bytes`, and supervise the child until it exits or
/// the deadline expires.
fn spawn_and_capture(
command: &mut Command,
timeout: Duration,
max_output_bytes: usize,
stdin_payload: Option<Vec<u8>>,
) -> Result<Captured, ForeignError> {
command
.stdin(if stdin_payload.is_some() {
Stdio::piped()
} else {
Stdio::null()
})
.stdout(Stdio::piped())
.stderr(Stdio::piped());
let start = Instant::now();
let mut child = command.spawn().map_err(|error| ForeignError::Spawn {
message: error.to_string(),
})?;
let (Some(stdout), Some(stderr)) = (child.stdout.take(), child.stderr.take()) else {
kill_and_reap(&mut child);
return Err(ForeignError::Io {
message: "the child stdio pipes could not be captured".to_string(),
});
};
if let Some(payload) = stdin_payload {
let Some(mut stdin) = child.stdin.take() else {
kill_and_reap(&mut child);
return Err(ForeignError::Io {
message: "the child stdin pipe could not be captured".to_string(),
});
};
// Writing must not block the supervisor, so it happens on its own
// thread; closing the handle at the end signals EOF to the kernel.
let writer = thread::Builder::new()
.name("marqdo-foreign-stdin-writer".to_string())
.spawn(move || {
let _ = stdin.write_all(&payload);
let _ = stdin.flush();
});
if let Err(error) = writer {
kill_and_reap(&mut child);
return Err(ForeignError::Io {
message: format!("cannot start the foreign stdin writer: {error}"),
});
}
}
let total = Arc::new(AtomicUsize::new(0));
let overflow = Arc::new(AtomicBool::new(false));
let stdout_reader = match spawn_reader(
stdout,
Arc::clone(&total),
Arc::clone(&overflow),
max_output_bytes,
) {
Ok(reader) => reader,
Err(error) => {
kill_and_reap(&mut child);
return Err(error);
}
};
let stderr_reader = match spawn_reader(
stderr,
Arc::clone(&total),
Arc::clone(&overflow),
max_output_bytes,
) {
Ok(reader) => reader,
Err(error) => {
kill_and_reap(&mut child);
drop(stdout_reader);
return Err(error);
}
};
let deadline = start.checked_add(timeout);
let mut timed_out = false;
let mut exit_status: Option<ExitStatus> = None;
loop {
if overflow.load(Ordering::Acquire) {
kill_and_reap(&mut child);
break;
}
match child.try_wait() {
Ok(Some(status)) => {
exit_status = Some(status);
break;
}
Ok(None) => {}
Err(error) => {
kill_and_reap(&mut child);
return Err(ForeignError::Io {
message: format!("waiting for the foreign kernel failed: {error}"),
});
}
}
if let Some(deadline) = deadline {
if Instant::now() >= deadline {
kill_and_reap(&mut child);
timed_out = true;
break;
}
}
thread::sleep(POLL_INTERVAL);
}
let stdout = collect_reader(stdout_reader);
let stderr = collect_reader(stderr_reader);
let duration = start.elapsed();
if overflow.load(Ordering::Acquire) {
return Err(ForeignError::OutputTooLarge {
limit: max_output_bytes,
});
}
let outcome = if timed_out {
WaitOutcome::TimedOut
} else if let Some(status) = exit_status {
WaitOutcome::Exited(status)
} else {
// Unreachable: the loop only exits with one of the two states above.
return Err(ForeignError::Io {
message: "the foreign kernel ended in an unknown state".to_string(),
});
};
Ok(Captured {
outcome,
stdout,
stderr,
duration,
})
}
fn collect_reader(state: ReaderState) -> Vec<u8> {
let ReaderState { data, done, handle } = state;
let deadline = Instant::now().checked_add(READER_GRACE);
while !done.load(Ordering::Acquire) {
match deadline {
Some(deadline) if Instant::now() >= deadline => break,
_ => thread::sleep(Duration::from_millis(1)),
}
}
let bytes = data.lock().map(|guard| guard.clone()).unwrap_or_default();
if done.load(Ordering::Acquire) {
if let Some(handle) = handle {
let _ = handle.join();
}
}
bytes
}
fn kill_and_reap(child: &mut Child) {
let _ = child.kill();
let _ = child.wait();
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn languages_are_normalized() {
assert_eq!(normalize_language("python"), Some("python"));
assert_eq!(normalize_language(" Python3 "), Some("python"));
assert_eq!(normalize_language("py"), Some("python"));
assert_eq!(normalize_language("javascript"), Some("javascript"));
assert_eq!(normalize_language("JS"), Some("javascript"));
assert_eq!(normalize_language("node"), Some("javascript"));
assert_eq!(normalize_language("cobol"), None);
assert_eq!(normalize_language(""), None);
}
#[test]
fn request_envelope_is_versioned() {
let mut request = RunRequest::new("python", "print(1)");
request.input = Some(serde_json::json!({"r": 2}));
let payload = request_envelope(&request).expect("encode");
let decoded: Json = serde_json::from_slice(&payload).expect("decode");
assert_eq!(decoded["wire_version"], marqdo_value::WIRE_VERSION);
assert_eq!(decoded["kind"], REQUEST_KIND);
assert_eq!(decoded["input"]["r"], 2);
let request = RunRequest::new("python", "");
let payload = request_envelope(&request).expect("encode");
let decoded: Json = serde_json::from_slice(&payload).expect("decode");
assert!(decoded["input"].is_null());
}
}
+374
View File
@@ -0,0 +1,374 @@
//! Integration tests against the real interpreters installed in the
//! environment (`python3` and `node`).
//!
//! The tests exercise the public contract the host layer relies on: explicit
//! execution only, the versioned stdin envelope, strict `call` protocol,
//! failure preservation, timeout killing, output limits and detection.
use std::time::Duration;
use marqdo_foreign::{
call, detect, normalize_language, run, ForeignError, KernelInfo, RunRequest, RunStatus,
};
use marqdo_value::Value;
use serde_json::json;
fn request(language: &str, source: &str) -> RunRequest {
RunRequest {
language: language.to_string(),
source: source.to_string(),
input: None,
timeout: Duration::from_secs(30),
max_output_bytes: 1024 * 1024,
}
}
fn python(source: &str) -> RunRequest {
request("python", source)
}
fn node(source: &str) -> RunRequest {
request("javascript", source)
}
fn kernel(language: &str) -> KernelInfo {
detect(language).unwrap_or_else(|| panic!("`{language}` kernel must be installed for tests"))
}
#[test]
fn detect_finds_python_and_node_versions() {
let python = kernel("python");
assert_eq!(python.language, "python");
assert!(python.program.is_file());
assert!(
python.version.to_ascii_lowercase().contains("python"),
"unexpected python version string: {:?}",
python.version
);
let alias = kernel("py");
assert_eq!(alias.language, "python");
assert!(alias.version.contains("Python"));
let javascript = kernel("javascript");
assert_eq!(javascript.language, "javascript");
assert!(javascript.program.is_file());
assert!(
javascript.version.starts_with('v') || !javascript.version.is_empty(),
"unexpected node version string: {:?}",
javascript.version
);
assert!(detect("node").is_some());
assert!(detect("cobol").is_none());
assert_eq!(normalize_language("js"), Some("javascript"));
}
#[test]
fn run_success_captures_stdout() {
let result = run(&python("print('hello from python')")).expect("run");
assert_eq!(result.status, RunStatus::Success);
assert_eq!(result.exit_code, Some(0));
assert_eq!(result.stdout.trim(), "hello from python");
assert!(result.stderr.is_empty());
assert!(result.value.is_none());
assert!(result.duration < Duration::from_secs(20));
}
#[test]
fn stdin_envelope_carries_the_input() {
let source = r#"import json, sys
req = json.load(sys.stdin)
assert req["wire_version"] == 1, req
assert req["kind"] == "request", req
print(json.dumps({"echo": req["input"]["message"]}))
"#;
let mut req = python(source);
req.input = Some(json!({"message": "ping"}));
let result = run(&req).expect("run");
assert_eq!(
result.status,
RunStatus::Success,
"stderr: {}",
result.stderr
);
let decoded: serde_json::Value = serde_json::from_str(&result.stdout).expect("json output");
assert_eq!(decoded["echo"], "ping");
}
#[test]
fn stdin_envelope_sends_null_for_missing_input() {
let source = r#"import json, sys
req = json.load(sys.stdin)
print(json.dumps({"is_null": req["input"] is None}))
"#;
let result = run(&python(source)).expect("run");
assert_eq!(
result.status,
RunStatus::Success,
"stderr: {}",
result.stderr
);
let decoded: serde_json::Value = serde_json::from_str(&result.stdout).expect("json output");
assert_eq!(decoded["is_null"], true);
}
#[test]
fn call_decodes_a_python_wire_value() {
let source = r#"import json, sys
json.load(sys.stdin)
print(json.dumps({"type": "int", "decimal": "42"}))
"#;
let result = call(&python(source)).expect("call");
assert_eq!(result.status, RunStatus::Success);
assert_eq!(result.exit_code, Some(0));
assert_eq!(result.value, Some(Value::int(42)));
}
#[test]
fn call_decodes_a_node_wire_value() {
let source = r#"import { readFileSync } from "node:fs";
const request = JSON.parse(readFileSync(0, "utf8"));
process.stdout.write(JSON.stringify({ type: "text", value: request.input.message }));
"#;
let mut req = node(source);
req.input = Some(json!({"message": "from node"}));
let result = call(&req).expect("call");
assert_eq!(result.status, RunStatus::Success);
assert_eq!(result.value, Some(Value::text("from node")));
}
#[test]
fn node_run_success_captures_stdout() {
let source = r#"import { readFileSync } from "node:fs";
const request = JSON.parse(readFileSync(0, "utf8"));
console.log(`hello ${request.input.name}`);
"#;
let mut req = node(source);
req.input = Some(json!({"name": "node"}));
let result = run(&req).expect("run");
assert_eq!(
result.status,
RunStatus::Success,
"stderr: {}",
result.stderr
);
assert_eq!(result.stdout.trim(), "hello node");
}
#[test]
fn node_commonjs_syntax_is_supported() {
let source = r#"const fs = require("node:fs");
const request = JSON.parse(fs.readFileSync(0, "utf8"));
console.log(`cjs ${request.input.value}`);
"#;
let mut req = node(source);
req.input = Some(json!({"value": "ok"}));
let result = run(&req).expect("run");
assert_eq!(
result.status,
RunStatus::Success,
"stderr: {}",
result.stderr
);
assert_eq!(result.stdout.trim(), "cjs ok");
}
#[test]
fn non_zero_exit_is_failed_and_keeps_stderr() {
let source = r#"import sys
print("about to fail", file=sys.stderr)
sys.exit(3)
"#;
let result = run(&python(source)).expect("run");
assert_eq!(result.status, RunStatus::Failed);
assert_eq!(result.exit_code, Some(3));
assert!(
result.stderr.contains("about to fail"),
"stderr was: {:?}",
result.stderr
);
assert!(result.stdout.is_empty());
}
#[test]
fn non_zero_exit_is_preserved_by_call() {
let source = r#"import sys
print("call failed", file=sys.stderr)
sys.exit(7)
"#;
let result = call(&python(source)).expect("call");
assert_eq!(result.status, RunStatus::Failed);
assert_eq!(result.exit_code, Some(7));
assert!(result.stderr.contains("call failed"));
assert!(result.value.is_none());
}
#[test]
fn timeout_kills_the_kernel() {
let mut req = python("import time\ntime.sleep(10)\n");
req.timeout = Duration::from_millis(200);
let result = run(&req).expect("run");
assert_eq!(result.status, RunStatus::TimedOut);
assert_eq!(result.exit_code, None);
assert!(
result.duration < Duration::from_secs(5),
"timeout took {:?}",
result.duration
);
}
#[test]
fn call_reports_timeout_as_an_error() {
let mut req = python("import time\ntime.sleep(10)\n");
req.timeout = Duration::from_millis(200);
match call(&req) {
Err(ForeignError::Timeout { seconds }) => assert!((seconds - 0.2).abs() < 1e-6),
other => panic!("expected Timeout, got {other:?}"),
}
}
#[test]
fn call_rejects_stdout_noise() {
let source = r#"print("debug log line")
print('{"type": "int", "decimal": "42"}')
"#;
match call(&python(source)) {
Err(ForeignError::Protocol { .. }) => {}
other => panic!("expected Protocol error, got {other:?}"),
}
}
#[test]
fn call_rejects_non_json_stdout() {
match call(&python("print('not a wire value')")) {
Err(ForeignError::Protocol { .. }) => {}
other => panic!("expected Protocol error, got {other:?}"),
}
}
#[test]
fn call_rejects_unknown_wire_types() {
let source = r#"print('{"type": "mystery"}')"#;
match call(&python(source)) {
Err(ForeignError::Protocol { .. }) => {}
other => panic!("expected Protocol error, got {other:?}"),
}
}
#[test]
fn oversized_output_is_an_error() {
let source = "print('x' * 200000)";
let mut req = python(source);
req.max_output_bytes = 1024;
match run(&req) {
Err(ForeignError::OutputTooLarge { limit }) => assert_eq!(limit, 1024),
other => panic!("expected OutputTooLarge, got {other:?}"),
}
}
#[test]
fn oversized_stderr_is_an_error() {
let source = r#"import sys
sys.stderr.write("y" * 200000)
"#;
let mut req = python(source);
req.max_output_bytes = 512;
match run(&req) {
Err(ForeignError::OutputTooLarge { limit }) => assert_eq!(limit, 512),
other => panic!("expected OutputTooLarge, got {other:?}"),
}
}
#[test]
#[cfg(unix)]
fn child_environment_only_keeps_path() {
let source = r#"import json, os
print(json.dumps(sorted(os.environ)))
"#;
let result = run(&python(source)).expect("run");
assert_eq!(
result.status,
RunStatus::Success,
"stderr: {}",
result.stderr
);
let keys: Vec<String> = serde_json::from_str(&result.stdout).expect("json output");
assert!(
keys.iter().any(|key| key == "PATH"),
"PATH must be preserved for the kernel: {keys:?}"
);
assert!(
!keys.iter().any(|key| key == "HOME"),
"the child must not inherit the parent environment: {keys:?}"
);
}
#[test]
fn relative_writes_happen_in_a_fresh_cleaned_directory() {
let source = r#"import os
with open("marqdo-foreign-relative-test.txt", "w", encoding="utf-8") as handle:
handle.write("x")
print(os.getcwd())
"#;
let result = run(&python(source)).expect("run");
assert_eq!(
result.status,
RunStatus::Success,
"stderr: {}",
result.stderr
);
let working_directory = result.stdout.trim();
assert!(!working_directory.is_empty());
assert!(
!working_directory.starts_with(env!("CARGO_MANIFEST_DIR")),
"foreign cwd must not be the project: {working_directory}"
);
assert!(
!std::path::Path::new(working_directory).exists(),
"the temporary working directory must be removed: {working_directory}"
);
assert!(
!std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("marqdo-foreign-relative-test.txt")
.exists(),
"relative writes must not touch the project"
);
}
#[test]
fn kernel_that_ignores_stdin_does_not_hang() {
let mut req = python("print('done')");
req.input = Some(json!({"blob": "x".repeat(4 * 1024 * 1024)}));
let result = run(&req).expect("run");
assert_eq!(
result.status,
RunStatus::Success,
"stderr: {}",
result.stderr
);
assert_eq!(result.stdout.trim(), "done");
}
#[test]
fn unknown_language_is_unavailable() {
match run(&request("cobol", "DISPLAY 'HI'.")) {
Err(ForeignError::KernelUnavailable { language, hint }) => {
assert_eq!(language, "cobol");
assert!(!hint.is_empty());
}
other => panic!("expected KernelUnavailable, got {other:?}"),
}
}
#[test]
fn error_messages_are_human_readable() {
let error = ForeignError::OutputTooLarge { limit: 4096 };
assert!(error.to_string().contains("4096"));
let error = ForeignError::KernelUnavailable {
language: "python".to_string(),
hint: "install it".to_string(),
};
assert!(error.to_string().contains("python"));
assert!(error.to_string().contains("install it"));
}
-2
View File
@@ -9,11 +9,9 @@ repository.workspace = true
authors.workspace = true
[dependencies]
marqdo-span = { workspace = true }
marqdo-value = { workspace = true }
num-bigint = { workspace = true }
num-rational = { workspace = true }
num-traits = { workspace = true }
serde = { workspace = true }
thiserror = { workspace = true }
+394
View File
@@ -0,0 +1,394 @@
//! 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);
}
}
+146
View File
@@ -0,0 +1,146 @@
//! Structured errors returned by the native math kernel.
//!
//! The kernel never panics on untrusted LaTeX. Every failure is reported as a
//! [`MathError`] with a stable [`MathErrorKind`], a human readable message and
//! (for parse failures) the byte offset into the original LaTeX source. The
//! host layer is expected to map [`MathErrorKind::Unsupported`] to the
//! `math.unsupported` diagnostic code and the remaining kinds to the matching
//! expression diagnostics.
use serde::{Deserialize, Serialize};
use std::fmt;
/// Broad category of a math kernel failure.
///
/// The enum is deliberately small: the kernel only distinguishes "the input is
/// not in the supported grammar", "the input is in the grammar but outside the
/// supported subset", "a name is unbound" and "a value has the wrong type".
/// Resource-bound violations (exponent/result size) are reported as
/// [`MathErrorKind::Unsupported`] because they are a documented limitation of
/// the subset rather than a parse or type problem.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MathErrorKind {
/// The input is malformed LaTeX for the supported subset.
Parse,
/// The input is well-formed but outside the deliberately limited subset, or
/// the requested operation/equation shape is not supported.
Unsupported,
/// A variable used by the formula has no binding.
UndefinedVariable,
/// A binding or operand has an incompatible type, or an operation is
/// undefined for the supplied values (for example division by zero).
Type,
}
impl MathErrorKind {
/// Stable lowercase label used by diagnostics and tests.
pub const fn as_str(self) -> &'static str {
match self {
MathErrorKind::Parse => "parse",
MathErrorKind::Unsupported => "unsupported",
MathErrorKind::UndefinedVariable => "undefined-variable",
MathErrorKind::Type => "type",
}
}
}
impl fmt::Display for MathErrorKind {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
/// A structured error produced by [`crate::parse`], [`crate::evaluate`] or
/// [`crate::substitute`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MathError {
/// Failure category.
pub kind: MathErrorKind,
/// Human readable explanation. Messages are diagnostic text; callers should
/// branch on [`MathError::kind`] rather than on the wording.
pub message: String,
/// Byte offset into the original LaTeX source, when the failure is tied to
/// a specific token.
pub position: Option<usize>,
}
impl MathError {
/// Construct an error with an explicit kind and optional byte position.
pub fn new(kind: MathErrorKind, message: impl Into<String>, position: Option<usize>) -> Self {
Self {
kind,
message: message.into(),
position,
}
}
/// Construct a [`MathErrorKind::Parse`] error.
pub fn parse(message: impl Into<String>, position: Option<usize>) -> Self {
Self::new(MathErrorKind::Parse, message, position)
}
/// Construct a [`MathErrorKind::Unsupported`] error.
pub fn unsupported(message: impl Into<String>, position: Option<usize>) -> Self {
Self::new(MathErrorKind::Unsupported, message, position)
}
/// Construct a [`MathErrorKind::UndefinedVariable`] error.
pub fn undefined_variable(message: impl Into<String>, position: Option<usize>) -> Self {
Self::new(MathErrorKind::UndefinedVariable, message, position)
}
/// Construct a [`MathErrorKind::Type`] error.
pub fn type_error(message: impl Into<String>, position: Option<usize>) -> Self {
Self::new(MathErrorKind::Type, message, position)
}
/// The documented result-size guard was hit. Reported as `Unsupported` so
/// callers can surface a stable `math.unsupported` diagnostic instead of a
/// crash or an out-of-memory abort.
pub fn size_bound(message: impl Into<String>) -> Self {
Self::unsupported(message, None)
}
}
impl fmt::Display for MathError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.kind)?;
if let Some(position) = self.position {
write!(f, " at byte {position}")?;
}
write!(f, ": {}", self.message)
}
}
impl std::error::Error for MathError {}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn display_includes_kind_and_position() {
let err = MathError::parse("expected an expression", Some(3));
assert_eq!(err.to_string(), "parse at byte 3: expected an expression");
assert_eq!(err.kind.as_str(), "parse");
}
#[test]
fn constructors_use_stable_kinds() {
assert_eq!(
MathError::unsupported("x", None).kind,
MathErrorKind::Unsupported
);
assert_eq!(
MathError::undefined_variable("x", None).kind,
MathErrorKind::UndefinedVariable
);
assert_eq!(MathError::type_error("x", None).kind, MathErrorKind::Type);
assert_eq!(MathError::size_bound("x").kind, MathErrorKind::Unsupported);
assert_eq!(
MathErrorKind::UndefinedVariable.to_string(),
"undefined-variable"
);
}
}
+695
View File
@@ -0,0 +1,695 @@
//! Exact evaluation, equation solving and substitution.
//!
//! Numeric semantics are documented on the crate root. In short: literals,
//! integer/float bindings and the operators `+ - * / ^` are evaluated as exact
//! rationals; `\pi`, `\e` and non-perfect square roots introduce an `f64`
//! approximation. The final value is [`Value::Int`] exactly when the exact
//! result is an integer and [`Value::Float`] otherwise.
use std::collections::BTreeMap;
use num_bigint::{BigInt, Sign};
use num_rational::Ratio;
use num_traits::{One, Signed, ToPrimitive, Zero};
use marqdo_value::Value;
use crate::ast::{Expr, Formula, FormulaKind, Rational};
use crate::error::MathError;
/// Maximum magnitude of an integer exponent accepted by `^`.
pub const MAX_EXPONENT: u64 = 10_000;
/// Maximum number of bits (binary digits) allowed for the numerator and for the
/// denominator of an exact intermediate or result. This bounds memory and CPU
/// for hostile formulas such as `(2^10000)^10000`.
pub const MAX_RESULT_BITS: u64 = 1_000_000;
/// A number during evaluation: either exact or an explicit `f64`
/// approximation produced by an irrational operation.
#[derive(Debug, Clone)]
enum Numeric {
Exact(Rational),
Approx(f64),
}
impl Numeric {
fn exact_zero() -> Self {
Numeric::Exact(Ratio::from_integer(BigInt::zero()))
}
fn exact_one() -> Self {
Numeric::Exact(Ratio::from_integer(BigInt::one()))
}
fn is_zero(&self) -> bool {
match self {
Numeric::Exact(value) => value.is_zero(),
Numeric::Approx(value) => *value == 0.0,
}
}
fn neg(self) -> Result<Self, MathError> {
match self {
Numeric::Exact(value) => Ok(Numeric::Exact(-value)),
Numeric::Approx(value) => Ok(Numeric::Approx(-value)),
}
}
fn to_approx(&self) -> Result<f64, MathError> {
match self {
Numeric::Approx(value) => Ok(*value),
Numeric::Exact(value) => ratio_to_f64(value).ok_or_else(|| {
MathError::size_bound(
"an exact intermediate result is too large to represent as a Float",
)
}),
}
}
fn add(self, other: Numeric) -> Result<Self, MathError> {
match (self, other) {
(Numeric::Exact(left), Numeric::Exact(right)) => {
Ok(Numeric::Exact(checked_ratio(left + right)?))
}
(left, right) => Ok(Numeric::Approx(left.to_approx()? + right.to_approx()?)),
}
}
fn sub(self, other: Numeric) -> Result<Self, MathError> {
match (self, other) {
(Numeric::Exact(left), Numeric::Exact(right)) => {
Ok(Numeric::Exact(checked_ratio(left - right)?))
}
(left, right) => Ok(Numeric::Approx(left.to_approx()? - right.to_approx()?)),
}
}
fn mul(self, other: Numeric) -> Result<Self, MathError> {
match (self, other) {
(Numeric::Exact(left), Numeric::Exact(right)) => {
Ok(Numeric::Exact(exact_mul(&left, &right)?))
}
(left, right) => Ok(Numeric::Approx(left.to_approx()? * right.to_approx()?)),
}
}
fn div(self, other: Numeric) -> Result<Self, MathError> {
if other.is_zero() {
return Err(division_by_zero());
}
match (self, other) {
(Numeric::Exact(left), Numeric::Exact(right)) => {
Ok(Numeric::Exact(checked_ratio(left / right)?))
}
(left, right) => Ok(Numeric::Approx(left.to_approx()? / right.to_approx()?)),
}
}
fn sqrt(self) -> Result<Self, MathError> {
match self {
Numeric::Exact(value) => {
if value.is_negative() {
return Err(MathError::type_error(
"square root of a negative number is not supported by the real-valued subset",
None,
));
}
let numerator_root = integer_sqrt(value.numer());
let denominator_root = integer_sqrt(value.denom());
if &(&numerator_root * &numerator_root) == value.numer()
&& &(&denominator_root * &denominator_root) == value.denom()
{
Ok(Numeric::Exact(Ratio::new(numerator_root, denominator_root)))
} else {
let approximate = ratio_to_f64(&value).ok_or_else(|| {
MathError::size_bound(
"square root operands are outside the representable Float range",
)
})?;
Ok(Numeric::Approx(approximate.sqrt()))
}
}
Numeric::Approx(value) => {
if value < 0.0 {
return Err(MathError::type_error(
"square root of a negative number is not supported by the real-valued subset",
None,
));
}
Ok(Numeric::Approx(value.sqrt()))
}
}
}
fn pow(self, exponent: BigInt) -> Result<Self, MathError> {
let negative_exponent = exponent.sign() == Sign::Minus;
let magnitude = exponent.magnitude();
let bound = num_bigint::BigUint::from(MAX_EXPONENT);
if *magnitude > bound {
return Err(MathError::size_bound(format!(
"exponent magnitude exceeds the supported bound of {MAX_EXPONENT}"
)));
}
let exponent_u32 = magnitude
.to_u32()
.ok_or_else(|| MathError::size_bound("exponent is outside the supported bound"))?;
match self {
Numeric::Exact(base) => {
if exponent_u32 == 0 {
if base.is_zero() {
return Err(MathError::type_error(
"0 ^ 0 is undefined in the native math subset",
None,
));
}
return Ok(Numeric::Exact(Ratio::from_integer(BigInt::one())));
}
if base.is_zero() && negative_exponent {
return Err(division_by_zero());
}
let max_bits = base.numer().bits().max(base.denom().bits());
let estimated_bits = max_bits.saturating_mul(u64::from(exponent_u32));
if estimated_bits > MAX_RESULT_BITS {
return Err(MathError::size_bound(format!(
"exponentiation result would exceed the supported size bound of {MAX_RESULT_BITS} bits"
)));
}
let numerator = base.numer().pow(exponent_u32);
let denominator = base.denom().pow(exponent_u32);
let result = if negative_exponent {
Ratio::new(denominator, numerator)
} else {
Ratio::new(numerator, denominator)
};
Ok(Numeric::Exact(checked_ratio(result)?))
}
Numeric::Approx(base) => {
if base == 0.0 && negative_exponent {
return Err(division_by_zero());
}
let exponent = exponent_u32 as i32;
Ok(Numeric::Approx(base.powi(exponent)))
}
}
}
fn into_value(self) -> Result<Value, MathError> {
match self {
Numeric::Exact(value) => {
if value.is_integer() {
Ok(Value::Int(value.to_integer()))
} else {
Ok(Value::Float(ratio_to_f64(&value).ok_or_else(|| {
MathError::size_bound("exact result is too large to represent as a Float")
})?))
}
}
Numeric::Approx(value) => Ok(Value::Float(value)),
}
}
}
fn division_by_zero() -> MathError {
MathError::type_error(
"division by zero is not defined in the native math subset",
None,
)
}
fn checked_ratio(value: Rational) -> Result<Rational, MathError> {
if value.numer().bits() > MAX_RESULT_BITS || value.denom().bits() > MAX_RESULT_BITS {
return Err(MathError::size_bound(format!(
"intermediate result exceeds the supported size bound of {MAX_RESULT_BITS} bits"
)));
}
Ok(value)
}
/// Convert an exact rational to `f64` without going through `Ratio`'s
/// `ToPrimitive` impl (which is bound to a different `num-bigint` version in
/// `num-rational` 0.4). Returns `None` when the value is outside the finite
/// `f64` range or would lose everything to underflow.
fn ratio_to_f64(value: &Rational) -> Option<f64> {
if value.is_zero() {
return Some(0.0);
}
let negative = value.numer().sign() == Sign::Minus;
let (numerator_mantissa, numerator_exponent) = scaled_f64_mantissa(&value.numer().abs());
let (denominator_mantissa, denominator_exponent) = scaled_f64_mantissa(value.denom());
let exponent = numerator_exponent - denominator_exponent;
if exponent > 1023 {
return None;
}
if exponent < -1075 {
return Some(if negative { -0.0 } else { 0.0 });
}
let mut result = numerator_mantissa / denominator_mantissa;
result *= 2_f64.powi(exponent as i32);
if !result.is_finite() {
return None;
}
Some(if negative { -result } else { result })
}
/// Decompose a non-negative integer into `(mantissa, exponent)` such that the
/// value is approximately `mantissa * 2^exponent` and `mantissa` fits in `f64`.
fn scaled_f64_mantissa(value: &BigInt) -> (f64, i64) {
debug_assert!(!value.is_negative());
let bits = value.bits();
if bits == 0 {
return (0.0, 0);
}
// Keep the most significant 64 bits; the low bits only affect the last
// ~11 bits of the f64 mantissa, which is below the documented precision.
let shift = bits.saturating_sub(64);
let top = (value >> shift).to_u64().unwrap_or(u64::MAX);
(top as f64, shift as i64)
}
fn exact_mul(left: &Rational, right: &Rational) -> Result<Rational, MathError> {
// Pre-check before allocating so that multiplying two large operands cannot
// allocate an out-of-bound intermediate.
let numerator_bits = left.numer().bits().saturating_add(right.numer().bits());
let denominator_bits = left.denom().bits().saturating_add(right.denom().bits());
if numerator_bits > MAX_RESULT_BITS || denominator_bits > MAX_RESULT_BITS {
return Err(MathError::size_bound(format!(
"multiplication result would exceed the supported size bound of {MAX_RESULT_BITS} bits"
)));
}
checked_ratio(left * right)
}
/// Integer square root of a non-negative integer (Newton iteration).
fn integer_sqrt(value: &BigInt) -> BigInt {
debug_assert!(!value.is_negative());
if value.is_zero() {
return BigInt::zero();
}
let mut estimate = BigInt::one() << value.bits().div_ceil(2) as usize;
loop {
let next = (&estimate + value / &estimate) >> 1;
if next >= estimate {
return estimate;
}
estimate = next;
}
}
/// Convert a finite `f64` into the exact binary rational it represents.
fn float_to_ratio(value: f64) -> Option<Rational> {
if !value.is_finite() {
return None;
}
if value == 0.0 {
return Some(Ratio::from_integer(BigInt::zero()));
}
let bits = value.to_bits();
let negative = (bits >> 63) == 1;
let exponent_bits = ((bits >> 52) & 0x7ff) as i32;
let fraction = bits & ((1_u64 << 52) - 1);
let (mantissa, exponent) = if exponent_bits == 0 {
(fraction, -1074_i32)
} else {
(fraction | (1_u64 << 52), exponent_bits - 1075)
};
let mut numerator = BigInt::from(mantissa);
let mut denominator = BigInt::one();
if exponent >= 0 {
numerator <<= exponent as usize;
} else {
denominator <<= (-exponent) as usize;
}
if negative {
numerator = -numerator;
}
Some(Ratio::new(numerator, denominator))
}
/// Convert a [`Value`] binding into a kernel number.
fn binding_numeric(name: &str, bindings: &BTreeMap<String, Value>) -> Result<Numeric, MathError> {
match bindings.get(name) {
None => Err(MathError::undefined_variable(
format!("variable `{name}` is not bound"),
None,
)),
Some(Value::Int(value)) => Ok(Numeric::Exact(Ratio::from_integer(value.clone()))),
Some(Value::Float(value)) => float_to_ratio(*value).map(Numeric::Exact).ok_or_else(|| {
MathError::type_error(
format!(
"binding `{name}` is a non-finite Float; the math kernel only accepts finite numeric bindings"
),
None,
)
}),
Some(other) => Err(MathError::type_error(
format!(
"binding `{name}` has type {} but the math kernel requires Int or Float",
other.type_name()
),
None,
)),
}
}
fn eval_expr(expr: &Expr, bindings: &BTreeMap<String, Value>) -> Result<Numeric, MathError> {
match expr {
Expr::Number(value) => Ok(Numeric::Exact(value.clone())),
Expr::Variable(name) => binding_numeric(name, bindings),
Expr::Constant(constant) => Ok(Numeric::Approx(constant.value())),
Expr::Neg(inner) => eval_expr(inner, bindings)?.neg(),
Expr::Add(left, right) => eval_expr(left, bindings)?.add(eval_expr(right, bindings)?),
Expr::Sub(left, right) => eval_expr(left, bindings)?.sub(eval_expr(right, bindings)?),
Expr::Mul(left, right) => eval_expr(left, bindings)?.mul(eval_expr(right, bindings)?),
Expr::Div(left, right) => eval_expr(left, bindings)?.div(eval_expr(right, bindings)?),
Expr::Pow(base, exponent) => {
let base = eval_expr(base, bindings)?;
base.pow(integer_exponent(&eval_expr(exponent, bindings)?)?)
}
Expr::Sqrt(inner) => eval_expr(inner, bindings)?.sqrt(),
}
}
/// Require a numeric value to be an integer and return it.
fn integer_exponent(value: &Numeric) -> Result<BigInt, MathError> {
match value {
Numeric::Exact(value) if value.is_integer() => Ok(value.to_integer()),
_ => Err(MathError::type_error(
"exponent must be an integer in the native math subset",
None,
)),
}
}
/// A linear/affine form `coefficient * target + constant`.
struct Affine {
coefficient: Numeric,
constant: Numeric,
}
impl Affine {
fn constant(value: Numeric) -> Self {
Self {
coefficient: Numeric::exact_zero(),
constant: value,
}
}
fn target() -> Self {
Self {
coefficient: Numeric::exact_one(),
constant: Numeric::exact_zero(),
}
}
fn is_target_free(&self) -> bool {
self.coefficient.is_zero()
}
fn neg(self) -> Result<Self, MathError> {
Ok(Self {
coefficient: self.coefficient.neg()?,
constant: self.constant.neg()?,
})
}
fn add(self, other: Self) -> Result<Self, MathError> {
Ok(Self {
coefficient: self.coefficient.add(other.coefficient)?,
constant: self.constant.add(other.constant)?,
})
}
fn sub(self, other: Self) -> Result<Self, MathError> {
Ok(Self {
coefficient: self.coefficient.sub(other.coefficient)?,
constant: self.constant.sub(other.constant)?,
})
}
fn scale(self, factor: Numeric) -> Result<Self, MathError> {
let coefficient = self.coefficient.mul(factor.clone())?;
let constant = self.constant.mul(factor)?;
Ok(Self {
coefficient,
constant,
})
}
}
/// Build the affine form of `expr` with respect to `target`.
///
/// Variables other than `target` are resolved from `bindings`. Operations that
/// are not affine in `target` are rejected as unsupported instead of being
/// approximated or reported as a solution.
fn to_affine(
expr: &Expr,
target: &str,
bindings: &BTreeMap<String, Value>,
) -> Result<Affine, MathError> {
match expr {
Expr::Number(value) => Ok(Affine::constant(Numeric::Exact(value.clone()))),
Expr::Constant(constant) => Ok(Affine::constant(Numeric::Approx(constant.value()))),
Expr::Variable(name) if name == target => Ok(Affine::target()),
Expr::Variable(name) => Ok(Affine::constant(binding_numeric(name, bindings)?)),
Expr::Neg(inner) => to_affine(inner, target, bindings)?.neg(),
Expr::Add(left, right) => {
let left = to_affine(left, target, bindings)?;
let right = to_affine(right, target, bindings)?;
left.add(right)
}
Expr::Sub(left, right) => {
let left = to_affine(left, target, bindings)?;
let right = to_affine(right, target, bindings)?;
left.sub(right)
}
Expr::Mul(left, right) => {
let left = to_affine(left, target, bindings)?;
let right = to_affine(right, target, bindings)?;
match (left.is_target_free(), right.is_target_free()) {
(true, true) => Ok(Affine::constant(
left.constant.mul(right.constant)?,
)),
(true, false) => right.scale(left.constant),
(false, true) => left.scale(right.constant),
(false, false) => Err(MathError::unsupported(
format!(
"cannot solve for `{target}`: the equation is not linear in the target (it appears in both factors of a product)"
),
None,
)),
}
}
Expr::Div(left, right) => {
let left = to_affine(left, target, bindings)?;
let right = to_affine(right, target, bindings)?;
if !right.is_target_free() {
return Err(MathError::unsupported(
format!(
"cannot solve for `{target}`: the target appears in a denominator, which is outside the supported linear forms"
),
None,
));
}
if right.constant.is_zero() {
return Err(division_by_zero());
}
let inverse = Numeric::exact_one().div(right.constant)?;
left.scale(inverse)
}
Expr::Pow(base, exponent) => {
if exponent.occurrences(target) > 0 {
return Err(MathError::unsupported(
format!(
"cannot solve for `{target}`: the target appears in an exponent, which is not an affine form"
),
None,
));
}
let exponent_value = eval_expr(exponent, bindings)?;
let exponent = integer_exponent(&exponent_value)?;
let base = to_affine(base, target, bindings)?;
if base.is_target_free() {
let value = base.constant.pow(exponent)?;
return Ok(Affine::constant(value));
}
if exponent.is_zero() {
return Ok(Affine::constant(Numeric::exact_one()));
}
if exponent.is_one() {
return Ok(base);
}
Err(MathError::unsupported(
format!(
"cannot solve for `{target}`: the target appears in a power with exponent {exponent}, which is not an affine form"
),
None,
))
}
Expr::Sqrt(inner) => {
if inner.occurrences(target) > 0 {
return Err(MathError::unsupported(
format!(
"cannot solve for `{target}`: the target appears under a square root, which is not an affine form"
),
None,
));
}
Ok(Affine::constant(eval_expr(inner, bindings)?.sqrt()?))
}
}
}
/// Evaluate `formula` with `bindings`.
///
/// For an expression the result is the exact value (or a [`Value::Float`] when
/// the exact value is not integral or an irrational operation was involved).
/// For an equation `target` selects the variable to solve for; it must occur
/// exactly once and the equation must be linear in it.
pub fn evaluate(
formula: &Formula,
bindings: &BTreeMap<String, Value>,
target: Option<&str>,
) -> Result<Value, MathError> {
match (&formula.kind, target) {
(FormulaKind::Expression(expr), None) => eval_expr(expr, bindings)?.into_value(),
(FormulaKind::Expression(_), Some(_)) => Err(MathError::unsupported(
"a target variable is only meaningful for an equation; the formula is a plain expression",
None,
)),
(FormulaKind::Equation { .. }, None) => Err(MathError::unsupported(
"evaluating an equation requires a target variable to solve for",
None,
)),
(FormulaKind::Equation { left, right }, Some(target)) => {
solve_equation(left, right, target, bindings)
}
}
}
fn solve_equation(
left: &Expr,
right: &Expr,
target: &str,
bindings: &BTreeMap<String, Value>,
) -> Result<Value, MathError> {
if target.is_empty() {
return Err(MathError::unsupported(
"target variable name must not be empty",
None,
));
}
if target == "pi" || target == "e" {
return Err(MathError::unsupported(
format!("`{target}` is a reserved constant, not a solvable variable"),
None,
));
}
let occurrences = left.occurrences(target) + right.occurrences(target);
match occurrences {
0 => {
return Err(MathError::unsupported(
format!("cannot solve for `{target}`: the variable does not occur in the equation"),
None,
));
}
1 => {}
count => {
return Err(MathError::unsupported(
format!(
"cannot solve for `{target}`: the variable occurs {count} times, but only a single occurrence in an affine equation is supported"
),
None,
));
}
}
let left = to_affine(left, target, bindings)?;
let right = to_affine(right, target, bindings)?;
let coefficient = left.coefficient.sub(right.coefficient)?;
let constant = left.constant.sub(right.constant)?;
if coefficient.is_zero() {
return Err(MathError::unsupported(
format!(
"cannot solve for `{target}`: the equation does not uniquely determine the variable"
),
None,
));
}
constant.neg()?.div(coefficient)?.into_value()
}
/// Replace every bound variable in `formula` with its exact value.
///
/// Unbound variables stay symbolic. The returned formula gets a deterministic,
/// re-parseable [`Formula::source`] rendering; `Float` bindings are inserted as
/// the exact rational value of the `f64` (never as a rounded or lossy decimal).
pub fn substitute(
formula: &Formula,
bindings: &BTreeMap<String, Value>,
) -> Result<Formula, MathError> {
let kind = match &formula.kind {
FormulaKind::Expression(expr) => FormulaKind::Expression(substitute_expr(expr, bindings)?),
FormulaKind::Equation { left, right } => FormulaKind::Equation {
left: substitute_expr(left, bindings)?,
right: substitute_expr(right, bindings)?,
},
};
let substituted = Formula {
source: String::new(),
kind,
};
Ok(Formula {
source: substituted.render(),
kind: substituted.kind,
})
}
fn substitute_expr(expr: &Expr, bindings: &BTreeMap<String, Value>) -> Result<Expr, MathError> {
match expr {
Expr::Number(_) | Expr::Constant(_) => Ok(expr.clone()),
Expr::Variable(name) => match bindings.get(name) {
None => Ok(expr.clone()),
Some(Value::Int(value)) => Ok(Expr::Number(Ratio::from_integer(value.clone()))),
Some(Value::Float(value)) => match float_to_ratio(*value) {
Some(value) => Ok(Expr::Number(value)),
None => Err(MathError::type_error(
format!(
"binding `{name}` is a non-finite Float; the math kernel only accepts finite numeric bindings"
),
None,
)),
},
Some(other) => Err(MathError::type_error(
format!(
"binding `{name}` has type {} but the math kernel requires Int or Float",
other.type_name()
),
None,
)),
},
Expr::Neg(inner) => Ok(Expr::Neg(Box::new(substitute_expr(inner, bindings)?))),
Expr::Add(left, right) => Ok(Expr::Add(
Box::new(substitute_expr(left, bindings)?),
Box::new(substitute_expr(right, bindings)?),
)),
Expr::Sub(left, right) => Ok(Expr::Sub(
Box::new(substitute_expr(left, bindings)?),
Box::new(substitute_expr(right, bindings)?),
)),
Expr::Mul(left, right) => Ok(Expr::Mul(
Box::new(substitute_expr(left, bindings)?),
Box::new(substitute_expr(right, bindings)?),
)),
Expr::Div(left, right) => Ok(Expr::Div(
Box::new(substitute_expr(left, bindings)?),
Box::new(substitute_expr(right, bindings)?),
)),
Expr::Pow(base, exponent) => Ok(Expr::Pow(
Box::new(substitute_expr(base, bindings)?),
Box::new(substitute_expr(exponent, bindings)?),
)),
Expr::Sqrt(inner) => Ok(Expr::Sqrt(Box::new(substitute_expr(inner, bindings)?))),
}
}
+171
View File
@@ -0,0 +1,171 @@
//! Native Formula kernel for a deliberately limited, documented math subset.
//!
//! This crate is the native math kernel of the Marqdo toolchain. A Markdown math
//! node becomes an inert [`marqdo_value::FormulaValue`]; nothing is evaluated
//! implicitly. The host layer calls [`parse`], [`substitute`] and [`evaluate`]
//! explicitly, and evaluation is gated by the `math.*` capabilities.
//!
//! **The kernel never proves anything.** It computes exact or floating values
//! and solves a restricted affine equation. It does not establish a theorem,
//! does not simplify a formula into a proof obligation and must not be presented
//! as a formal verifier. See the blueprint section 5 ("原生 Math") and
//! `spec/evaluation.md`.
//!
//! # Guarantees
//!
//! * No panics on untrusted LaTeX. Malformed input, unsupported constructs,
//! unbounded work and wrong value types all become a structured [`MathError`].
//! * Exact rational arithmetic (`num-rational` `Ratio` over `num-bigint`) is used
//! wherever possible; integers are arbitrary precision.
//! * A formula is never silently simplified, guessed or partially accepted:
//! anything outside the grammar below is an error.
//!
//! # Supported grammar
//!
//! The parser accepts exactly the following LaTeX subset (whitespace is
//! insignificant; byte offsets are reported on parse errors):
//!
//! ```text
//! formula = expr [ "=" expr ] ; single '=' only, never assignment
//! expr = term { ("+" | "-") term } ;
//! term = unary { ("*" | "/" | "·" | "×" | implicit) unary } ;
//! unary = ("+" | "-") unary | power ;
//! power = primary [ "^" unary ] ; right associative
//! primary = number
//! | identifier Unicode letter (plus digits/underscore)
//! | "\pi" | "pi" | "\e" | "e" constants
//! | "(" expr ")" | "\left(" expr "\right)"
//! | "{" expr "}" grouping
//! | "\frac{" expr "}{" expr "}" exact division
//! | "\sqrt{" expr "}" real square root
//! ;
//! number = digits [ "." digits ] | "." digits ; decimal, no exponent form
//! ```
//!
//! Notes on the grammar:
//!
//! * `\cdot` and `\times` are accepted as synonyms for `*`.
//! * Implicit multiplication is accepted between adjacent factors where the
//! meaning is unambiguous: `2x`, `\pi r^2`, `(a)(b)` and `m a`. Concatenated
//! letters form one identifier (`ma` is the variable `ma`; write `m a` or
//! `m * a` for a product). Two adjacent number literals are a parse error.
//! * Unicode identifiers are supported (for example `面积`, `r`, `速度`). Plain
//! multi-letter identifiers are allowed as variables, but the names of common
//! elementary functions (`sin`, `cos`, `log`, `exp`, …) are reserved and
//! rejected as unsupported so that `sin(x)` is not silently read as a product.
//! * A single top-level `=` creates an equation (`F = m a`). It is **not**
//! assignment and never writes a binding. A second `=` is a parse error.
//!
//! # Unsupported constructs
//!
//! Everything outside the grammar is a structured [`MathErrorKind::Unsupported`]
//! or [`MathErrorKind::Parse`] error: matrices, sums/integrals, function calls
//! (`\sin`, `\cos`, …), multi-letter commands, `\left[`/`\right]`, mismatched or
//! missing braces, scientific notation (`1e3`), commas, arrays, subscripts,
//! superscript commands other than the `^` operator, `\frac`/`\sqrt` without
//! braced arguments, and so on. Labels, alignment characters and line breaks are
//! likewise unsupported. Underscores are ordinary identifier characters rather
//! than subscripts: `x_1` is the variable named `x_1`, not `x` subscript `1`.
//!
//! # Constants and ambiguity handling
//!
//! * `\pi` and `pi` denote the circle ratio; `\e` and `e` denote Euler's number.
//! * These spellings are **reserved**: a binding with the key `pi` or `e` never
//! overrides the constant, and they cannot be used as a solve target. Use a
//! different variable name (for example `E`, `x`, `r`).
//! * `2e` is parsed as `2 * e` (number times the constant); `2e3` is rejected as
//! scientific notation rather than silently reinterpreted.
//!
//! # Numeric semantics
//!
//! * Decimal literals are exact rationals: `0.25` is `1/4`, not a binary float.
//! * `Int` bindings become exact integers. `Float` bindings are interpreted as
//! the exact binary rational value of the `f64` (no rounding is introduced);
//! non-finite `Float` bindings are a [`MathErrorKind::Type`] error.
//! * `+ - * / ^` are exact when both operands are exact. Division keeps a
//! rational, so `\frac{1}{3} * 3` evaluates exactly to `1`.
//! * The final value is [`marqdo_value::Value::Int`] exactly when the exact result is an
//! integer, and [`marqdo_value::Value::Float`] otherwise. Consequently `1.5 + 2.5` returns
//! `Int(4)`, while `1 / 2` returns `Float(0.5)`.
//! * `\pi`, `\e` and a `\sqrt` of a non-perfect square introduce an `f64`
//! approximation; any result derived from one of them is a [`marqdo_value::Value::Float`].
//! Precision caveats: approximations follow IEEE-754 binary64, so only about
//! 15–17 significant decimal digits are reliable and repeated operations may
//! accumulate error. The kernel never claims an approximate result is exact.
//! * `\sqrt` of a perfect square of an exact rational stays exact (`\sqrt{4}` is
//! `Int(2)`, `\sqrt{1/4}` is `Float(0.5)`); a negative radicand is a type
//! error because the subset is real-valued.
//! * The exponent of `^` must evaluate to an integer. Its magnitude is bounded by
//! [`MAX_EXPONENT`]. Integer powers with a negative exponent are exact
//! reciprocals. `0 ^ 0` is a type error.
//! * Exact intermediate/result numerators and denominators are bounded by
//! [`MAX_RESULT_BITS`]; exceeding the bound returns a structured
//! `Unsupported` error instead of hanging or exhausting memory.
//! * Parsing is bounded by [`MAX_SOURCE_BYTES`], [`MAX_PARSE_DEPTH`] and
//! [`MAX_AST_NODES`]. The node bound also bounds later recursion depth for
//! long operator chains, so hostile input cannot overflow the stack during
//! evaluation, rendering or substitution.
//! * Division by zero, `0 ^ 0` and other undefined real operations are
//! [`MathErrorKind::Type`] errors (the kernel has no dedicated division error
//! kind, so the host maps the message/kind to `runtime.division_by_zero`).
//!
//! # Equations
//!
//! [`evaluate`] of an equation requires `target`. The target must occur exactly
//! once and the equation must be affine in it. The kernel supports `+`, `-`,
//! multiplication by a target-free side, division where the target is in the
//! numerator, and inversion of those operations in either direction (`2x = 4`,
//! `4 = 2x`, `x / 2 = 3`, `3 = x / 2`). Other variables are substituted from
//! `bindings` first; missing bindings are [`MathErrorKind::UndefinedVariable`].
//!
//! Solving a target that occurs zero times or more than once, that appears in a
//! denominator, under a root, in an exponent or in a non-affine product is a
//! structured [`MathErrorKind::Unsupported`] error. A target passed for a plain
//! expression, or an equation without a target, is likewise `Unsupported`.
//!
//! # Substitution
//!
//! [`substitute`] replaces bound variables with exact numeric literals and keeps
//! unbound variables symbolic. The returned [`Formula::source`] is a
//! deterministic canonical rendering that [`parse`] accepts again. Because the
//! rendering is canonical, it is not byte-identical to the original formatting.
#![forbid(unsafe_code)]
mod ast;
mod error;
mod eval;
mod parse;
pub use ast::{render_expr, Constant, Expr, Formula, FormulaKind, Rational};
pub use error::{MathError, MathErrorKind};
pub use eval::{evaluate, substitute, MAX_EXPONENT, MAX_RESULT_BITS};
pub use parse::{parse, MAX_AST_NODES, MAX_PARSE_DEPTH, MAX_SOURCE_BYTES};
#[cfg(test)]
mod tests {
use super::*;
use marqdo_value::Value;
use std::collections::BTreeMap;
/// End-to-end smoke test for the API shape documented on the crate root.
#[test]
fn public_api_round_trip() {
let formula = parse("A = \\pi r^2").unwrap();
assert!(formula.is_equation());
assert_eq!(formula.source, "A = \\pi r^2");
let mut bindings = BTreeMap::new();
bindings.insert("r".to_string(), Value::int(2));
let area = evaluate(&formula, &bindings, Some("A")).unwrap();
let Value::Float(area) = area else {
panic!("area should be an approximate Float");
};
assert!((area - std::f64::consts::PI * 4.0).abs() < 1e-12);
let substituted = substitute(&formula, &bindings).unwrap();
assert_eq!(substituted.source, "A = \\pi * 2 ^ 2");
assert!(substituted.is_equation());
assert_eq!(substituted.kind, parse("A = \\pi * 2 ^ 2").unwrap().kind);
}
}
+837
View File
@@ -0,0 +1,837 @@
//! Lexer and recursive-descent parser for the documented math subset.
//!
//! The parser is intentionally strict: anything outside the subset becomes a
//! structured [`MathError`] instead of being skipped, guessed or silently
//! simplified. It never panics on untrusted input: recursion depth, source size
//! and numeric literal size are all bounded before the corresponding work
//! happens.
use std::iter::Peekable;
use std::str::CharIndices;
use num_bigint::BigInt;
use num_rational::Ratio;
use crate::ast::{Constant, Expr, Formula, FormulaKind, Rational};
use crate::error::MathError;
/// Maximum accepted source length in bytes. Longer inputs are rejected before
/// tokenization so that a hostile formula cannot consume unbounded memory.
pub const MAX_SOURCE_BYTES: usize = 1_000_000;
/// Maximum parser recursion depth (parentheses, groups, unary chains, fractions
/// and roots all consume one level). Deeper input is a parse error instead of a
/// stack overflow.
pub const MAX_PARSE_DEPTH: usize = 256;
/// Maximum number of AST nodes in one formula. This bounds evaluation,
/// substitution and rendering recursion depth: a long left-associative chain
/// such as `1 + 1 + ...` would otherwise build a very deep tree even though the
/// parser loop itself is iterative. Deeper formulas are rejected with a parse
/// error instead of risking a stack overflow later.
pub const MAX_AST_NODES: usize = 512;
/// Maximum number of digits in one numeric literal.
const MAX_LITERAL_DIGITS: usize = 100_000;
/// Plain identifiers that name elementary functions in ordinary LaTeX. They are
/// reported as unsupported instead of being silently reinterpreted as variables
/// or implicit multiplication.
const FUNCTION_NAMES: &[&str] = &[
"sin", "cos", "tan", "cot", "sec", "csc", "arcsin", "arccos", "arctan", "sinh", "cosh", "tanh",
"log", "ln", "lg", "exp", "abs", "min", "max", "floor", "ceil", "round", "det", "dim", "gcd",
"lcm", "lim", "sup", "inf", "arg", "Re", "Im",
];
#[derive(Debug, Clone, PartialEq)]
enum TokenKind {
Number(Rational),
Ident(String),
Constant(Constant),
Plus,
Minus,
Star,
Slash,
Caret,
LParen,
RParen,
LBrace,
RBrace,
Equals,
Frac,
Sqrt,
Eof,
}
#[derive(Debug, Clone)]
struct Token {
kind: TokenKind,
/// Byte offset of the first byte of the token.
start: usize,
}
impl Token {
fn describe(&self) -> String {
match &self.kind {
TokenKind::Number(_) => "a number".to_string(),
TokenKind::Ident(name) => format!("identifier `{name}`"),
TokenKind::Constant(constant) => match constant {
Constant::Pi => "`\\pi`".to_string(),
Constant::E => "`\\e`".to_string(),
},
TokenKind::Plus => "`+`".to_string(),
TokenKind::Minus => "`-`".to_string(),
TokenKind::Star => "`*`".to_string(),
TokenKind::Slash => "`/`".to_string(),
TokenKind::Caret => "`^`".to_string(),
TokenKind::LParen => "`(`".to_string(),
TokenKind::RParen => "`)`".to_string(),
TokenKind::LBrace => "`{`".to_string(),
TokenKind::RBrace => "`}`".to_string(),
TokenKind::Equals => "`=`".to_string(),
TokenKind::Frac => "`\\frac`".to_string(),
TokenKind::Sqrt => "`\\sqrt`".to_string(),
TokenKind::Eof => "the end of the formula".to_string(),
}
}
}
/// Parse `latex` into a [`Formula`].
///
/// The supported grammar is documented on the crate root. The returned formula
/// keeps the original source in [`Formula::source`] and exposes the parsed
/// [`FormulaKind`] for inspection.
pub fn parse(latex: &str) -> Result<Formula, MathError> {
if latex.len() > MAX_SOURCE_BYTES {
return Err(MathError::parse(
format!(
"formula source is {} bytes; the supported limit is {MAX_SOURCE_BYTES} bytes",
latex.len()
),
Some(0),
));
}
let tokens = lex(latex)?;
Parser {
tokens,
position: 0,
depth: 0,
nodes: 0,
}
.parse_formula(latex)
}
fn lex(source: &str) -> Result<Vec<Token>, MathError> {
Lexer {
source,
chars: source.char_indices().peekable(),
tokens: Vec::new(),
}
.run()
}
struct Lexer<'a> {
source: &'a str,
chars: Peekable<CharIndices<'a>>,
tokens: Vec<Token>,
}
impl<'a> Lexer<'a> {
fn run(mut self) -> Result<Vec<Token>, MathError> {
while let Some(&(start, ch)) = self.chars.peek() {
if ch.is_whitespace() {
self.chars.next();
continue;
}
let kind = match ch {
'+' => {
self.chars.next();
TokenKind::Plus
}
'-' => {
self.chars.next();
TokenKind::Minus
}
'*' => {
self.chars.next();
TokenKind::Star
}
'/' => {
self.chars.next();
TokenKind::Slash
}
'^' => {
self.chars.next();
TokenKind::Caret
}
'(' => {
self.chars.next();
TokenKind::LParen
}
')' => {
self.chars.next();
TokenKind::RParen
}
'{' => {
self.chars.next();
TokenKind::LBrace
}
'}' => {
self.chars.next();
TokenKind::RBrace
}
'=' => {
self.chars.next();
TokenKind::Equals
}
'\\' => self.lex_command()?,
ch if ch.is_ascii_digit() || ch == '.' => self.lex_number()?,
ch if is_ident_start(ch) => self.lex_identifier()?,
other => {
return Err(MathError::unsupported(
format!("unsupported character `{other}` in a formula"),
Some(start),
));
}
};
self.tokens.push(Token { kind, start });
}
self.tokens.push(Token {
kind: TokenKind::Eof,
start: self.source.len(),
});
Ok(self.tokens)
}
fn lex_identifier(&mut self) -> Result<TokenKind, MathError> {
let start = self.current_offset();
let mut text = String::new();
while let Some(&(_, ch)) = self.chars.peek() {
if is_ident_continue(ch) {
text.push(ch);
self.chars.next();
} else {
break;
}
}
match text.as_str() {
"pi" => Ok(TokenKind::Constant(Constant::Pi)),
"e" => Ok(TokenKind::Constant(Constant::E)),
_ if FUNCTION_NAMES.contains(&text.as_str()) => Err(MathError::unsupported(
format!(
"function `{text}` is not supported; the native math subset has no function calls"
),
Some(start),
)),
_ => Ok(TokenKind::Ident(text)),
}
}
/// Byte offset of the next unconsumed character (or the source end).
fn current_offset(&mut self) -> usize {
match self.chars.peek() {
Some(&(offset, _)) => offset,
None => self.source.len(),
}
}
fn lex_number(&mut self) -> Result<TokenKind, MathError> {
let start = self.current_offset();
let mut integer_digits = String::new();
while let Some(&(_, ch)) = self.chars.peek() {
if ch.is_ascii_digit() {
integer_digits.push(ch);
self.chars.next();
} else {
break;
}
}
let mut fraction_digits = String::new();
if matches!(self.chars.peek(), Some(&(_, '.'))) {
self.chars.next();
while let Some(&(_, ch)) = self.chars.peek() {
if ch.is_ascii_digit() {
fraction_digits.push(ch);
self.chars.next();
} else {
break;
}
}
if fraction_digits.is_empty() {
return Err(MathError::parse(
"malformed decimal literal: expected digits after `.`",
Some(start),
));
}
}
if integer_digits.is_empty() && fraction_digits.is_empty() {
return Err(MathError::parse("malformed numeric literal", Some(start)));
}
if integer_digits.len() + fraction_digits.len() > MAX_LITERAL_DIGITS {
return Err(MathError::parse(
format!(
"numeric literal has more than {MAX_LITERAL_DIGITS} digits, which is outside the supported resource bound"
),
Some(start),
));
}
// Reject scientific notation (`1e3`) explicitly: it is outside the
// subset and would otherwise parse as `1 * e3`.
if matches!(self.chars.peek(), Some(&(_, 'e' | 'E')))
&& self.number_is_followed_by_exponent()
{
return Err(MathError::parse(
"scientific notation is not supported; write an explicit product such as `2 * 10 ^ 3`",
Some(start),
));
}
let integer_text = if integer_digits.is_empty() {
"0"
} else {
&integer_digits
};
let numerator = parse_bigint(integer_text, start)?;
if fraction_digits.is_empty() {
return Ok(TokenKind::Number(Ratio::from_integer(numerator)));
}
let mut all_digits = String::with_capacity(integer_digits.len() + fraction_digits.len());
all_digits.push_str(if integer_digits.is_empty() {
"0"
} else {
&integer_digits
});
all_digits.push_str(&fraction_digits);
let numerator = parse_bigint(&all_digits, start)?;
let denominator = BigInt::from(10_u32).pow(fraction_digits.len() as u32);
Ok(TokenKind::Number(Ratio::new(numerator, denominator)))
}
/// Look past the current `e`/`E` to decide whether it introduces an
/// exponent (`1e3`, `1e-3`) rather than the Euler constant (`2e`).
fn number_is_followed_by_exponent(&self) -> bool {
let mut chars = self.chars.clone();
let _ = chars.next(); // the 'e' / 'E'
match chars.next().map(|(_, ch)| ch) {
Some(ch) if ch.is_ascii_digit() => true,
Some('+' | '-') => {
matches!(chars.next().map(|(_, ch)| ch), Some(ch) if ch.is_ascii_digit())
}
_ => false,
}
}
fn lex_command(&mut self) -> Result<TokenKind, MathError> {
let start = self.current_offset();
self.chars.next(); // consume the backslash
let mut name = String::new();
while let Some(&(_, ch)) = self.chars.peek() {
if ch.is_ascii_alphabetic() {
name.push(ch);
self.chars.next();
} else {
break;
}
}
match name.as_str() {
"pi" => Ok(TokenKind::Constant(Constant::Pi)),
"e" => Ok(TokenKind::Constant(Constant::E)),
"cdot" | "times" => Ok(TokenKind::Star),
"frac" => Ok(TokenKind::Frac),
"sqrt" => Ok(TokenKind::Sqrt),
"left" => self.lex_left_right(start, '('),
"right" => self.lex_left_right(start, ')'),
"" => Err(MathError::unsupported(
"unsupported LaTeX control symbol; only alphabetic commands such as `\\pi` are supported",
Some(start),
)),
other => Err(MathError::unsupported(
format!(
"unsupported LaTeX command `\\{other}`; the native math subset only supports `\\frac`, `\\sqrt`, `\\cdot`, `\\times`, `\\left(`, `\\right)`, `\\pi` and `\\e`"
),
Some(start),
)),
}
}
fn lex_left_right(&mut self, start: usize, expected: char) -> Result<TokenKind, MathError> {
while let Some(&(_, ch)) = self.chars.peek() {
if ch.is_whitespace() {
self.chars.next();
} else {
break;
}
}
match self.chars.next() {
Some((_, ch)) if ch == expected => Ok(if expected == '(' {
TokenKind::LParen
} else {
TokenKind::RParen
}),
_ => Err(MathError::unsupported(
format!(
"only the parenthesis forms `\\left(` and `\\right)` are supported, not `\\{}` followed by another delimiter",
if expected == '(' { "left" } else { "right" }
),
Some(start),
)),
}
}
}
fn parse_bigint(digits: &str, position: usize) -> Result<BigInt, MathError> {
digits
.parse::<BigInt>()
.map_err(|_| MathError::parse("numeric literal is too large to represent", Some(position)))
}
fn is_ident_start(ch: char) -> bool {
ch.is_alphabetic() || ch == '_'
}
fn is_ident_continue(ch: char) -> bool {
ch.is_alphanumeric() || ch == '_'
}
struct Parser {
tokens: Vec<Token>,
position: usize,
depth: usize,
nodes: usize,
}
impl Parser {
fn peek(&self) -> &Token {
// The lexer always appends an Eof token, so indexing is in bounds.
&self.tokens[self.position.min(self.tokens.len() - 1)]
}
fn advance(&mut self) -> Token {
let token = self.peek().clone();
if self.position < self.tokens.len() - 1 {
self.position += 1;
}
token
}
/// Record one constructed AST node, enforcing [`MAX_AST_NODES`].
fn node(&mut self, expr: Expr) -> Result<Expr, MathError> {
self.nodes += 1;
if self.nodes > MAX_AST_NODES {
return Err(MathError::parse(
format!(
"formula contains more than the supported limit of {MAX_AST_NODES} syntax nodes"
),
Some(self.peek().start),
));
}
Ok(expr)
}
fn enter_depth(&mut self) -> Result<(), MathError> {
self.depth += 1;
if self.depth > MAX_PARSE_DEPTH {
return Err(MathError::parse(
format!("formula nesting exceeds the supported limit of {MAX_PARSE_DEPTH} levels"),
Some(self.peek().start),
));
}
Ok(())
}
fn parse_formula(mut self, source: &str) -> Result<Formula, MathError> {
if matches!(self.peek().kind, TokenKind::Eof) {
return Err(MathError::parse("empty formula", Some(0)));
}
let left = self.parse_expr()?;
let kind = if matches!(self.peek().kind, TokenKind::Equals) {
let equals = self.advance();
if matches!(self.peek().kind, TokenKind::Eof) {
return Err(MathError::parse(
"expected a right-hand side after `=`",
Some(equals.start + 1),
));
}
let right = self.parse_expr()?;
if matches!(self.peek().kind, TokenKind::Equals) {
return Err(MathError::parse(
"more than one `=` in a formula; at most one equation is supported and `=` is never assignment",
Some(self.peek().start),
));
}
FormulaKind::Equation { left, right }
} else {
FormulaKind::Expression(left)
};
if !matches!(self.peek().kind, TokenKind::Eof) {
return Err(MathError::parse(
format!("unexpected {} after the formula", self.peek().describe()),
Some(self.peek().start),
));
}
Ok(Formula {
source: source.to_string(),
kind,
})
}
fn parse_expr(&mut self) -> Result<Expr, MathError> {
let mut left = self.parse_term()?;
loop {
match self.peek().kind {
TokenKind::Plus => {
self.advance();
let right = self.parse_term()?;
left = self.node(Expr::Add(Box::new(left), Box::new(right)))?;
}
TokenKind::Minus => {
self.advance();
let right = self.parse_term()?;
left = self.node(Expr::Sub(Box::new(left), Box::new(right)))?;
}
_ => return Ok(left),
}
}
}
fn parse_term(&mut self) -> Result<Expr, MathError> {
let mut left = self.parse_unary()?;
loop {
if matches!(self.peek().kind, TokenKind::Star) {
self.advance();
let right = self.parse_unary()?;
left = self.node(Expr::Mul(Box::new(left), Box::new(right)))?;
} else if matches!(self.peek().kind, TokenKind::Slash) {
self.advance();
let right = self.parse_unary()?;
left = self.node(Expr::Div(Box::new(left), Box::new(right)))?;
} else if can_start_primary(&self.peek().kind) {
if matches!(left, Expr::Number(_))
&& matches!(self.peek().kind, TokenKind::Number(_))
{
return Err(MathError::parse(
"two adjacent number literals are ambiguous; insert an operator",
Some(self.peek().start),
));
}
// Implicit multiplication: `2x`, `\pi r^2`, `m a`.
let right = self.parse_unary()?;
left = self.node(Expr::Mul(Box::new(left), Box::new(right)))?;
} else {
return Ok(left);
}
}
}
fn parse_unary(&mut self) -> Result<Expr, MathError> {
self.enter_depth()?;
let result = self.parse_unary_inner();
self.depth -= 1;
result
}
fn parse_unary_inner(&mut self) -> Result<Expr, MathError> {
match self.peek().kind {
TokenKind::Minus => {
self.advance();
let inner = self.parse_unary()?;
self.node(Expr::Neg(Box::new(inner)))
}
TokenKind::Plus => {
self.advance();
self.parse_unary()
}
_ => self.parse_power(),
}
}
fn parse_power(&mut self) -> Result<Expr, MathError> {
let base = self.parse_primary()?;
if matches!(self.peek().kind, TokenKind::Caret) {
self.advance();
let exponent = self.parse_unary()?;
return self.node(Expr::Pow(Box::new(base), Box::new(exponent)));
}
Ok(base)
}
fn parse_primary(&mut self) -> Result<Expr, MathError> {
self.enter_depth()?;
let result = self.parse_primary_inner();
self.depth -= 1;
result
}
fn parse_primary_inner(&mut self) -> Result<Expr, MathError> {
let token = self.peek().clone();
match token.kind {
TokenKind::Number(value) => {
self.advance();
self.node(Expr::Number(value))
}
TokenKind::Ident(name) => {
self.advance();
self.node(Expr::Variable(name))
}
TokenKind::Constant(constant) => {
self.advance();
self.node(Expr::Constant(constant))
}
TokenKind::LParen => {
self.advance();
let inner = self.parse_expr()?;
self.expect_closing(TokenKind::RParen, "`)`", token.start)?;
Ok(inner)
}
TokenKind::LBrace => {
self.advance();
let inner = self.parse_expr()?;
self.expect_closing(TokenKind::RBrace, "`}`", token.start)?;
Ok(inner)
}
TokenKind::Frac => {
self.advance();
let numerator = self.parse_braced_argument("\\frac")?;
let denominator = self.parse_braced_argument("\\frac")?;
self.node(Expr::Div(Box::new(numerator), Box::new(denominator)))
}
TokenKind::Sqrt => {
self.advance();
let inner = self.parse_braced_argument("\\sqrt")?;
self.node(Expr::Sqrt(Box::new(inner)))
}
TokenKind::Eof => Err(MathError::parse(
"expected an expression, found the end of the formula",
Some(token.start),
)),
other => Err(MathError::parse(
format!(
"expected an expression, found {}",
Token {
kind: other,
start: token.start
}
.describe()
),
Some(token.start),
)),
}
}
fn parse_braced_argument(&mut self, command: &str) -> Result<Expr, MathError> {
if !matches!(self.peek().kind, TokenKind::LBrace) {
return Err(MathError::parse(
format!("`{command}` requires a braced argument such as `{command}{{x}}`"),
Some(self.peek().start),
));
}
let open = self.advance();
let inner = self.parse_expr()?;
self.expect_closing(TokenKind::RBrace, "`}`", open.start)?;
Ok(inner)
}
fn expect_closing(
&mut self,
expected: TokenKind,
description: &str,
open_position: usize,
) -> Result<(), MathError> {
if std::mem::discriminant(&self.peek().kind) == std::mem::discriminant(&expected) {
self.advance();
Ok(())
} else {
Err(MathError::parse(
format!(
"expected {description} to close the group opened at byte {open_position}, found {}",
self.peek().describe()
),
Some(self.peek().start),
))
}
}
}
fn can_start_primary(kind: &TokenKind) -> bool {
matches!(
kind,
TokenKind::Number(_)
| TokenKind::Ident(_)
| TokenKind::Constant(_)
| TokenKind::LParen
| TokenKind::LBrace
| TokenKind::Frac
| TokenKind::Sqrt
)
}
#[cfg(test)]
mod tests {
use super::*;
fn parse_ok(source: &str) -> Formula {
parse(source).unwrap_or_else(|err| panic!("expected {source:?} to parse: {err}"))
}
fn parse_err(source: &str) -> MathError {
parse(source).unwrap_err()
}
#[test]
fn precedence_matches_standard_arithmetic() {
let formula = parse_ok("1 + 2 * 3");
assert_eq!(
formula.kind,
FormulaKind::Expression(Expr::Add(
Box::new(Expr::Number(Ratio::from_integer(BigInt::from(1)))),
Box::new(Expr::Mul(
Box::new(Expr::Number(Ratio::from_integer(BigInt::from(2)))),
Box::new(Expr::Number(Ratio::from_integer(BigInt::from(3)))),
)),
))
);
}
#[test]
fn unary_minus_binds_looser_than_power() {
// -2^2 is -(2^2), not (-2)^2.
let formula = parse_ok("-2^2");
assert!(matches!(
formula.kind,
FormulaKind::Expression(Expr::Neg(_))
));
}
#[test]
fn power_is_right_associative() {
let formula = parse_ok("2^3^2");
let FormulaKind::Expression(Expr::Pow(_, exponent)) = formula.kind else {
panic!("expected a power");
};
assert!(matches!(*exponent, Expr::Pow(_, _)));
}
#[test]
fn implicit_multiplication_joins_adjacent_factors() {
let formula = parse_ok("\\pi r^2");
let FormulaKind::Expression(Expr::Mul(left, right)) = formula.kind else {
panic!("expected multiplication");
};
assert!(matches!(*left, Expr::Constant(Constant::Pi)));
assert!(matches!(*right, Expr::Pow(_, _)));
// `F = m a` is an equation whose right side is a product.
let formula = parse_ok("F = m a");
let FormulaKind::Equation { right, .. } = formula.kind else {
panic!("expected an equation");
};
assert!(matches!(right, Expr::Mul(_, _)));
}
#[test]
fn left_and_right_parentheses_are_accepted() {
assert_eq!(
parse_ok("\\left(1 + 2\\right) * 3").kind,
parse_ok("(1 + 2) * 3").kind
);
}
#[test]
fn frac_and_sqrt_become_dedicated_nodes() {
let formula = parse_ok("\\frac{1}{2} + \\sqrt{4}");
let FormulaKind::Expression(Expr::Add(left, right)) = formula.kind else {
panic!("expected addition");
};
assert!(matches!(*left, Expr::Div(_, _)));
assert!(matches!(*right, Expr::Sqrt(_)));
}
#[test]
fn single_equals_is_an_equation() {
let formula = parse_ok("A = \\pi r^2");
assert!(formula.is_equation());
assert_eq!(formula.variables().len(), 2);
}
#[test]
fn more_than_one_equals_is_a_parse_error() {
let err = parse_err("a = b = c");
assert_eq!(err.kind, crate::error::MathErrorKind::Parse);
assert!(err.message.contains("more than one"));
}
#[test]
fn empty_and_malformed_input_is_a_parse_error() {
assert_eq!(parse_err("").kind, crate::error::MathErrorKind::Parse);
for source in ["1 +", "(1 + 2", "\\frac{1}{2", "{1 + 2", "1 + 2)", "= 3"] {
let err = parse_err(source);
assert_eq!(
err.kind,
crate::error::MathErrorKind::Parse,
"source {source:?}"
);
assert!(err.position.is_some(), "source {source:?}");
}
}
#[test]
fn unsupported_commands_are_structured() {
for source in [
"\\begin{matrix}1&2\\end{matrix}",
"\\int_0^1 x dx",
"\\sin(x)",
"\\sum_{i=1}^n i",
"sin(1)",
] {
let err = parse_err(source);
assert_eq!(
err.kind,
crate::error::MathErrorKind::Unsupported,
"source {source:?}"
);
}
}
#[test]
fn unknown_characters_are_structured() {
let err = parse_err("1, 2");
assert_eq!(err.kind, crate::error::MathErrorKind::Unsupported);
assert!(err.message.contains("unsupported character"));
}
#[test]
fn deep_nesting_is_rejected_without_stack_overflow() {
let source = format!("{}1{}", "(".repeat(10_000), ")".repeat(10_000));
let err = parse_err(&source);
assert_eq!(err.kind, crate::error::MathErrorKind::Parse);
assert!(err.message.contains("nesting"));
}
#[test]
fn excessive_node_count_is_rejected() {
// A long left-associative chain is cheap to parse iteratively but would
// build a very deep tree; the node budget rejects it first.
let source = format!("{}1", "1 + ".repeat(MAX_AST_NODES));
let err = parse_err(&source);
assert_eq!(err.kind, crate::error::MathErrorKind::Parse);
assert!(err.message.contains("syntax nodes"), "{}", err.message);
}
#[test]
fn very_long_chain_is_rejected_without_stack_overflow() {
let source = format!("{}1", "1 + ".repeat(200_000));
let err = parse_err(&source);
assert_eq!(err.kind, crate::error::MathErrorKind::Parse);
}
#[test]
fn numeric_literal_bounds_are_enforced() {
let source = "9".repeat(MAX_LITERAL_DIGITS + 1);
let err = parse_err(&source);
assert_eq!(err.kind, crate::error::MathErrorKind::Parse);
assert!(err.message.contains("digits"));
}
}
+596
View File
@@ -0,0 +1,596 @@
//! End-to-end tests for the native Formula kernel.
//!
//! These tests exercise the public contract used by the host layer:
//! `parse`, `evaluate` and `substitute`. They cover the documented grammar,
//! exact numeric semantics, equation solving, structured errors and resource
//! bounds.
use std::collections::BTreeMap;
use marqdo_math::{evaluate, parse, substitute, MathError, MathErrorKind, MAX_EXPONENT};
use marqdo_value::Value;
use num_bigint::BigInt;
fn empty() -> BTreeMap<String, Value> {
BTreeMap::new()
}
fn bindings(entries: &[(&str, Value)]) -> BTreeMap<String, Value> {
entries
.iter()
.map(|(name, value)| ((*name).to_string(), value.clone()))
.collect()
}
fn eval(source: &str, bindings: &BTreeMap<String, Value>) -> Result<Value, MathError> {
evaluate(&parse(source).expect("fixture must parse"), bindings, None)
}
fn solve(
source: &str,
bindings: &BTreeMap<String, Value>,
target: &str,
) -> Result<Value, MathError> {
evaluate(
&parse(source).expect("fixture must parse"),
bindings,
Some(target),
)
}
fn assert_int(value: &Value, expected: i64) {
assert_eq!(value, &Value::int(expected), "value was {value:?}");
}
fn assert_float_close(value: &Value, expected: f64) {
let Value::Float(actual) = value else {
panic!("expected a Float, got {value:?}");
};
assert!(
(actual - expected).abs() <= 1e-12 * expected.abs().max(1.0),
"expected {expected}, got {actual}"
);
}
#[test]
fn precedence_and_parentheses() {
assert_int(&eval("1 + 2 * 3", &empty()).unwrap(), 7);
assert_int(&eval("(1 + 2) * 3", &empty()).unwrap(), 9);
assert_int(&eval("10 - 3 - 2", &empty()).unwrap(), 5);
assert_int(&eval("8 / 4 / 2", &empty()).unwrap(), 1);
assert_int(&eval("2 + 3 * 4 ^ 2", &empty()).unwrap(), 50);
// Power is right associative, unary minus binds looser than power.
assert_int(&eval("2 ^ 3 ^ 2", &empty()).unwrap(), 512);
assert_int(&eval("-2 ^ 2", &empty()).unwrap(), -4);
assert_int(&eval("(-2) ^ 2", &empty()).unwrap(), 4);
}
#[test]
fn exact_big_integer_arithmetic() {
let Value::Int(power) = eval("2 ^ 100", &empty()).unwrap() else {
panic!("expected an Int");
};
assert_eq!(power.to_string(), "1267650600228229401496703205376");
let Value::Int(product) = eval(
"123456789012345678901234567890 * 987654321098765432109876543210",
&empty(),
)
.unwrap() else {
panic!("expected an Int");
};
assert_eq!(
product.to_string(),
"121932631137021795226185032733622923332237463801111263526900"
);
let Value::Int(sum) = eval("2 ^ 200 + 1", &empty()).unwrap() else {
panic!("expected an Int");
};
assert_eq!(
sum.to_string(),
"1606938044258990275541962092341162602522202993782792835301377"
);
}
#[test]
fn division_stays_exact_when_it_reduces_to_an_integer() {
// 1/3 alone is a Float approximation, but three of them are exactly 1.
assert_int(&eval("(1 / 3) * 3", &empty()).unwrap(), 1);
assert_int(&eval("(2 / 7) * 7", &empty()).unwrap(), 2);
assert_int(&eval("100 / 4", &empty()).unwrap(), 25);
assert_float_close(&eval("10 / 4", &empty()).unwrap(), 2.5);
assert_float_close(&eval("1 / 3", &empty()).unwrap(), 1.0 / 3.0);
}
#[test]
fn decimal_literals_are_exact_rationals() {
// 1.5 + 2.5 is exactly 4, which is integral, so the result is an Int.
assert_int(&eval("1.5 + 2.5", &empty()).unwrap(), 4);
assert_int(&eval("0.25 * 4", &empty()).unwrap(), 1);
assert_float_close(&eval("0.1 + 0.2", &empty()).unwrap(), 0.3);
assert_float_close(&eval(".5 + 1", &empty()).unwrap(), 1.5);
}
#[test]
fn pi_r_squared_area() {
let mut bindings = empty();
bindings.insert("r".to_string(), Value::int(2));
let value = solve("A = \\pi r^2", &bindings, "A").unwrap();
assert_float_close(&value, std::f64::consts::PI * 4.0);
}
#[test]
fn perfect_and_non_perfect_square_roots() {
assert_int(&eval("\\sqrt{16}", &empty()).unwrap(), 4);
assert_int(&eval("\\sqrt{0}", &empty()).unwrap(), 0);
// \sqrt{1/4} = 1/2: exact but not integral, so it is a Float value.
assert_float_close(&eval("\\sqrt{\\frac{1}{4}}", &empty()).unwrap(), 0.5);
// Non-perfect squares are explicitly approximate Floats.
assert_float_close(
&eval("\\sqrt{2}", &empty()).unwrap(),
std::f64::consts::SQRT_2,
);
assert_float_close(&eval("\\sqrt{2} * \\sqrt{2}", &empty()).unwrap(), 2.0);
let err = eval("\\sqrt{-4}", &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Type);
}
#[test]
fn frac_is_exact_division() {
assert_int(&eval("\\frac{6}{2}", &empty()).unwrap(), 3);
assert_float_close(&eval("\\frac{6}{4}", &empty()).unwrap(), 1.5);
assert_float_close(
&eval("\\frac{\\frac{1}{2}}{\\frac{3}{4}}", &empty()).unwrap(),
2.0 / 3.0,
);
assert_int(&eval("\\frac{1}{3} + \\frac{2}{3}", &empty()).unwrap(), 1);
}
#[test]
fn left_right_parentheses_and_nesting() {
assert_int(
&eval(
"\\left(\\left(1 + 2\\right) * \\left(3 + 4\\right)\\right)",
&empty(),
)
.unwrap(),
21,
);
assert_int(&eval("\\left(1 + 2\\right) * 3", &empty()).unwrap(), 9);
assert_int(&eval("((((1 + 2)))) * 3", &empty()).unwrap(), 9);
assert_int(&eval("2 * {3 + 4}", &empty()).unwrap(), 14);
}
#[test]
fn unicode_identifiers() {
let bindings = bindings(&[("半径", Value::int(3))]);
assert_float_close(
&solve("面积 = \\pi 半径^2", &bindings, "面积").unwrap(),
std::f64::consts::PI * 9.0,
);
let substituted = substitute(&parse("半径 + 1").unwrap(), &bindings).unwrap();
assert_eq!(substituted.source, "3 + 1");
assert_int(&eval(&substituted.source, &empty()).unwrap(), 4);
}
#[test]
fn constants_and_their_ambiguity_rules() {
assert_float_close(&eval("\\pi", &empty()).unwrap(), std::f64::consts::PI);
assert_float_close(&eval("pi", &empty()).unwrap(), std::f64::consts::PI);
assert_float_close(&eval("\\e", &empty()).unwrap(), std::f64::consts::E);
assert_float_close(&eval("e", &empty()).unwrap(), std::f64::consts::E);
// `2e` is 2 times the constant, not scientific notation.
assert_float_close(&eval("2e", &empty()).unwrap(), 2.0 * std::f64::consts::E);
// `pi` and `e` are reserved: bindings do not shadow the constants.
let bindings = bindings(&[("pi", Value::int(3)), ("e", Value::int(3))]);
assert_float_close(&eval("pi", &bindings).unwrap(), std::f64::consts::PI);
assert_float_close(&eval("e", &bindings).unwrap(), std::f64::consts::E);
assert_eq!(
solve("pi = 3", &empty(), "pi").unwrap_err().kind,
MathErrorKind::Unsupported
);
}
#[test]
fn f_equals_m_a_solved_for_m() {
let bindings = bindings(&[("F", Value::int(12)), ("a", Value::int(3))]);
assert_int(&solve("F = m a", &bindings, "m").unwrap(), 4);
// F = m a is an equation, not assignment: solving for m never rebinds F.
assert_eq!(bindings.get("F"), Some(&Value::int(12)));
}
#[test]
fn f_equals_m_a_solved_for_a() {
let bindings = bindings(&[("F", Value::int(12)), ("m", Value::int(3))]);
assert_int(&solve("F = m a", &bindings, "a").unwrap(), 4);
}
#[test]
fn f_equals_m_a_solved_for_f() {
let bindings = bindings(&[("m", Value::int(3)), ("a", Value::int(4))]);
assert_int(&solve("F = m a", &bindings, "F").unwrap(), 12);
}
#[test]
fn linear_equation_solving_both_directions() {
// Target on the left and on the right; multiplication and division by a
// target-free side are both inverted.
assert_int(&solve("2 x = 4", &empty(), "x").unwrap(), 2);
assert_int(&solve("4 = 2 x", &empty(), "x").unwrap(), 2);
assert_int(&solve("x / 2 = 3", &empty(), "x").unwrap(), 6);
assert_int(&solve("3 = x / 2", &empty(), "x").unwrap(), 6);
assert_int(&solve("x + 2 = 5", &empty(), "x").unwrap(), 3);
assert_int(&solve("2 + x = 5", &empty(), "x").unwrap(), 3);
assert_int(&solve("2 x + 1 = 7", &empty(), "x").unwrap(), 3);
assert_int(&solve("x = 4", &empty(), "x").unwrap(), 4);
assert_int(&solve("x / 4 = 1 / 2", &empty(), "x").unwrap(), 2);
assert_int(&solve("(x + 1) * 2 = 8", &empty(), "x").unwrap(), 3);
// Other variables are substituted first.
let bindings = bindings(&[("y", Value::int(3))]);
assert_int(&solve("x = 2 y + 1", &bindings, "x").unwrap(), 7);
}
#[test]
fn equation_solving_requires_exactly_one_affine_occurrence() {
assert_eq!(
solve("x + x = 4", &empty(), "x").unwrap_err().kind,
MathErrorKind::Unsupported
);
assert_eq!(
solve("x * x = 4", &empty(), "x").unwrap_err().kind,
MathErrorKind::Unsupported
);
assert_eq!(
solve("x ^ 2 = 4", &empty(), "x").unwrap_err().kind,
MathErrorKind::Unsupported
);
assert_eq!(
solve("1 / x = 2", &empty(), "x").unwrap_err().kind,
MathErrorKind::Unsupported
);
assert_eq!(
solve("\\sqrt{x} = 2", &empty(), "x").unwrap_err().kind,
MathErrorKind::Unsupported
);
assert_eq!(
solve("2 = 4", &empty(), "x").unwrap_err().kind,
MathErrorKind::Unsupported
);
assert_eq!(
solve("x * 0 = 1", &empty(), "x").unwrap_err().kind,
MathErrorKind::Unsupported
);
}
#[test]
fn target_errors_are_structured() {
let err = evaluate(&parse("A = 2").unwrap(), &empty(), None).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Unsupported);
assert!(err.message.contains("target"));
let err = evaluate(&parse("1 + 2").unwrap(), &empty(), Some("x")).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Unsupported);
let err = solve("A = 2", &empty(), "B").unwrap_err();
assert_eq!(err.kind, MathErrorKind::Unsupported);
assert!(err.message.contains("does not occur"));
let err = solve("A = 2", &empty(), "").unwrap_err();
assert_eq!(err.kind, MathErrorKind::Unsupported);
}
#[test]
fn unsupported_constructs_are_structured() {
for source in [
"\\begin{matrix} 1 & 2 \\\\ 3 & 4 \\end{matrix}",
"\\int_0^1 x dx",
"\\sin(x)",
"\\cos(x) + 1",
"\\sum_{i=1}^{n} i",
"\\alpha + 1",
"\\frac12",
"1e3",
"\\left[ 1, 2 \\right]",
] {
let err = parse(source).unwrap_err();
assert!(
matches!(err.kind, MathErrorKind::Unsupported | MathErrorKind::Parse),
"source {source:?} produced {err:?}"
);
assert!(
err.position.is_some(),
"source {source:?} lost its position"
);
}
}
#[test]
fn malformed_latex_is_a_parse_error_with_position() {
for source in [
"",
"1 +",
"(1 + 2",
"\\frac{1}{2",
"\\frac{1}",
"\\sqrt 2",
"{1 + 2",
"1 + 2}",
"1 + 2)",
"1.2.3",
"1 2",
"a = b = c",
] {
let err = parse(source).unwrap_err();
assert_eq!(
err.kind,
MathErrorKind::Parse,
"source {source:?} produced {err:?}"
);
assert!(err.position.is_some(), "source {source:?}");
}
}
#[test]
fn undefined_variables_are_reported() {
let err = eval("1 + x", &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::UndefinedVariable);
assert!(err.message.contains('x'));
let err = solve("A = x + 1", &empty(), "A").unwrap_err();
assert_eq!(err.kind, MathErrorKind::UndefinedVariable);
}
#[test]
fn non_numeric_bindings_are_type_errors() {
for value in [
Value::Bool(true),
Value::text("two"),
Value::List(vec![Value::int(2)]),
Value::None,
Value::Float(f64::NAN),
Value::Float(f64::INFINITY),
] {
let err = eval("x + 1", &bindings(&[("x", value)])).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Type);
}
// Unused bindings of other types are irrelevant.
assert_int(
&eval("1 + 1", &bindings(&[("x", Value::text("unused"))])).unwrap(),
2,
);
}
#[test]
fn float_bindings_are_exact_numeric_values() {
let bindings = bindings(&[("x", Value::Float(2.5))]);
assert_float_close(&eval("x", &bindings).unwrap(), 2.5);
// 2.5 + 0.5 is exactly 3, so the exact-result rule yields an Int.
assert_int(&eval("x + 0.5", &bindings).unwrap(), 3);
assert_float_close(&eval("x / 2", &bindings).unwrap(), 1.25);
}
#[test]
fn division_by_zero_is_a_structured_error() {
for source in ["1 / 0", "\\frac{1}{0}", "1 / (2 - 2)"] {
let err = eval(source, &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Type, "source {source:?}");
assert!(
err.message.contains("division by zero"),
"source {source:?} produced {err:?}"
);
}
let err = solve("x / 0 = 1", &empty(), "x").unwrap_err();
assert_eq!(err.kind, MathErrorKind::Type);
}
#[test]
fn exponent_must_be_an_integer() {
for source in ["2 ^ 0.5", "2 ^ \\frac{1}{2}", "2 ^ \\pi"] {
let err = eval(source, &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Type, "source {source:?}");
}
}
#[test]
fn negative_integer_exponents_are_exact_reciprocals() {
assert_float_close(&eval("2 ^ -3", &empty()).unwrap(), 0.125);
assert_int(&eval("(1 / 2) ^ -2", &empty()).unwrap(), 4);
let err = eval("0 ^ -1", &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Type);
}
#[test]
fn huge_exponents_are_bounded_not_hung() {
let err = eval(&format!("2 ^ {}", MAX_EXPONENT + 1), &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Unsupported);
assert!(err.message.contains("exponent"));
let err = eval("2 ^ 1000000", &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Unsupported);
// Each factor is under the exponent bound, but the product size is not.
let err = eval("(2 ^ 10000) ^ 10000", &empty()).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Unsupported);
// At the documented exponent bound the result is still computed exactly.
let Value::Int(bounded) = eval("2 ^ 10000", &empty()).unwrap() else {
panic!("expected an Int");
};
assert_eq!(bounded.bits(), 10001);
}
#[test]
fn substitute_replaces_bindings_deterministically() {
let formula = parse("A = \\pi r^2").unwrap();
let bindings = bindings(&[("r", Value::int(2))]);
let substituted = substitute(&formula, &bindings).unwrap();
// The rendering is canonical, re-parseable and deterministic.
assert_eq!(substituted.source, "A = \\pi * 2 ^ 2");
assert_eq!(substituted.render(), substituted.source);
assert_eq!(parse(&substituted.source).unwrap().kind, substituted.kind);
let direct = evaluate(&formula, &bindings, Some("A")).unwrap();
let via_substitution = evaluate(&substituted, &empty(), Some("A")).unwrap();
assert_eq!(direct, via_substitution);
let second = substitute(&formula, &bindings).unwrap();
assert_eq!(substituted.source, second.source);
}
#[test]
fn substitute_leaves_unbound_variables_symbolic() {
let formula = parse("x + y * 2").unwrap();
let substituted = substitute(&formula, &bindings(&[("x", Value::int(3))])).unwrap();
assert_eq!(substituted.source, "3 + y * 2");
assert!(substituted.variables().contains("y"));
assert!(!substituted.variables().contains("x"));
let value = evaluate(&substituted, &bindings(&[("y", Value::int(4))]), None).unwrap();
assert_int(&value, 11);
}
#[test]
fn substitute_rejects_unsupported_binding_types() {
let formula = parse("x + 1").unwrap();
let err = substitute(&formula, &bindings(&[("x", Value::text("two"))])).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Type);
}
#[test]
fn scientific_notation_and_adjacent_numbers_are_rejected() {
assert_eq!(parse("1e3").unwrap_err().kind, MathErrorKind::Parse);
assert_eq!(parse("1E3").unwrap_err().kind, MathErrorKind::Parse);
assert_eq!(parse("1e-3").unwrap_err().kind, MathErrorKind::Parse);
assert_eq!(parse("1 2").unwrap_err().kind, MathErrorKind::Parse);
}
#[test]
fn error_display_includes_kind_and_position() {
let err = parse("\\frac{1}{2").unwrap_err();
let rendered = err.to_string();
assert!(rendered.starts_with("parse at byte "), "{rendered}");
assert!(rendered.contains("expected `}`"), "{rendered}");
}
#[test]
fn hostile_inputs_never_panic() {
// A small corpus of adversarial inputs: all must produce a structured error
// (or a value), never a panic or an unbounded computation.
let sources = [
"\\",
"\\\\",
"\\\\\\\\",
"\\frac",
"\\frac{}{}",
"\\sqrt{}",
"{}",
"((((",
"))))",
"^^^^",
"----------------x",
"1 + + + +",
"1 // 2",
"\\left(1",
"\\right)",
"\\left[1\\right]",
"1..2",
"..",
"∞",
"1 × 2",
"1 · 2",
"2 ^ 2 ^ 2 ^ 2",
"\\pi 2 3",
"x = ",
"= x",
"x = = y",
"\\frac{1}{2} \\frac{3}{4}",
];
for source in sources {
match parse(source) {
Ok(formula) => {
// If it parses, evaluation must be structured as well.
let _ = evaluate(&formula, &empty(), None);
}
Err(err) => {
assert!(
!err.message.is_empty(),
"structured error must have a message for {source:?}"
);
}
}
}
}
#[test]
fn dot_and_times_are_multiplication_operators() {
assert_int(&eval("2 \\cdot 3", &empty()).unwrap(), 6);
assert_int(&eval("2 \\times 3", &empty()).unwrap(), 6);
assert_int(&eval("2 \\cdot 3 \\times 4", &empty()).unwrap(), 24);
}
#[test]
fn solve_target_on_the_left_of_a_product() {
let bindings = bindings(&[("F", Value::int(20)), ("a", Value::int(5))]);
assert_int(&solve("m a = F", &bindings, "m").unwrap(), 4);
assert_int(&solve("(m + 1) a = F", &bindings, "m").unwrap(), 3);
}
#[test]
fn substitution_with_float_and_negative_bindings_reparses() {
// A Float binding is substituted as its exact numeric value, and the
// canonical rendering must evaluate to the same value as the direct form.
let formula = parse("x * 2").unwrap();
let x_is_float = bindings(&[("x", Value::Float(2.5))]);
let substituted = substitute(&formula, &x_is_float).unwrap();
let direct = evaluate(&formula, &x_is_float, None).unwrap();
let re_evaluated = evaluate(&parse(&substituted.source).unwrap(), &empty(), None).unwrap();
assert_eq!(direct, re_evaluated);
assert_int(&direct, 5);
// Negative substituted literals keep a parseable rendering.
let formula = parse("x + 1").unwrap();
let x_is_negative = bindings(&[("x", Value::int(-3))]);
let substituted = substitute(&formula, &x_is_negative).unwrap();
let value = evaluate(&parse(&substituted.source).unwrap(), &empty(), None).unwrap();
assert_int(&value, -2);
}
#[test]
fn large_exact_results_are_returned_as_integers() {
let Value::Int(value) = eval("2 ^ 10000", &empty()).unwrap() else {
panic!("expected an Int");
};
assert_eq!(value.bits(), 10001);
// A non-perfect square of the same order remains representable as Float.
assert!(matches!(
eval("\\sqrt{2}", &empty()).unwrap(),
Value::Float(_)
));
}
#[test]
fn long_operator_chains_within_the_node_budget_still_evaluate() {
// Each `+`/`*` needs two leaf nodes plus one operator node, so 200
// operators stay inside the documented 512-node budget.
let source = format!("{}1", "1 + ".repeat(200));
assert_int(&eval(&source, &empty()).unwrap(), 201);
let source = format!("{}1", "2 * ".repeat(200));
assert_eq!(
eval(&source, &empty()).unwrap(),
Value::Int(BigInt::from(2).pow(200))
);
}
#[test]
fn oversized_formulas_are_rejected_with_a_structured_error() {
// Well over the documented node budget, but not deep enough to be caught by
// the nesting guard: this must be a parse error, not a stack overflow.
let source = format!("{}1", "1 + ".repeat(200_000));
let err = parse(&source).unwrap_err();
assert_eq!(err.kind, MathErrorKind::Parse);
}