#Astrolabe

#为什么选 Astrolabe？ | Why Astrolabe?

#特性 | Features

• 位置感知 — 每个解析器自动追踪行号、列号和字节偏移
• 显式回溯控制 — commit/alt 机制避免隐式回溯的指数爆炸
• 组合子风格 — 小函数组合成大解析器，无需外部代码生成
• 精确错误报告 — 字符级位置 + 输入上下文片段
• JSON/HTTP 解析器 — 开箱即用的格式解析子包
• Z3 形式化验证 — 核心 commit/alt 语义已机械化证明
• 4 后端全通 — wasm / wasm-gc / js / native 均通过 122 项测试
• 双语文档 — 所有公共 API 均有中英双语 /// 注释

#快速开始 | Quick Start

moon add walkzzz/astrolabe

// 基础：匹配单字符
let p = @astrolabe.char('a')
inspect!(p.parse("abc"), content="Ok('a')")

// 组合：变换结果
let greeting = @astrolabe.map(@astrolabe.string("hello"), fn(s) { s.length() })
inspect!(greeting.parse("hello"), content="Ok(5)")

// 选择：有序回溯
let letter_or_digit = @astrolabe.alt(
  @astrolabe.char_range('a', 'z'),
  @astrolabe.char_range('0', '9'),
)

// 完整解析：要求全部输入被消费
let full = @astrolabe.bind(@astrolabe.char('a'), fn(_) {
  @astrolabe.bind(@astrolabe.char('b'), fn(_) {
    @astrolabe.pure("ab")
  })
})
inspect!(full.parse_full("ab"), content="Ok(\"ab\")")

#核心：commit/alt 回溯控制 | Commitment Semantics

// alt 默认回溯
@astrolabe.alt(@astrolabe.string("ab"), @astrolabe.string("ac"))
  |> .parse("ac")  // Ok("ac") — "ab" 失败后回溯，"ac" 成功

// commit 阻止回溯
@astrolabe.alt(
  @astrolabe.bind(@astrolabe.char('a'), fn(_) {
    @astrolabe.commit(@astrolabe.char('b'))  // 看到第一个字符后承诺
  }),
  @astrolabe.string("ac"),
)
  |> .parse("ac")  // Err — 'a' 已消耗，'b' 失败且已承诺，不回溯

#承诺传播表 | Commitment Propagation

#错误报告 | Error Reporting

let p = @astrolabe.string("hello")
match p.parse_full("helLO") {
  Err(e) => println(e.format_with_input("helLO"))
  // line 1, column 4 (offset 3):
  // expected hello
  //   ...helLO
  //       ^
  _ => ()
}

#子包 | Subpackages

#JSON 解析器

let json = @astrolabe/json.parse("{\"name\": \"Alice\", \"age\": 30}")
// Ok(JObj([("name", JStr("Alice")), ("age", JNum(30.0))]))

// JValue 支持 stringify
match json {
  Ok(v) => println(v.stringify())  // {"name": "Alice", "age": 30}
  _ => ()
}

#HTTP 解析器

// URI 解析
let uri = @astrolabe/http.parse_uri_string("https://example.com:8080/path?q=1#sec")
// Ok({ scheme: "https", host: "example.com", port: Some(8080), path: "/path", ... })

// HTTP 请求解析
let req = @astrolabe/http.parse_request_string(
  "GET /index.html HTTP/1.1\r\nHost: example.com\r\n\r\n"
)
// Ok({ req_method: GET, uri: "/index.html", version: { major: 1, minor: 1 }, ... })

// 类型方法：impl Show + to_string
match req {
  Ok(r) => println(r.to_string())  // GET /index.html HTTP/1.1\r\nHost: example.com\r\n\r\n
  _ => ()
}

#API 一览 | API Reference

#入口函数 | Entry Points

#基础组合子 | Basic Combinators

#组合组合子 | Compose Combinators

#控制组合子 | Control Combinators

#HTTP 类型方法 | HTTP Type Methods

#MoonBit 惯用法 | MoonBit Idioms

#性能基准 | Benchmarks

moon bench --target native benchmarks/

#形式化验证 | Formal Verification

#示例 | Examples

moon run examples/uri          # URI 解析器
moon run examples/csv_header   # CSV 头解析器
moon run examples/calc         # 四则运算计算器
moon run cmd/main              # 交互式 CLI 演示

#项目结构 | Project Structure

astrolabe/
├── core/          Pos, State, ParseError, Parser[T]
├── basic/         char, string, take, satisfy, ...
├── compose/       map, bind, seq2-seq4, many, sep_by, ...
├── control/       commit, alt, choice, label
├── json/          JValue + JSON 解析器 + stringify
├── http/          Method, Request, Uri + 解析器 + impl Show
├── proof/         Z3 形式化验证 (7 goals proved)
├── benchmarks/    25 个基准测试
├── examples/      URI, CSV, 计算器
├── cmd/main/      CLI 演示
└── docs/          API 参考、教程、迁移指南、形式化规范

#文档 | Documentation

#License