# 機能設計書 117-pcre

## 概要

本ドキュメントは、Nim標準ライブラリの`pcre`ラッパーモジュールの機能設計について記載する。このモジュールはPCRE（Perl Compatible Regular Expressions）ライブラリへのNimバインディングを提供する。

### 本機能の処理概要

pcreモジュールは、PCRE正規表現ライブラリ（バージョン8.x）をNimから利用するためのラッパーを提供する。Perl互換の強力な正規表現機能をNimプログラムから直接利用できる。

**業務上の目的・背景**：正規表現は文字列処理において不可欠な機能である。PCREはPerl互換の高機能な正規表現エンジンであり、複雑なパターンマッチング、キャプチャグループ、後方参照、先読み/後読みなどの機能を提供する。

**機能の利用シーン**：
- 文字列のパターンマッチング
- テキストの検索と置換
- 入力バリデーション
- ログ解析
- テンプレートパース

**主要な処理内容**：
1. `compile` - 正規表現パターンのコンパイル
2. `exec` - コンパイル済みパターンでのマッチング実行
3. `study` - マッチング最適化のための追加解析
4. `get_substring` / `get_named_substring` - キャプチャグループの取得
5. `fullinfo` - コンパイル済みパターンの情報取得

**関連システム・外部連携**：
- PCRE動的ライブラリ（libpcre）
- reモジュール（PCREを使用した高レベルAPI）

**権限による制御**：特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | ライブラリ機能としてreモジュール等から使用 |

## 機能種別

文字列処理 / パターンマッチング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pattern | cstring | Yes | 正規表現パターン | 有効なPCRE構文 |
| options | cint | No | コンパイルオプション | 有効なオプションフラグ |
| subject | cstring | Yes | マッチング対象文字列 | - |
| startoffset | cint | No | 開始オフセット | >= 0 |
| ovector | ptr cint | Yes | マッチ位置配列 | 十分なサイズ |

### 入力データソース

プログラムコード内の文字列

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ptr Pcre | ptr Pcre | コンパイル済み正規表現 |
| cint | cint | マッチ数または負のエラーコード |
| ExtraData | ptr ExtraData | study結果 |

### 出力先

メモリ上のオブジェクト

## 処理フロー

### 処理シーケンス

```
1. compile()で正規表現をコンパイル
   └─ パターン、オプション、エラー情報を渡す
   └─ ptr Pcreを取得

2. study()でオプションの最適化（JIT含む）
   └─ STUDY_JIT_COMPILEでJIT有効化

3. exec()またはdfa_exec()でマッチング実行
   └─ subject、開始位置、ovectorを渡す
   └─ マッチ数またはエラーコードを返す

4. マッチ成功時
   └─ ovectorからマッチ位置を取得
   └─ get_substring()でキャプチャグループ取得

5. リソース解放
   └─ free_substring()
   └─ free_study()
   └─ （Pcre構造体のfreeはPCREが管理）
```

### フローチャート

