# 機能設計書 67-正規表現検索

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける正規表現によるパターン検索機能の設計を記述する。

### 本機能の処理概要

正規表現検索機能は、端末の出力内容に対してOniguruma正規表現ライブラリを使用したパターンマッチングを提供する機能である。URLリンクの自動検出、カスタムリンクパターンのマッチング、クリック可能なリンクのハイライト表示などに使用される。

**業務上の目的・背景**：ターミナル出力には、URL、ファイルパス、エラーメッセージなど、パターンによって識別できる有用な情報が多く含まれる。正規表現検索機能により、これらのパターンを自動的に検出し、クリック可能なリンクとして表示したり、ハイライトしたりすることができる。これにより、ターミナル作業の効率が向上する。

**機能の利用シーン**：
- URLの自動検出とクリックによるブラウザ起動
- ファイルパスの検出とエディタでの開く操作
- カスタムパターン（チケット番号、コミットハッシュなど）の検出
- マウスホバー時のリンクハイライト

**主要な処理内容**：
1. Oniguruma正規表現のコンパイル
2. 端末出力テキストに対するパターンマッチング
3. マッチ結果のハイライト表示
4. クリック時のアクション実行（URLオープンなど）
5. 設定ファイルからのカスタムリンクパターン読み込み

**関連システム・外部連携**：
- Oniguruma: 正規表現エンジン
- システムオープン: xdg-open（Linux）、open（macOS）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主機能 | リンクハイライト、クリック操作 |
| 13 | 検索オーバーレイ | 補助機能 | 正規表現パターンでの検索（将来実装） |

## 機能種別

パターンマッチング / リンク検出

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| regex | []const u8 | Yes | 正規表現パターン文字列 | 有効な正規表現 |
| action | Action | Yes | マッチ時のアクション（open, _open_osc8） | - |
| highlight | Highlight | Yes | ハイライト条件（always, hover, mods付き） | - |

### 入力データソース

- 設定ファイル: linkキー（カスタムリンクパターン）
- 組み込み: URLパターン、OSC8ハイパーリンク

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| matched_text | []const u8 | マッチしたテキスト |
| start_pos | Point | マッチ開始位置 |
| end_pos | Point | マッチ終了位置 |

### 出力先

- レンダラー: ハイライト描画
- システムオープン: マッチしたURLやパスを開く

## 処理フロー

### 処理シーケンス

```
1. 初期化
   └─ 設定からlinkパターン読み込み
   └─ Oniguruma Regexオブジェクト作成

2. レンダリング時
   └─ 各行のテキストを取得
   └─ 各linkパターンに対してマッチング
   └─ マッチした範囲をハイライト

3. マウスイベント
   └─ ホバー時: mods条件チェック、ハイライト更新
   └─ クリック時: アクション実行（URLオープンなど）

4. OSC8ハイパーリンク
   └─ エスケープシーケンス解析
   └─ ハイパーリンク情報を行に埋め込み
   └─ クリック時に埋め込まれたURLを開く
```

### フローチャート

