#MoonBean

#适合谁用

• 用 Beancount 或 Fava 记账的个人和小企业：在已验证范围内比较错误类别、行号和最终余额（见一致性测试和下方迁移边界）。
• 想在应用里内嵌账本能力的 MoonBit 开发者：不需要文件系统和外部进程，include 由宿主通过回调提供。
• 需要离线运行的场景：浏览器、wasm 宿主、没有 Python 环境的机器。
• 想读代码学习的人：parser、decimal、booking、BQL 按包拆开，可以单独复用。

#从 Beancount 迁移

moonbean query examples/migration/queries.beancount 'SELECT account FROM (SELECT account)'
# unsupported query.unsupported.subquery at BQL:1:22
moonbean query examples/migration/queries.beancount 'SELECT account FROM postings JOIN postings'
# unsupported query.unsupported.join at BQL:1:30
moonbean query examples/migration/queries.beancount 'SELECT account PIVOT currency'
# unsupported query.unsupported.pivot at BQL:1:16

#Playground

./scripts/build-web.sh                # 产物在 web/dist
python3 -m http.server -d web/dist 8000
node web/smoke.mjs                    # 用示例账本断言导出函数的结果
node web/dom-smoke.mjs                # 无头 Chrome：账本里的恶意字符串不会变成 HTML

#版本对应

# 源码测试
git checkout v0.1.1
moon test --target all

# 安装包调用：在仓库外新建模块，复制 examples/library_demo 的 main.mbt 和 moon.pkg 到 cmd/main
moon new consumer && cd consumer
moon add sundaysebasidian-byte/moonbean@0.1.1
moon run cmd/main

# 线上引擎：打开 Pages；对应的构建见 Actions 中 Pages 工作流的运行记录
gh run list --workflow pages.yml --limit 1

#安装

moon add sundaysebasidian-byte/moonbean

moon version --all
moon build

#命令行

# 校验账本，错误输出为 file:line: code: message
moon run cmd/main --target native -- check examples/full-year-2024.beancount

# 试算平衡表，可以指定日期快照和折算币种
moon run cmd/main --target native -- bal examples/full-year-2024.beancount
moon run cmd/main --target native -- bal examples/full-year-2024.beancount --at 2024-06-30 --convert CNY

# 资产负债表、损益表、某个账户的流水、重复交易
moon run cmd/main --target native -- bs examples/full-year-2024.beancount
moon run cmd/main --target native -- is examples/full-year-2024.beancount
moon run cmd/main --target native -- register examples/full-year-2024.beancount Assets:Bank:Checking
moon run cmd/main --target native -- dups examples/full-year-2024.beancount

# BQL 查询，输出文本或 JSON
moon run cmd/main --target native -- query examples/full-year-2024.beancount \
  'SELECT account, sum(units) FROM postings GROUP BY account ORDER BY account'
moon run cmd/main --target native -- query examples/full-year-2024.beancount \
  'SELECT account, sum(units) FROM postings GROUP BY account ORDER BY account' --json

# 格式化（默认打印到标准输出，加 --write 原地写回）
moon run cmd/main --target native -- fmt examples/full-year-2024.beancount

# 导出结构化 JSON
moon run cmd/main --target native -- export examples/full-year-2024.beancount --json

moon run examples/library_demo

#作为库使用

import {
  "sundaysebasidian-byte/moonbean",
}

fn analyze(source : String) -> Unit {
  // 纯函数，不访问文件系统；include 由宿主提供 read 回调。
  let ledger = @moonbean.check_source("ledger.beancount", source)
  if ledger.has_errors() {
    for diagnostic in ledger.errors {
      println(@moonbean.diagnostic_text(diagnostic))
    }
    return
  }
  let realized = @moonbean.realize(ledger)
  for position in realized.inventory("Assets:Cash").positions {
    println(position.to_string())
  }
  let result = @moonbean.run_query(
    ledger,
    "SELECT account, sum(units) FROM postings GROUP BY account ORDER BY account",
  )
  println(result.to_text())
}

#覆盖范围

#语法与指令

#数值、记账与校验

#报表与 BQL

#格式化与命令行

#一致性测试

ledgers: 120, compared: 118, passed: 118, failed: 0, extensions: 2

• 118 份可比较的账本全部通过：诊断集合、最终余额、原始 price 条目和固定 BQL 查询一致；插件合成位置的比较规则见 conformance。
• 另外 2 份用到 AVERAGE 和 {*}，beancount 3.2.3 不支持，只用本项目自己的测试验证。
• 逐份结果、比较口径和已知差异见 docs/conformance.md。

./scripts/oracle.sh            # 安装固定版本的 oracle 并运行比较
./scripts/oracle.sh --markdown # 重新生成逐份结果表

python3 scripts/random_differential.py --seed 7 --out .oracle-cache/differential/seed-7 --allow-known-extensions
python3 scripts/random_differential.py --seed 20261101 --out .oracle-cache/differential/seed-20261101 --allow-known-extensions
python3 scripts/report_differential.py
python3 scripts/include_smoke.py
python3 scripts/bql_differential.py
python3 scripts/cli_smoke.py

#性能

export MOON_HOME=/tmp/moon-new PATH=/tmp/moon-new/bin:$PATH
python3 scripts/bench-matrix.py --out .oracle-cache/performance-new
python3 scripts/bench-summary.py .oracle-cache/performance-new
python3 scripts/bench-compare.py .oracle-cache/performance-new

#和 mooncakes 上其他项目的区别

#限制与路线图

• 上述 5 个内置插件原生执行；其他插件只记录并给出警告，不运行 Python。
• document 不检查文件是否存在；未实现的 option 不会改变行为。
• BQL 按逐项清单实现：子查询、PIVOT 和 31 个标量签名未实现，JOIN/SQL LIKE 不属于已验证的 oracle 语法；数值算术区分 int/Decimal，不含通用 Amount/Inventory 运算。正则用 MoonBit core 的 Regex 子集，非法或不支持的模式会明确报错并保留位置。BQL 字符串的反斜杠和重复引号与 oracle 一样保留原字符，不按 Python 或 C 转义解码。
• Playground 一次只处理一段文本，不加载 include。

1. 插件扩展点（宿主可以注册自定义校验和变换）。
2. 更完整的 BQL（完整对象运算、子查询、PIVOT、金额运算、期间转换的归一化）；LIKE/JOIN 不属于 beanquery 0.2.0 的已验证语法。
3. account_rounding 的输出语义。
4. 更大账本的增量 realize 和缓存。

#许可证与合规

• 不复制它们的源码、注释或测试数据，规范依据只有公开文档（Language Syntax、How Inventories Work、BQL、Precision & Tolerances）。
• tests/ledgers/ 和 examples/ 下的账本都是自己写的。
• Beancount 只在一致性测试里作为外部黑盒：固定版本、装进临时 virtualenv、运行后比较输出。
• Playground 的页面、样式和脚本也都是自己写的，没有使用 Beancount 或 Fava 的任何代码、样式或资源。
• 详见 NOTICE。

#开发

moon check --deny-warn --target all
moon test --target all
moon fmt --check
moon info && git diff --exit-code
./scripts/build-web.sh && node web/smoke.mjs && node web/dom-smoke.mjs

#0.2.3 compatibility boundary