# 機能設計書 15-omz theme use

## 概要

本ドキュメントは、Oh My Zshの`omz theme use`コマンドの機能設計について記載する。このコマンドは指定されたテーマを現在のzshセッションに動的にロードする機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Oh My Zshでは多数のテーマが利用可能であり、ユーザーは好みのテーマを探索する必要がある。`.zshrc`を編集してシェルを再起動するのは手間がかかるため、現在のセッションで一時的にテーマを試用できる機能が求められる。本機能は、テーマファイルを`source`で読み込むことで、即座にプロンプトの外観を変更し、テーマの試用を容易にする。

**機能の利用シーン**：
- 新しいテーマを試用したい場合（シェル再起動なしで即座に確認）
- 一時的にテーマを変更したい場合
- `.zshrc`を編集せずにテーマを試したい場合
- テーマ開発時に変更を即座に反映させたい場合

**主要な処理内容**：
1. 引数で指定されたテーマ名を受け取る
2. `$ZSH_CUSTOM`、`$ZSH_CUSTOM/themes`、`$ZSH/themes`の順でテーマファイルを検索
3. テーマファイルを`source`で読み込み
4. `$ZSH_THEME`変数を更新
5. `random`以外のテーマの場合は`$RANDOM_THEME`をクリア

**関連システム・外部連携**：特になし。ローカルファイルシステムのみを参照する。

**権限による制御**：特になし。テーマファイルへの読み取り権限があれば実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | omz theme use | 主画面 | 指定テーマを現在のセッションにロード |

## 機能種別

設定変更・動的ロード

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| theme | 文字列 | Yes | ロードするテーマ名 | テーマファイルの存在確認 |

### 入力データソース

- `$ZSH_CUSTOM/$theme.zsh-theme`: カスタムテーマファイル（優先度1）
- `$ZSH_CUSTOM/themes/$theme.zsh-theme`: カスタムテーマファイル（優先度2）
- `$ZSH/themes/$theme.zsh-theme`: ビルトインテーマファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | - | 標準出力への出力はなし（エラー時のみ） |

### 出力先

- 標準エラー出力: エラーメッセージ（テーマが見つからない場合）
- シェル環境: `$ZSH_THEME`変数の更新、プロンプトの変更

### 副作用

- `$ZSH_THEME`変数が更新される
- `$RANDOM_THEME`変数がクリアされる（randomテーマ以外）
- テーマファイル内で定義された変数・関数が現在のセッションに追加される
- プロンプト（`$PROMPT`、`$RPROMPT`等）が更新される

## 処理フロー

### 処理シーケンス

