# 画面設計書 22-theme_chooser.sh

## 概要

本ドキュメントは、Oh My Zshのテーマ選択ツール `theme_chooser.sh` の設計仕様を定義する。このスクリプトは対話形式でテーマをプレビューし、お気に入りリストに追加できるCLIツールである。

### 本画面の処理概要

本スクリプトは、Oh My Zshで利用可能なすべてのテーマを順番にプレビュー表示し、ユーザーがお気に入りのテーマを選択してリストに保存できる対話型ツールである。

**業務上の目的・背景**：Oh My Zshには多数のテーマが同梱されており（150以上）、ユーザーが自分の好みに合ったテーマを見つけるのは容易ではない。本ツールは各テーマを実際にプレビュー表示することで、ユーザーが視覚的にテーマを比較・選択できるようにする。お気に入りリスト機能により、後で再検討するためのテーマを記録しておくことができる。

**画面へのアクセス方法**：
1. 直接実行: `$ZSH/tools/theme_chooser.sh` または `zsh $ZSH/tools/theme_chooser.sh`
2. オプション付き実行: `theme_chooser.sh -l`（一覧表示）、`theme_chooser.sh -s`（プレビュー表示のみ）
3. テーマ指定: `theme_chooser.sh <theme_name>`（特定テーマのみプレビュー）

**主要な操作・処理内容**：
1. `$ZSH/themes` ディレクトリからすべての `.zsh-theme` ファイルを検出
2. 各テーマを順番にソースして、実際のPROMPTとRPROMPTを表示
3. ユーザーにお気に入りリストへの追加を確認（y/N形式）
4. 選択されたテーマを `~/.zsh_favlist` ファイルに保存
5. 重複チェックを行い、既にリストにあるテーマは追加しない

**画面遷移**：
- 入口：ユーザーによる直接実行
- 出口：全テーマのプレビュー完了後に終了（他画面への遷移なし）

**権限による表示制御**：特になし。ただし、お気に入りリストファイル `~/.zsh_favlist` への書き込み権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | theme_chooser.sh | 主機能 | 対話的にテーマを試して選択するツール |
| 3 | テーマ読み込み | 補助機能 | is_theme関数を使用してテーマファイルをプレビュー用に読み込み |

## 画面種別

CLI対話型ツール

## URL/ルーティング

```
$ZSH/tools/theme_chooser.sh [options] [theme]
```

### コマンドラインオプション

| オプション | 説明 |
|-----------|------|
| -l | 利用可能なテーマ名を一覧表示 |
| -s | 全テーマをプレビュー表示（お気に入り登録プロンプトなし） |
| -h | ヘルプメッセージを表示 |
| [theme] | 指定したテーマのみをプレビュー |

## 入出力項目

### 入力パラメータ

| No | パラメータ名 | 位置 | 必須 | デフォルト値 | 説明 |
|----|-------------|------|------|-------------|------|
| 1 | option | オプション | いいえ | なし | -l/-s/-h のいずれか |
| 2 | theme | $1 | いいえ | なし | プレビューするテーマ名 |

### 環境変数

| 変数名 | 必須 | 説明 |
|--------|------|------|
| ZSH | はい | Oh My Zshのインストールディレクトリ |
| HOME | はい | お気に入りリストファイルの配置先 |
| COLUMNS | いいえ | ターミナル幅（ヘッダー装飾に使用） |

### ユーザー入力

| 入力種別 | フォーマット | 説明 |
|---------|-------------|------|
| お気に入り確認 | y/N | 表示中のテーマをお気に入りリストに追加するか |

## 表示項目

### バナー表示

スクリプト起動時（オプションなし実行時）に "ZSH THEME CHOOSER" のASCIIアートバナーを表示。

### テーマプレビュー表示

| 要素 | 説明 |
|-----|------|
| ヘッダー区切り線 | 青色の罫線（─）とテーマ名を表示 |
| PROMPT | テーマのPROMPT変数を展開して表示 |
| RPROMPT | テーマのRPROMPT変数を展開して表示 |
| 確認プロンプト | "Do you want to add it to your favourite list?" |

