oni-comb-rs: Instructions file for Codex

• 日本語でやりとりしてください

プロジェクト概要

oni-comb-rs は Rust 製パーサーコンビネータライブラリの v2 リブート版。旧 v1 の Rc<dyn Fn> ベース設計を捨て、trait + 具象コンビネータ型（Map, Zip, Or 等）で構成する。動的ディスパッチ・ヒープ確保を排し、Applicative/Alternative 主体で最適化しやすい設計を目指している。

ビルド・テスト

# ビルド
cargo build

# 全テスト実行
cargo test

# parser crateのみテスト
cargo test -p oni-comb-parser

# 特定テスト実行
cargo test -p oni-comb-parser -- test_name

# クリーンビルド
cargo clean && cargo build

アーキテクチャ

Cargo workspace 構成。現在のメンバーは parser クレートのみ。

コア型の階層

InputStream (trait)    -- 入力ストリーム抽象。Checkpoint による巻き戻しを提供
  └─ StrInputStream    -- &str 向け実装。Checkpoint = usize (byte offset)

Parser (trait)         -- parse_next(&mut self, &mut I) -> PResult<O, E>
  └─ ParserExt (trait) -- map/zip/zip_left/zip_right/or/attempt/cut/optional/many0/many1/sep_by0/sep_by1/chainl1/chainr1/flat_map/and_then のメソッドチェーン

Fail (enum)            -- Backtrack(E) | Cut(E) | Incomplete | ZeroProgress
PResult<T, E>          -- Result<T, Fail<E>>

モジュール構成 (modules/parser/src/)

モジュール	役割
input_stream.rs	InputStream トレイト（Checkpoint, Slice, reset, is_eof）
str_input_stream.rs	StrInputStream<'a> — &str 向け InputStream 実装
parser.rs	Parser<I> トレイト（Output, Error, parse_next）
parser_ext.rs	ParserExt<I> — 全 Parser に自動実装されるコンビネータメソッド
fail.rs	Fail<E> enum と PResult 型エイリアス
combinator/	各コンビネータの具象型（Map, Zip, ZipLeft, ZipRight, Or, Attempt, Cut, Optional, Many, Many1, SepBy0, SepBy1, ChainL1, ChainR1, FlatMap）
text/	テキスト専用パーサー（Char, Tag, Satisfy, TakeWhile0/1, Eof, Whitespace0/1, Identifier, Integer, QuotedString）

設計上の重要な判断

• Fail::Backtrack vs Fail::Cut: or は Backtrack のみリカバリし、Cut はそのまま伝播。attempt は Cut を Backtrack に降格、cut は Backtrack を Cut に昇格
• flat_map は実装済みだが Applicative 優先を推奨: ベンチマークで zip ≒ flat_map（同一型）を確認済み。ただし異種型分岐では Box<dyn Parser> が必要で ~15ns のオーバーヘッドが発生するため、Applicative (zip, or) を優先し flat_map は文脈依存の分岐に限定する方針
• 再帰は boxed recursion: 再帰の結び目だけ Box<dyn Parser> に落とし、非再帰部分は具象型を維持
• 入力型は当面 &str 限定: no_std/streaming/bytes は後回し
• many/sep_by/chainl1 は専用ループコンビネータ: flat_map 再帰ではなくループで実装