# 機能設計書 45-フォント一覧

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「フォント一覧」機能の設計を記述する。この機能は、CLIコマンド`+list-fonts`を通じて、システムにインストールされている利用可能なフォントを一覧表示する。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルエミュレータのフォント設定において、どのフォントが利用可能かを事前に確認できることは重要である。特にプログラミングフォントやNerd Fontsなど、特定のグリフを含むフォントを使用したいユーザーにとって、システムにインストールされているフォントの一覧を確認し、Ghosttyの設定ファイルで指定すべきフォント名を特定することが必要である。

**機能の利用シーン**：
- 新しいフォントをインストールした後に利用可能か確認する
- font-familyに設定するフォント名を確認する
- 特定のスタイル（ボールド、イタリック）のフォントを検索する
- モノスペースフォントのみを一覧表示する

**主要な処理内容**：
1. フォントディスカバリ機構の初期化
2. フィルタ条件（ファミリー、スタイル、ボールド、イタリック）の適用
3. フォントのイテレーションと情報収集
4. ファミリー別にグループ化した結果の出力
5. ソート（アルファベット順）

**関連システム・外部連携**：
- システムフォントディスカバリAPI（fontconfig等）
- ファイルシステム（フォントファイル）

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

## 関連画面

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

## 機能種別

情報表示 / CLI出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| family | ?[:0]const u8 | No | 検索するフォントファミリー名 | なし |
| style | ?[:0]const u8 | No | 検索するスタイル名 | なし |
| bold | bool | No | ボールドスタイルでフィルタ | デフォルト: false |
| italic | bool | No | イタリックスタイルでフィルタ | デフォルト: false |

### 入力データソース

- コマンドライン: `ghostty +list-fonts [オプション]`
- システムフォントディスカバリ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ファミリー名 | []const u8 | フォントファミリー名 |
| フォント名 | []const u8 | 個別のフォント名（スタイル含む） |

### 出力先

- 標準出力（stdout）
- エラー時: 標準エラー出力（stderr）

## 処理フロー

### 処理シーケンス

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

2. フォントディスカバリの存在確認
   └─ コンパイル時にディスカバリ機構がない場合はエラー

3. フォントディスカバリの初期化
   └─ Discover.init()

4. フォント検索の実行
   └─ discover()にフィルタオプションを渡す

5. 結果の収集とグループ化
   └─ ファミリー名でマップに格納

6. ソート処理
   └─ ファミリー指定がない場合はアルファベット順ソート

7. 出力
   └─ ファミリーごとにグループ化して出力
```

### フローチャート

```mermaid
flowchart TD
    A[+list-fonts実行] --> B[引数パース]
    B --> C{ディスカバリ機構あり?}
    C -->|No| D[エラー出力]
    C -->|Yes| E[Discover.init]
    E --> F[discover実行]
    F --> G[結果イテレーション]
    G --> H{次のフォントあり?}
    H -->|Yes| I[ファミリー名/フォント名取得]
    I --> J[マップに格納]
    J --> H
    H -->|No| K{ファミリー指定なし?}
    K -->|Yes| L[アルファベット順ソート]
    K -->|No| M[優先順位順維持]
    L --> N[結果出力]
    M --> N
    N --> O[終了コード0]
    D --> P[終了コード1]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-45-01 | ファミリー未指定時ソート | ファミリーが指定されていない場合はアルファベット順でソート | family == null |
| BR-45-02 | ファミリー指定時順序維持 | ファミリーが指定されている場合はGhosttyの優先順序を維持 | family != null |
| BR-45-03 | モノスペースデフォルト | ファミリー未指定時はモノスペースフォントのみを表示 | family == null かつ monospace == true |
| BR-45-04 | スタイル優先 | bold/italic/styleフラグは結果の優先順位付けに使用（完全フィルタではない） | フラグ指定時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | NoDiscovery | フォントディスカバリ機構がビルドに含まれていない | エラーメッセージを表示 |
| - | フォント名取得失敗 | フォントからファミリー/フルネームを取得できない | エラーログを出力して続行 |

### リトライ仕様

リトライなし。

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

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

## パフォーマンス要件

- システムにインストールされているフォント数に依存
- 通常は数秒以内に完了

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

- システムフォント情報のみを表示（機密情報なし）

## 備考

- フォントディスカバリはコンパイル時オプションであり、無効化されている場合は機能しない
- ファミリー指定時の出力順序はGhosttyがフォントを選択する優先順位と同じ

---

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

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

### 推奨読解順序

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

Options構造体とフォントディスカバリの型を理解する。

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

**読解のコツ**: Options構造体には`_arena`フィールドがあり、CLIパーサーがメモリ管理に使用する。`deinit`で解放される。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 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. **63-65行目**: argsIteratorの初期化と引数パース
2. **78-92行目**: ディスカバリ機構の存在確認
3. **103-113行目**: discover()の実行とフィルタオプション設定
4. **114-135行目**: 結果のイテレーションとマップへの格納
5. **137-144行目**: ソート処理
6. **146-161行目**: 結果出力

#### Step 3: フォントディスカバリ処理

フォント検索の内部処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | list_fonts.zig | `src/cli/list_fonts.zig` | discover呼び出し（106-113行目） |
| 3-2 | discovery.zig | `src/font/discovery.zig` | Discover構造体とdiscover関数 |

**主要処理フロー**:
- **106-113行目**: フィルタオプションの設定
  - family: 指定されたファミリー名
  - style: 指定されたスタイル名
  - bold/italic: スタイルフラグ
  - monospace: ファミリー未指定時はtrue

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

```
ghostty +list-fonts [options]
    │
    └─ cli.list_fonts.run
           │
           ├─ args.argsIterator
           │
           ├─ args.parse (Optionsへ)
           │
           └─ runArgs
                  │
                  ├─ font.Discover.init
                  │
                  ├─ disco.discover
                  │      ├─ family filter
                  │      ├─ style filter
                  │      ├─ bold/italic filter
                  │      └─ monospace filter
                  │
                  ├─ disco_it.next (イテレーション)
                  │      ├─ face.familyName
                  │      └─ face.name
                  │
                  ├─ std.mem.sortUnstable (ソート)
                  │
                  └─ stdout.print (出力)
```

### データフロー図

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

コマンドライン ──────▶ Options解析 ────────▶ フィルタ条件
     │                     │
     │                     ▼
システムフォント ────▶ font.Discover ────▶ フォント情報
                          │
                          ▼
                    HashMap<ファミリー, フォント一覧>
                          │
                          ▼
                    sortUnstable ────────▶ ソート済み一覧
                          │
                          ▼
                    stdout.print ────────▶ 標準出力
                    "ファミリー名"
                    "  フォント名1"
                    "  フォント名2"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_fonts.zig | `src/cli/list_fonts.zig` | ソース | フォント一覧コマンドの実装 |
| discovery.zig | `src/font/discovery.zig` | ソース | フォントディスカバリ機構 |
| args.zig | `src/cli/args.zig` | ソース | コマンドライン引数パーサー |
| main.zig | `src/font/main.zig` | ソース | フォントモジュールのエントリーポイント |
