# 機能設計書 72-spectrum_ls

## 概要

本ドキュメントは、Oh My Zshのカラー表示ライブラリ（lib/spectrum.zsh）で提供される`spectrum_ls`関数の機能設計について記述する。

### 本機能の処理概要

`spectrum_ls`関数は、ターミナルで利用可能な256色のフォアグラウンド（前景）カラーを一覧表示するユーティリティ関数である。各色のコード番号（000〜255）とともにサンプルテキストをその色で表示し、テーマやプロンプトのカスタマイズ時に適切な色を選択する際の参考となる。

**業務上の目的・背景**：Zshのプロンプトやテーマをカスタマイズする際、256色パレットから適切な色を選択する必要がある。しかし、色コードだけでは実際の色がわからないため、視覚的に全色を確認できる機能が求められる。本機能はその要求に応え、色選択の効率化を図る。

**機能の利用シーン**：
- 新しいテーマを作成する際に、使用する色を決定する場合
- プロンプトのカスタマイズで、Git状態やユーザー情報の表示色を選ぶ場合
- 既存のテーマの色を調整・変更する場合
- ターミナルエミュレータの256色サポートを確認する場合

**主要な処理内容**：
1. `localoptions nopromptsubst`で一時的にプロンプト置換を無効化
2. サンプルテキスト（ZSH_SPECTRUM_TEXT）を取得（デフォルト: "Arma virumque cano Troiae qui primus ab oris"）
3. 000から255までループし、各色コードでサンプルテキストを表示
4. FG配列（定義済み）から色エスケープシーケンスを取得し、print -Pで出力

**関連システム・外部連携**：ターミナルエミュレータの256色サポートが必要。色表示はANSIエスケープシーケンス（38;5;Nm形式）を使用する。

**権限による制御**：特に権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | ターミナル | 主画面 | 256色フォアグラウンドカラーの一覧表示 |

## 機能種別

参照処理（カラーパレット表示）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 関数は引数を取らない | - |

### 入力データソース

- 環境変数 ZSH_SPECTRUM_TEXT（オプション、サンプルテキストのカスタマイズ用）
- FG連想配列（spectrum.zshで定義済み、色コードをキーとしたエスケープシーケンス）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 色サンプル行 | string | "NNN: [色付きサンプルテキスト]" 形式の256行 |

### 出力先

- 標準出力（ターミナル）

## 処理フロー

### 処理シーケンス

```
1. シェルオプション設定
   └─ setopt localoptions nopromptsubst で一時的に設定変更
2. サンプルテキスト取得
   └─ ZSH_SPECTRUM_TEXT環境変数、未設定時はデフォルト値を使用
3. 色コードループ（000〜255）
   └─ 各コードについて:
      - FG[$code]から色エスケープシーケンスを取得
      - print -P でコード番号と色付きサンプルテキストを出力
      - $reset_colorでリセット
```

### フローチャート