```mermaid
flowchart TD
    A[設定読み込み] --> B[linkパターン抽出]
    B --> C{各パターン}
    C --> D[oni.Regex.init]
    D --> E[Surface.Linkリストに追加]

    F[レンダリング] --> G[行テキスト取得]
    G --> H{各Link}
    H --> I[regex.search]
    I --> J{マッチ?}
    J -->|Yes| K[ハイライト範囲記録]
    J -->|No| H
    K --> H

    L[マウスホバー] --> M{mods条件満たす?}
    M -->|Yes| N[カーソル下リンク検索]
    M -->|No| O[ハイライトなし]
    N --> P{マッチあり?}
    P -->|Yes| Q[リンクハイライト]
    P -->|No| O

    R[マウスクリック] --> S{リンク上?}
    S -->|Yes| T[action実行]
    S -->|No| U[通常クリック処理]
    T --> V{action種別}
    V -->|open| W[xdg-open/open実行]
    V -->|_open_osc8| X[OSC8 URL取得して開く]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-67-01 | UTF-8エンコーディング | 正規表現はUTF-8エンコーディングで処理 | 常時 |
| BR-67-02 | デフォルト構文 | Onigurumaデフォルト構文を使用 | 常時 |
| BR-67-03 | ハイライト条件 | always/hover/mods指定に基づいてハイライト | 常時 |
| BR-67-04 | URLパターン | RFC準拠のURLパターンを組み込み | 常時 |
| BR-67-05 | OSC8優先 | OSC8ハイパーリンクはカスタムパターンより優先 | OSC8リンク存在時 |

### 計算ロジック

正規表現のコンパイルは`oni.Regex.init`で行い、マッチングは`oni.Regex.search`で実行される。

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 正規表現コンパイルエラー | 無効な正規表現パターン | エラーログ出力、パターンをスキップ |
| - | マッチングエラー | マッチ処理中のエラー | エラーログ出力、処理継続 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 正規表現コンパイルは起動時またはリロード時に1回実行
- マッチングはレンダリングフレームごとに実行されるため高速に完了すること
- 大量のパターンがある場合でもフレームレートに影響を与えないこと

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

- ユーザー指定の正規表現は任意のパターンが許可される
- 開くURLは表示内容と一致することを確認可能（OSC8では埋め込みURL使用）

## 備考

- Onigurumaは鬼車（Oniguruma）正規表現ライブラリで、Ruby等でも使用される
- 将来的に検索オーバーレイでの正規表現検索対応も計画されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Link.zig | `src/input/Link.zig` | Link構造体定義（1-80行目） |
| 1-2 | link.zig | `src/renderer/link.zig` | レンダラー用Link構造体 |

**読解のコツ**: `Link`構造体は`regex`パターン、`action`（クリック時動作）、`highlight`（ハイライト条件）の3フィールドを持つ。`Action`と`Highlight`はunion型で複数の種類を表現する。

#### Step 2: 正規表現エンジンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Link.zig | `src/input/Link.zig` | oniRegex関数（54-63行目） |
| 2-2 | url.zig | `src/config/url.zig` | URLパターン正規表現 |

**主要処理フロー**:
1. **54-63行目**: `oni.Regex.init`でパターンをコンパイル
2. **57行目**: パターン文字列を渡す
3. **59行目**: UTF-8エンコーディング指定
4. **60行目**: デフォルト構文を使用

#### Step 3: Surface統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Surface.zig | `src/Surface.zig` | Link構造体（340-344行目） |

**主要処理フロー**:
- **340-344行目**: Surface内部のLink構造体（oni.Regexをコンパイル済みで保持）
- 設定リロード時に正規表現を再コンパイル

#### Step 4: レンダラー統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | generic.zig | `src/renderer/generic.zig` | リンクマッチング処理 |

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

```
設定読み込み
    │
    └─ Config.links解析
           │
           └─ Link構造体リスト作成
                  │
                  └─ oni.Regex.init (各パターン)
                         │
                         └─ Surface.Linkリストへ格納

レンダリング
    │
    └─ Renderer.renderLinks
           │
           ├─ 行テキスト取得
           │
           └─ 各Link
                  │
                  └─ oni.Regex.search
                         │
                         ├─ マッチあり: ハイライト追加
                         │
                         └─ マッチなし: 次のLink

マウスクリック
    │
    └─ Surface.handleMouseClick
           │
           └─ リンク位置判定
                  │
                  └─ Link.action実行
                         │
                         ├─ .open: システムオープン
                         │
                         └─ ._open_osc8: OSC8 URL取得→オープン
```

### データフロー図

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

設定ファイル ────────▶ Config.links ───▶ Link構造体リスト
(link=...)                    │
                              ▼
                      oni.Regex.init ───▶ コンパイル済み正規表現
                              │
                              ▼
行テキスト ─────────▶ oni.Regex.search ───▶ マッチ結果
                              │
                              ▼
                      ハイライト範囲 ───▶ レンダラー描画

クリックイベント ────▶ action判定 ───▶ xdg-open/open実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Link.zig | `src/input/Link.zig` | ソース | Link構造体定義 |
| link.zig | `src/renderer/link.zig` | ソース | レンダラー用Link |
| url.zig | `src/config/url.zig` | ソース | URLパターン正規表現 |
| Surface.zig | `src/Surface.zig` | ソース | Link統合 |
| generic.zig | `src/renderer/generic.zig` | ソース | リンクレンダリング |
| Config.zig | `src/config/Config.zig` | ソース | link設定解析 |
| build_options.zig | `src/terminal/build_options.zig` | ソース | Oniguruma有効化フラグ |
