# 機能設計書 91-grep設定

## 概要

本ドキュメントは、Oh My Zshのgrep設定機能（lib/grep.zsh）の設計を記述する。この機能はGNU grepがサポートするカラー出力オプションと除外パターンを自動設定し、grep/egrep/fgrepコマンドのエイリアスを定義する。

### 本機能の処理概要

Oh My Zshのgrep設定機能は、シェル起動時にgrepコマンドの使い勝手を向上させるための自動設定を行う機能である。

**業務上の目的・背景**：開発者やシステム管理者がgrepコマンドを使用してファイル内のテキストを検索する際、デフォルトのgrepは出力がモノクロでマッチ箇所が見づらく、また.git等のバージョン管理ディレクトリを無駄に検索してしまう問題がある。本機能は、これらの問題を自動的に解決し、ユーザーの作業効率を向上させる。

**機能の利用シーン**：ターミナルでgrepコマンドを実行するすべての場面で本機能の恩恵を受ける。特に、ソースコードの検索、ログファイルの解析、設定ファイルの確認など、日常的なコマンドライン作業において有効である。

**主要な処理内容**：
1. キャッシュファイルの存在確認（1日以内に更新されたものがあるか）
2. grepコマンドが--colorオプションと--exclude-dirオプションをサポートしているかを検出
3. サポートされているオプションに基づいてGREP_OPTIONS変数を設定
4. grep、egrep、fgrepのエイリアスを定義
5. エイリアス設定をキャッシュファイルに保存（次回起動時の高速化）
6. 一時変数と関数のクリーンアップ

**関連システム・外部連携**：GNU grep（または互換コマンド）、ZSHキャッシュシステム

**権限による制御**：特になし。ただし、キャッシュディレクトリへの書き込み権限がない場合はキャッシュが保存されない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLI機能であり、関連画面はない |

## 機能種別

シェル設定 / エイリアス定義 / 環境最適化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ZSH_CACHE_DIR | 環境変数 | No | キャッシュディレクトリのパス | - |

### 入力データソース

- **ZSH_CACHE_DIR環境変数**: Oh My Zshのキャッシュディレクトリパス（oh-my-zsh.shで設定済み）
- **システムのgrepコマンド**: コマンドの機能検出に使用

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| grepエイリアス | alias | カラー出力と除外パターンを設定したgrepコマンド |
| egrepエイリアス | alias | grep -Eへのエイリアス |
| fgrepエイリアス | alias | grep -Fへのエイリアス |
| キャッシュファイル | file | $ZSH_CACHE_DIR/grep-alias |

### 出力先

- シェルのエイリアス定義（メモリ上）
- キャッシュファイル（$ZSH_CACHE_DIR/grep-alias）

## 処理フロー

### 処理シーケンス

