# 画面設計書 8-omz theme list

## 概要

本ドキュメントは、Oh My Zshの`omz theme list`コマンドインターフェースの画面設計書です。利用可能なテーマの一覧を表示する機能を定義します。

### 本画面の処理概要

`omz theme list`コマンドは、Oh My Zshで利用可能なすべてのテーマの一覧を表示します。テーマはビルトイン（標準同梱）とカスタム（ユーザー追加）に分類されて表示され、現在使用中のテーマも確認できます。

**業務上の目的・背景**：Oh My Zshには150以上のビルトインテーマが存在し、ユーザーは独自のカスタムテーマを追加することも可能です。ターミナルの見た目をカスタマイズする際、どのようなテーマが利用可能かを把握することが重要です。本コマンドにより、ユーザーはテーマの探索と選択を効率的に行えます。

**画面へのアクセス方法**：ターミナルで以下のコマンドを実行します。
- `omz theme list` - すべての利用可能なテーマを一覧表示

**主要な操作・処理内容**：
1. `$ZSH_CUSTOM`ディレクトリからカスタムテーマを検索
2. `$ZSH/themes`ディレクトリからビルトインテーマを検索
3. 現在使用中のテーマ（`$ZSH_THEME`）を表示
4. カスタムテーマとビルトインテーマを分類して表示
5. パイプ出力時は1行1テーマ形式で出力

**画面遷移**：
- 遷移元：`omz theme`コマンドから
- 遷移先：表示完了後、シェルプロンプトに戻る

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | omzコマンド | 主機能 | omzコマンドの統合CLIインターフェースを通じてテーマ一覧を表示 |
| 13 | omz theme list | 主機能 | 利用可能なテーマ一覧を表示 |

## 画面種別

一覧表示

## URL/ルーティング

```
omz theme list
```

## 入出力項目

### 入力項目

なし（引数なし）

### 出力項目

| 項目名 | 出力先 | 説明 |
|--------|--------|------|
| テーマ一覧 | 標準出力（stdout） | カテゴリ別のテーマ名リスト |

## 表示項目

| 項目 | 説明 | 表示形式 |
|------|------|----------|
| Current theme | 現在使用中のテーマ | 太字・下線（`%U%BCurrent theme%b%u: <name>`） |
| Random theme | randomテーマ使用時の実際のテーマ | `<name> (via random)` |
| Custom themes | カスタムテーマのセクションヘッダー | 太字・下線（`%U%BCustom themes%b%u:`） |
| カスタムテーマ名 | $ZSH_CUSTOM配下のテーマ | 複数列表示（print -lac） |
| Built-in themes | ビルトインテーマのセクションヘッダー | 太字・下線（`%U%BBuilt-in themes%b%u:`） |
| ビルトインテーマ名 | $ZSH/themes配下のテーマ | 複数列表示（print -lac） |

## イベント仕様

### 1-テーマ一覧表示イベント

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

**処理フロー**：
1. カスタムテーマをグロブで検索（`$ZSH_CUSTOM/**/*.zsh-theme`）
2. ビルトインテーマをグロブで検索（`$ZSH/themes/*.zsh-theme`）
3. 出力先がパイプかターミナルかを判定
4. パイプ出力時：1行1テーマ形式で出力
5. ターミナル出力時：
   a. 現在のテーマ（`$ZSH_THEME`）を表示
   b. カスタムテーマをヘッダー付きで複数列表示
   c. ビルトインテーマをヘッダー付きで複数列表示

**データの流れ**：
```
コマンド実行 → テーマ検索 → 分類・整形 → stdout
```

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

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

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

本コマンドは情報表示のみを行い、ファイルシステムやデータベースへの変更は発生しません。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| ヘッダー | Current theme: <name> | $ZSH_THEMEが設定されている場合 |
| ヘッダー | Custom themes: | カスタムテーマが存在する場合 |
| ヘッダー | Built-in themes: | ビルトインテーマが存在する場合 |

## 例外処理

| 例外状態 | 処理内容 | 戻り値 |
|----------|----------|--------|
| テーマが見つからない | 空の出力 | 0 |
| ディレクトリアクセスエラー | シェルのデフォルトエラー処理 | 非0 |