### テーマ一覧表示（-l オプション）

| 要素 | 説明 |
|-----|------|
| テーマ名 | `.zsh-theme` 拡張子を除いたファイル名を1行ずつ表示 |

## イベント仕様

### 1-スクリプト起動

**トリガー**: スクリプト実行

**処理フロー**:
1. `$ZSH/oh-my-zsh.sh` をソースして環境を初期化
2. getoptsでオプションを解析
3. オプションに応じて処理を分岐

### 2-テーマ一覧表示（-l）

**トリガー**: `-l` オプション指定

**処理内容**:
1. `$ZSH/themes` ディレクトリの全ファイルをリスト
2. 各ファイル名から `.zsh-theme` 拡張子を除去
3. テーマ名を標準出力に表示

### 3-テーマプレビュー（-s または 引数なし）

**トリガー**: `-s` オプションまたはオプションなし実行

**処理内容**:
1. オプションなしの場合、バナーを表示
2. `$ZSH/themes` ディレクトリの全テーマをループ
3. 各テーマに対して `theme_preview` 関数を実行
4. オプションなしの場合、お気に入り登録を確認
5. 確認で「y」の場合、`insert_favlist` 関数を実行

### 4-単一テーマプレビュー

**トリガー**: テーマ名を引数に指定

**処理内容**:
1. 指定されたテーマ名に `.zsh-theme` を付加
2. `theme_preview` 関数でプレビュー表示

### 5-お気に入り登録

**トリガー**: プロンプトで「y」を入力

**処理内容**:
1. `~/.zsh_favlist` ファイルに既存登録をチェック
2. 未登録の場合、テーマ名を追記
3. 既登録の場合、"Already in favlist" を表示

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

本スクリプトはデータベースを使用しない。ファイルベースのお気に入りリスト管理を行う。

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

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

### ファイル操作

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| お気に入り登録 | ~/.zsh_favlist | READ/APPEND | 重複チェック後にテーマ名を追記 |

## メッセージ仕様

| No | メッセージ種別 | メッセージ内容 | 表示条件 |
|----|---------------|---------------|----------|
| 1 | 確認 | "Do you want to add it to your favourite list (~/.zsh_favlist)? [y/N]" | テーマプレビュー後 |
| 2 | 情報 | "Already in favlist" | 既にお気に入りに登録済みの場合 |
| 3 | 情報 | "Saved to favlist" | お気に入りへの追加成功時 |
| 4 | ヘルプ | "Usage: $0 [options] [theme]" | -h オプション時 |

## 例外処理

| No | 例外状況 | 処理内容 |
|----|---------|----------|
| 1 | テーマディレクトリが存在しない | lsコマンドのエラーにより正常に動作しない |
| 2 | 指定テーマが存在しない | sourceエラーが発生（エラーハンドリングなし） |
| 3 | お気に入りファイルへの書き込み権限なし | シェルのエラーメッセージが表示される |

## 備考

- ライセンス: WTFPL (Do What The Fuck You Want To Public License, Version 2)
- 作者: fox (fox91 at anche dot no)
- テーマファイルは `$ZSH/themes/*.zsh-theme` のパターンで検索される
- お気に入りリストファイルは `~/.zsh_favlist` に保存される
- プレビュー時に `(exit 1)` を実行してエラー状態を模擬している（プロンプト表示確認用）

---

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

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

### 推奨読解順序

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

まず、スクリプトで使用される定数と設定ファイルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 行10-11: THEMES_DIRとFAVLIST定数の定義 |
| 1-2 | theme_chooser.sh | `tools/theme_chooser.sh` | 行12: oh-my-zsh.shのソースで環境初期化 |

**読解のコツ**: `$ZSH` 環境変数はOh My Zshのインストールディレクトリを指し、通常は `~/.oh-my-zsh` である。

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

処理の起点となるオプション解析とメイン処理を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 行80-88: getopts によるオプション解析 |
| 2-2 | theme_chooser.sh | `tools/theme_chooser.sh` | 行90-98: メイン処理の条件分岐 |

