# 機能設計書 38-pegs

## 概要

本ドキュメントは、NimプログラミングのParsing Expression Grammar (PEG) モジュールである`pegs`モジュールの機能設計を記載する。pegsモジュールは正規表現に代わるパターンマッチング機能を提供し、文法定義に基づいたテキスト解析を可能にする。

### 本機能の処理概要

pegsモジュールはPEG（Parsing Expression Grammar）に基づいたパターンマッチング機能を提供する。正規表現とは異なり、PEGは文法規則を組み合わせてパターンを構築し、曖昧さのないマッチングを実現する。

**業務上の目的・背景**：テキスト解析は多くのアプリケーションで必要とされる。正規表現は広く使われているが、複雑なパターンでは読みにくくなることがある。PEGは文法規則として記述できるため、より構造化されたパターン記述が可能。また、バックトラックの扱いが明確で、予測可能なマッチング動作を提供する。

**機能の利用シーン**：
- プログラミング言語のパーサ実装
- 設定ファイルの解析
- ログファイルのパターンマッチング
- データバリデーション
- テキスト変換・置換

**主要な処理内容**：
1. Peg型の定義（パターンを表す抽象構文木）
2. PEGパターンの構築（term, charSet, sequence, /等）
3. パターン演算子（*, +, ?, &, !）
4. キャプチャ機能（capture, backref）
5. マッチング関数（match, find, replace等）
6. 文字列からのPEGコンパイル（peg, pegマクロ）
7. Unicode文字クラス（letter, lower, upper, whitespace）

**関連システム・外部連携**：unicodeモジュールをインポート（Unicode文字判定用）。macrosモジュールでpegマクロを実装。

**権限による制御**：権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面には関連しない（ライブラリモジュール） |

## 機能種別

パターンマッチング / テキスト解析 / 文法処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pattern | Peg/string | Yes | PEGパターン | 構文チェック |
| s | string | Yes | マッチング対象の文字列 | なし |
| captures | var openArray[string] | No | キャプチャ結果を格納 | MaxSubpatterns以下 |

### 入力データソース

プログラム内の文字列データ。PEGパターンはPeg型オブジェクトまたは文字列として指定。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| マッチ長 | int | マッチした文字数（-1で失敗） |
| キャプチャ | seq[string]/openArray[string] | キャプチャされた部分文字列 |
| 置換結果 | string | 置換後の文字列 |

### 出力先

戻り値として呼び出し元に返される。

## 処理フロー

### 処理シーケンス

```
1. PEGパターンの構築
   └─ 演算子や関数でPeg型を構築、または文字列からコンパイル
2. マッチング実行
   └─ 入力文字列をパターンに従って走査
3. キャプチャ処理
   └─ captureで囲まれた部分を記録
4. 結果の返却
   └─ マッチ長とキャプチャを返す
```

### フローチャート

