#MoonDocopt

#解决什么问题

• CLI 作者：先写用户能阅读的 Usage，再用同一文档约束选项、子命令、互斥和重复参数；解析后直接做业务计算。
• 脚本迁移者：把已有 docopt 风格接口迁移到 MoonBit，不必改写为 code-first 参数注册树。
• 嵌入式控制台/宿主程序作者：复用已编译解析器，用字符串或 JSON 请求获得结构化结果、错误、帮助和版本，宿主自行管理 I/O 与生命周期。

#已实现

• 必选组 (...)、可选组 [...]、分支 |、一个或多个 ...、多行 Usage 与 [options]。
• 长短别名、短选项组合、附着值、长选项唯一前缀、重复计数/列表、默认值、--、options_first。
• 编译一次多次解析；对外结果、数组和默认值做防御性复制。
• Flag / Text / Missing / Count / Texts，严格 Int32、范围和 choice 转换。
• 显式 Parsed / Help / Version，错误分为 language / arguments / limit / conversion。
• 文档、语法深度、展开大小、argv 和匹配工作预算；严格 JSON 请求接口。
• 参数元数据与词法前缀建议；POSIX 风格分词和安全引号往返。

#安装与环境

moon add jqlssg/moondocopt@0.1.0

import {
  "jqlssg/moondocopt" @docopt,
}
pkgtype(kind: "executable")

///|
fn main {
  try {
    let parser = @docopt.Parser::new(
      "Usage: greet <name> [--times=N]\nOptions:\n  --times=N  Repeat count [default: 1]",
    )
    let values = parser.parse(["MoonBit", "--times=2"])
    let name = values.require_text("<name>")
    let times = values.integer("--times", minimum=1, maximum=10)
    for _ in 0..<times {
      println("你好，" + name)
    }
  } catch {
    e => println("error: " + e.message())
  }
}

moon run . --target wasm-gc

#三个可以实际运行的工作流

# 1. 数据处理工具：类型校验后求平均值并缩放，不只是显示解析字典
moon run examples/reduce --target wasm-gc -- mean 3 5 --scale=2
# {"operation":"mean","count":2,"result":8}

# 2. 迁移构建入口：把帮助文档定义的输入变成每个源文件的编译任务 argv
moon run examples/buildplan --target wasm-gc -- debug --define=LOG=1 src/a.c
# 一个任务：cc -c src/a.c -o build/object-0.o -g -DLOG=1

# 3. 应用内控制台：过滤宿主记录、排序、限量，再返回业务数据
moon run examples/console --target wasm-gc -- select --tag=core --limit=1
# {"matched":2,"rows":[{"id":"parser","score":90}]}

#API 与语义

let p = @docopt.Parser::new(
  "Usage: tool [-v]... [--path=P]... <file>\nOptions:\n  -v  Verbose\n  --path=P  Search paths",
)
let v = p.parse(["-vv", "--path=a", "--path=b", "input.txt"])
assert_eq(v.count("-v"), 2)
assert_eq(v.texts("--path"), ["a", "b"])
assert_eq(v.require_text("<file>"), "input.txt")

• 规范键：有长别名时使用长选项名，例如 -o --output=FILE 的键是 --output。
• 未提供的单值参数为 Missing，布尔项为 Flag(false)，重复布尔为 Count(0)，重复值为 Texts([])；文档默认值会覆盖相应缺省。
• parse 只做语法匹配；run(argv, help=true, version=Some("0.1.0")) 额外识别帮助/版本，返回 Outcome，不直接输出或退出。帮助/版本选项应在文档里声明；非法选项语法仍优先报错。
• parse(argv, options_first=true) 在第一个位置参数后停止解释选项。-- 按 docopt 的规则保留为位置项，是否接收由 Usage 决定，不能假设它始终被丢弃。
• 类型访问器不做隐式强转：例如 integer 只接收十进制文本并检查 Int32 溢出；类型不符抛 Conversion。
• parameters() / describe() 返回参数说明；suggest(prefix) 只按已知命令/别名的词法前缀建议，不是有上下文的 shell completion。
• 公共接口完整清单见 pkg.generated.mbti。

#JSON 宿主接入

let p = @docopt.Parser::new("Usage: greet <name>")
let response = p.request_json("{\"argv\":[\"MoonBit\"],\"help\":false}")
assert_eq(response, ({"status":"parsed","values":{"<name>":"MoonBit"}} : Json))

#资源限制与信任边界

#兼容、测试与开发

moon info
moon fmt
moon check --deny-warn
moon build --deny-warn --target wasm-gc
moon test --deny-warn --target wasm-gc
python scripts/check_workflows.py --target wasm-gc
python scripts/audit.py

# 重新生成独立上游/差分答案，无需联网或 pip
python scripts/generate_oracles.py
moon fmt
# 在 clean checkout 应无差异
 git diff --exit-code

#许可与 AI 使用