# 画面設計書 5-CtrlP（ファイル検索）

## 概要

本ドキュメントは、space-vimにおけるCtrlP（ファイル検索）の画面設計について記載する。CtrlPはctrlpvim/ctrlp.vimプラグインにより提供されるファイル検索機能であり、Ctrl-Pで起動するファイル検索ウィンドウを提供する。FZFの代替として利用可能である。

### 本画面の処理概要

**業務上の目的・背景**：FZFと同様に、プロジェクト内のファイルを素早く検索・オープンすることが目的である。CtrlPはFZFより軽量であり、外部依存が少ないため、FZFが利用できない環境でのファイル検索代替手段として提供されている。また、VCSルートからの検索や、最近使用したファイル（MRU）検索機能も備えている。

**画面へのアクセス方法**：以下の方法でCtrlP画面にアクセスできる。
- `Ctrl-P`キーバインド：ファイル検索
- `SPC f r`キーバインド：最近使用したファイル検索（MRU）
- `:CtrlP`コマンド
- `:CtrlPMRU`コマンド

**主要な操作・処理内容**：
1. 検索クエリをインクリメンタルに入力
2. ファイル名の部分一致で候補が絞り込まれる
3. `Ctrl-j`/`Ctrl-k`で候補間を移動
4. `Enter`で選択したファイルを開く
5. `Ctrl-v`で垂直分割、`Ctrl-x`で水平分割
6. `Ctrl-t`で新しいタブで開く
7. `ESC`または`Ctrl-c`でキャンセル

**画面遷移**：
- エディタ画面 -> `Ctrl-P` -> CtrlPファイル検索画面
- CtrlPファイル検索画面 -> ファイル選択 -> エディタ画面（選択ファイル）
- CtrlPファイル検索画面 -> `ESC` -> エディタ画面

**権限による表示制御**：特になし。ファイルシステムのパーミッションに依存する。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 35 | CtrlP連携 | 主機能 | Ctrl-Pで起動するファイル検索ウィンドウ |
| 15 | ファイル操作(SPC f) | 補助機能 | SPC f rで最近使用したファイル検索 |

## 画面種別

ポップアップ / 検索ウィンドウ

## URL/ルーティング

- ファイル検索: `:CtrlP`、`Ctrl-P`
- MRU検索: `:CtrlPMRU`、`SPC f r`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| g:ctrlp_working_path_mode | 入力（設定） | String | 検索起点ディレクトリの決定方法（'ra'） |
| g:ctrlp_match_window_bottom | 入力（設定） | Number | ウィンドウ位置（0=上） |
| g:ctrlp_by_filename | 入力（設定） | Number | ファイル名のみでマッチ（1） |
| g:ctrlp_max_height | 入力（設定） | Number | 最大ウィンドウ高さ（10） |
| g:ctrlp_switch_buffer | 入力（設定） | String | 既存バッファへのジャンプ方法（'et'） |
| g:ctrlp_regexp | 入力（設定） | Number | 正規表現検索有効（1） |
| g:ctrlp_use_caching | 入力（設定） | Number | キャッシュ使用（1） |
| g:ctrlp_mruf_max | 入力（設定） | Number | MRU最大件数（250） |
| g:ctrlp_custom_ignore | 入力（設定） | Dictionary | 無視パターン |
| g:ctrlp_user_command | 入力（設定） | String/List | 検索コマンド（ag/git） |
| 検索クエリ | 入力 | String | ユーザーが入力する検索文字列 |
| 選択ファイルパス | 出力 | String | 選択されたファイルの絶対パス |

## 表示項目

| 項目 | 表示内容 | 説明 |
|-----|---------|------|
| プロンプト | 検索入力欄 | 検索文字列を入力 |
| 候補一覧 | マッチしたファイル一覧 | 相対パス表示 |
| モード表示 | 検索モード（files/mru等） | ステータス表示 |
| マッチ数 | マッチした候補数 | カウント表示 |

## イベント仕様

### 1-ファイル検索（CtrlP）

`Ctrl-P`押下時、`:CtrlP`コマンドが実行され、CtrlPファイル検索ウィンドウが画面上部に表示される。

### 2-MRU検索（CtrlPMRU）

`SPC f r`押下時、`:CtrlPMRU`コマンドが実行され、最近使用したファイルの一覧が表示される。