**主要処理フロー**:
1. **行80-88**: `-l`（一覧表示）、`-s`（プレビュー表示）、`-h`（ヘルプ）を解析
2. **行90-98**: オプションなしの場合の処理を分岐

#### Step 3: テーマプレビュー処理を理解する

テーマの実際の表示ロジック。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 行22-30: theme_preview関数 |

**主要処理フロー**:
- **行23**: 引数からテーマファイル名を取得
- **行24**: sedで`.zsh-theme`拡張子を除去してテーマ名を抽出
- **行25**: 青色の区切り線とテーマ名をヘッダーとして表示
- **行26**: テーマファイルをsourceして環境変数（PROMPT, RPROMPT）を設定
- **行28**: `(exit 1)` でエラー状態を模擬
- **行29**: PROMPTとRPROMPTを展開表示

#### Step 4: テーマ選択ループを理解する

全テーマを順番に処理するループ処理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 行67-78: theme_chooser関数 |

**主要処理フロー**:
- **行68**: `$THEMES_DIR` 内の全ファイルをループ
- **行70**: 各テーマでtheme_preview関数を呼び出し
- **行72-74**: 引数なしの場合、お気に入り登録を確認

#### Step 5: お気に入り登録処理を理解する

ファイルベースのお気に入り管理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 行57-65: insert_favlist関数 |

**主要処理フロー**:
- **行58**: grepでお気に入りリストに既存登録がないかチェック
- **行59**: 既登録の場合 "Already in favlist" を表示
- **行61**: 未登録の場合、ファイルにテーマ名を追記

#### Step 6: ユーティリティ関数を理解する

対話入力やヘルプ表示などの補助機能。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | theme_chooser.sh | `tools/theme_chooser.sh` | 行14-20: noyes関数（y/N確認） |
| 6-2 | theme_chooser.sh | `tools/theme_chooser.sh` | 行40-48: usage関数（ヘルプ表示） |
| 6-3 | theme_chooser.sh | `tools/theme_chooser.sh` | 行50-55: list_themes関数（テーマ一覧） |
| 6-4 | theme_chooser.sh | `tools/theme_chooser.sh` | 行32-38: banner関数（ASCIIアート） |

**主要処理フロー**:
- **行15**: `read "a?$1"` でプロンプト付き入力を受け付け
- **行16-18**: N/n/空文字で0（true）、それ以外で1（false）を返す

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

```
theme_chooser.sh [options] [theme]
    |
    +-- source $ZSH/oh-my-zsh.sh (環境初期化)
    |
    +-- getopts (オプション解析)
    |       |
    |       +-- -l: list_themes()
    |       |       +-- ls $THEMES_DIR
    |       |       +-- sed (拡張子除去)
    |       |
    |       +-- -s: theme_chooser(0)
    |       |       +-- [全テーマループ]
    |       |           +-- theme_preview()
    |       |
    |       +-- -h: usage()
    |
    +-- (オプションなし)
            |
            +-- (引数なし): banner() + theme_chooser()
            |       +-- [全テーマループ]
            |           +-- theme_preview()
            |           +-- noyes() (確認)
            |           +-- insert_favlist() (登録)
            |
            +-- (引数あり): theme_preview($1.zsh-theme)
```

### データフロー図

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

コマンドライン引数        getopts解析
(-l/-s/-h/theme)         オプション判定
        |                         |
        v                         v
$ZSH/themes/*.zsh-theme   theme_preview関数
(テーマファイル)          ├── source (テーマ読み込み)
        |                 └── print (PROMPT/RPROMPT表示)
        |                         |
        v                         v
                          [標準出力]
                          ├── ヘッダー区切り線
                          ├── テーマ名
                          └── プロンプト表示
        |
        v
ユーザー入力 (y/N)        noyes関数
        |                 入力判定
        |                         |
        v                         v
~/.zsh_favlist            insert_favlist関数
(お気に入りリスト)        ├── grep (重複チェック)
                          └── echo >> (追記)
                                  |
                                  v
                          [~/.zsh_favlist]
                          テーマ名が1行ずつ保存
```

### 関連ファイル一覧

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