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:
1 parent
17b68da7f9
commit
f6c3efa849
9 files changed
+4032
-2
No files matched your search
@@ -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());
|
||||
}
|
||||
}
|
||||
@@ -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"));
|
||||
}
|
||||
@@ -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 }
|
||||
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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"
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -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)?))),
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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"));
|
||||
}
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
Reference in new issue
Block a user