# 機能設計書 39-expand-or-complete-with-dots

## 概要

本ドキュメントは、Oh My Zshの`expand-or-complete-with-dots`関数の機能設計について記載する。この関数は、TABキーによる補完処理中に待機インジケータ（デフォルトで赤い「...」）を表示し、補完完了後に画面を再描画する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：大量のファイルやコマンドがある環境では、補完処理に時間がかかることがある。この間、ユーザーに視覚的なフィードバックがないと、シェルがフリーズしたように見えてしまう。待機インジケータを表示することで、処理が進行中であることをユーザーに知らせ、より良いユーザー体験を提供する。

**機能の利用シーン**：TABキーを押して補完を実行した際、補完処理に時間がかかる場合に待機インジケータが表示される。COMPLETION_WAITING_DOTS変数が有効な場合にのみ機能する。

**主要な処理内容**：
1. COMPLETION_WAITING_DOTSの値を確認（trueの場合はデフォルトの赤い「...」を使用）
2. 行折り返しを一時的に無効化してインジケータを表示
3. 標準の`expand-or-complete`ウィジェットを呼び出して補完を実行
4. 画面を再描画してインジケータを消去

**関連システム・外部連携**：ZSHのZLEシステム（Zsh Line Editor）と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ターミナル | 結果表示画面 | TABキーによる補完操作時に表示 |

## 機能種別

ユーザーインターフェース・フィードバック処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし（ZLEウィジェット） | - | - | TABキー押下でトリガーされる | - |

### 入力データソース

- **環境変数**: COMPLETION_WAITING_DOTS - 待機インジケータの表示内容（trueまたはカスタム文字列）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 待機インジケータ | string | プロンプト展開された待機文字列（デフォルト: 赤い「...」） |

### 出力先

ターミナル画面（補完処理中のみ一時表示）

## 処理フロー

### 処理シーケンス

```
1. COMPLETION_WAITING_DOTSの値をチェック
   └─ trueの場合、デフォルト値"%F{red}...%f"を設定
2. 行折り返しを無効化（ESCシーケンス\e[?7l）
3. プロンプト展開した待機インジケータを表示
   └─ ${(%)COMPLETION_WAITING_DOTS}でプロンプト形式を展開
4. 行折り返しを再有効化（ESCシーケンス\e[?7h）
5. 標準の補完ウィジェットを呼び出し
   └─ zle expand-or-complete
6. 画面を再描画
   └─ zle redisplay
```

### フローチャート

```mermaid
flowchart TD
    A[TABキー押下] --> B{COMPLETION_WAITING_DOTS = true?}
    B -->|Yes| C[デフォルト値を設定]
    B -->|No| D[カスタム値を使用]
    C --> E[行折り返し無効化]
    D --> E
    E --> F[待機インジケータ表示]
    F --> G[行折り返し再有効化]
    G --> H[expand-or-complete実行]
    H --> I[画面再描画]
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-39-1 | デフォルトインジケータ | COMPLETION_WAITING_DOTS=trueの場合、赤い「...」を使用 | true設定時 |
| BR-39-2 | カスタムインジケータ | COMPLETION_WAITING_DOTSに文字列を設定した場合、その値を使用 | 文字列設定時 |
| BR-39-3 | 行折り返し制御 | インジケータ表示時は行折り返しを無効化 | 常時 |
| BR-39-4 | プロンプト展開 | %F{color}などのプロンプト形式を展開して表示 | 常時 |

### 計算ロジック

プロンプト展開:
```zsh
${(%)COMPLETION_WAITING_DOTS}
# (%): プロンプト展開フラグ
# %F{red}: 前景色を赤に設定
# %f: 前景色をリセット
```

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

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

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | この関数ではエラー処理は実装されていない | - |

### リトライ仕様

リトライは実装されていない

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

該当なし

## パフォーマンス要件

- 補完処理の開始前に即座にインジケータを表示する必要がある
- printfによる表示は非常に高速

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

- 特になし

## 備考

- emacs、viins、vicmdの各モードで^I（TAB）にバインドされる
- ターミナルがESCシーケンスをサポートしていない場合、インジケータが正しく表示されない可能性がある

---

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

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

### 推奨読解順序

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

この関数で使用される環境変数とESCシーケンスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | completion.zsh | `lib/completion.zsh` | COMPLETION_WAITING_DOTS変数の使用方法 |

**読解のコツ**:
- `\e[?7l`: 行折り返し無効化のDECSCLシーケンス
- `\e[?7h`: 行折り返し有効化のDECSCLシーケンス
- `${(%)var}`: ZSHのプロンプト展開（%F、%fなどを処理）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | completion.zsh | `lib/completion.zsh` | `expand-or-complete-with-dots`関数の定義（62-69行目） |

**主要処理フロー**:
1. **61行目**: `if [[ ${COMPLETION_WAITING_DOTS:-false} != false ]]` - 有効化チェック
2. **64行目**: `[[ $COMPLETION_WAITING_DOTS = true ]] && COMPLETION_WAITING_DOTS="%F{red}...%f"` - デフォルト値設定
3. **66行目**: `printf '\e[?7l%s\e[?7h' "${(%)COMPLETION_WAITING_DOTS}"` - インジケータ表示
4. **67行目**: `zle expand-or-complete` - 補完実行
5. **68行目**: `zle redisplay` - 画面再描画

#### Step 3: キーバインド設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | completion.zsh | `lib/completion.zsh` | キーバインド設定（70-74行目） |

**主要処理フロー**:
- **70行目**: `zle -N expand-or-complete-with-dots` - ウィジェット登録
- **72行目**: `bindkey -M emacs "^I" expand-or-complete-with-dots` - emacsモード
- **73行目**: `bindkey -M viins "^I" expand-or-complete-with-dots` - vi挿入モード
- **74行目**: `bindkey -M vicmd "^I" expand-or-complete-with-dots` - viコマンドモード

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

```
TABキー (^I) 押下
    │
    └─ expand-or-complete-with-dots()
           │
           ├─ COMPLETION_WAITING_DOTS値チェック
           │      └─ trueの場合: デフォルト値を設定
           │
           ├─ printf '\e[?7l%s\e[?7h' "${(%)...}"
           │      └─ 行折り返し無効化 + インジケータ表示 + 行折り返し有効化
           │
           ├─ zle expand-or-complete
           │      └─ 標準の補完処理を実行
           │
           └─ zle redisplay
                  └─ 画面を再描画
```

### データフロー図

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

TABキー押下 ────▶ expand-or-complete-with-dots
                        │
                        ▼
              COMPLETION_WAITING_DOTS取得
                        │
                        ▼
              printf (インジケータ表示) ────▶ ターミナル画面
                        │                      "..."表示
                        ▼
              zle expand-or-complete
                        │
                        ▼
              zle redisplay ────────────────▶ ターミナル画面
                                              補完結果表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| completion.zsh | `lib/completion.zsh` | ソース | expand-or-complete-with-dots関数の定義元 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/completion.zshを読み込むメインスクリプト |
