mooncalc

    Excel-compatible spreadsheet formula engine in MoonBit

    excel
    formula
    spreadsheet
    engine
    Download zip
    Version
    0.4.0
    License
    MIT
    Last updated
    4 hours ago
    Downloads
    19

    #MoonCalc

    Excel 兼容的电子表格公式引擎,用 MoonBit 编写。

    状态(2026-11-17,M8 完成):60 函数引擎(MoonBit)+核心引用语义(跨表 Sheet!A1、工作簿级定义名称、整列整行 A:A/2:2,ADR 0008)、native CLI、wasm-gc playground、mbtexcel 读→算→写示例(多表版);AST 缓存(热态约 2.6×)、增量重算(改一格 5×)、可选迭代计算、错误解释 API(explain + 依赖图)。真实 Excel 答案键语料 1,267/1,267(100%)(桌面 Excel 2024 · 16.0.20527.20196 · zh-CN 生成;2 条奇数参数 IFS + 3 条非法/重复定义名称被 Excel 拒绝录入,显式标为子集外;5 条超出声明子集的探针另存 corpus/excluded/ 不计分),无未归因失败:1,247 精确命中 + 3 clock-tolerance + 16 excel-precision + 1 surrogate-representation。另有 12 条 M8 语义探针(corpus/probes/)与 mbtexcel 0.3.2 的差分对照(docs/comparison-mbtexcel.md)。2026 MoonBit 年度黑客松 11 月赛参赛项目。

    #这是什么

    MoonCalc 接收一组单元格——每个单元格承载字面值或公式——按 Excel 语义求值并返回结果或错误值。它不读写 .xlsx 文件,文件读写交给 mbtexcel 这类工具,MoonCalc 只负责计算。

    项目走“窄而深”的路线:实现 60 个核心函数,覆盖逻辑、文本、数学、统计、查找、日期六族;每个函数的弱类型强制转换、错误值传播和边界情形都要严格对照真实 Excel。正确性用真实 Excel 生成的答案键语料逐条验证,对外公开用例数和通过率,未通过的用例逐条归因。

    #浏览器演示

    在线 playground(push main 自动部署):https://buguoshixc.github.io/mooncalc/

    错误传播与增量重算

    错误传播 + explain 上溯:选中错误格 B1,详情面板给出传播链与错误源;改 A1 后只重算下游 3 个公式格(计数器 3/4 · incremental,无关的 E1 不重算)。

    迭代计算收敛

    勾选「Iterative calculation」(Excel 默认 ≤100 次、最大变化 0.001),循环引用从 0 收敛到 ≈20/≈10;取消勾选回到 Excel 默认(环上 = 0)。

    #快速开始

    export PATH="$HOME/.moon/bin:$PATH" # 全量验证:双目标构建 + 159 项单测 + 零 IO 守卫 bash scripts/check.sh # CLI:求值一个含引用链/错误传播/循环引用的网格 moon build --target native _build/native/debug/build/buguoshixc/mooncalc/cmd/main/main.exe eval --grid tests/fixtures/grid.json # 跑分:真实 Excel 权威语料(默认 corpus/cases) bash scripts/run-bench.sh # 性能基准:进程内大网格重算(默认 1 万格,见 docs/performance.md) moon build --target native --release _build/native/release/build/buguoshixc/mooncalc/cmd/main/main.exe perf --cells 100000 # 浏览器 playground(wasm-gc):支持 CSV 拖拽/按钮导入(行主序,=公式格可直接算) bash scripts/build-playground.sh (cd playground && python3 -m http.server 8080) # 打开 http://localhost:8080/ # headless Chromium 冒烟(39 断言,零 npm 依赖) node scripts/smoke.mjs

    在线 playground 已部署 GitHub Pages:https://buguoshixc.github.io/mooncalc/(push main 自动构建部署,见 .github/workflows/pages.yml)。

    #XLSX 读 → 算 → 写(示例壳,核心零改动)

    examples/xlsx-demo 演示与 moonbitlang/mbtexcel 组合的完整链路(M8 多表版):3 个工作表 + 工作簿级名称,mbtexcel 读 xlsx → 按 SHEET!A1 契约组装网格 → MoonCalc 进程内求值(跨表/名称/整列整行)→ 按宿主表回写缓存值 → 逐表读回断言 65 项。文件 IO 只发生在示例壳层,引擎本体保持纯计算。

    export PATH="$HOME/.moon/bin:$PATH" moon run examples/xlsx-demo --target native -- gen # 生成 fixture _build/xlsx-demo/input.xlsx moon run examples/xlsx-demo --target native -- run # 3 表读→算→写 output.xlsx,并逐表读回断言 # xlsx-demo verification PASS: 65/65 (formula + cached value + literal + expected-result checks)

    完整演示脚本见 docs/demo.md。

    #作为 mooncakes 库使用

    已发布:mooncakes.io/buguoshixc/mooncalc(0.3.0;M8 版 0.4.0 已就绪、moon publish --dry-run 通过,API 文档由平台依据 /// 注释自动生成)。

    moon add buguoshixc/mooncalc

    在包清单 moon.pkg 中 import:

    import {
    "buguoshixc/mooncalc" @mooncalc,
    }

    最小用法(内存网格 → 重算 → 读结果;文件 IO 与时钟注入由调用方负责):

    fn main {
    let grid = @mooncalc.new_grid()
    grid.cells["A1"] = @mooncalc.Cell::Literal(@mooncalc.Value::Num(6.0))
    grid.cells["B1"] = @mooncalc.Cell::Formula("=A1*7")

    // now: None 时 TODAY/NOW 按契约返回 #NUM!;需要时钟时传入 Excel 序列日。
    let out = @mooncalc.recalc(grid, { now: None })
    match out.cells.get("B1") {
    Some(r) => println(r.value) // Num(42)
    None => println("missing")
    }
    }

    • eval_formula(formula, grid, options):单公式求值;解析失败走 Result 的 Err 通道,求值错误值(如 #DIV/0!)作为 Value::Err 返回。
    • eval_at(addr, grid, options):求值单个单元格。
    • recalc(grid, options):整网格按依赖关系重算,循环引用复刻 Excel 默认(环上为 0,circular: true)。
    • recalc_cached(grid, options, cache):同 recalc,复用调用方持有的 ParseCache(按公式全文缓存 AST),交互式编辑场景热态约 2.6×(记录值 2.65×,见 docs/performance.md)。
    • recalc_init / recalc_update:增量重算——改一格只重算下游闭包,输出与全量逐字段一致(环/解析错误自动回退全量),10 万格改一格约 5×。recalc_update_report 另返回重算元数据(重算公式格清单 + 是否回退全量),playground 的「本次重算 N/M 格」计数器即由此驱动。
    • recalc_iterative / eval_formula_iterative:可选迭代计算(对齐 Excel「启用迭代计算」,默认 100 次/0.001),默认路径不变。
    • eval_at_key(key, grid, options) / explain_at_key(key, grid, options):M8 限定键入口,key 形如 SHEET!A1(默认表用裸 A1),与 eval_at/explain 等价但可直接寻址跨表格。
    • Grid.names:工作簿级定义名称(Map[String,String],ASCII 大写名 → 引用文本),随网格一起传入;跨表引用、名称与整列整行由解析器/求值器直接支持(ADR 0008)。
    • explain(addr, grid, options):错误解释——贡献性错误传播路径(最左错误规则感知)与错误源头;dependency_graph(grid) 提供 AST 级依赖图;跨表/名称/整列整行等不可枚举依赖按 oversized 降级披露。
    • 完整 API 见 pkg.generated.mbti;发布后 mooncakes 会依据 /// 文档注释自动生成 API 文档。

    #正确性指标(诚实口径)

    层数字性质
    单元/快照测试159/159手写期望(引擎语义回归 + codec + 语法 + bench 桶 + 限制边界 + 确定性 fuzz + 增量等价 + 迭代 + explain)
    过渡语料 bench34/34(100%)source: manual,非权威,仅证明流程
    用例规格1,277 条(corpus/spec/,每函数 ≥15 + M8 refs 批 106)1,272 条已生成权威答案键(2 条奇数参数 IFS + 3 条非法/重复定义名称被 Excel 拒录);其中 5 条超出声明子集或属非稳态,另存 corpus/excluded/,验收分母 1,267
    真实 Excel 语料1,267/1,267(100%)桌面 Excel 为唯一裁判;1,247 match + 3 clock-tolerance + 16 excel-precision + 1 surrogate-representation,0 条未归因失败,见 corpus/reports/real.json;M8 refs 批(98 条)含跨表/名称/整列整行

    比较策略:默认精确相等;15 位有效数字表征差(相对差 ≤1e-14)单列 excel-precision 桶并通过(源头是 Excel/VBA 只能以 15 位十进制序列化答案);clock 用例按绝对天数容差(--clock-tol,默认 1e-6 天)单列 clock-tolerance 桶并通过(now 由生成器在同一重算里经 =NOW() 辅助格捕获);孤代理对表征差(VBA 将 REPLACE 半代理对切割产生的孤代理对序列化为 U+FFFD)单列 surrogate-representation 桶并通过;相对差 <1e-9 仍单列 numeric-tolerance 桶计失败并归因。权威报告:corpus/reports/real.json。

    #设计要点

    • 纯计算核心,不做任何 IO:同一份核心同时编译到 native 和 wasm-gc;scripts/check.sh 机械守卫(双目标构建 + grep 禁 @fs/@sys/println)。native 侧跑答案键语料对照,wasm-gc 侧做浏览器 playground。
    • 输入是内存网格契约:单元格网格是唯一数据契约,JSON 序列化跨进程传递;CLI 与 wasm 导出共用同一 codec。
    • 函数子集是公开契约:子集外行为显式约定(未知函数 #NAME?、TEXT 子集外 #VALUE!),见 docs/semantics.md。
    • 核心不读系统时钟:TODAY/NOW 由调用方注入 now(未注入 → #NUM!),同一份语料任何时候跑出同样结果。
    • 循环引用复刻 Excel 默认(迭代关闭):环上单元格 = 0,元数据标 circular:true;循环定义名称按真实 Excel 答案键返回 #NAME?(不返回 0)。
    • M8 核心引用语义:跨表引用/区域 Sheet!A1、带引号表名、工作簿级定义名称、整列整行按 used-range 展开(不静默截断;缺表 #REF!);增量/解释对不可枚举依赖显式回退并披露(ADR 0008)。
    • 离线、确定性:不调用模型 API 或网络服务,适合放进 CI 做回归对照。
    • 不崩溃保证:复刻 Excel 公式限制(≤8192 字符、≤64 层嵌套),超限返回 ParseError;长二元链迭代求值,任何输入在 native 与 wasm-gc 上都不会栈溢出(边界回归 + 确定性 fuzz 守卫)。

    #函数子集(60,已全部实现)

    族函数
    逻辑IF、IFS、SWITCH、AND、OR、NOT、IFERROR、XOR
    文本LEFT、RIGHT、MID、LEN、TRIM、UPPER、LOWER、CONCAT、TEXTJOIN、TEXT、VALUE、FIND、SUBSTITUTE、REPLACE、SEARCH、PROPER
    数学ROUND、ROUNDUP、ROUNDDOWN、ABS、INT、MOD、POWER、SQRT、SUM、SUMIF、SUMPRODUCT、CEILING、FLOOR
    统计AVERAGE、COUNT、COUNTA、COUNTIF、MIN、MAX、MEDIAN、STDEV、VAR、PERCENTILE
    查找VLOOKUP、XLOOKUP、HLOOKUP、INDEX、MATCH、CHOOSE
    日期DATE、EOMONTH、YEAR、MONTH、DAY、TODAY、NOW

    逐函数状态与用例数:docs/support-matrix.md。已实现的语义细节(强制转换三表、比较排序、错误传播顺序、Lotus 日期 bug、TEXT 子集、语料裁定项):docs/semantics.md。

    #仓库状态

    #语料生成(用户侧动作)

    权威语料已由桌面 Excel 生成并放入 corpus/cases/(1,267 条;旧 8 文件 1,169 条 + M8 refs 批 98 条。2 条奇数参数 IFS 与 3 条非法/重复定义名称被 Excel 拒绝录入,见 corpus/cases/logic.skipped.txt、refs.skipped.txt;5 条超出声明子集的探针另存 corpus/excluded/;来源、版本与 SHA-256 见 corpus/cases/PROVENANCE.md)。重新生成时在桌面 Excel 运行 corpus/excel/generate_corpus.bas:全量用 GenerateCorpus,单批(如 corpus/spec/refs.tsv)用 GenerateCorpusOne(说明见 corpus/excel/README.md),把导出的 JSON 放入 corpus/cases/,然后:

    _build/native/debug/build/buguoshixc/mooncalc/cmd/main/main.exe bench --corpus corpus/cases --report corpus/reports/real.json

    #设计文档

    #许可证

    本项目采用 MIT License,参见 LICENSE。

    Cell

    单元格内容:Literal(Value) 字面值,或 Formula(String) 公式源码(前导 = 可有可无)。

    CellAddr

    单元格地址(1 基行列 + $ 绝对标记)。用 parse_addr 从 "A1"/"$B$2" 解析。

    DepGraph

    网格依赖图:公式格 → 直接前驱 / 格 → 直接下游(AST 级,区域展开)。

    EvalOptions

    求值选项。now 是调用方注入的时钟(Excel 序列日,含小数):TODAY/NOW 依赖它, 未注入时按显式契约返回 #NUM!(核心从不读取系统时钟)。

    EvalOutput

    单格/单公式求值结果:value 为标量化后的值,circular 表示该格是否落在循环引用环上。

    ExplainOutput

    错误解释结果:目标值、传播路径(源→目标)、错误源头、解析失败消息。

    ExplainStep

    错误传播路径上的一步(addr/formula/value/is_source/precedents)。

    Grid

    单元格网格:Map[String, Cell],键为 A1 形式的大写地址。引擎的唯一输入数据契约。

    IterOptions

    迭代计算选项(对应 Excel「启用迭代计算」):max_iterations 默认 100, max_change 默认 0.001。用 new_iter_options() 缺省构造。

    ParseCache

    调用方持有的公式 AST 缓存:按公式全文缓存解析结果(含解析失败消息)。

    跨多次 recalc_cached 复用可跳过重复解析;公式文本变化即产生新键,无需手动失效。

    ParseError

    公式解析失败(语法/不支持的引用形式)。与求值产生的 XlError 是两条独立通道。

    RangeValue

    行主序的区域值(rows × cols),元素为 Value。

    RecalcOutput

    全网格重算结果:cells 只含公式格的结果,parse_errors 记录解析失败的格与原因。

    RecalcReport

    增量重算元数据:recomputed 为本次实际重新求值的公式格(地址升序), full_fallback 表示是否回退全量重算(环 / 解析错误 / 超大区域)。

    RecalcState

    增量重算状态(调用方持有,单所有者):依赖图 + AST 缓存 + 上次求值结果。

    Value

    单元格的值:Num(数字)、Text(文本)、Bool(布尔)、Err(错误值)、Blank(空白) 或 Range(区域值)。

    公式结果不会是真空白:输出边界把 Blank 归一为 Num(0);Blank 只作为网格输入状态存在。

    XlError

    7 种 Excel 错误值:#DIV/0!、#N/A、#NAME?、#NULL!、#NUM!、#REF!、#VALUE!。

    date_serial

    fn date_serial(y : Int, m : Int, d : Int) -> Result[Int,
    XlError
    ]
    用 Excel 的 1900 日期系统算法(含 Lotus 幻影日 1900-02-29)把年月日折算为序列日。

    年参数 0..1899 会先 +1900,再按月溢出归一化;越界(序列 <0 或 >2958465)返回 #NUM!。

    dependency_graph

    提取整网格依赖图;任一区域超 65536 格返回 None。

    eval_at

    求值网格中某个单元格(取该格的缓存结果);空白格返回 Blank。

    这是 eval_formula("=<addr>", ...) 的便捷形式,循环引用语义与 recalc 一致。

    eval_at_key

    求值限定键对应的单元格("A1" 或 "SHEET!A1",表名大小写不敏感)。

    缺失的工作表按下标语义返回 #REF!;空白格返回 Blank。

    eval_formula

    解析并求值单条公式(不写入网格)。

    • formula:公式源码,前导 = 可有可无。
    • grid:公式引用的单元格网格(字面值或公式);引用会递归求值。
    • options:求值选项(时钟注入)。

    解析失败返回 Err(ParseError);求值阶段的错误值(如 #DIV/0!)作为 Ok 中的 Value::Err 返回。 顶层结果按标量上下文归一化:Blank→0,多格区域按值模型规则处理。

    eval_formula_iterative

    单公式迭代求值(公式挂到空键参与整网格迭代);解析失败走 Err(ParseError) 通道。

    explain

    解释单元格的错误来源:贡献性错误传播路径(最左错误规则感知)。

    目标非错误值或落在环上时 steps 为空;上游超 256 格降级为纯错误前驱链。

    explain_at_key

    解释限定键对应单元格的错误来源("A1" 或 "SHEET!A1")。

    new_grid

    创建一个空的单元格网格。

    new_iter_options

    fn new_iter_options(max_iterations? : Int, max_change? : Double) ->
    IterOptions
    创建迭代选项;缺省即 Excel 默认(100 次、最大变化 0.001)。

    new_parse_cache

    创建一个空的公式 AST 缓存。

    parse_addr

    解析 A1 形式的单元格地址(支持 $ 绝对标记);非法地址返回 None。

    parse_column

    fn parse_column(s : String) -> Int?
    解析列字母(1..3 个 ASCII 字母)为 1 基列号;非法返回 None。

    parse_qualified_addr

    fn parse_qualified_addr(key : String) -> (String,
    CellAddr
    )?
    解析限定地址:SHEET!A1 / 裸 A1;表名可带单引号。返回 (工作表名, 地址)。

    parse_row

    fn parse_row(s : String) -> Int?
    解析行号文本(纯 ASCII 数字)为 1 基行号;非法返回 None。

    recalc

    按依赖关系重算整个网格(DFS + 记忆化 + 环检测)。

    循环引用复刻 Excel 默认(迭代计算关闭):环上单元格结果为 0,元数据 circular: true。

    recalc_cached

    按依赖关系重算整个网格,复用调用方持有的 AST 缓存;语义与 recalc 完全一致。

    同一份缓存可跨多次重算复用(公式文本未变的格跳过解析),适合交互式编辑场景。 循环引用复刻 Excel 默认(迭代计算关闭):环上单元格结果为 0,元数据 circular: true。

    recalc_iterative

    启用迭代计算重算整个网格:环上格从 0 起迭代至收敛或次数上限,circular: true 但值为迭代结果。默认 recalc(迭代关闭)不受影响。

    recalc_update

    增量重算:只重算 changed 的下游闭包,输出与 recalc(grid, options) 逐字段一致。

    changed 必须列出相对上次调用网格内容发生变化的全部地址(含 Literal↔Formula 切换与删除)。出现循环引用、解析错误或超大区域时自动回退全量重算,调用方无需感知。

    recalc_update_report

    同 recalc_update,另返回重算元数据(交互式场景展示「本次重算 N/M 格」用)。

    sheet_key

    fn sheet_key(sheet : String, addr :
    CellAddr
    ) -> String
    限定键:默认工作表(空串)返回裸地址,否则 SHEET!A1(表名 ASCII 大写)。

    split_key

    fn split_key(key : String) -> (String, String)
    限定键拆成 (工作表名, 地址文本);无 ! 时为默认工作表(空串)。

    valid_name_token

    fn valid_name_token(name : String) -> Bool
    定义名称字符集:[A-Za-z_][A-Za-z0-9_]*。

    valid_sheet_name

    fn valid_sheet_name(name : String) -> Bool
    工作表名合法性:1..31 字符且不含 : \ / ? * [ ] !。

    Source Files