# 機能設計書 84-theme_chooser.sh

## 概要

本ドキュメントは、Oh My Zshのテーマを対話的にプレビュー・選択できる`theme_chooser.sh`ツールの機能設計について記述する。

### 本機能の処理概要

Oh My Zshに含まれる全テーマを順次プレビュー表示し、ユーザーがお気に入りリストに追加できる対話的なテーマ選択ツールである。各テーマの実際のプロンプト表示を確認しながら、好みのテーマを記録できる。

**業務上の目的・背景**：Oh My Zshには150以上のテーマが含まれており、最適なテーマを見つけることは容易ではない。各テーマを手動で設定して確認するのは非効率であるため、全テーマを一覧で確認しながら気に入ったものを記録できるツールが必要となる。このツールにより、ユーザーは効率的にテーマを比較・選択できる。

**機能の利用シーン**：新規にOh My Zshをインストールした後、または新しいテーマを探したい場合に使用する。対話モードでは各テーマを確認しながらお気に入りに追加でき、後で参照できるリストを作成できる。

**主要な処理内容**：
1. $ZSH/themesディレクトリから全テーマファイルを取得
2. 各テーマを順次sourceしてプロンプトをプレビュー表示
3. ユーザーの選択に応じてお気に入りリストに追加
4. テーマ一覧表示、全テーマ表示、単一テーマプレビューのオプション提供

**関連システム・外部連携**：oh-my-zsh.shをsourceしてOh My Zsh環境を初期化する。

**権限による制御**：特になし。読み取り専用の操作。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | theme_chooser.sh | 主画面 | 対話的にテーマを試して選択するツール |

## 機能種別

ユーティリティ / 対話型ツール

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| -l | フラグ | No | テーマ名の一覧を表示 | - |
| -s | フラグ | No | 全テーマを表示（お気に入り追加なし） | - |
| -h | フラグ | No | ヘルプメッセージを表示 | - |
| theme | 文字列 | No | 単一テーマ名（プレビュー表示） | - |

### 入力データソース

- `$ZSH/themes/`ディレクトリ：テーマファイル（.zsh-theme）
- ユーザー入力：対話モードでのお気に入り追加の応答

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 画面出力 | 文字列 | テーマプレビュー、バナー、プロンプト表示 |
| ~/.zsh_favlist | ファイル | お気に入りテーマリスト |

### 出力先

- 標準出力：テーマプレビュー、メニュー
- `~/.zsh_favlist`：お気に入りリスト

## 処理フロー

### 処理シーケンス

```
1. 引数の解析
   └─ getoptsでオプション（-l/-s/-h）を判定
2. モード別処理
   ├─ -l: テーマ名一覧を表示
   ├─ -s: 全テーマを表示（お気に入り追加なし）
   ├─ -h: ヘルプ表示
   └─ 引数あり: 指定テーマのプレビュー
3. デフォルト動作（引数なし）
   └─ バナー表示後、対話モードで全テーマをプレビュー
4. 対話モード
   ├─ テーマをsourceしてプロンプト表示
   ├─ お気に入り追加の確認
   └─ 選択されたテーマを~/.zsh_favlistに追加
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{オプション解析}
    B -->|-l| C[list_themes: テーマ名一覧表示]
    B -->|-s| D[theme_chooser 0: 全テーマ表示]
    B -->|-h| E[usage: ヘルプ表示]
    B -->|引数あり| F[theme_preview: 単一テーマプレビュー]
    B -->|引数なし| G[banner: バナー表示]
    G --> H[theme_chooser: 対話モード]
    H --> I{次のテーマ}
    I -->|あり| J[theme_preview: プレビュー表示]
    J --> K{お気に入りに追加?}
    K -->|Yes| L[insert_favlist: リストに追加]
    K -->|No| I
    L --> I
    I -->|なし| M[終了]
    C --> M
    D --> M
    E --> M
    F --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-84-001 | 重複チェック | 既にお気に入りリストにあるテーマは追加しない | insert_favlist実行時 |
| BR-84-002 | デフォルトNo | お気に入り追加の確認はデフォルトNo | 空Enter入力時 |
| BR-84-003 | 拡張子除去 | テーマ名表示時は.zsh-theme拡張子を除去 | theme_preview/list_themes実行時 |

### 計算ロジック

テーマ名抽出：
- コマンド: `echo $THEME | sed s/\.zsh-theme$//`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | テーマ不在 | 指定テーマファイルが存在しない | エラーメッセージなし（sourceエラー） |

