# 機能設計書 3-テーマ読み込み

## 概要

本ドキュメントは、Oh My Zsh（以下OMZ）のテーマ読み込み機能に関する機能設計書である。$ZSH_THEME変数で指定されたテーマファイル（.zsh-theme）をZSH_CUSTOM、ZSH_CUSTOM/themes、ZSH/themesから検索して読み込む処理について記述する。

### 本機能の処理概要

本機能は、OMZ初期化時にユーザーが指定したテーマを読み込み、シェルのプロンプト外観をカスタマイズする。テーマにはプロンプト文字列、色設定、Git情報表示等が含まれる。

**業務上の目的・背景**：ターミナル作業の効率化と視認性向上のため、プロンプトのカスタマイズは重要な機能である。OMZは150以上の公式テーマを提供しており、ユーザーは好みや作業内容に応じてテーマを選択できる。Git情報やシステム状態の表示により、開発作業の効率が向上する。

**機能の利用シーン**：シェル起動時に自動実行される。ユーザーは.zshrcでZSH_THEME変数を設定することでテーマを指定する。また、`omz theme use`コマンドで一時的にテーマを変更したり、`omz theme set`コマンドで永続的にテーマを変更することも可能。

**主要な処理内容**：
1. ZSH_THEME変数の確認
2. is_theme関数によるテーマファイルの検索
3. テーマファイルのsource
4. プロンプト変数（PROMPT, RPROMPT等）の設定

**関連システム・外部連携**：Git（git_prompt_info等の関数経由）、各種バージョン管理システム情報の取得

**権限による制御**：特になし。テーマファイルへの読み取り権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | omz theme use | 補助機能 | is_theme関数を使用してテーマファイルを読み込み |
| 22 | theme_chooser.sh | 補助機能 | is_theme関数を使用してテーマファイルをプレビュー用に読み込み |

## 機能種別

初期化処理 / 外観設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ZSH_THEME | 環境変数(文字列) | No | 使用するテーマ名 | テーマファイルが存在すること |
| ZSH | 環境変数(文字列) | Yes | OMZインストールディレクトリ | 必須 |
| ZSH_CUSTOM | 環境変数(文字列) | No | カスタムテーマディレクトリ | 未定義時は$ZSH/custom |
| RANDOM_THEME | 変数 | No | ランダムテーマ使用時の実際のテーマ名 | 自動設定 |

### 入力データソース

- ユーザーの.zshrcファイル（ZSH_THEME変数の定義）
- $ZSH/themes/以下の公式テーマ
- $ZSH_CUSTOM/以下のカスタムテーマ
- $ZSH_CUSTOM/themes/以下のカスタムテーマ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PROMPT | 変数 | 左プロンプト文字列 |
| RPROMPT | 変数 | 右プロンプト文字列（オプション） |
| PS1 | 変数 | PROMPTと同義 |
| ZSH_THEME_*変数群 | 変数 | テーマ固有の設定変数 |
| 関数群 | 関数 | テーマが定義する補助関数 |

### 出力先

- シェル環境（プロンプト変数、関数等）

## 処理フロー

### 処理シーケンス

