Implements the first vertical slices of RFC-CM-0001/0002 on top of a113d89:
- P1: opaque Memory regions (64 KiB pages, budgets, grow-only), byte
read/write, Memory-index place assignment, wire/host-boundary rejection.
- CM-A04/A05: value-semantics List/Map/Text/Table primitives and the
recoverable Result map convention.
- CM-A06: opaque Resource handles, resource.open/read/write/close, stdout
write, granted project-file read and buffered write, strict fail-closed.
- CM-A07 Compat-A: explicit .mq.md format/utf8/io chain matching builtin
print for the covered value types; builtin remains default.
- P2 fixtures: allocators, list/tree/graph/hash, integer codecs, UTF-8
encode/decode, CSV/JSON subsets, table filter/sort/join, bytecode VM.
- ADRs 0022-0027, spec updates, evidence reports and 68 semantic goldens.
Gate: cargo fmt --check, clippy -D warnings, 407 tests passed.
228 lines
7.7 KiB
Rust
228 lines
7.7 KiB
Rust
//! Strict, independent expression and statement parser for executable Markdown
|
|
//! payloads.
|
|
//!
|
|
//! This crate is the only grammar for Marqdo executable payloads. It knows
|
|
//! nothing about Markdown and nothing about the runtime: the Markdown AST
|
|
//! decides *where* a payload exists, this crate decides *what the payload
|
|
//! means* (see `spec/expression.ebnf` and `spec/evaluation.md`).
|
|
//!
|
|
//! # Public API
|
|
//!
|
|
//! ```rust
|
|
//! use marqdo_expression::{parse_expression, parse_statement};
|
|
//!
|
|
//! let stmt = parse_statement("结果 = 阶乘(n=3)").unwrap();
|
|
//! assert_eq!(stmt.span().start, 0);
|
|
//!
|
|
//! let expr = parse_expression("2 ** -1").unwrap();
|
|
//! assert_eq!(expr.span().start, 0);
|
|
//! ```
|
|
//!
|
|
//! The contractual surface is:
|
|
//!
|
|
//! * [`parse_expression`] — parse a complete expression payload.
|
|
//! * [`parse_statement`] — parse a complete statement payload (assignment or
|
|
//! expression).
|
|
//! * [`parse_arguments`] — parse a leading `( ... )` argument list, used for
|
|
//! Markdown-link calls such as `> [计算面积](./math.mq.md#计算面积)(r=3)`.
|
|
//! * the [`ast`] module (re-exported at the crate root).
|
|
//! * [`ParseError`] — structured `expr.parse` diagnostics with byte spans.
|
|
//!
|
|
//! Everything else, including [`lexer`], is an implementation detail that is
|
|
//! exposed only to make diagnostics and tests easier.
|
|
//!
|
|
//! # Grammar summary
|
|
//!
|
|
//! The grammar is frozen in `spec/expression.ebnf`. In order of decreasing
|
|
//! precedence: prefix `not` / `-` / `+`, `**` (right associative), postfix
|
|
//! calls `.name` / `[index]`, `* / // %`, `+ -`, a single non-associative
|
|
//! comparison, `and`, `or`. Assignment is only available at statement start;
|
|
//! its target is a bare identifier or an index expression (`m[8] = 42`).
|
|
//!
|
|
//! Notable lexical rules:
|
|
//!
|
|
//! * identifiers use Unicode XID (`XID_Start XID_Continue*`), so `阶乘` and
|
|
//! `café` are identifiers;
|
|
//! * `true`, `false`, `None`, `and`, `or`, `not` are reserved keywords;
|
|
//! * integers are arbitrary-precision decimal literals;
|
|
//! * floats require digits on both sides of `.` (`.5` and `1.` are invalid)
|
|
//! and may carry an exponent;
|
|
//! * text literals are double quoted and support `\\`, `\"`, `\n`, `\t`, `\r`
|
|
//! and `\u{...}` escapes;
|
|
//! * comments are not supported;
|
|
//! * nesting deeper than [`MAX_NESTING_DEPTH`] is a structured parse error, so
|
|
//! hostile payloads cannot overflow the parser stack.
|
|
//!
|
|
//! # Spans and errors
|
|
//!
|
|
//! Spans are half-open byte offsets relative to the payload string. Errors use
|
|
//! the stable diagnostic code [`EXPR_PARSE`] (`"expr.parse"`) and follow the
|
|
//! same shape used elsewhere in the toolchain (code + message + span).
|
|
//!
|
|
//! # Example payloads
|
|
//!
|
|
//! ```rust
|
|
//! use marqdo_expression::parse_statement;
|
|
//!
|
|
//! let stmt = parse_statement("打印(\"面积 = \" + 文本(area))").unwrap();
|
|
//! assert!(matches!(
|
|
//! stmt.kind,
|
|
//! marqdo_expression::StatementKind::Expr(_)
|
|
//! ));
|
|
//! ```
|
|
//!
|
|
//! The parser never panics on malformed input: every failure is a
|
|
//! [`ParseError`].
|
|
|
|
#![forbid(unsafe_code)]
|
|
|
|
pub mod ast;
|
|
pub mod lexer;
|
|
mod parser;
|
|
|
|
use std::fmt;
|
|
|
|
use serde::Serialize;
|
|
|
|
pub use ast::{
|
|
Arg, AssignTarget, BinaryOp, Expr, Ident, RecordEntry, Statement, StatementKind, UnaryOp,
|
|
};
|
|
pub use marqdo_span::Span;
|
|
pub use parser::MAX_NESTING_DEPTH;
|
|
|
|
/// Stable diagnostic code for every expression parse failure.
|
|
pub const EXPR_PARSE: &str = "expr.parse";
|
|
|
|
/// A structured expression/statement parse failure.
|
|
///
|
|
/// `code` is always [`EXPR_PARSE`]. `span` is a byte range into the payload
|
|
/// string and may be empty (for example at end of input).
|
|
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
|
|
pub struct ParseError {
|
|
/// Stable diagnostic code, always `"expr.parse"`.
|
|
pub code: &'static str,
|
|
/// Human readable explanation of the failure.
|
|
pub message: String,
|
|
/// Byte range in the payload where the failure was detected.
|
|
pub span: Span,
|
|
}
|
|
|
|
impl ParseError {
|
|
/// Create a parse error with the fixed `expr.parse` code.
|
|
pub fn new(span: Span, message: impl Into<String>) -> Self {
|
|
Self {
|
|
code: EXPR_PARSE,
|
|
message: message.into(),
|
|
span,
|
|
}
|
|
}
|
|
|
|
/// Stable diagnostic code (always `"expr.parse"`).
|
|
pub fn code(&self) -> &'static str {
|
|
self.code
|
|
}
|
|
}
|
|
|
|
impl fmt::Display for ParseError {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
write!(f, "{}: {} at {}", self.code, self.message, self.span)
|
|
}
|
|
}
|
|
|
|
impl std::error::Error for ParseError {}
|
|
|
|
/// Parse a complete expression payload.
|
|
///
|
|
/// The whole input must be consumed; empty input, trailing tokens, unsupported
|
|
/// constructs and assignments are [`ParseError`]s.
|
|
pub fn parse_expression(source: &str) -> Result<Expr, ParseError> {
|
|
parser::parse_expression(source)
|
|
}
|
|
|
|
/// Parse a complete statement payload.
|
|
///
|
|
/// A statement is either `<bare identifier> = <expression>` or a bare
|
|
/// expression (typically a call). The whole input must be consumed.
|
|
pub fn parse_statement(source: &str) -> Result<Statement, ParseError> {
|
|
parser::parse_statement(source)
|
|
}
|
|
|
|
/// Parse a leading parenthesised argument list.
|
|
///
|
|
/// `source` must start with `(` and contain exactly one argument list, e.g.
|
|
/// `(r=3, precision=2)`. Argument rules are identical to call arguments:
|
|
/// positional arguments precede named arguments, named arguments are unique,
|
|
/// and a single trailing comma is allowed. Trailing tokens are an error.
|
|
///
|
|
/// This exists so the frontend can parse Markdown-link calls of the form
|
|
/// `> [计算面积](./math.mq.md#计算面积)(r=3)` without re-lexing the payload.
|
|
pub fn parse_arguments(source: &str) -> Result<Vec<Arg>, ParseError> {
|
|
parser::parse_arguments(source)
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn public_api_parses_expression_and_statement() {
|
|
assert!(parse_expression("1 + 2 * 3").is_ok());
|
|
assert!(parse_statement("x = 1").is_ok());
|
|
assert!(parse_arguments("(r=3)").is_ok());
|
|
}
|
|
|
|
#[test]
|
|
fn empty_payloads_are_errors() {
|
|
for source in ["", " ", "\n\t"] {
|
|
let err = parse_expression(source).unwrap_err();
|
|
assert_eq!(err.code, EXPR_PARSE);
|
|
assert_eq!(err.code(), "expr.parse");
|
|
assert!(err.message.contains("expression"));
|
|
|
|
let err = parse_statement(source).unwrap_err();
|
|
assert_eq!(err.code, EXPR_PARSE);
|
|
assert!(err.message.contains("statement"));
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn parse_error_displays_code_and_span_and_implements_error() {
|
|
let err = parse_expression("1 2").unwrap_err();
|
|
let rendered = err.to_string();
|
|
assert!(rendered.starts_with("expr.parse: "), "{rendered}");
|
|
assert!(rendered.contains("2..3"), "{rendered}");
|
|
assert!(rendered.contains("unexpected"), "{rendered}");
|
|
|
|
let dyn_error: &dyn std::error::Error = &err;
|
|
assert!(dyn_error.source().is_none());
|
|
|
|
let custom = ParseError::new(Span::new(4, 9), "boom");
|
|
assert_eq!(custom.code, "expr.parse");
|
|
assert_eq!(custom.message, "boom");
|
|
assert_eq!(custom.span, Span::new(4, 9));
|
|
}
|
|
|
|
#[test]
|
|
fn ast_types_are_reachable_from_the_crate_root() {
|
|
let expr: Expr = parse_expression("f(1)").unwrap();
|
|
let statement: Statement = parse_statement("f(1)").unwrap();
|
|
let _: StatementKind = statement.kind;
|
|
let _: BinaryOp = BinaryOp::Add;
|
|
let _: UnaryOp = UnaryOp::Not;
|
|
let _: Arg = Arg {
|
|
name: None,
|
|
value: expr,
|
|
span: Span::default(),
|
|
};
|
|
let _: RecordEntry = RecordEntry {
|
|
key: "k".to_owned(),
|
|
key_span: Span::default(),
|
|
value: Expr::None,
|
|
};
|
|
let _: Ident = Ident {
|
|
name: "x".to_owned(),
|
|
span: Span::default(),
|
|
};
|
|
}
|
|
}
|