### 3-検索バックエンド

agが利用可能な場合、agを検索バックエンドとして使用する。それ以外の場合はgitコマンドを使用する。

### 4-キャッシュ管理

`g:ctrlp_use_caching`が1の場合、検索結果をキャッシュする。agが利用可能な場合はキャッシュを無効化する（十分高速なため）。

## データベース更新仕様

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

該当なし（ファイルシステム検索のみ）

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|---------|
| 情報 | プロンプト（>>） | 検索画面表示時 |
| 情報 | モード表示（files/mru） | モード切替時 |

## 例外処理

| 状態 | 処理 |
|------|------|
| 検索結果なし | 空の候補一覧を表示 |
| VCSルートが見つからない | カレントディレクトリを起点に検索 |
| ag/git未インストール | デフォルトの検索方法を使用 |

## 備考

- CtrlPプラグインは`ctrlpvim/ctrlp.vim`により提供される
- `FelikZ/ctrlp-py-matcher`プラグインでPythonベースの高速マッチングが有効
- FZFの代替として提供されており、環境に応じて選択可能
- tmuxレイヤーがロードされている場合、遅延読み込みは無効
- agが利用可能な場合、`grepprg`もagに設定される

---

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

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

### 推奨読解順序

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

CtrlPの設定データ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+vim/ctrlp/config.vim` | CtrlPの設定変数を確認 |

**読解のコツ**: `g:ctrlp_*`で始まる設定変数がCtrlPの動作を制御している。特に`g:ctrlp_user_command`が検索バックエンドを決定する重要な設定。

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

プラグインのロードとキーマッピングの設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+vim/ctrlp/packages.vim` | プラグイン登録と条件分岐を確認 |
| 2-2 | config.vim | `layers/+vim/ctrlp/config.vim` | キーマッピング設定を確認 |

**主要処理フロー**:
1. **packages.vim 1-7行目**: tmuxレイヤー有無による遅延読み込み分岐
2. **config.vim 2行目**: `g:ctrlp_working_path_mode = 'ra'`でVCSルート検索
3. **config.vim 11-12行目**: `Ctrl-P`マッピング設定
4. **config.vim 23-32行目**: ag/gitコマンドの自動選択

#### Step 3: 検索バックエンドの選択を理解する

ag/gitコマンドの自動選択ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+vim/ctrlp/config.vim` | 23-32行目のag/git分岐 |

**主要処理フロー**:
- **23行目**: `executable('ag')`でagの存在確認
- **25行目**: agが存在する場合、`grepprg`をagに設定
- **27行目**: `g:ctrlp_user_command`をagに設定
- **29行目**: agが高速なためキャッシュを無効化
- **31行目**: agがない場合はgitコマンドを使用

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

```
Ctrl-P (nnoremap)
    │
    └─ :CtrlP コマンド
           │
           ├─ CtrlPプラグインロード（初回のみ）
           │
           └─ CtrlP検索ウィンドウ表示
                  │
                  ├─ [ag利用可能時]
                  │      │
                  │      └─ ag コマンド実行
                  │
                  └─ [ag未インストール時]
                         │
                         └─ git ls-files コマンド実行
```

### データフロー図

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

Ctrl-P / SPC f r ─────▶ config.vim ───────────────▶ CtrlPコマンド
キー押下                  (キーマッピング)

ag/git確認 ───────────▶ config.vim ───────────────▶ 検索コマンド選択
                        (条件分岐)

検索クエリ ───────────▶ ctrlp.vim ────────────────▶ ファジーマッチング
                        (検索処理)

ctrlp-py-matcher ─────▶ pymatcher ────────────────▶ 高速マッチング
                        (Pythonマッチャー)

選択アイテム ─────────▶ ctrlp.vim ────────────────▶ バッファオープン
                        (選択処理)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+vim/ctrlp/packages.vim` | ソース | プラグイン登録 |
| config.vim | `layers/+vim/ctrlp/config.vim` | ソース | 設定・キーマッピング |
| ctrlp.vim | 外部プラグイン（ctrlpvim/ctrlp.vim） | プラグイン | CtrlP本体機能 |
| ctrlp-py-matcher | 外部プラグイン（FelikZ/ctrlp-py-matcher） | プラグイン | Pythonマッチャー |