```
1. テーマ指定確認
   └─ ZSH_THEME変数が空でないか確認
   └─ 空の場合はテーマ読み込みをスキップ

2. テーマファイル検索
   └─ is_theme関数でテーマファイルを検索
   └─ 検索順序: ZSH_CUSTOM → ZSH_CUSTOM/themes → ZSH/themes

3. テーマ読み込み
   └─ 見つかったテーマファイルをsource
   └─ 見つからない場合は警告メッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[初期化開始] --> B{ZSH_THEME設定あり?}
    B -->|No| C[テーマ読み込みスキップ]
    B -->|Yes| D{ZSH_CUSTOM/テーマ名.zsh-theme存在?}
    D -->|Yes| E[ZSH_CUSTOMからsource]
    D -->|No| F{ZSH_CUSTOM/themes/テーマ名.zsh-theme存在?}
    F -->|Yes| G[ZSH_CUSTOM/themesからsource]
    F -->|No| H{ZSH/themes/テーマ名.zsh-theme存在?}
    H -->|Yes| I[ZSH/themesからsource]
    H -->|No| J[警告メッセージ出力]
    E --> K[プロンプト設定完了]
    G --> K
    I --> K
    J --> L[デフォルトプロンプト使用]
    C --> L
    K --> M[完了]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | カスタムテーマ優先 | ZSH_CUSTOM直下のテーマを最優先で読み込む | 同名テーマが複数存在する場合 |
| BR-02 | テーマ検索順序 | ZSH_CUSTOM → ZSH_CUSTOM/themes → ZSH/themes | 常時 |
| BR-03 | 空テーマ許容 | ZSH_THEMEが空の場合はテーマを読み込まない | ZSH_THEME="" |
| BR-04 | 存在しないテーマ許容 | 存在しないテーマは警告のみで継続 | 常時 |
| BR-05 | テーマファイル形式 | .zsh-theme拡張子のファイルのみ対象 | 常時 |

### 計算ロジック

**テーマ判定（is_theme関数）**:
```zsh
is_theme() {
  local base_dir=$1
  local name=$2
  builtin test -f $base_dir/$name.zsh-theme
}
```

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | テーマ未検出警告 | 指定テーマが存在しない | `[oh-my-zsh] theme 'xxx' not found`メッセージを出力して継続 |

### リトライ仕様

リトライは行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- テーマ読み込みはシェル起動時間に影響するため、効率的な検索が求められる
- 一部のテーマ（powerline系等）は複雑なプロンプト生成を行うため、起動時間に影響する可能性がある

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

- テーマファイルは任意のZSHコードを実行するため、信頼できるソースからのテーマのみ使用すること
- ZSH_CUSTOMディレクトリのパーミッションを適切に設定すること

## 備考

- `random`テーマを指定すると、利用可能なテーマからランダムに1つが選択される
- テーマ切り替え後はシェルの再起動またはsourceが必要
- 一部のテーマはPowerline対応フォントのインストールが必要

---

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

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

### 推奨読解順序

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

テーマシステムで扱う変数とファイル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | ZSH_THEME変数、テーマ検索パスの関係 |

**読解のコツ**:
- ZSH_THEMEはユーザーが.zshrcで設定
- テーマファイルは`.zsh-theme`拡張子

#### Step 2: is_theme関数を理解する

テーマ存在確認関数の動作を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 215-219行目のis_theme関数 |

**主要処理フロー**:
- **215-219行目**: is_theme関数定義
  ```zsh
  is_theme() {
    local base_dir=$1
    local name=$2
    builtin test -f $base_dir/$name.zsh-theme
  }
  ```

#### Step 3: テーマ読み込み処理を理解する

テーマの検索と読み込みロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | oh-my-zsh.sh | `oh-my-zsh.sh` | 221-231行目のテーマ読み込み処理 |

**主要処理フロー**:
- **221行目**: `if [[ -n "$ZSH_THEME" ]]; then` - テーマ指定確認
- **222-223行目**: ZSH_CUSTOM直下を検索、sourceを実行
- **224-225行目**: ZSH_CUSTOM/themesを検索、sourceを実行
- **226-227行目**: ZSH/themesを検索、sourceを実行
- **228-230行目**: 見つからない場合の警告出力

#### Step 4: omz theme useコマンドを理解する

CLI経由でのテーマ一時適用を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cli.zsh | `lib/cli.zsh` | 862-883行目の_omz::theme::use関数 |

**主要処理フロー**:
- **863-866行目**: 引数チェック
- **868-877行目**: テーマファイルの検索とsource
- **880-882行目**: ZSH_THEME変数とRANDOM_THEME変数の更新

#### Step 5: omz theme setコマンドを理解する

CLI経由でのテーマ永続設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | cli.zsh | `lib/cli.zsh` | 796-860行目の_omz::theme::set関数 |

**主要処理フロー**:
- **802-808行目**: テーマ存在確認
- **811-825行目**: AWKスクリプトによる.zshrc編集
- **827-839行目**: 新規.zshrcファイル作成と置換
- **848-853行目**: 構文エラーチェックとロールバック
- **859行目**: シェルリロード

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

```
oh-my-zsh.sh (初期化時)
    │
    └─ is_theme() - テーマ存在チェック
           ├─ ZSH_CUSTOM検索
           ├─ ZSH_CUSTOM/themes検索
           └─ ZSH/themes検索
                  │
                  └─ source "$theme.zsh-theme" - テーマ読み込み

lib/cli.zsh (omz theme use)
    │
    └─ _omz::theme::use()
           ├─ ZSH_CUSTOM検索
           ├─ ZSH_CUSTOM/themes検索
           ├─ ZSH/themes検索
           ├─ source "$theme.zsh-theme"
           └─ ZSH_THEME更新

lib/cli.zsh (omz theme set)
    │
    └─ _omz::theme::set()
           ├─ テーマ存在確認
           ├─ AWKで.zshrc編集
           ├─ zsh -n構文チェック
           └─ _omz::reload()
```

### データフロー図

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

.zshrc
  │
  └─ ZSH_THEME="name" ───▶ oh-my-zsh.sh
                              │
                              └─▶ is_theme() ───────────────▶ テーマ検索結果
                                      │
$ZSH/themes/                          │
$ZSH_CUSTOM/themes/    ───────────────┘
$ZSH_CUSTOM/                          │
                                      ▼
                              source theme.zsh-theme
                                      │
                                      └─▶ PROMPT, RPROMPT ──▶ シェルプロンプト表示
                                      └─▶ 補助関数定義 ─────▶ シェル環境
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | テーマ読み込みのエントリーポイント |
| cli.zsh | `lib/cli.zsh` | ソース | omz themeコマンド実装 |
| *.zsh-theme | `themes/*.zsh-theme` | ソース | 公式テーマファイル |
| *.zsh-theme | `$ZSH_CUSTOM/*.zsh-theme` | ソース | カスタムテーマファイル |
| *.zsh-theme | `$ZSH_CUSTOM/themes/*.zsh-theme` | ソース | カスタムテーマファイル |
| git.zsh | `lib/git.zsh` | ソース | Git情報取得関数（テーマで使用） |
| theme-and-appearance.zsh | `lib/theme-and-appearance.zsh` | ソース | 色変数定義 |
| .zshrc | `~/.zshrc` | 設定 | ZSH_THEME変数の定義 |
| theme_chooser.sh | `tools/theme_chooser.sh` | ソース | テーマ選択ツール |
