# 画面設計書 7-omz plugin load

## 概要

本ドキュメントは、Oh My Zshの`omz plugin load`コマンドインターフェースの画面設計書です。指定されたプラグインを現在のシェルセッションに動的に読み込む機能を定義します。

### 本画面の処理概要

`omz plugin load`コマンドは、指定されたプラグインを現在のシェルセッションに一時的に読み込みます。.zshrcは変更せず、次回のシェル起動時には読み込まれません。プラグインのテストや一時的な使用に適しています。

**業務上の目的・背景**：プラグインを恒久的に有効化する前に、その動作を確認したい場合があります。また、特定の作業セッションでのみプラグインを使用したい場合もあります。本コマンドにより、.zshrcを変更することなくプラグインを試用でき、シェルの再起動も不要です。これにより、プラグインの評価や一時的な機能拡張が容易になります。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz plugin load <plugin>` - 単一のプラグインを読み込み
- `omz plugin load <plugin1> <plugin2> ...` - 複数のプラグインを同時に読み込み

**主要な操作・処理内容**：
1. 指定されたプラグインの存在を確認（カスタム/ビルトインディレクトリ）
2. プラグインのディレクトリを`$fpath`に追加
3. プラグインファイル（.plugin.zsh）をsource
4. 補完ファイルがある場合は`compinit -D`で補完を再初期化

**画面遷移**：
- 遷移元：`omz plugin`コマンドから
- 遷移先：読み込み完了後、シェルプロンプトに戻る（リロードなし）

**権限による表示制御**：なし。ファイルシステムへの読み取りアクセス権のみ必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてプラグインを読み込み |
| 12 | omz plugin load | 主機能 | 指定プラグインを現在のセッションに動的にロード |
| 2 | プラグイン読み込み | 補助機能 | _omz_source関数を使用してプラグインファイルを読み込み |

## 画面種別

機能実行（プラグイン動的読み込み）

## URL/ルーティング

```
omz plugin load <plugin> [...]
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| plugin | string | はい | 読み込むプラグイン名（複数指定可） |

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| 警告メッセージ | 標準エラー出力（stderr） | プラグインが見つからない場合の警告 |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| 警告：未発見 | プラグインが見つからない場合の警告 | `omz plugin load: plugin '<name>' not found` |
| 警告：無効 | 有効なプラグインでない場合の警告 | `omz plugin load: '<name>' is not a valid plugin` |

## イベント仕様

### 1-プラグイン動的読み込みイベント

**トリガー**：`omz plugin load <plugin> [...]`コマンドの実行

**処理フロー**：
1. 引数の存在を検証
2. 各プラグインについて：
   a. カスタムプラグインディレクトリでプラグインの存在を確認
   b. 見つからない場合、ビルトインプラグインディレクトリで確認
   c. 両方で見つからない場合、警告を表示してスキップ
   d. プラグインの有効性を検証（.plugin.zshまたは_で始まる補完ファイルの存在）
   e. プラグインディレクトリを`$fpath`の先頭に追加
   f. 補完ファイルの存在をチェック
   g. プラグインファイル（.plugin.zsh）をsource
3. 補完ファイルがあった場合、`compinit -D`を実行

**データの流れ**：
```
ユーザー入力 → プラグイン検索 → fpath更新 → source実行 → 補完再初期化
```

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| プラグイン読み込み | なし | - | ファイルシステムへの変更なし |

本コマンドは現在のシェルセッションのメモリ内でのみ動作し、.zshrcや他のファイルへの変更は発生しません。

### シェル変数への影響

| 変数名 | 操作種別 | 概要 |
|--------|---------|------|
| fpath | UPDATE | プラグインディレクトリを先頭に追加 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| 使用方法 | `Usage: omz plugin load <plugin> [...]` | プラグイン名が指定されていない場合 |
| 警告 | `plugin '<plugin>' not found` | プラグインディレクトリが存在しない場合 |
| 警告 | `'<plugin>' is not a valid plugin` | .plugin.zshも補完ファイルもない場合 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| 引数なし | 使用方法を表示 | 1 |
| プラグイン未発見 | 警告を表示して次のプラグインへ | 継続 |
| 無効なプラグイン | 警告を表示して次のプラグインへ | 継続 |

## 備考

- 読み込みは現在のセッションにのみ影響し、.zshrcは変更されない
- 補完ファイルがある場合、`compinit -D -d "$_comp_dumpfile"`で補完を再初期化
- `-D`オプションにより新しいダンプファイルは生成されない（次回セッションに影響しない）
- 既に`$fpath`にあるディレクトリは重複追加されない
- カスタムプラグインが優先的に検索される

