#MoonTTL

#特性

• 多格式支持：完整支持 Turtle, TriG, N-Triples, N-Quads 和 N3 格式的解析与序列化—— 现役三方言：N-Quads/N-Triples（gen_nquads）、TriG/Turtle（gen_trig，Turtle 由运行时方言开关裁决）、 N3（gen_n3v2，含公式/规则/操作符谓词/集合/属性列表）。
• RDF 1.2 兼容：全面支持最新的 RDF 1.2 国际标准规范；每方言带语法版本开关 （rdf12：转义标量口径 + 方向性语言标签 --ltr/--rtl；1.1 侧显式关闭）。
• 高性能：基于状态机的词法分析器设计，双词法器（MoonBit Lexermoon / C FFI Lexerc）同字母表、 逐 token parity 钉死；提供分层基准（词法 / 转换 / 状态机 / 完整引擎）。
• 生成器纪律：三方言均由表/TOML 数据驱动生成（生成契约 = Trait / 枚举 / Context； Actions / EffectHandler / Supervisor 三面接线），生成物 *.mbt 禁手编、有黄金对拍门。
• 轻量级：专注于核心解析功能，保持依赖最小化。

#安装

{
  "name": "your_username/your_project",
  "deps": [
    "thy1016/moonttl"
  ]
}

#命令行工具

#从字符串解析

moon run src/cmd/main -- "<http://example.org/s> <http://example.org/p> <http://example.org/o> ."

#从文件解析

echo '<http://example.org/s> <http://example.org/p> <http://example.org/o> .' > test.nq
moon run src/cmd/main -- -f test.nq

#详细输出模式

moon run src/cmd/main -- -v -f test.nq

#命令行选项

• -f, --file <path> - 指定输入文件路径
• -v, --verbose - 启用详细输出模式
• <input> - 直接输入 N-Quads 格式的字符串

#N-Quads 格式说明

<http://example.org/s> <http://example.org/p> <http://example.org/o> .

#示例代码

let content = "<http://example.org/s> <http://example.org/p> <http://example.org/o> .\n"
let data = @utf8.encode(content).to_array()

let lexer = @lib.Lexer::Lexer(
  @lib.RdfLexer::RdfLexer(@lib.RdfMode::NTriples, false, []),
  data,
  true,
  @lib.MIN_BUFFER_SIZE,
  @lib.MAX_BUFFER_SIZE,
  Some(b"#"),
  0,
  0,
)

let logger = @lib.make_console_logger()

let machine = @lib.NQuadsRecognizer::{
  current_state: @lib.NQuadsState::ExpectSubject,
  stack: [@lib.NQuadsState::ExpectSubject],
  emit_quad: false,
  temp_literal: None,
  lenient: false,
  debug_logger: logger,
  last_range: @lib.Range::default(),
  errors: [],
}

let context = @lib.RdfContext::NQuadsRecognizerContext(@lib.NQuadsRecognizerContext::{
  with_graph_name: true,
  lexer_options: { base_iri: None },
})

let generic_machine = @lib.GenericStateMachine::GenericStateMachine(
  machine,
  context,
  debug_logger=logger,
)
let parser = @lib.Parser::{
  lexer,
  engine: generic_machine,
  context,
  errors: [],
}


for ;; {
  match parser.parse_next() {
    Some(Ok(quad)) => println("Parsed: \{quad}")
    Some(Err(e)) => println("Error: \{e}")
    None => break
  }
}

#用户文档（guides/）

#项目结构

src/
├── gen_nquads/       # N-Quads/N-Triples 解析器（生成契约 + 用户层；含词法器/物化/序列化/套件）
├── gen_trig/         # TriG/Turtle 解析器（同上；TriG 超集 + Turtle 方言开关）
├── gen_n3v2/         # N3 解析器（同上；公式/规则/量化/路径/@keywords）
├── cmd/main/         # 命令行工具（`moon run src/cmd/main -- <file>`）
├── examples/         # 三方言可运行示例：nquads / trig / n3
├── bench/            # 基准程序
└── quick_machine/    # 快测机（表驱动的模型执行对照）

#Examples

#解析 N-Quads 文件

moon run src/examples/nquads

Written N-Quads content to: ./example.nq
Parsing N-Quads file...
[1] Quad<http://example.org/s1, http://example.org/p1, http://example.org/o1>
[2] Quad<http://example.org/s2, http://example.org/p2, http://example.org/o2>
[3] Quad<http://example.org/s3, http://example.org/p3, http://example.org/o3>
[4] Error: InvalidTurtleToken - Unexpected end of input turtle .

=== Summary ===
Total quads parsed: 3

• 从字符串创建 N-Quads 内容并写入文件
• 从文件读取并解析为二进制数据
• 使用词法分析器和状态机解析 RDF 四元组
• 错误处理和结果汇总

#解析 TriG 文件（图块 / GRAPH / Turtle 方言）

moon run src/examples/trig

#解析 N3 文件（公式 / 规则 / 操作符 / @keywords）

moon run src/examples/n3

#测试与验证