## 備考

- テーマ名は`.zsh-theme`拡張子を除いた名前で表示される
- カスタムテーマは`$ZSH_CUSTOM/themes/`または`$ZSH_CUSTOM/`直下の任意のサブディレクトリに配置可能
- `random`テーマが選択されている場合、実際に適用されたテーマ名が`$RANDOM_THEME`から表示される
- パイプ出力時はエスケープ処理（`${(q-)...}`）されたテーマ名が1行ずつ出力される

---

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

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

### 推奨読解順序

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

テーマ一覧機能で使用される主要なデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cli.zsh | `lib/cli.zsh` | 行767で`custom_themes`と`builtin_themes`の配列宣言を確認 |
| 1-2 | oh-my-zsh.sh | `oh-my-zsh.sh` | `$ZSH_THEME`と`$RANDOM_THEME`変数を確認 |

**読解のコツ**: zshのグロブ修飾子`(-.N:r:gs:...:::)`は複雑ですが、`:r`は拡張子を除去、`:gs:pattern:replacement:`はグローバル置換を意味します。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cli.zsh | `lib/cli.zsh` | `_omz::theme`関数（745-764行目）でサブコマンドルーティングを確認 |
| 2-2 | cli.zsh | `lib/cli.zsh` | `_omz::theme::list`関数（766-794行目）がlist処理の本体 |

**主要処理フロー**:
1. **行746**: サブコマンドが指定されていない、または対応する関数がない場合はヘルプを表示
2. **行760-763**: サブコマンド関数を動的に呼び出し

#### Step 3: テーマ一覧ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cli.zsh | `lib/cli.zsh` | 行767-769でテーマ検索グロブを確認 |
| 3-2 | cli.zsh | `lib/cli.zsh` | 行771-775でパイプ出力処理を確認 |
| 3-3 | cli.zsh | `lib/cli.zsh` | 行777-793でターミナル出力処理を確認 |

**主要処理フロー**:
- **行768**: カスタムテーマのグロブ（複雑なパス正規化を含む）
- **行769**: ビルトインテーマのグロブ
- **行772-774**: パイプ出力時は`print -l`で1行ずつ出力
- **行777-782**: 現在のテーマを表示（random時は実際のテーマ名も表示）
- **行784-788**: カスタムテーマをヘッダー付きで表示
- **行790-793**: ビルトインテーマをヘッダー付きで表示

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

```
omz theme list
    │
    └─ omz (エントリーポイント)
           │
           └─ _omz::theme
                  │
                  └─ _omz::theme::list
                         │
                         ├─ テーマ検索
                         │      ├─ $ZSH_CUSTOM/**/*.zsh-theme
                         │      └─ $ZSH/themes/*.zsh-theme
                         │
                         ├─ [パイプ出力]
                         │      └─ print -l
                         │
                         └─ [ターミナル出力]
                                ├─ Current theme表示
                                │      └─ $ZSH_THEME / $RANDOM_THEME
                                ├─ Custom themes表示
                                │      └─ print -P / print -lac
                                └─ Built-in themes表示
                                       └─ print -P / print -lac
```

### データフロー図

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

(引数なし) ───▶ _omz::theme::list
                       │
                       ▼
                 テーマ検索
                       │
         ┌─────────────┴─────────────┐
         │                           │
  $ZSH_CUSTOM/**/*.zsh-theme   $ZSH/themes/*.zsh-theme
         │                           │
         ▼                           ▼
   custom_themes配列          builtin_themes配列
         │                           │
         └───────────┬───────────────┘
                     │
                     ▼
                出力先判定
                     │
        ┌────────────┴────────────┐
        │                         │
    [パイプ]                  [ターミナル]
        │                         │
        ▼                         ▼
    print -l              Current theme表示
        │                         │
        │                 Custom themes表示
        │                         │
        │                Built-in themes表示
        │                         │
        └───────────┬─────────────┘
                    │
                    ▼
                 stdout
```

### 関連ファイル一覧

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