# 機能設計書 48-色名一覧

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「色名一覧」機能の設計を記述する。この機能は、CLIコマンド`+list-colors`を通じて、Ghosttyで使用可能な名前付きRGB色（X11カラー）を一覧表示する。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルエミュレータやテーマ設定において、色を名前で指定できることは便利である。Ghosttyは標準的なX11カラー名をサポートしており、ユーザーがこれらの色名と対応するRGB値を確認できることで、設定ファイルでの色指定が容易になる。

**機能の利用シーン**：
- 設定ファイルで使用可能な色名を確認する
- 色名とRGB値の対応を確認する
- 特定の色を設定に使用する際の参考にする

**主要な処理内容**：
1. X11カラーマップからの色名取得
2. アルファベット順ソート
3. TTY検出による出力形式の切り替え
4. 色付きプリティプリント（TTY）
5. プレーンテキスト出力（非TTY）

**関連システム・外部連携**：
- X11カラー定義（内蔵）
- vaxisライブラリ（プリティプリント）

**権限による制御**：特になし。すべてのユーザーが色名一覧を実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| なし | - | - | CLI専用機能のため画面関連なし |

## 機能種別

情報表示 / CLI出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| plain | bool | No | フォーマットなしで出力するかどうか | デフォルト: false |

### 入力データソース

- コマンドライン: `ghostty +list-colors [オプション]`
- 内蔵X11カラーマップ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 色名 | []const u8 | X11カラー名 |
| RGB値 | RGB | 色のRGB値（16進数表記） |

### 出力先

- 標準出力（stdout）

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数のパース
   └─ Options構造体への値設定

2. X11カラーマップからキー取得
   └─ x11_color.map.keys()

3. アルファベット順ソート
   └─ 大文字小文字を無視してソート

4. 出力モードの決定
   └─ TTY + !plain: プリティプリント
   └─ それ以外: プレーン出力

5. 出力
   └─ プリティプリント: 色付きで複数列表示
   └─ プレーン: "名前 = #RRGGBB" 形式
```

### フローチャート

```mermaid
flowchart TD
    A[+list-colors実行] --> B[引数パース]
    B --> C[x11_color.mapからキー取得]
    C --> D[アルファベット順ソート]
    D --> E{TTY && !plain?}
    E -->|Yes| F[prettyPrint]
    E -->|No| G[プレーン出力]
    F --> H[vaxis初期化]
    H --> I[列数計算]
    I --> J[色付き出力]
    J --> K[終了コード0]
    G --> L[name = #RRGGBB形式出力]
    L --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-48-01 | アルファベット順 | 色名は大文字小文字を無視してアルファベット順でソート | 常時 |
| BR-48-02 | プリティプリント | TTY出力かつ--plainでない場合は色付き複数列表示 | isTty() && !opts.plain |
| BR-48-03 | 列幅計算 | プリティプリント時は端末幅に基づいて列数を計算 | プリティプリント時 |

### 計算ロジック

列数計算:
```
column_size = max_name_len + 15  // 名前 + " = #RRGGBB XX" + ガター
columns = (win.width + 2) / column_size
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | I/Oエラー | 標準出力への書き込み失敗 | エラーを返す |

### リトライ仕様

リトライなし。

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

トランザクションは使用しない。

## パフォーマンス要件

- 瞬時に実行完了すること（静的データの出力のみ）

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

- 色情報は機密情報を含まない

## 備考

- X11カラー名はRGB.txtに基づく標準的な色名
- プリティプリント時は実際の色でカラーブロックを表示

---

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

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

### 推奨読解順序

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

Options構造体とX11カラーマップを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | list_colors.zig | `src/cli/list_colors.zig` | Options構造体の定義（10-23行目） |
| 1-2 | x11_color.zig | `src/terminal/x11_color.zig` | X11カラーマップの定義 |

**読解のコツ**: x11_color.mapは静的なHashMapで、色名からRGB値へのマッピングを保持する。

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

run関数の処理フローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | list_colors.zig | `src/cli/list_colors.zig` | run関数（25-74行目） |

**主要処理フロー**:
1. **33-40行目**: 引数パース
2. **42-44行目**: x11_color.mapからキー取得
3. **46-50行目**: アルファベット順ソート
4. **53-57行目**: TTY判定とprettyPrint呼び出し
5. **59-70行目**: プレーン出力

#### Step 3: プリティプリント処理

色付き出力の詳細を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | list_colors.zig | `src/cli/list_colors.zig` | prettyPrint関数（76-209行目） |

**主要処理フロー**:
- **78-102行目**: vaxisとTTYの初期化
- **106-109行目**: 最大色名長の計算
- **112-114行目**: 列数の計算
- **116-206行目**: 各色の出力ループ

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

```
ghostty +list-colors [options]
    │
    └─ cli.list_colors.run
           │
           ├─ args.parse (Optionsへ)
           │
           ├─ x11_color.map.keys()
           │
           ├─ sortUnstable (アルファベット順)
           │
           └─ [TTY && !plain]
                  │
                  ├─ prettyPrint
                  │      ├─ vaxis.init
                  │      ├─ getWinsize (端末サイズ取得)
                  │      ├─ max_name_len計算
                  │      ├─ columns計算
                  │      └─ 色付き出力ループ
                  │
                  └─ [else] プレーン出力
                         └─ "name = #RRGGBB" 形式
```

### データフロー図

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

コマンドライン ──────▶ Options解析 ────────▶ フラグ
     │                     │
     │                     ▼
x11_color.map ────────▶ keys()取得 ────────▶ [][]const u8
     │                     │
     │                     ▼
     │              sortUnstable
     │                     │
     │                     ▼
     └──────────────▶ [TTY]
                          │
                          ├─ prettyPrint
                          │      ├─ 色名表示
                          │      ├─ #RRGGBB表示
                          │      └─ カラーブロック表示
                          │
                          └─ [非TTY] "name = #RRGGBB"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_colors.zig | `src/cli/list_colors.zig` | ソース | 色名一覧コマンドの実装 |
| x11_color.zig | `src/terminal/x11_color.zig` | ソース | X11カラーマップの定義 |
| tui.zig | `src/cli/tui.zig` | ソース | TUI機能の共通ユーティリティ |
| vaxis | 外部ライブラリ | ライブラリ | ターミナルUI描画 |