```mermaid
flowchart TD
    A[spectrum_ls呼び出し] --> B[localoptions nopromptsubst設定]
    B --> C[ZSH_SPECTRUM_TEXT取得/デフォルト設定]
    C --> D[code = 000]
    D --> E{code <= 255?}
    E -->|Yes| F["print -P '$code: $FG[$code]$text$reset_color'"]
    F --> G[code++]
    G --> E
    E -->|No| H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-01 | 色コード範囲 | 000から255までの256色を表示 | 常時 |
| BR-72-02 | デフォルトテキスト | ZSH_SPECTRUM_TEXT未設定時は"Arma virumque cano Troiae qui primus ab oris"を使用 | ZSH_SPECTRUM_TEXT未設定時 |
| BR-72-03 | 色リセット | 各行末で$reset_colorを適用し色をリセット | 常時 |

### 計算ロジック

特になし（表示のみ）

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 表示異常 | ターミナルが256色をサポートしていない場合 | 256色対応ターミナルを使用する |

### リトライ仕様

リトライは不要（即時完了する処理）

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

トランザクション管理なし

## パフォーマンス要件

即時完了（数秒以内、256回のprint実行）

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

- 特にセキュリティ上の脆弱性はない
- 表示専用機能のため外部への影響なし

## 備考

- デフォルトのサンプルテキスト "Arma virumque cano Troiae qui primus ab oris" はウェルギリウスの叙事詩『アエネーイス』の冒頭句（「武勇と英雄を歌う、トロイアの岸辺より最初に来たりし者を」）
- FG/BG/FX連想配列はspectrum.zshの初期化時にグローバルに定義される
- 姉妹関数として`spectrum_bls`（背景色表示）がある

---

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

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

### 推奨読解順序

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

まず、色情報を格納するFG/BG/FX連想配列の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | spectrum.zsh | `lib/spectrum.zsh` | FG/BG/FX連想配列の定義（5-20行目） |

**読解のコツ**: Zshの`typeset -AHg`は「連想配列（-A）」「非表示（-H）」「グローバル（-g）」を指定。FXはテキスト装飾（太字、下線など）、FGはフォアグラウンド色、BGはバックグラウンド色を格納。

**主要処理フロー**:
1. **5行目**: `typeset -AHg FX FG BG` - 3つの連想配列をグローバル定義
2. **7-15行目**: FX配列にテキスト装飾のエスケープシーケンスを設定
3. **17-20行目**: 000-255のループでFG/BG配列に色エスケープシーケンスを設定

#### Step 2: spectrum_ls関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | spectrum.zsh | `lib/spectrum.zsh` | spectrum_ls関数の定義（23-29行目） |

**主要処理フロー**:
- **23行目**: `function spectrum_ls()` - 関数定義開始
- **24行目**: `setopt localoptions nopromptsubst` - プロンプト置換を一時的に無効化
- **25行目**: `local ZSH_SPECTRUM_TEXT=...` - サンプルテキストを変数展開（${:-default}構文）
- **26-28行目**: forループで000〜255の色を順番に表示
- **27行目**: `print -P`でプロンプト形式の出力（%{...%}エスケープ処理）

#### Step 3: 色エスケープシーケンスの構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | spectrum.zsh | `lib/spectrum.zsh` | 色コード生成ループ（17-20行目） |

**主要処理フロー**:
- **17行目**: `for color in {000..255}; do` - 色コードループ
- **18行目**: `FG[$color]="%{[38;5;${color}m%}"` - ANSI 256色フォアグラウンド形式
- **19行目**: `BG[$color]="%{[48;5;${color}m%}"` - ANSI 256色バックグラウンド形式

**読解のコツ**: `38;5;N`はANSI拡張256色のフォアグラウンド指定、`48;5;N`はバックグラウンド指定。`%{...%}`はZshプロンプトでエスケープシーケンスをゼロ幅として扱う。

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

```
spectrum_ls() (lib/spectrum.zsh:23-29)
    │
    ├─ setopt localoptions nopromptsubst
    │
    ├─ ZSH_SPECTRUM_TEXT変数参照/デフォルト設定
    │
    └─ for code in {000..255}
           └─ print -P "$code: ${FG[$code]}${text}%{$reset_color%}"
```

### データフロー図

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

ZSH_SPECTRUM_TEXT ─────▶ spectrum_ls関数
(環境変数/デフォルト)          │
                              │
FG連想配列 ────────────────────┼───▶ for code in {000..255} ───▶ 標準出力
(256色エスケープシーケンス)    │          │                    (256行のカラー表示)
                              │          ▼
$reset_color ─────────────────┴───▶ print -P
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| spectrum.zsh | `lib/spectrum.zsh` | ソース | spectrum_ls/spectrum_bls関数およびFG/BG/FX配列の定義 |
| theme-and-appearance.zsh | `lib/theme-and-appearance.zsh` | ソース | $reset_color変数の定義 |
| oh-my-zsh.sh | `oh-my-zsh.sh` | ソース | lib/spectrum.zshを読み込むメインスクリプト |