```mermaid
flowchart TD
    A[PEGパターン] --> B{パターン種別}
    B -->|terminal| C[文字列マッチ]
    B -->|sequence| D[順次マッチ]
    B -->|choice| E[選択マッチ]
    B -->|repetition| F[繰り返しマッチ]
    C --> G{マッチ成功?}
    D --> G
    E --> G
    F --> G
    G -->|Yes| H[マッチ長返却]
    G -->|No| I[-1返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 貪欲マッチ | *, +は貪欲（最長）マッチ | 繰り返し演算子 |
| BR-02 | 順序付き選択 | /は左から順に試行、最初のマッチで確定 | 選択演算子 |
| BR-03 | キャプチャ上限 | 最大20個のサブパターンをキャプチャ可能 | capture使用時 |
| BR-04 | UTF-8サポート | Unicode文字を正しく処理 | useUnicode=true |

### 計算ロジック

PEG演算子の意味:
- `sequence(a, b)`: aの後にbをマッチ
- `a / b`: aを試行、失敗ならbを試行
- `*a`: aの0回以上の繰り返し
- `+a`: aの1回以上の繰り返し
- `?a`: aの0回または1回
- `&a`: aをマッチするが消費しない（先読み）
- `!a`: aがマッチしないことを確認（否定先読み）

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

### テーブル別操作詳細

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| -1（戻り値） | マッチ失敗 | パターンが一致しない | 戻り値のチェック |
| ValueError | Exception | 不正なPEG文字列 | パターンの修正 |
| AssertionDefect | Defect | 無限ループになるパターン | パターンの修正 |

### リトライ仕様

リトライは不要。戻り値で成功・失敗を判定。

## トランザクション仕様

トランザクション管理は不要。

## パフォーマンス要件

- メモ化なしで実装（シンプルさ優先）
- スーパーオペレータとインライン化でパフォーマンス最適化
- 正規表現エンジンと競争力のある性能を目指す

## セキュリティ考慮事項

- 複雑なパターンによるReDoS（正規表現サービス拒否）類似の攻撃に注意
- ユーザー入力からPEGパターンを構築する場合は検証が必要

## 備考

pegsモジュールは正規表現モジュール（re）の代替として使用できる。文法規則を明確に記述したい場合や、曖昧さを排除したい場合に有用。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

PegKind列挙型とPeg型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | pegs.nim | `lib/pure/pegs.nim` | PegKind列挙型（40-74行目） |
| 1-2 | pegs.nim | `lib/pure/pegs.nim` | NonTerminalObj, Peg型（75-92行目） |

**読解のコツ**: Pegはバリアント型（case object）で、kindによって異なるフィールドを持つ。pkSequence, pkOrderedChoiceなどはsonsフィールドに子要素を持つ。

#### Step 2: エントリーポイントを理解する

モジュール冒頭のドキュメントを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | pegs.nim | `lib/pure/pegs.nim` | モジュールドキュメント（10-16行目） |
| 2-2 | pegs.nim | `lib/pure/pegs.nim` | 定数（24-37行目） |

**主要処理フロー**:
1. **10-13行目**: PEGマッチングの概要説明
2. **36-37行目**: MaxSubpatterns=20（キャプチャ上限）

#### Step 3: パターンコンストラクタを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | pegs.nim | `lib/pure/pegs.nim` | term, termIgnoreCase（147-167行目） |
| 3-2 | pegs.nim | `lib/pure/pegs.nim` | charSet（169-175行目） |
| 3-3 | pegs.nim | `lib/pure/pegs.nim` | /, sequence（203-223行目） |

**主要処理フロー**:
- **147-152行目**: term関数 - 終端文字列からPegを構築
- **169-175行目**: charSet関数 - 文字集合からPegを構築
- **203-206行目**: /演算子 - 順序付き選択
- **220-223行目**: sequence関数 - シーケンス

#### Step 4: 繰り返し・オプション演算子を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | pegs.nim | `lib/pure/pegs.nim` | ?, *, +演算子（225-260行目） |
| 4-2 | pegs.nim | `lib/pure/pegs.nim` | &, !演算子（262-268行目） |

**主要処理フロー**:
- **225-233行目**: ?演算子 - オプション
- **235-247行目**: *演算子 - 貪欲繰り返し
- **258-260行目**: +演算子 - 1回以上の繰り返し
- **262-268行目**: &, !演算子 - 先読み・否定先読み

#### Step 5: キャプチャ機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | pegs.nim | `lib/pure/pegs.nim` | capture, backref（311-334行目） |

**主要処理フロー**:
- **311-313行目**: capture関数 - キャプチャグループの作成
- **315-334行目**: backref関数 - 後方参照

#### Step 6: Unicode文字クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | pegs.nim | `lib/pure/pegs.nim` | any, anyRune, newLine（270-280行目） |
| 6-2 | pegs.nim | `lib/pure/pegs.nim` | unicodeLetter等（282-301行目） |

**主要処理フロー**:
- **270-276行目**: any, anyRune - 任意の1文字/1Rune
- **282-301行目**: Unicode文字クラス（letter, lower, upper, title, whitespace）

### プログラム呼び出し階層図

```
pegs.nim (メインモジュール)
    │
    ├─ パターンコンストラクタ
    │      ├─ term / termIgnoreCase / termIgnoreStyle
    │      ├─ charSet
    │      ├─ sequence
    │      └─ / (orderedChoice)
    │
    ├─ 演算子
    │      ├─ * (greedy repetition)
    │      ├─ + (positive repetition)
    │      ├─ ? (optional)
    │      ├─ & (and predicate)
    │      └─ ! (not predicate)
    │
    ├─ キャプチャ
    │      ├─ capture
    │      └─ backref / backrefIgnoreCase / backrefIgnoreStyle
    │
    ├─ 文字クラス
    │      ├─ any / anyRune / newLine
    │      └─ unicodeLetter / unicodeLower / unicodeUpper / unicodeTitle / unicodeWhitespace
    │
    └─ マッチング関数
           ├─ match
           ├─ find
           └─ replace / replacef
```

### データフロー図

```
[入力]                         [処理]                              [出力]

パターン文字列     ───▶  peg("pattern")       ───▶  Peg型オブジェクト
"a+b"                    (パターンコンパイル)

Peg + 対象文字列   ───▶  match/find           ───▶  マッチ長/位置
                         (パターンマッチング)

Peg + 対象文字列   ───▶  replace             ───▶  置換後文字列
+ 置換文字列             (パターン置換)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| pegs.nim | `lib/pure/pegs.nim` | ソース | メインモジュール、Peg型、演算子、マッチング |
| unicode.nim | `lib/pure/unicode.nim` | ソース | Unicode文字判定 |
| macros.nim | `lib/core/macros.nim` | ソース | pegマクロの実装基盤 |
| strutils.nim | `lib/pure/strutils.nim` | ソース | 文字列操作 |
| strformat.nim | `lib/pure/strformat.nim` | ソース | 文字列フォーマット |
| pegdocs.txt | `doc/pegdocs.txt` | ドキュメント | PEG構文の詳細説明 |