### リトライ仕様

リトライは行わない。

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

トランザクション管理なし。お気に入りリストへの追加は即時反映。

## パフォーマンス要件

特になし。対話的なツールであり、ユーザーの操作速度に依存。

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

- テーマファイルをsourceするため、悪意あるテーマは任意コード実行の可能性あり
- 公式テーマのみを対象とすることを想定

## 備考

- WTFPLライセンス（Do What The Fuck You Want To Public License）
- 作者: fox (fox91 at anche dot no)
- カラー出力にANSIエスケープシーケンスを使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 80-98行目: メイン処理（getoptsによるオプション解析） |

**読解のコツ**: zshスクリプトだが、基本的なシェルスクリプトの構文を使用。

**主要処理フロー**:
1. **10-12行目**: THEMES_DIR、FAVLISTの定義とoh-my-zsh.shの読み込み
2. **80-88行目**: getoptsによるオプション解析
3. **90-98行目**: オプションなしの場合のデフォルト動作

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 14-20行目: noyes関数 |
| 2-2 | theme_chooser.sh | `tools/theme_chooser.sh` | 22-30行目: theme_preview関数 |
| 2-3 | theme_chooser.sh | `tools/theme_chooser.sh` | 50-55行目: list_themes関数 |
| 2-4 | theme_chooser.sh | `tools/theme_chooser.sh` | 57-65行目: insert_favlist関数 |
| 2-5 | theme_chooser.sh | `tools/theme_chooser.sh` | 67-78行目: theme_chooser関数 |

**主要処理フロー**:
- **14-20行目**: noyes関数はデフォルトNoの確認プロンプト
- **22-30行目**: theme_previewはテーマをsourceしてプロンプトをprint -Pで表示
- **25行目**: ヘッダー行の表示（テーマ名を中央配置）
- **26行目**: テーマファイルをsource
- **29行目**: PROMPTとRPROMPTを表示
- **50-55行目**: list_themesは全テーマ名を出力
- **57-65行目**: insert_favlistはお気に入りリストに追加（重複チェックあり）
- **67-78行目**: theme_chooserは全テーマを順次プレビュー

#### Step 3: バナー表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 32-38行目: banner関数 |

**主要処理フロー**:
- **34-36行目**: ANSIカラーコードを使用したASCIIアートバナー

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

```
theme_chooser.sh
    │
    ├─ banner()
    │
    ├─ theme_chooser()
    │      │
    │      ├─ theme_preview()
    │      │      └─ source $THEMES_DIR/$THEME
    │      │
    │      ├─ noyes()
    │      │
    │      └─ insert_favlist()
    │
    ├─ list_themes()
    │
    └─ usage()
```

### データフロー図

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

$ZSH/themes/*.zsh-theme ─┐
                         │
コマンドライン引数 ───────┼─▶ theme_chooser.sh ─────────▶ 画面出力
                         │         │                    (プレビュー)
ユーザー入力 ────────────┘         │
                                   └─▶ ~/.zsh_favlist
                                       (お気に入りリスト)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| theme_chooser.sh | `tools/theme_chooser.sh` | ソース | テーマ選択ツールのメインスクリプト |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | Oh My Zsh環境の初期化 |
| *.zsh-theme | `themes/*.zsh-theme` | テンプレート | 各テーマファイル |
| .zsh_favlist | `~/.zsh_favlist` | 設定 | お気に入りテーマリスト |
