# 画面設計書 9-omz theme use

## 概要

本ドキュメントは、Oh My Zshの`omz theme use`コマンドインターフェースの画面設計書です。指定されたテーマを現在のシェルセッションに一時的に適用する機能を定義します。

### 本画面の処理概要

`omz theme use`コマンドは、指定されたテーマを現在のシェルセッションに一時的に適用します。.zshrcは変更せず、次回のシェル起動時には元のテーマに戻ります。テーマのプレビューや一時的な変更に適しています。

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

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz theme use <theme>` - 指定テーマを現在のセッションに適用

**主要な操作・処理内容**：
1. 指定されたテーマの存在を確認（カスタム/ビルトインディレクトリ）
2. テーマファイル（.zsh-theme）をsource
3. `$ZSH_THEME`変数を更新
4. randomテーマでない場合は`$RANDOM_THEME`をunset

**画面遷移**：
- 遷移元：`omz theme`コマンドから
- 遷移先：テーマ適用後、即座に新しいプロンプトが表示される（リロードなし）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてテーマを一時適用 |
| 15 | omz theme use | 主機能 | 指定テーマを現在のセッションにロード |
| 3 | テーマ読み込み | 補助機能 | is_theme関数を使用してテーマファイルを読み込み |

## 画面種別

機能実行（テーマ一時適用）

## URL/ルーティング

```
omz theme use <theme>
```

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| theme | string | はい | 適用するテーマ名 |

### 出力項目

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

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| エラー：未発見 | テーマが見つからない場合のエラー | `omz theme use: <name> theme not found` |

## イベント仕様

### 1-テーマ一時適用イベント

**トリガー**：`omz theme use <theme>`コマンドの実行

**処理フロー**：
1. 引数の存在を検証
2. テーマファイルの検索（優先順位）：
   a. `$ZSH_CUSTOM/$1.zsh-theme`
   b. `$ZSH_CUSTOM/themes/$1.zsh-theme`
   c. `$ZSH/themes/$1.zsh-theme`
3. 見つかった場合、テーマファイルをsource
4. `$ZSH_THEME`変数を更新
5. randomテーマでない場合は`$RANDOM_THEME`をunset

**データの流れ**：
```
ユーザー入力 → テーマ検索 → source実行 → 変数更新 → プロンプト更新
```

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| テーマ一時適用 | なし | - | ファイルシステムへの変更なし |

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

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

| 変数名 | 操作種別 | 概要 |
|--------|---------|------|
| ZSH_THEME | UPDATE | 指定されたテーマ名に更新 |
| RANDOM_THEME | DELETE | randomでない場合はunset |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| 使用方法 | `Usage: omz theme use <theme>` | テーマ名が指定されていない場合 |
| エラー | `<theme> theme not found` | テーマファイルが見つからない場合 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| 引数なし | 使用方法を表示 | 1 |
| テーマ未発見 | エラーメッセージを表示 | 1 |

## 備考

- テーマの適用は現在のセッションにのみ影響し、.zshrcは変更されない
- テーマの検索順序：`$ZSH_CUSTOM/<theme>.zsh-theme` > `$ZSH_CUSTOM/themes/<theme>.zsh-theme` > `$ZSH/themes/<theme>.zsh-theme`
- テーマ適用後、プロンプトは即座に更新される（リロード不要）
- `random`テーマを指定した場合は`$RANDOM_THEME`は維持される
- テーマファイルのsourceにより、PROMPT、RPROMPT等の変数が更新される

---

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

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

### 推奨読解順序

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

テーマ一時適用機能で使用される主要な変数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | `$ZSH_THEME`と`$RANDOM_THEME`変数を確認 |
| 1-2 | cli.zsh | `lib/cli.zsh` | 行869-882でテーマファイル検索パスを確認 |

**読解のコツ**: zshのテーマファイルは主にPROMPT、RPROMPT変数を設定するスクリプトです。sourceすることで即座にプロンプトが変更されます。

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

テーマ一時適用コマンドのエントリーポイントを確認します。

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

**主要処理フロー**:
1. **行863-866**: 引数チェック
2. **行868-878**: テーマファイルの検索とsource
3. **行880-882**: `$ZSH_THEME`の更新と`$RANDOM_THEME`のunset

#### Step 3: テーマ検索と適用ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 行869-877でテーマファイル検索を確認 |
| 3-2 | cli.zsh | `lib/cli.zsh` | 行880-882で変数更新を確認 |

**主要処理フロー**:
- **行869**: `$ZSH_CUSTOM/$1.zsh-theme`を優先チェック
- **行871**: `$ZSH_CUSTOM/themes/$1.zsh-theme`をチェック
- **行873**: `$ZSH/themes/$1.zsh-theme`をチェック
- **行875-877**: すべて見つからない場合はエラー
- **行881**: `$ZSH_THEME`を更新
- **行882**: `random`でなければ`$RANDOM_THEME`をunset

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

```
omz theme use <theme>
    │
    └─ _omz::theme::use
           │
           ├─ 引数チェック
           │
           ├─ テーマファイル検索
           │      ├─ $ZSH_CUSTOM/$1.zsh-theme
           │      ├─ $ZSH_CUSTOM/themes/$1.zsh-theme
           │      └─ $ZSH/themes/$1.zsh-theme
           │
           ├─ [発見] → source
           │      └─ PROMPT, RPROMPT等の変数が更新
           │
           ├─ [未発見] → エラー
           │
           └─ 変数更新
                  ├─ ZSH_THEME="$1"
                  └─ [random以外] → unset RANDOM_THEME
```

### データフロー図

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

テーマ名 ───▶ _omz::theme::use
                    │
                    ▼
              テーマファイル検索
                    │
    ┌───────────────┼───────────────┐
    │               │               │
$ZSH_CUSTOM/     $ZSH_CUSTOM/     $ZSH/
 $1.zsh-theme    themes/$1        themes/$1
    │               │               │
    └───────┬───────┴───────┬───────┘
            │               │
        [発見]          [未発見]
            │               │
            ▼               ▼
         source         エラー出力
            │               │
            ▼               │
    PROMPT変数更新          │
            │               │
            ▼               │
    ZSH_THEME更新           │
            │               │
            ▼               │
   RANDOM_THEME処理         │
            │               │
            └───────┬───────┘
                    │
                    ▼
              プロンプト更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cli.zsh | `lib/cli.zsh` | ソース | omz theme useコマンドの実装 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | $ZSH_THEME、$RANDOM_THEME変数の定義 |
| *.zsh-theme | `themes/` | テーマ | ビルトインテーマファイル |
| *.zsh-theme | `$ZSH_CUSTOM/` | テーマ | カスタムテーマファイル |
