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:
1 parent
b5c07385e9
commit
5e74ff39f2
28 files changed
+799
-99
No files matched your search
+97
-11
@@ -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
@@ -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
@@ -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:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user