//! Marqdo AST (Phase I). use std::collections::HashMap; use crate::diagnostics::Span; use crate::formula::Expr as FormulaExpr; use crate::value::CodeBlock; /// Frontmatter file import under nested `import:\n bind: path.mq.md` (see `doc/design/module-namespace.md`). #[derive(Debug, Clone)] pub struct Import { pub path: String, pub bind: String, } /// Frontmatter short-name bind under nested `import:\n bind: lib.member` (same map as file import). #[derive(Debug, Clone)] pub struct Use { pub path: Vec, pub bind: String, } #[derive(Debug, Clone)] pub struct Module { pub imports: Vec, pub uses: Vec, pub functions: Vec, /// Populated by the loader: bind name → imported module (not flattened). pub import_modules: HashMap, /// Unresolved Artifact Metadata (from frontmatter); filled by parse. pub metadata_raw: Vec<(String, crate::binding::MetaValue)>, /// Bound metadata after load-time Binding resolve (insertion order). pub metadata: Vec<(String, crate::value::Value)>, } impl Default for Module { fn default() -> Self { Self { imports: Vec::new(), uses: Vec::new(), functions: Vec::new(), import_modules: HashMap::new(), metadata_raw: Vec::new(), metadata: Vec::new(), } } } #[derive(Debug, Clone)] pub struct Param { pub name: String, pub default: Option, /// True when collected by v0.3 body/prose inference (not an explicit `+` line). pub inferred: bool, } #[derive(Debug, Clone)] pub struct Function { pub name: String, /// Heading depth 1–6. Level 1 = object/type; level ≥ 2 = function/method. pub level: u8, pub span: Span, pub params: Vec, pub body: Vec, pub children: Vec, /// Base type name for `# Child = > Parent` (objects only). pub base: Option, /// Prose `` `名` `` never read/assigned on the executable surface (not params). pub dead_binds: Vec, /// 渐进式契约(T2.1):形参/返回/对象字段契约(附着在文档表上,升参推断前提取)。 pub contract: Option, /// 集合契约(T2.1):变量名 → 字段契约(紧邻 `` `名` = `` 绑定之前的文档表)。 pub var_contracts: HashMap, } impl Function { /// `# Name` — object / type (constructor body). pub fn is_object(&self) -> bool { self.level == 1 } } /// Whether this function needs an instance receiver. /// /// A direct child of a level-1 object may be an associated function: when its /// executable body does not read `self` / `自`, it can be invoked through its /// definition path (`lib.Type.fact`). Child declarations are not traversed; /// each declaration owns its own receiver requirement. pub fn function_uses_receiver(fun: &Function) -> bool { fn is_receiver(name: &str) -> bool { matches!(name, "self" | "自") } fn expr_uses_receiver(expr: &Expr) -> bool { match expr { Expr::Var(name) => is_receiver(name), Expr::Interp(parts) => parts.iter().any(|part| match part { InterpPart::Var(name) | InterpPart::Index { base: name, .. } => is_receiver(name), InterpPart::Lit(_) => false, }), Expr::Unary { expr, .. } => expr_uses_receiver(expr), Expr::Binary { left, right, .. } => { expr_uses_receiver(left) || expr_uses_receiver(right) } Expr::Call(call) => { call.receiver.as_deref().is_some_and(is_receiver) || call.args.iter().any(|arg| match arg { Arg::Positional(value) | Arg::Named { value, .. } => expr_uses_receiver(value), }) } Expr::List(items) => items.iter().any(expr_uses_receiver), Expr::Map(entries) => entries.iter().any(|(_, value)| expr_uses_receiver(value)), Expr::Index { base, label } => { expr_uses_receiver(base) || matches!(label, IndexKey::Var(name) if is_receiver(name)) } Expr::Occluded { payload, .. } => payload.as_deref().is_some_and(expr_uses_receiver), Expr::Literal(_) | Expr::Formula(_) | Expr::Code(_) => false, } } fn stmt_uses_receiver(stmt: &Stmt) -> bool { match stmt { Stmt::Assign { value, .. } | Stmt::Return { value, .. } | Stmt::Expr { value, .. } => { expr_uses_receiver(value) } Stmt::Call { call, .. } => { call.receiver.as_deref().is_some_and(is_receiver) || call.args.iter().any(|arg| match arg { Arg::Positional(value) | Arg::Named { value, .. } => expr_uses_receiver(value), }) } Stmt::Branch { arms, .. } => arms.iter().any(|arm| { arm.condition.as_ref().is_some_and(expr_uses_receiver) || arm.body.iter().any(stmt_uses_receiver) }), Stmt::While { condition, body, .. } => { expr_uses_receiver(condition) || body.iter().any(stmt_uses_receiver) } Stmt::ForEach { collection, body, .. } => { is_receiver(collection) || body.iter().any(stmt_uses_receiver) } } } fun.body.iter().any(stmt_uses_receiver) } /// Source line of a statement (every variant carries a span). pub fn stmt_line(st: &Stmt) -> u32 { match st { Stmt::Assign { span, .. } | Stmt::Return { span, .. } | Stmt::Call { span, .. } | Stmt::Expr { span, .. } | Stmt::Branch { span, .. } | Stmt::While { span, .. } | Stmt::ForEach { span, .. } => span.line, } } /// Depth-first walk over every statement of a function: its body, nested block /// bodies (branch arms / loops) and child functions. /// /// `` slimming: three view modules each re-implemented this recursion; the /// traversal lives here so collectors only supply the per-statement logic. pub fn walk_stmts(fun: &Function, f: &mut impl FnMut(&Stmt)) { fn go(st: &Stmt, f: &mut impl FnMut(&Stmt)) { f(st); match st { Stmt::Branch { arms, .. } => { for arm in arms { for b in &arm.body { go(b, f); } } } Stmt::While { body, .. } | Stmt::ForEach { body, .. } => { for b in body { go(b, f); } } _ => {} } } for st in &fun.body { go(st, f); } for c in &fun.children { walk_stmts(c, f); } } #[derive(Debug, Clone)] pub enum Stmt { Assign { name: String, value: Expr, span: Span, /// Inclusive last source line (covers following `$$` fence or table rows). end_line: u32, }, Return { value: Expr, span: Span, }, /// Statement-form call (`> …`); return value discarded. Call { call: CallExpr, span: Span, }, /// Bold expression statement (`**n + 1**`); value evaluated and discarded. Expr { value: Expr, span: Span, }, Branch { arms: Vec, span: Span, }, While { condition: Expr, body: Vec, span: Span, }, ForEach { item: String, collection: String, /// `` M3: occlusion form `- [描述](遍历 集合 为 变量)` carries prose. label: Option, body: Vec, span: Span, }, } #[derive(Debug, Clone)] pub struct BranchArm { pub condition: Option, // None = else pub body: Vec, } #[derive(Debug, Clone)] pub struct CallExpr { pub callee: String, /// Bare library path segments, e.g. `["time","parse"]` for `time.parse`. /// Mutually exclusive with `receiver` (instance method). pub path: Option>, /// When set, `` `recv`.callee `` method call; receiver is a variable name. pub receiver: Option, pub args: Vec, /// Pre-bracket modifiers: `礼貌 [问候] x` → `["礼貌"]`, expanded to `礼貌=True` at eval. /// See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md). pub pre_modifiers: Vec, /// True when the call was authored with `[callee]` (even with no modifiers). /// View prefers `修饰 [callee] …` / `[callee] …` over `> callee …` when set. pub bracket_marked: bool, } impl CallExpr { /// Fold `pre_modifiers` into leading `name=True` named args (conflicts → Err). pub fn with_modifiers_expanded(&self) -> Result { let mut call = self.clone(); for m in &call.pre_modifiers { if call .args .iter() .any(|a| matches!(a, Arg::Named { name, .. } if name == m)) { return Err(format!( "pre-bracket modifier `{m}` conflicts with named argument `{m}`" )); } } if call.pre_modifiers.is_empty() { return Ok(call); } let mut args = Vec::with_capacity(call.pre_modifiers.len() + call.args.len()); for m in &call.pre_modifiers { args.push(Arg::Named { name: m.clone(), value: Expr::Literal(Literal::Bool(true)), }); } args.append(&mut call.args); call.args = args; call.pre_modifiers.clear(); Ok(call) } } #[derive(Debug, Clone)] pub enum Arg { Positional(Expr), Named { name: String, value: Expr }, } #[derive(Debug, Clone)] pub enum Expr { Literal(Literal), Var(String), /// Text with embedded `` `var` `` segments. Interp(Vec), Unary { op: UnaryOp, expr: Box, }, Binary { op: BinaryOp, left: Box, right: Box, }, Call(CallExpr), List(Vec), /// Object literal / horizontal table (`map` value). Map(Vec<(String, Expr)>), /// Collection index: `` [拿铁](菜单) `` / `` [`名`](菜单) `` (preferred), or /// legacy footnote `` `菜单`[^拿铁] `` / `` `菜单`[^`名`] ``. Index { base: Box, /// Key or 1-based list index; see [`IndexKey`]. label: IndexKey, }, /// Parsed `$$…$$` formula tree (from assignment RHS). Formula(FormulaExpr), /// Bound ```lang … ``` fence (`code` value). Code(CodeBlock), /// `[描述](实现)` — **occlusion**: `label` is inert prose (never executed, /// only scanned for keywords and checked for staleness), `payload` is the /// only thing that runs. `payload: None` means the empty-payload stub /// (`[某某功能开发中]()`), which evaluates to `None`. `` M2 Occluded { label: String, payload: Option>, }, } #[derive(Debug, Clone)] pub enum InterpPart { Lit(String), Var(String), /// `` `base`[^label] `` — variable followed by footnote index inside interpolated /// text (chained labels fold into one part, e.g. `` `x`[^a][^b] `` → two labels). Index { base: String, labels: Vec }, } /// Map / list index key (`[key](coll)` or legacy `[^…]`). #[derive(Debug, Clone, PartialEq, Eq)] pub enum IndexKey { /// Static text: `[拿铁](…)` / `[^拿铁]` / `[^1]`. Lit(String), /// Dynamic: `` [`品名`](…) `` / `` [^`品名`] `` — evaluate variable, then stringify as key. Var(String), } #[derive(Debug, Clone)] pub enum Literal { None, Bool(bool), Int(i64), /// Decimal literal (`0.85`, `3.14`). Num(f64), Text(String), } #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum UnaryOp { Not, Neg, } #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum BinaryOp { Add, Sub, Mul, Div, Eq, Ne, Lt, Le, Gt, Ge, And, Or, } /// Pretty-print AST for `--dump-ast`. pub fn format_ast_dump(path: &str, module: &Module) -> String { let mut out = String::new(); out.push_str(&format!("=== marqdo: ast ({path}) ===\n")); if !module.imports.is_empty() { let specs: Vec = module .imports .iter() .map(|i| format!("import {}:{}", i.bind, i.path)) .collect(); out.push_str(&format!("(imports {:?})\n", specs)); } for fun in &module.functions { dump_fun(&mut out, fun, 0); } out.push_str("=== marqdo: end ast ===\n"); out } fn dump_fun(out: &mut String, fun: &Function, depth: usize) { let pad = " ".repeat(depth); let kind = if fun.is_object() { "object" } else { "fun" }; let params = format_params(&fun.params); let dead = if fun.dead_binds.is_empty() { String::new() } else { format!(" dead={:?}", fun.dead_binds) }; match &fun.base { Some(base) => out.push_str(&format!( "{pad}({kind} level={} {:?} extends={base:?} params={params}{dead} @{}\n", fun.level, fun.name, fun.span )), None => out.push_str(&format!( "{pad}({kind} level={} {:?} params={params}{dead} @{}\n", fun.level, fun.name, fun.span )), } for stmt in &fun.body { dump_stmt(out, stmt, depth + 1); } for child in &fun.children { dump_fun(out, child, depth + 1); } out.push_str(&format!("{pad})\n")); } fn dump_stmt(out: &mut String, stmt: &Stmt, depth: usize) { let pad = " ".repeat(depth); match stmt { Stmt::Assign { name, value, span, end_line, } => { out.push_str(&format!( "{pad}(assign {name:?} {value:?} @{span}..{end_line})\n" )); } Stmt::Return { value, span } => { out.push_str(&format!("{pad}(return {value:?} @{span})\n")); } Stmt::Call { call, span } => { out.push_str(&format!( "{pad}(call recv={:?} {:?} {:?} @{span}\n", call.receiver, call.callee, call.args )); } Stmt::Expr { value, span } => { out.push_str(&format!("{pad}(expr {value:?} @{span})\n")); } Stmt::Branch { arms, span } => { out.push_str(&format!("{pad}(branch @{span}\n")); for arm in arms { out.push_str(&format!("{pad} (arm cond={:?}\n", arm.condition)); for s in &arm.body { dump_stmt(out, s, depth + 2); } out.push_str(&format!("{pad} )\n")); } out.push_str(&format!("{pad})\n")); } Stmt::While { condition, body, span, } => { out.push_str(&format!("{pad}(while {condition:?} @{span}\n")); for s in body { dump_stmt(out, s, depth + 1); } out.push_str(&format!("{pad})\n")); } Stmt::ForEach { item, collection, label: _, body, span, } => { out.push_str(&format!( "{pad}(foreach {item:?} in {collection:?} @{span}\n" )); for s in body { dump_stmt(out, s, depth + 1); } out.push_str(&format!("{pad})\n")); } } } fn format_params(params: &[Param]) -> String { let parts: Vec = params .iter() .map(|p| { let mut s = p.name.clone(); if p.default.is_some() { s.push('?'); } if p.inferred { s.push_str(" inferred"); } s }) .collect(); format!("[{}]", parts.join(", ")) }