```
1. 引数の検証
   └─ テーマ名が指定されているか確認

2. テーマファイルの検索
   ├─ $ZSH_CUSTOM/$theme.zsh-themeを確認
   ├─ $ZSH_CUSTOM/themes/$theme.zsh-themeを確認
   └─ $ZSH/themes/$theme.zsh-themeを確認

3. テーマファイルのロード
   └─ 見つかったファイルをsourceで読み込み

4. 変数の更新
   ├─ ZSH_THEME=$theme を設定
   └─ random以外の場合は RANDOM_THEME をunset
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{テーマ名が指定されている?}
    B -->|No| C[使用法を表示して終了]
    B -->|Yes| D{$ZSH_CUSTOM/$theme.zsh-themeが存在?}
    D -->|Yes| E[source $ZSH_CUSTOM/$theme.zsh-theme]
    D -->|No| F{$ZSH_CUSTOM/themes/$theme.zsh-themeが存在?}
    F -->|Yes| G[source $ZSH_CUSTOM/themes/$theme.zsh-theme]
    F -->|No| H{$ZSH/themes/$theme.zsh-themeが存在?}
    H -->|Yes| I[source $ZSH/themes/$theme.zsh-theme]
    H -->|No| J[エラー: テーマが見つからない]
    E --> K[ZSH_THEME=$themeを設定]
    G --> K
    I --> K
    K --> L{$theme = random?}
    L -->|No| M[unset RANDOM_THEME]
    L -->|Yes| N[終了]
    M --> N
    J --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | テーマ検索優先順位 | `$ZSH_CUSTOM/$theme.zsh-theme` → `$ZSH_CUSTOM/themes/$theme.zsh-theme` → `$ZSH/themes/$theme.zsh-theme`の順で検索 | 常時 |
| BR-02 | 即時反映 | テーマをロードした時点でプロンプトが即座に変更される | 常時 |
| BR-03 | セッション限定 | 本機能で変更したテーマは現在のセッションでのみ有効 | 常時 |
| BR-04 | RANDOM_THEMEクリア | `random`以外のテーマを選択した場合、`$RANDOM_THEME`変数をクリア | $theme != random |

### 計算ロジック

特になし。

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

本機能ではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 引数なしエラー | テーマ名が指定されていない | 使用法を表示して終了（リターンコード1） |
| - | テーマ未検出エラー | 指定されたテーマファイルが見つからない | エラーメッセージを出力して終了（リターンコード1） |

### リトライ仕様

リトライは行わない。

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

該当なし。テーマのロードは即座に反映され、ロールバック機能はない。

## パフォーマンス要件

- テーマファイルの検索とロードは通常1秒以内に完了すること
- テーマファイルのサイズに依存（通常は数KB程度）

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

- テーマファイルはzshスクリプトとして実行されるため、信頼できるソースのテーマのみを使用すること
- `$ZSH_CUSTOM`に配置されたカスタムテーマは、ユーザーの責任で管理される
- ビルトインテーマはOh My Zshプロジェクトでレビューされている

## 備考

- 本機能でロードしたテーマは現在のセッションでのみ有効
- 永続的にテーマを設定するには`omz theme set`を使用する
- `random`テーマを使用すると、起動時にランダムなテーマが選択され、`$RANDOM_THEME`に実際のテーマ名が格納される

---

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

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

### 推奨読解順序

#### Step 1: 関数の全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | `_omz::theme::use`関数の定義位置（862-884行目）を確認 |

**読解のコツ**: テーマファイルの検索は`[[ -f ... ]]`による存在確認で行われる。最初に見つかったファイルが使用される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | omz関数（3-21行目）からのコマンドディスパッチを確認 |
| 2-2 | cli.zsh | `lib/cli.zsh` | _omz::theme関数（745-764行目）からのサブコマンドディスパッチを確認 |

**主要処理フロー**:
1. **3-21行目**: `omz`関数がコマンドライン引数を解析し、`_omz::$command`を呼び出す
2. **745-764行目**: `_omz::theme`関数が`use`サブコマンドを受け取り、`_omz::theme::use`を呼び出す

#### Step 3: テーマロード処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | `_omz::theme::use`関数（862-884行目）の実装詳細 |

**主要処理フロー**:
- **863-866行目**: 引数チェックと使用法表示
- **868-870行目**: `$ZSH_CUSTOM/$theme.zsh-theme`の確認とsource
- **871-873行目**: `$ZSH_CUSTOM/themes/$theme.zsh-theme`の確認とsource
- **874-876行目**: `$ZSH/themes/$theme.zsh-theme`の確認とsource
- **877-879行目**: テーマが見つからない場合のエラー処理
- **881-883行目**: `$ZSH_THEME`と`$RANDOM_THEME`の更新

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

```
omz (3-21行目)
    │
    └─ _omz::theme (745-764行目)
           │
           └─ _omz::theme::use (862-884行目)
                  │
                  ├─ テーマファイル検索
                  │      ├─ $ZSH_CUSTOM/$theme.zsh-theme
                  │      ├─ $ZSH_CUSTOM/themes/$theme.zsh-theme
                  │      └─ $ZSH/themes/$theme.zsh-theme
                  │
                  ├─ source (テーマファイル)
                  │
                  └─ ZSH_THEME, RANDOM_THEME 更新
```

### データフロー図

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

テーマ名            ───▶ テーマファイル検索
(コマンドライン)           │
                          ├─ $ZSH_CUSTOM優先
                          └─ $ZSH/themesフォールバック
                               │
                               ▼
                          source (テーマファイル)      ───▶ $PROMPT更新
                               │
                               ▼
                          変数更新
                               │
                               ├─ ZSH_THEME=$theme
                               └─ unset RANDOM_THEME
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omzコマンドのCLI実装。_omz::theme::use関数を含む |
| *.zsh-theme | `themes/*.zsh-theme` | テーマ | プロンプト定義ファイル。各テーマはPROMPT変数等を設定 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $ZSH_THEMEに基づくテーマ読み込みの初期化処理 |
