feat(markup): code-as-docs narration surface (G1–G4) and drop --- body end

Treat --- as Markdown HR everywhere, end side-effect helpers with empty returns,
and accept soft emphasis, float literals, and dynamic footnote keys so LLM-friendly
.mq.md stays runnable. Ship the weekend coffee example plus gold fixtures.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-09-14 10:16:48 +08:00
1 parent b5c07385e9
commit 5e74ff39f2
28 files changed
+799 -99

No files matched your search

+97 -11
View File
@@ -2,7 +2,7 @@
use anyhow::{bail, Result};
use crate::ast::{BinaryOp, CallExpr, Expr, InterpPart, Literal, UnaryOp};
use crate::ast::{BinaryOp, CallExpr, Expr, IndexKey, InterpPart, Literal, UnaryOp};
pub fn parse_expr(input: &str) -> Result<Expr> {
parse_expr_mode(input, false)
@@ -195,7 +195,7 @@ pub fn parse_interp(s: &str) -> Expr {
for label in labels {
e = Expr::Index {
base: Box::new(e),
label: label.clone(),
label: IndexKey::Lit(label.clone()),
};
}
return e;
@@ -516,11 +516,36 @@ impl<'a> Parser<'a> {
self.i += '空'.len_utf8();
return Ok(Expr::Literal(Literal::None));
}
if self.peek_char().map(|c| c.is_ascii_digit()).unwrap_or(false) {
if self.peek_char().map(|c| c.is_ascii_digit()).unwrap_or(false)
|| (self.peek_char() == Some('.')
&& self
.rest()
.chars()
.nth(1)
.map(|c| c.is_ascii_digit())
.unwrap_or(false))
{
let start = self.i;
while self.peek_char().map(|c| c.is_ascii_digit()).unwrap_or(false) {
self.bump_char();
}
if self.peek_char() == Some('.') {
self.bump_char();
let frac_start = self.i;
while self.peek_char().map(|c| c.is_ascii_digit()).unwrap_or(false) {
self.bump_char();
}
// Require at least one digit on one side of the dot.
let int_part = &self.src[start..frac_start.saturating_sub(1)];
let frac_part = &self.src[frac_start..self.i];
if int_part.is_empty() && frac_part.is_empty() {
bail!("invalid number literal");
}
let n: f64 = self.src[start..self.i]
.parse()
.map_err(|e| anyhow::anyhow!("invalid float: {e}"))?;
return Ok(Expr::Literal(Literal::Num(n)));
}
let n: i64 = self.src[start..self.i].parse()?;
return Ok(Expr::Literal(Literal::Int(n)));
}
@@ -691,7 +716,7 @@ impl<'a> Parser<'a> {
for label in labels {
e = Expr::Index {
base: Box::new(e),
label,
label: IndexKey::Lit(label),
};
}
e
@@ -736,11 +761,36 @@ impl<'a> Parser<'a> {
}
}
/// Parse `[^label]` after a value; label is text until `]`.
fn parse_footnote_label(&mut self) -> Result<String> {
/// Parse `[^label]` or `` [^`ident`] `` after a value.
fn parse_footnote_label(&mut self) -> Result<IndexKey> {
if !self.eat("[^") {
bail!("expected [^ footnote index");
}
self.skip_ws();
if self.eat("`") {
let start = self.i;
while let Some(c) = self.peek_char() {
if c == '`' {
break;
}
if c == '\n' || c == '\r' || c == ']' {
bail!("unterminated footnote var `[^`…`]`");
}
self.bump_char();
}
let name = self.src[start..self.i].trim().to_string();
if !self.eat("`") {
bail!("unterminated footnote var `[^`…`]`");
}
self.skip_ws();
if !self.eat("]") {
bail!("unterminated footnote index [^…]");
}
if name.is_empty() {
bail!("empty footnote var `[^`]`");
}
return Ok(IndexKey::Var(name));
}
let start = self.i;
while let Some(c) = self.peek_char() {
if c == ']' {
@@ -758,7 +808,7 @@ impl<'a> Parser<'a> {
if label.is_empty() {
bail!("empty footnote index `[^]`");
}
Ok(label)
Ok(IndexKey::Lit(label))
}
}
@@ -1038,7 +1088,7 @@ mod tests {
match e {
Expr::Index { base, label } => {
assert!(matches!(base.as_ref(), Expr::Var(n) if n == "ev"));
assert_eq!(label, "result");
assert_eq!(label, IndexKey::Lit("result".into()));
}
other => panic!("expected Index, got {other:?}"),
}
@@ -1214,13 +1264,25 @@ mod tests {
}
// Bare `m`[^key] with no prefix → Expr::Index
let e = parse_interp("`m`[^苹果]");
assert!(matches!(e, Expr::Index { label, .. } if label == "苹果"));
assert!(matches!(
e,
Expr::Index {
label: IndexKey::Lit(ref s),
..
} if s == "苹果"
));
// Chained labels fold into one Index part with multiple labels.
let e = parse_interp("`m`[^a][^b]");
match &e {
Expr::Index { base, label } => {
assert!(matches!(base.as_ref(), Expr::Index { label: l, .. } if l == "a"));
assert_eq!(label, "b");
assert!(matches!(
base.as_ref(),
Expr::Index {
label: IndexKey::Lit(ref l),
..
} if l == "a"
));
assert_eq!(label, &IndexKey::Lit("b".into()));
}
other => panic!("expected chained Index, got {other:?}"),
}
@@ -1241,6 +1303,30 @@ mod tests {
other => panic!("expected Interp, got {other:?}"),
}
}
#[test]
fn float_literal_and_dynamic_footnote_key() {
let e = parse_expr("0.85").unwrap();
assert!(matches!(e, Expr::Literal(Literal::Num(n)) if (n - 0.85).abs() < 1e-12));
let e = parse_expr("28 * 0.85").unwrap();
assert!(matches!(e, Expr::Binary { op: BinaryOp::Mul, .. }));
let e = parse_expr_prefer_var("菜单[^`名`]").unwrap();
match e {
Expr::Index { base, label } => {
assert!(matches!(base.as_ref(), Expr::Var(n) if n == "菜单"));
assert_eq!(label, IndexKey::Var("名".into()));
}
other => panic!("expected dynamic Index, got {other:?}"),
}
let e = parse_expr("m[^拿铁]").unwrap();
assert!(matches!(
e,
Expr::Index {
label: IndexKey::Lit(ref s),
..
} if s == "拿铁"
));
}
}
+48 -8
View File
@@ -12,7 +12,7 @@ pub use prose::{scan_prose_line, ProseBit};
use anyhow::{bail, Result};
use crate::ast::{
BranchArm, Expr, Function, Import, Literal, Module, Param, Stmt, Use,
BranchArm, Expr, Function, Import, IndexKey, Literal, Module, Param, Stmt, Use,
};
use crate::diagnostics::{bail_at, Diagnostic, Span};
use crate::lex::{classify_source, ClassifiedLine, LineKind};
@@ -33,8 +33,18 @@ pub fn parse_classified(lines: &[ClassifiedLine]) -> Result<Module> {
while cur.skip_noise() {
let Some(line) = cur.peek() else { break };
let trimmed = line.text.trim();
// Module-level Markdown thematic breaks (`---` / `***`) are narrative skip.
if is_frame(trimmed) {
cur.bump();
continue;
}
if is_heading(trimmed) {
functions.push(cur.parse_function(1)?);
} else if line.kind == LineKind::Comment {
// Intro paragraphs may still contain return-shaped italics (`返回*值*`)
// or leftover soft emphasis; executable prose belongs inside functions.
cur.bump();
continue;
} else {
bail!(
"{}:1: expected heading (`#` object or `##` function), got: {trimmed}",
@@ -246,13 +256,19 @@ impl<'a> Cursor<'a> {
value: Expr::Literal(Literal::None),
span,
});
break;
// Objects (`#`) may still declare `##` methods after the constructor return.
if level >= 2 {
break;
}
continue;
}
// --- / *** at function body top level ends the function (no return).
// `---` / `***` = Markdown thematic break (narrative skip), not function end.
// Side-effect-only helpers end with `*None*` / whole-line `**` / `****`, or at
// the next heading / EOF.
if is_frame(trimmed) {
self.bump();
break;
continue;
}
if is_heading(trimmed) {
@@ -271,6 +287,7 @@ impl<'a> Cursor<'a> {
col: 1,
};
let bits = scan_prose_line(line.text.trim_end_matches(['\r', '\n']));
let mut end_body = false;
for bit in bits {
match bit {
ProseBit::Decl { name, default, .. } => {
@@ -284,9 +301,16 @@ impl<'a> Cursor<'a> {
}
ProseBit::ItalicReturn { inner, .. } => {
fun.body.push(stmt_from_italic_return(&inner, span.clone())?);
// `##`+ : return ends the function so outer/sibling lines attach.
// `#` objects: keep scanning for method headings.
end_body = level >= 2;
break;
}
}
}
if end_body {
break;
}
continue;
}
@@ -299,7 +323,12 @@ impl<'a> Cursor<'a> {
continue;
}
fun.body.push(self.parse_simple_stmt()?);
let stmt = self.parse_simple_stmt()?;
let end_body = matches!(stmt, Stmt::Return { .. }) && level >= 2;
fun.body.push(stmt);
if end_body {
break;
}
}
merge_inferred_params(&mut fun, &prose_decls)?;
@@ -315,7 +344,8 @@ impl<'a> Cursor<'a> {
let trimmed = line.text.trim();
if is_frame(trimmed) {
bail!("{span}: unexpected frame line as statement");
// Should be skipped by callers; keep defensive message if reached.
bail!("{span}: unexpected frame line as statement (use empty return `*None*` / `**` / `****` to end a side-effect body)");
}
if trimmed.starts_with("$$") {
@@ -844,7 +874,12 @@ impl<'a> Cursor<'a> {
body.push(self.parse_loop_or_err()?);
continue;
}
body.push(self.parse_simple_stmt()?);
let stmt = self.parse_simple_stmt()?;
let end_arm = matches!(stmt, Stmt::Return { .. });
body.push(stmt);
if end_arm {
break;
}
}
Ok(body)
}
@@ -1372,7 +1407,12 @@ fn collect_reads_expr(expr: &Expr, reads: &mut std::collections::HashSet<String>
collect_reads_expr(right, reads);
}
Expr::Unary { expr, .. } => collect_reads_expr(expr, reads),
Expr::Index { base, .. } => collect_reads_expr(base, reads),
Expr::Index { base, label } => {
collect_reads_expr(base, reads);
if let IndexKey::Var(n) = label {
reads.insert(n.clone());
}
}
Expr::List(xs) => {
for x in xs {
collect_reads_expr(x, reads);
+106 -13
View File
@@ -1,4 +1,7 @@
//! Inline prose scan for Markup v0.3 (叙述中的 `` `名` `` / `**代码**` / `*返回*`).
//!
//! Soft Markdown emphasis that does not look like code/return is skipped (G2 —
//! [code-as-docs-gaps.md](../../../doc/design/code-as-docs-gaps.md)).
use crate::lex::{matching_bold_close_inline, matching_italic_close_inline};
@@ -36,13 +39,12 @@ pub fn scan_prose_line(line: &str) -> Vec<ProseBit> {
if c == b'*' && i + 1 < bytes.len() && bytes[i + 1] == b'*' {
let rest = &line[i..];
if let Some(close_rel) = matching_bold_close_inline(rest) {
// close_rel is index within `rest` of first `*` of closing `**`
let inner = rest[2..close_rel].to_string();
out.push(ProseBit::BoldCode {
inner,
at: i,
});
i += close_rel + 2;
let next = i + close_rel + 2;
if looks_like_bold_code(&inner) {
out.push(ProseBit::BoldCode { inner, at: i });
}
i = next;
continue;
}
i += 1;
@@ -56,11 +58,11 @@ pub fn scan_prose_line(line: &str) -> Vec<ProseBit> {
}
if let Some(close_rel) = matching_italic_close_inline(rest) {
let inner = rest[1..close_rel].to_string();
out.push(ProseBit::ItalicReturn {
inner,
at: i,
});
i += close_rel + 1;
let next = i + close_rel + 1;
if looks_like_italic_return(line, i, next, &inner) {
out.push(ProseBit::ItalicReturn { inner, at: i });
}
i = next;
continue;
}
}
@@ -69,6 +71,79 @@ pub fn scan_prose_line(line: &str) -> Vec<ProseBit> {
out
}
/// Whether `**inner**` should execute (assign / call / expr), not soft emphasis.
pub fn looks_like_bold_code(inner: &str) -> bool {
let t = inner.trim();
if t.is_empty() {
return false;
}
if t.contains('=') || t.starts_with('>') {
return true;
}
if t.chars().any(|c| matches!(c, '+' | '-' | '*' | '/' | '(' | ')' | '[' | ']')) {
return true;
}
let parts: Vec<&str> = t.split_whitespace().collect();
if parts.len() >= 2 {
return parts[1..].iter().any(|p| {
p.contains('=')
|| p.starts_with('"')
|| p.starts_with('\'')
|| p.starts_with('`')
|| p.chars().all(|c| c.is_ascii_digit())
|| (p.contains('.')
&& p.chars()
.filter(|c| *c != '.')
.all(|c| c.is_ascii_digit()))
});
}
false
}
/// Whether `*inner*` is a return (vs mid-prose English/CJK emphasis).
fn looks_like_italic_return(line: &str, at: usize, after: usize, inner: &str) -> bool {
let t = inner.trim();
if t.is_empty()
|| matches!(
t,
"None" | "无" | "空" | "True" | "False" | "真" | "假" | "true" | "false"
)
{
return true;
}
if t.starts_with('>')
|| t.contains('=')
|| t.chars()
.any(|c| matches!(c, '+' | '-' | '*' | '/' | '(' | ')' | '[' | ']'))
{
return true;
}
// Whole-line return: only ws outside the italic span.
let before = line[..at].trim();
let after_s = line.get(after..).unwrap_or("").trim();
if before.is_empty() && after_s.is_empty() {
return true;
}
// Narration "返回*n*" / "return *n*"
if before.ends_with("返回") || before.ends_with("return") || before.ends_with("Return") {
return true;
}
// Mid-prose simple word → soft emphasis (G2).
if is_simple_emphasis_word(t) {
return false;
}
// Multi-token or dotted id mid-line: keep as return (rare).
true
}
fn is_simple_emphasis_word(t: &str) -> bool {
if t.chars().any(|c| c.is_whitespace()) {
return false;
}
t.chars()
.all(|c| c.is_alphanumeric() || c == '_' || !c.is_ascii())
}
fn scan_backtick_decl(line: &str, start: usize) -> Option<(ProseBit, usize)> {
let rest = &line[start + 1..];
let end = rest.find('`')?;
@@ -78,9 +153,7 @@ fn scan_backtick_decl(line: &str, start: usize) -> Option<(ProseBit, usize)> {
}
let after_tick = start + 1 + end + 1;
let after = line.get(after_tick..)?;
// `` `名`=默认 `` — optional default glued after closing tick
if let Some(stripped) = after.strip_prefix('=') {
// default runs until whitespace or CJK punctuation-ish break for prose
let def_end = stripped
.find(|c: char| {
c.is_whitespace()
@@ -147,4 +220,24 @@ mod tests {
_ => panic!("{:?}", bits[0]),
}
}
#[test]
fn soft_bold_emphasis_skipped() {
let bits = scan_prose_line("本文件既是**说明**也是**程序**。");
assert!(bits.is_empty(), "{bits:?}");
assert!(!looks_like_bold_code("说明"));
assert!(looks_like_bold_code("n=n+1"));
assert!(looks_like_bold_code("加一 37"));
}
#[test]
fn soft_italic_emphasis_skipped() {
let bits = scan_prose_line("When soft=True, *only* FIND continues.");
assert!(bits.is_empty(), "{bits:?}");
let bits = scan_prose_line("*总额*");
assert!(
matches!(&bits[..], [ProseBit::ItalicReturn { inner, .. }] if inner == "总额"),
"{bits:?}"
);
}
}