```mermaid
flowchart TD
    A[パターン文字列] --> B[compile]
    B --> C{成功?}
    C -->|Yes| D[study - optional]
    C -->|No| E[エラー処理]
    D --> F[exec]
    F --> G{マッチ?}
    G -->|Yes| H[ovectorからマッチ位置取得]
    G -->|No| I[マッチなし]
    H --> J[get_substring]
    J --> K[結果を使用]
    K --> L[free_substring]
    L --> M[free_study]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-117-01 | UTF-8サポート | UTF8フラグでUTF-8モード有効化 | 日本語等の処理時 |
| BR-117-02 | JIT | STUDY_JIT_COMPILEでJITコンパイル | 高速化が必要時 |
| BR-117-03 | 大文字小文字 | CASELESSフラグで無視 | オプション |
| BR-117-04 | マルチライン | MULTILINEフラグで^$が行にマッチ | オプション |
| BR-117-05 | DOTALL | DOTALLフラグで.が改行にもマッチ | オプション |

### 計算ロジック

ovectorサイズ = (キャプチャグループ数 + 1) * 3

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ERROR_NOMATCH (-1) | マッチなし | パターンがマッチしない | 正常な結果として処理 |
| ERROR_NULL (-2) | NULLエラー | 引数がNULL | 引数を確認 |
| ERROR_BADOPTION (-3) | 不正オプション | 無効なオプション指定 | オプションを確認 |
| ERROR_BADUTF8 (-10) | UTF-8エラー | 不正なUTF-8文字列 | 入力を検証 |
| ERROR_NOMEMORY (-6) | メモリ不足 | メモリ割り当て失敗 | リソースを確認 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- compile()はコストが高いため、結果をキャッシュ推奨
- study()でJIT有効化すると高速化
- ovectorサイズは適切に設定

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

- ReDoS（正規表現DoS）に注意
- ユーザー入力からのパターン生成は慎重に
- タイムアウト設定を検討

## 備考

- PCREバージョン8.36ベース
- PCRE2（バージョン10.x）は別モジュール

---

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

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

### 推奨読解順序

#### Step 1: 型定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | pcre.nim | `lib/wrappers/pcre.nim` | Pcre/ExtraData型（256-279行目） |
| 1-2 | pcre.nim | `lib/wrappers/pcre.nim` | CalloutBlock型（286-303行目） |
| 1-3 | pcre.nim | `lib/wrappers/pcre.nim` | JitCallback型（310行目） |

**読解のコツ**: Pcre型は不透明型（opaque）。ExtraDataはマッチング時の追加情報を渡すための構造体。

#### Step 2: オプションフラグを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | pcre.nim | `lib/wrappers/pcre.nim` | コンパイルオプション（57-104行目） |
| 2-2 | pcre.nim | `lib/wrappers/pcre.nim` | エラーコード（107-145行目） |
| 2-3 | pcre.nim | `lib/wrappers/pcre.nim` | INFO_*定数（189-216行目） |
| 2-4 | pcre.nim | `lib/wrappers/pcre.nim` | STUDY_*オプション（239-242行目） |

#### Step 3: 主要関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | pcre.nim | `lib/wrappers/pcre.nim` | compile/compile2（333-344行目） |
| 3-2 | pcre.nim | `lib/wrappers/pcre.nim` | exec（375-382行目） |
| 3-3 | pcre.nim | `lib/wrappers/pcre.nim` | dfa_exec（364-373行目） |
| 3-4 | pcre.nim | `lib/wrappers/pcre.nim` | study（434-436行目） |
| 3-5 | pcre.nim | `lib/wrappers/pcre.nim` | fullinfo（398-401行目） |

#### Step 4: 結果取得関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | pcre.nim | `lib/wrappers/pcre.nim` | get_substring（418-422行目） |
| 4-2 | pcre.nim | `lib/wrappers/pcre.nim` | get_named_substring（403-408行目） |
| 4-3 | pcre.nim | `lib/wrappers/pcre.nim` | get_stringnumber（410-411行目） |
| 4-4 | pcre.nim | `lib/wrappers/pcre.nim` | free_substring（394-395行目） |

#### Step 5: JIT関連を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | pcre.nim | `lib/wrappers/pcre.nim` | jit_exec（384-392行目） |
| 5-2 | pcre.nim | `lib/wrappers/pcre.nim` | jit_stack_alloc/free（450-453行目） |
| 5-3 | pcre.nim | `lib/wrappers/pcre.nim` | assign_jit_stack（455-457行目） |

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

```
アプリケーション
    │
    ├─ compile(pattern, options, ...)
    │      └─ PCREライブラリ: pcre_compile
    │
    ├─ study(code, STUDY_JIT_COMPILE, ...)
    │      └─ PCREライブラリ: pcre_study
    │
    ├─ exec(code, extra, subject, ...)
    │      └─ PCREライブラリ: pcre_exec
    │             │
    │             └─ マッチ位置をovectorに格納
    │
    ├─ get_substring(subject, ovector, n, ...)
    │      └─ PCREライブラリ: pcre_get_substring
    │
    └─ free_substring(ptr)
           └─ PCREライブラリ: pcre_free_substring
```

### データフロー図

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

パターン文字列 ───▶ compile() ────▶ ptr Pcre
    │
ptr Pcre ──────────▶ study() ─────▶ ptr ExtraData
    │
subject + Pcre ────▶ exec() ──────▶ ovector (マッチ位置)
    │                                    │
    │                                    ▼
subject + ovector ─▶ get_substring ▶ キャプチャ文字列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| pcre.nim | `lib/wrappers/pcre.nim` | ソース | PCREラッパー |
| re.nim | `lib/impure/re.nim` | ソース | PCREを使用した高レベルAPI |
| nre.nim | `lib/impure/nre.nim` | ソース | 別のPCREラッパー（推奨） |