---

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

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

### 推奨読解順序

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

プラグイン動的読み込み機能で使用される主要な変数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | 行499で`base`変数（プラグインのベースディレクトリ）を確認 |
| 1-2 | cli.zsh | `lib/cli.zsh` | 行499で`has_completion`変数（補完ファイルの有無）を確認 |
| 1-3 | oh-my-zsh.sh | `oh-my-zsh.sh` | 行108-111で`$_comp_dumpfile`変数を確認 |

**読解のコツ**: `$fpath`はzshの関数パスで、補完関数やその他の関数を検索するディレクトリのリストです。

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

プラグイン動的読み込みコマンドのエントリーポイントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | `_omz::plugin::load`関数（493-539行目）が処理の本体 |

**主要処理フロー**:
1. **行494-497**: 引数チェック
2. **行499-508**: プラグインディレクトリの検索（カスタム優先）
3. **行510-517**: プラグインの有効性検証と`$fpath`への追加
4. **行519-522**: 補完ファイルの存在チェック
5. **行524-527**: プラグインファイルのsource
6. **行530-538**: 補完があった場合の`compinit -D`実行

#### Step 3: プラグイン検索と検証ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 行501-508でプラグインディレクトリ検索を確認 |
| 3-2 | cli.zsh | `lib/cli.zsh` | 行510-517でプラグイン有効性検証を確認 |

**主要処理フロー**:
- **行501-502**: `$ZSH_CUSTOM/plugins/$plugin`を優先チェック
- **行503-504**: `$ZSH/plugins/$plugin`をフォールバックチェック
- **行505-508**: 両方で見つからない場合は警告してcontinue
- **行511**: `_$plugin`ファイルまたは`$plugin.plugin.zsh`ファイルの存在チェック
- **行515-516**: `$fpath`に未登録の場合のみ追加

#### Step 4: 補完再初期化ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | 行519-522で補完ファイル検出を確認 |
| 4-2 | cli.zsh | `lib/cli.zsh` | 行536-538で`compinit -D`実行を確認 |

**主要処理フロー**:
- **行520-521**: `$base/_*`パターンで補完ファイルを検索
- **行522**: `$#comp_files > 0`で補完の有無を判定
- **行536**: 補完がある場合のみ`compinit`を実行
- **行537**: `-D`オプションで新しいダンプファイルを生成しない

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

```
omz plugin load <plugin> [...]
    │
    └─ _omz::plugin::load
           │
           ├─ 引数チェック
           │
           └─ [各プラグインについてループ]
                  │
                  ├─ プラグインディレクトリ検索
                  │      ├─ $ZSH_CUSTOM/plugins/$plugin
                  │      └─ $ZSH/plugins/$plugin
                  │
                  ├─ [未発見] → 警告 → continue
                  │
                  ├─ プラグイン有効性検証
                  │      └─ _$plugin または $plugin.plugin.zsh の存在確認
                  │
                  ├─ [無効] → 警告 → continue
                  │
                  ├─ fpath更新
                  │      └─ fpath=("$base" $fpath)
                  │
                  ├─ 補完ファイル検出
                  │      └─ $base/_* パターンマッチ
                  │
                  └─ source実行
                         └─ source "$base/$plugin.plugin.zsh"

           │
           └─ [補完あり] → compinit -D -d "$_comp_dumpfile"
```

### データフロー図

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

プラグイン名 ───▶ _omz::plugin::load
                       │
                       ▼
                プラグイン検索
                       │
         ┌─────────────┼─────────────┐
         │             │             │
    [カスタム]    [ビルトイン]   [未発見]
         │             │             │
         └──────┬──────┘             ▼
                │                 警告出力
                ▼
           base変数設定
                │
                ▼
          有効性検証
                │
         ┌──────┴──────┐
         │             │
      [有効]        [無効]
         │             │
         │             ▼
         │         警告出力
         │
         ▼
      fpath更新
         │
         ▼
    補完ファイル検出
         │
         ▼
      source実行
         │
         ▼
   ┌─────┴─────┐
   │           │
[補完あり]  [補完なし]
   │           │
   ▼           │
compinit -D    │
   │           │
   └─────┬─────┘
         │
         ▼
    処理完了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz plugin loadコマンドの実装 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $_comp_dumpfile変数の定義 |
| *.plugin.zsh | `plugins/*/` | プラグイン | 読み込み対象のプラグインファイル |
| _* | `plugins/*/` | 補完 | プラグインの補完関数定義 |
