# 帳票設計書 3-list-fonts

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `list-fonts` コマンドが出力する利用可能フォント一覧の設計書です。

### 本帳票の処理概要

`list-fonts` コマンドは、システムで利用可能なフォントをファミリー別にリスト形式で標準出力に表示するCLIリストです。

**業務上の目的・背景**：ユーザーがGhosttyで使用可能なフォントを確認し、設定ファイルで指定するフォントファミリー名を正確に把握できるようにします。フォント設定のトラブルシューティングやフォント選択の参考として不可欠な機能です。

**帳票の利用シーン**：
- Ghosttyの`font-family`設定で使用するフォント名を確認したい場合
- 特定のスタイル（bold、italic）に対応するフォントを探したい場合
- フォントが正しくインストールされているか確認したい場合
- Ghosttyがどのフォントを認識しているか調査したい場合

**主要な出力内容**：
1. フォントファミリー名（グループヘッダー）
2. フォントフェイス名（各ファミリー内の個別フォント）
3. フィルタリング結果（オプション指定時）

**帳票の出力タイミング**：`ghostty +list-fonts` コマンド実行時（各種フィルタオプション対応）

**帳票の利用者**：エンドユーザー、システム管理者、デザイナー

## 帳票種別

CLIリスト（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +list-fonts` | コマンド実行 |
| - | CLI | `ghostty +list-fonts --family="Font Name"` | フィルタ付き実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（stdout） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力への表示 |
| 文字コード | UTF-8 |

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 無 |
| カラー出力 | 無 |
| インタラクティブ | 無 |

## 帳票レイアウト

### レイアウト概要

フォント一覧は階層的なテキスト形式で、ファミリー別にグループ化されて出力されます。

```
┌─────────────────────────────────────┐
│  ファミリー名1                        │
│    フォントフェイス名1-1              │
│    フォントフェイス名1-2              │
│                                     │
│  ファミリー名2                        │
│    フォントフェイス名2-1              │
│    ...                              │
└─────────────────────────────────────┘
```

### ヘッダー部

ヘッダーはありません。

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|------|
| 1 | ファミリー名 | フォントファミリーの名前 | font.Discover | "{s}\n" | 可変 |
| 2 | フォントフェイス名 | 個別フォントの名前 | face.name() | "  {s}\n" | 可変（2文字インデント） |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| --family | 特定ファミリーのみ表示 | No |
| --style | 特定スタイル名でフィルタ | No |
| --bold | ボールドフォントを優先 | No |
| --italic | イタリックフォントを優先 | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | ファミリー名 | 昇順（--family未指定時） |
| 2 | フォントフェイス名 | 昇順（--family未指定時） |

**注意**: `--family`指定時はソートなし（Ghosttyの優先度順）

### 改ページ条件

改ページなし（連続出力）

## データベース参照仕様

### 参照テーブル一覧

データベース参照はありません。システムのフォント発見機構を使用します。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| font.Discover | フォント検索 | プラットフォーム固有API |
| face.familyName | ファミリー名取得 | フォントメタデータ |
| face.name | フルフォント名取得 | フォントメタデータ |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| なし | - | - | 計算処理なし |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C{font.Discoverが有効?}
    C -->|No| D[エラーメッセージ出力]
    D --> E[終了コード1を返却]
    C -->|Yes| F[font.Discover初期化]
    F --> G[フォント検索実行]
    G --> H[ファミリー別にマップ構築]
    H --> I{--family指定あり?}
    I -->|No| J[ファミリー名でソート]
    I -->|Yes| K[ソートスキップ]
    J --> L[各ファミリーをループ]
    K --> L
    L --> M[ファミリー名出力]
    M --> N[フォントフェイス名出力]
    N --> O{全ファミリー処理完了?}
    O -->|No| L
    O -->|Yes| P[バッファフラッシュ]
    P --> Q[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| フォント発見機構なし | コンパイル時に無効化 | "Ghostty was built without a font discovery mechanism..." | ビルド設定確認 |
| ファミリー名取得失敗 | フォントメタデータ読み取りエラー | ログ出力のみ（スキップ） | 次のフォントへ |
| フォント名取得失敗 | フォントメタデータ読み取りエラー | ログ出力のみ（スキップ） | 次のフォントへ |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | システム依存（数百〜数千フォント） |
| 目標出力時間 | 数秒以内 |
| 同時出力数上限 | N/A |

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

- システムフォント情報のみを参照
- ファイルシステムへの書き込みなし
- ユーザー認証不要

## 備考

- `--family`指定時は優先度順で出力（Ghosttyのフォント選択ロジックと同一）
- monospaceフィルタは`--family`未指定時にデフォルトで有効

---

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

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

### 推奨読解順序

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

フォント発見とフォント情報の構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | list_fonts.zig | `src/cli/list_fonts.zig` | Options構造体（10-36行目）のフィルタオプション |
| 1-2 | main.zig | `src/font/main.zig` | font.Discover型の定義 |

**読解のコツ**: Optionsの各フィールドがCLIオプションに直接対応します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | list_fonts.zig | `src/cli/list_fonts.zig` | run関数（62-66行目）がエントリーポイント |
| 2-2 | list_fonts.zig | `src/cli/list_fonts.zig` | runArgs関数（68-165行目）がメイン処理 |

**主要処理フロー**:
1. **68-71行目**: オプション解析
2. **79-92行目**: font.Discover無効時のエラー処理
3. **103-113行目**: フォント検索パラメータ設定
4. **114-135行目**: フォント検索とマップ構築
5. **137-144行目**: ソート処理
6. **146-161行目**: 出力処理

#### Step 3: フォント発見機構を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | discovery.zig | `src/font/discovery.zig` | font.Discoverの実装 |
| 3-2 | Collection.zig | `src/font/Collection.zig` | フォントコレクション管理 |

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ list_fonts.run (list_fonts.zig:62)
                  │
                  └─ runArgs (list_fonts.zig:68)
                         │
                         ├─ args.parse (オプション解析)
                         │
                         ├─ font.Discover.init (フォント発見初期化)
                         │
                         ├─ disco.discover (フォント検索)
                         │      │
                         │      └─ disco_it.next (イテレータ)
                         │             │
                         │             ├─ face.familyName (ファミリー名取得)
                         │             └─ face.name (フォント名取得)
                         │
                         ├─ std.mem.sortUnstable (ソート)
                         │
                         └─ stdout.print (出力)
```

### データフロー図

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

CLIオプション ───▶ list_fonts.runArgs()
                      │
                      ▼
              font.Discover.init()
                      │
                      ▼
              disco.discover()
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
familyName        face.name       フィルタ条件
(メタデータ)      (メタデータ)     (オプション)
    │                 │                 │
    └────────▶ HashMap構築 ◀────────────┘
                      │
                      ▼
                   ソート
                      │
                      ▼
                stdout出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_fonts.zig | `src/cli/list_fonts.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| main.zig | `src/font/main.zig` | ソース | フォントモジュールエントリ |
| discovery.zig | `src/font/discovery.zig` | ソース | フォント発見機構 |
| Collection.zig | `src/font/Collection.zig` | ソース | フォントコレクション |
