#🔭 Astrolabe

#位置感知解析器组合子库 · Position-Aware Parser Combinator Library

#🧭 为什么选 Astrolabe？

#✨ 特性一览

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

#🚀 快速开始

moon add walkzzz/astrolabe

// 基础：匹配单字符
let p = @astrolabe.char('a')
match p.parse("abc") {
  Ok(c) => println("parsed: \{c}") // parsed: a
  Err(e) => println(e.format()) // 精确位置 + 上下文片段
}

// 组合：变换结果
let greeting = @astrolabe.map(@astrolabe.string("hello"), fn(s) { s.length() })
match greeting.parse("hello") {
  Ok(n) => println("length: \{n}") // length: 5
  Err(e) => println(e.format())
}

// 选择：有序回溯
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")
  })
})
match full.parse_full("ab") {
  Ok(v) => println("value: \{v}") // value: ab
  Err(e) => println(e.format())
}

#🔒 核心：commit/alt 回溯控制

// 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' 失败且已承诺，不回溯

序列自动承诺：bind/seq2 中，如果第一个解析器成功但第二个失败，错误自动标记为已承诺。

#🎯 错误报告

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
  //       ^
  _ => ()
}

#Raise 模式

let value : Char = try @astrolabe.parse_raise(p, "abc") catch {
  e => fail("unexpected: \{e}")
}

#📦 子包

#JSON 解析器（examples/json 包）

// moon.pkg
import {
  "walkzzz/astrolabe/examples/json" @json,
}

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

#HTTP 解析器（examples/http 包）

// moon.pkg
import {
  "walkzzz/astrolabe/examples/http" @http,
}

let uri = @http.parse_uri_string("https://example.com:8080/path?q=1#sec")
let req = @http.parse_request_string(
  "GET /index.html HTTP/1.1\r\nHost: example.com\r\n\r\n"
)

#📖 API 一览

#入口函数

#基础组合子

#组合组合子

#控制组合子

#🧪 MoonBit 惯用法

#⚡ 性能基准

moon bench --target native benchmarks/

上表为历史实测示例数据；当前 25 项基准以 moon bench --target native benchmarks/ 实时结果为准。

#🔬 形式化验证

#📂 项目结构

astrolabe/
├── astrolabe.mbt  根包门面 — pub using 扁平化导出全部公共 API
├── core/          Pos, State, ParseError, Parser[T]
├── char/          char, string, take, satisfy, take_while, ...
├── sequence/      map, bind, seq2-seq4, many, sep_by, option, between, ...
├── branch/        commit, alt, choice, label, not_followed_by, fix
├── proof/         形式化验证 — 7 个证明函数（SMT 支持的 proof 条件）
├── benchmarks/    25 个基准测试
├── examples/      uri, json, http, csv_header, calc 五个示例包
├── cmd/main/      CLI 演示
└── docs/          API 参考、教程、迁移指南、形式化规范、路线图

#📚 文档

#License

#🧭 Why Astrolabe?

#✨ Feature Highlights

• 📍 Position-aware — Every parser auto-tracks line, column, and byte offset
• 🔒 Explicit backtracking — commit/alt mechanism prevents exponential blowup
• 🧱 Combinator style — Compose small functions into big parsers, no code generation
• 🎯 Precise errors — Character-level position + input context snippets
• 📦 JSON/HTTP parsers — Ready-to-use format parsing subpackages
• 🔬 Z3 formal verification — Core commit/alt semantics mechanically proved
• ✅ 4 backends pass — wasm / wasm-gc / js / native all pass 198 tests, moon check --deny-warn --target all with zero warnings
• 🌐 Bilingual docs — All public APIs have Chinese+English /// comments

#🚀 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")
  })
})
match full.parse_full("ab") {
  Ok(v) => println("value: \{v}") // value: ab
  Err(e) => println(e.format())
}

#🔒 Core: commit/alt Backtrack Control

// alt backtracks by default
@astrolabe.alt(@astrolabe.string("ab"), @astrolabe.string("ac"))
  |> .parse("ac")  // Ok("ac") — "ab" fails, backtracks, "ac" succeeds

// commit prevents backtracking
@astrolabe.alt(
  @astrolabe.bind(@astrolabe.char('a'), fn(_) {
    @astrolabe.commit(@astrolabe.char('b'))  // commit after consuming first char
  }),
  @astrolabe.string("ac"),
)
  |> .parse("ac")  // Err — 'a' consumed, 'b' fails with commitment, no backtrack

Sequence commits automatically: In bind/seq2, if the first parser succeeds but the second fails, the error is automatically marked as committed.

#🎯 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
  //       ^
  _ => ()
}

#Raise Pattern

let value : Char = try @astrolabe.parse_raise(p, "abc") catch {
  e => fail("unexpected: \{e}")
}

#📦 Subpackages

#JSON Parser (examples/json package)

// moon.pkg
import {
  "walkzzz/astrolabe/examples/json" @json,
}

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

#HTTP Parser (examples/http package)

// moon.pkg
import {
  "walkzzz/astrolabe/examples/http" @http,
}

let uri = @http.parse_uri_string("https://example.com:8080/path?q=1#sec")
let req = @http.parse_request_string(
  "GET /index.html HTTP/1.1\r\nHost: example.com\r\n\r\n"
)

#📖 API Reference

#Entry Points

#Basic Combinators

#Compose Combinators

#Control Combinators

#🧪 MoonBit Idioms

#⚡ Benchmarks

moon bench --target native benchmarks/

Figures above are historical sample measurements; run moon bench --target native benchmarks/ for live numbers (25 benchmarks).

#🔬 Formal Verification

#📂 Project Structure

astrolabe/
├── astrolabe.mbt  Root facade — flattens all public API via `pub using`
├── core/          Pos, State, ParseError, Parser[T]
├── char/          char, string, take, satisfy, take_while, ...
├── sequence/      map, bind, seq2-seq4, many, sep_by, option, between, ...
├── branch/        commit, alt, choice, label, not_followed_by, fix
├── proof/         Formal verification — 7 proof functions (SMT-backed proof conditions)
├── benchmarks/    25 benchmarks
├── examples/      Five example packages: uri, json, http, csv_header, calc
├── cmd/main/      CLI demo
└── docs/          API reference, tutorial, migration guide, formal spec, roadmap

#📚 Documentation

#License