moon test                     # 全模块：507/507（默认档）；--target native 521/521
moon test src/gen_nquads      # 146/146（W3C N-Quads 89/89、rdf12-nt 29/29、rdf12-nq 27/27、ntriples 72/72）
moon test src/gen_trig        # 105/105（rdf-trig 357/357、rdf-turtle 316/316、rdf12 36/36 + 75/75）
moon test src/gen_n3v2        # 122/122（turtle 316/316、rdf12 75/75、N3Tests neg 23ok/0miss + pos+eval 205 clean）

#许可证声明

• W3C 3-clause BSD License — 允许修改和集成到开发工具中，但禁止对修改后的测试断言性能声明或规范一致性。
• W3C Test Suite License — 要求测试文件保持未修改状态，方可对外发布性能声明。

#测试覆盖范围

#性能基准

#基准测试环境

#性能对比

 实现                  解析时间    每秒解析     每条耗时
━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━  ━━━━━━━━━━━  ━━━━━━━━━━━
 MoonTTL (MoonBit)     0.56 ms     1,786,445    0.00056 ms
────────────────────  ──────────  ───────────  ───────────
 Oxigraph (Rust)       0.77 ms     1,294,934    0.00077 ms
────────────────────  ──────────  ───────────  ───────────
 rdflib (Python)       17.89 ms    55,900       0.0179 ms
────────────────────  ──────────  ───────────  ───────────
 Apache Jena (Java)    2,734 ms    36,576       0.0273 ms
────────────────────  ──────────  ───────────  ───────────
 no-brain-scan (C)     0.16 ms     6,250,000    0.0002 ms

### MoonTTL 性能分析

=== MoonBit 解析 test_1000.nq ===
文件: test_1000.nq
文件大小: 103670 bytes

=== 性能数据 ===
Lexer:       515.532 µs (5000 tokens)
ParserE:     575.14 µs (1000 quads)
验证:        1448.353 µs (1000 quads, 0 errors)
物化:        310.314 µs (1000 quads, 0 errors)

=== 总计 ===
总时间:      1.76 ms
三元组数量:  1000
每秒解析:    568,612
每三元组:    0.0018 ms

#运行基准测试

cd src/bench
./run_all.sh

#性能优化特性

• 零拷贝设计：词法分析器基于字节数组切片，避免不必要的内存分配
• 状态机驱动：使用有限状态机进行语法解析，保证 O(n) 时间复杂度
• 前瞻解析：减少函数调用开销
• 批量物化：验证和物化分离，支持批量处理
• 错误恢复：遇到错误自动跳过当前行，继续解析后续内容

#贡献指南

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启一个 Pull Request

#开发环境设置

#克隆仓库

#安装依赖

#运行测试

#构建项目

#许可证

• Apache License, Version 2.0, (LICENSE-APACHE or <http://www.apache.org/licenses/LICENSE-2.0>)

#贡献

#性能实测（2026-09-23）与对端口径

• 本机实测（口径 = --target native --release · 10k 语料）：6.137 ms / 1.630M triples·s⁻¹（0.000614 ms/三元）。
• 同机同档实测（2026-09-25，本机 Ryzen 7 5700G，--target native --release，同为 in-process 只量解析面）：本实现 0.00057 ms/三元（10k 档 5.697 ms）vs Oxigraph 0.5.11 0.00077 ms/三元（10k 档 7.689 ms）⇒ ≈1.35×。读法要紧：对端只解析，本实现是解析 + 四门深验 + 物化（不建图）——即本实现做更多事仍更快。旧叙事"≈3.3×–3.5×"基于 Oxigraph 公开读数 0.0020（500k 语料 / 异机），本机实测对端比它快 2.6×，故该公开读数不再作对端代表值；复现条件（命令 / 探针件 / 冷缓存 / 机指纹）见 perf-review.txt。
• 档位分档（B2）：基准档 = Deep（上表与对外数字均按 Deep）；Light 档（关两把开关：组装层轻验 + 物化层四门深验，逐方言同名不同义见 const.md §X 第 1 条）实测省幅 n3v2 ≈19–21%（合成 10k · 同进程交替 A/B · 带不交叠，两复跑）、nquads ≈12.5%（同法）、trig ≈19–21%（三次复跑，后两次判带不交叠；首轮因 light 一记离群判交叠，已留痕）。默认仍为 Deep：性能不换深验；Light 需调用方显式选择（口径见 src/gen_nquads/const.md §X）。

// 严格（默认，不变）
let slice = @nquads.SliceParser::new(engine, data)
let (quads, errs) = slice.parse_all()
let (emits, merrs) = mat.materialize_all(quads)          // 默认 Deep

// 轻验（显式；只要速度时用）
let slice = @nquads.SliceParser::new(engine, data, mode=@nquads.ValidateMode::Light)
let (quads, errs) = slice.parse_all()
let (emits, merrs) = @nquads.materialize_all(quads)   // nquads 物化 = 自由函数；n3v2/trig 走方法并接 `mode=`
// n3v2 / trig 同形：`N3SliceParser::new(...)` / `TrigSliceParser::new(...)` 亦接 `mode=`

• 单一声明源：数字、判据体、复现条件（target / 冷缓存 / 命令 / 机器指纹）与沿革勘误一律见 perf-review.txt（面四）；本 README 只引用，不另立数字。 （沿革：旧账面"5–6×"系预估投影，非实测；自 2026-09-23 起以 perf-review.txt 为准。）

#第三方来源与许可