```
1. キャッシュファイルパスの設定
   └─ __GREP_CACHE_FILE="$ZSH_CACHE_DIR"/grep-alias

2. キャッシュファイルの確認
   └─ 1日以内に更新されたキャッシュがあるか確認

3. キャッシュが有効な場合
   └─ キャッシュファイルをsourceしてエイリアスを復元

4. キャッシュが無効/存在しない場合
   ├─ grep-flags-available関数を定義
   ├─ 除外フォルダパターンを定義（.bzr,CVS,.git,.hg,.svn,.idea,.tox,.venv,venv）
   ├─ --exclude-dirオプションのサポートを確認
   │   ├─ サポートあり: GREP_OPTIONS="--color=auto --exclude-dir=..."
   │   └─ サポートなし: --excludeオプションのサポートを確認
   ├─ GREP_OPTIONSが設定されている場合
   │   ├─ grep/egrep/fgrepエイリアスを定義
   │   └─ キャッシュディレクトリが書き込み可能ならキャッシュに保存
   └─ 一時変数と関数をクリーンアップ

5. 最終クリーンアップ
   └─ __GREP_CACHE_FILE、__GREP_ALIAS_CACHES変数をunset
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[キャッシュファイルパス設定]
    B --> C{1日以内の<br/>キャッシュあり?}
    C -->|Yes| D[キャッシュをsource]
    C -->|No| E[grep-flags-available関数定義]
    E --> F[除外フォルダパターン定義]
    F --> G{--exclude-dir<br/>サポート?}
    G -->|Yes| H[GREP_OPTIONS設定<br/>--exclude-dir使用]
    G -->|No| I{--exclude<br/>サポート?}
    I -->|Yes| J[GREP_OPTIONS設定<br/>--exclude使用]
    I -->|No| K[GREP_OPTIONS未設定]
    H --> L{GREP_OPTIONS<br/>設定済み?}
    J --> L
    K --> L
    L -->|Yes| M[エイリアス定義]
    L -->|No| N[クリーンアップ]
    M --> O{キャッシュ<br/>書込可能?}
    O -->|Yes| P[キャッシュ保存]
    O -->|No| N
    P --> N
    D --> Q[終了]
    N --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-91-01 | キャッシュ有効期間 | キャッシュファイルは作成後1日間有効 | キャッシュファイルが存在する場合 |
| BR-91-02 | 除外フォルダ | .bzr,CVS,.git,.hg,.svn,.idea,.tox,.venv,venvを検索から除外 | --exclude-dirまたは--excludeがサポートされている場合 |
| BR-91-03 | カラー出力 | --color=autoオプションでマッチ箇所をハイライト | grepがカラー出力をサポートしている場合 |
| BR-91-04 | egrep/fgrep互換 | egrepはgrep -E、fgrepはgrep -Fとして定義 | grepエイリアスが設定された場合 |

### 計算ロジック

キャッシュ有効期間判定：
- ZSH glob修飾子 `(Nm-1)` を使用
- N: nullglob（マッチしなければ空）
- m-1: 最終更新が1日以内

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | grepオプション非対応 | grepが--color等をサポートしない古いバージョン | エイリアスを設定せずスキップ |
| - | キャッシュ書込不可 | ZSH_CACHE_DIRに書き込み権限がない | キャッシュ保存をスキップ（毎回検出処理を実行） |

### リトライ仕様

リトライ処理は実装されていない。次回のシェル起動時に再度処理が実行される。

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

該当なし

## パフォーマンス要件

- キャッシュ機構により、2回目以降のシェル起動は高速化
- grep機能検出は空文字列に対するgrepを実行するため、即座に完了

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

- キャッシュファイルは `alias -L` コマンドの出力を保存
- キャッシュファイルはユーザーのZSH_CACHE_DIRに保存され、他ユーザーからのアクセスは制限される

## 備考

- grep v2.5以降で--colorと--exclude-dirがサポートされた
- 古いシステムでは--excludeのみサポートされる場合がある
- egrep/fgrepは非推奨だが、互換性のためエイリアスを提供

---

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

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

### 推奨読解順序

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

本機能では特別なデータ構造は使用していないが、以下の変数が重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | grep.zsh | `lib/grep.zsh` | __GREP_CACHE_FILE、GREP_OPTIONS、EXC_FOLDERS変数の役割を理解 |

**読解のコツ**: ZSHのglob修飾子 `(Nm-1)` は「nullglob + 1日以内に更新」を意味する。この記法はZSH特有のもの。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | lib/*.zshの読み込みループ（197-199行目）を確認 |
| 2-2 | grep.zsh | `lib/grep.zsh` | ファイル全体が初期化処理として実行される |

**主要処理フロー**:
1. **1行目**: キャッシュファイルパスの定義
2. **4-5行目**: キャッシュファイルの有効性確認（ZSH glob修飾子使用）
3. **5-6行目**: 有効なキャッシュがあればsourceして終了
4. **8-10行目**: grep-flags-available関数の定義（オプション検出用）
5. **13行目**: 除外フォルダパターンの定義
6. **18-22行目**: --exclude-dirまたは--excludeのサポート確認とGREP_OPTIONS設定
7. **26-28行目**: エイリアスの定義
8. **31-33行目**: キャッシュへの保存
9. **36-38行目**: 一時変数・関数のクリーンアップ
10. **41行目**: 最終クリーンアップ

#### Step 3: grep機能検出を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | grep.zsh | `lib/grep.zsh` | grep-flags-available関数（8-10行目）の実装 |

**主要処理フロー**:
- **8-10行目**: `command grep "$@" "" &>/dev/null <<< ""`
  - 空文字列に対してgrepを実行し、指定オプションが使用可能か確認
  - 終了コードで判定（0=サポートあり、非0=サポートなし）

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

```
oh-my-zsh.sh
    │
    └─ lib/grep.zsh（source）
           │
           ├─ キャッシュファイル確認
           │      └─ ZSH glob修飾子 (Nm-1)
           │
           ├─ [キャッシュ有効] source "$__GREP_CACHE_FILE"
           │
           └─ [キャッシュ無効]
                  │
                  ├─ grep-flags-available()
                  │      └─ command grep "$@" "" &>/dev/null <<< ""
                  │
                  ├─ alias grep="grep $GREP_OPTIONS"
                  ├─ alias egrep="grep -E"
                  ├─ alias fgrep="grep -F"
                  │
                  └─ alias -L grep egrep fgrep >| "$__GREP_CACHE_FILE"
```

### データフロー図

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

ZSH_CACHE_DIR          キャッシュ確認                    エイリアス定義
    │                       │                               │
    v                       v                               v
キャッシュファイル ─────▶ 有効性判定 ─────▶ [有効] ─────▶ source実行 ─────▶ grep/egrep/fgrepエイリアス
    │                       │
    │                       v
    │                  [無効] ─────▶ grep機能検出 ─────▶ GREP_OPTIONS設定
    │                                     │
    │                                     v
    └──────────────────────────────── キャッシュ保存 ◀── エイリアス定義
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| grep.zsh | `lib/grep.zsh` | ソース | grep設定の本体 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/*.zshの読み込み |
| grep-alias | `$ZSH_CACHE_DIR/grep-alias` | キャッシュ | エイリアス設定のキャッシュ |
| zshrc.zsh-template | `templates/zshrc.zsh-template` | テンプレート | .zshrcのテンプレート |
