mooncalc

    Excel-compatible spreadsheet formula engine in MoonBit

    excel
    formula
    spreadsheet
    engine
    Download zip
    Version
    0.3.0
    License
    MIT
    Last updated
    15 hours ago
    Downloads
    12

    #MoonCalc

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

    状态(2026-11-15,M7 引擎增强):60 函数引擎(MoonBit,ADR 0007 扩列 +10)、native CLI、wasm-gc playground、mbtexcel 读→算→写示例已实现;新增 AST 缓存(热态 2.7×)、增量重算(改一格 5×)、可选迭代计算、错误解释 API(explain + 依赖图)。真实 Excel 答案键语料 1,001/1,001(100%)(Excel 2024 · 16.0.20527.20196 · zh-CN 生成;2 条奇数参数 IFS 被 Excel 拒绝录入,显式标为子集外),无未归因失败:996 条精确命中 + 4 条 clock-tolerance + 1 条 excel-precision(均在报告披露)。规格语料共 1,171 条(M7 新增 150 条函数规格 + 18 条迭代规格,答案键待桌面 Excel 生成)。2026 MoonBit 年度黑客松 11 月赛参赛项目。

    #这是什么

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

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

    #快速开始

    export PATH="$HOME/.moon/bin:$PATH" # 全量验证:双目标构建 + 88 项单测 + 零 IO 守卫 bash scripts/check.sh # CLI:求值一个含引用链/错误传播/循环引用的网格 moon build --target native _build/native/debug/build/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/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 冒烟(20 断言,零 npm 依赖) node scripts/smoke.mjs

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

    examples/xlsx-demo 演示与 moonbitlang/mbtexcel 组合的完整链路:mbtexcel 读 xlsx → MoonCalc 进程内求值(同一份 JSON 网格契约)→ mbtexcel 回写缓存值。文件 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 # 读→算→写 output.xlsx,并读回断言 # xlsx-demo verification PASS: 39/39 (formula + cached value + literal checks)

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

    #作为 mooncakes 库使用

    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.7×。
    • recalc_init / recalc_update:增量重算——改一格只重算下游闭包,输出与全量逐字段一致(环/解析错误自动回退全量),10 万格改一格约 5×。
    • recalc_iterative / eval_formula_iterative:可选迭代计算(对齐 Excel「启用迭代计算」,默认 100 次/0.001),默认路径不变。
    • explain(addr, grid, options):错误解释——贡献性错误传播路径(最左错误规则感知)与错误源头;dependency_graph(grid) 提供 AST 级依赖图。
    • 完整 API 见 pkg.generated.mbti;发布后 mooncakes 会依据 /// 文档注释自动生成 API 文档。

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

    层数字性质
    单元/快照测试88/88手写期望(引擎语义回归 + codec + 语法 + bench 桶 + 限制边界 + 确定性 fuzz)
    过渡语料 bench34/34(100%)source: manual,非权威,仅证明流程
    用例规格1,003 条(corpus/spec/,每函数 ≥15)1,001 条已生成权威答案键;2 条奇数参数 IFS 被 Excel 拒绝录入(子集外,不进入分母)
    真实 Excel 语料1,001/1,001(100%)Excel 2024 为唯一裁判;996 match + 4 clock-tolerance + 1 excel-precision,0 条未归因失败,见 corpus/reports/real.json

    比较策略:默认精确相等;15 位有效数字表征差(相对差 ≤1e-14)单列 excel-precision 桶并通过(源头是 Excel/VBA 只能以 15 位十进制序列化答案);clock 用例按绝对天数容差(--clock-tol,默认 1e-6 天)单列 clock-tolerance 桶并通过(now 由生成器在同一重算里经 =NOW() 辅助格捕获);相对差 <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。
    • 离线、确定性:不调用模型 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 2024 生成并放入 corpus/cases/(1,001 条;2 条奇数参数 IFS 被 Excel 拒绝录入,见 corpus/cases/logic.skipped.txt;来源与环境见 corpus/cases/PROVENANCE.md)。重新生成时在桌面 Excel 运行 corpus/excel/generate_corpus.bas(说明见 corpus/excel/README.md),把导出的 JSON 放入 corpus/cases/,然后:

    _build/native/debug/build/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 记录解析失败的格与原因。

    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_formula

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

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

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

    eval_formula_iterative

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

    explain

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

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

    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。

    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 切换与删除)。出现循环引用、解析错误或超大区域时自动回退全量重算,调用方无需感知。

    Source Files