# 機能設計書 46-キーバインド一覧

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける「キーバインド一覧」機能の設計を記述する。この機能は、CLIコマンド`+list-keybinds`を通じて、現在設定されているキーバインドを一覧表示する。

### 本機能の処理概要

**業務上の目的・背景**：Ghosttyは高度にカスタマイズ可能なキーバインドシステムを持つ。ユーザーが現在有効なキーバインドを確認し、カスタマイズの計画を立てたり、問題のトラブルシューティングを行ったりするために、設定されたキーバインドの一覧を表示する機能が必要である。

**機能の利用シーン**：
- 現在設定されているキーバインドを確認する
- デフォルトのキーバインドを確認する
- キーバインドのカスタマイズを計画する際の参考にする
- カスタム設定が正しく適用されているか確認する

**主要な処理内容**：
1. 設定ファイルの読み込み（またはデフォルト設定の使用）
2. キーバインドの収集とソート
3. コード化シーケンス（マルチキーシーケンス）の処理
4. TTY検出による出力形式の切り替え（プリティプリント/プレーン）
5. キーテーブルの処理

**関連システム・外部連携**：
- 設定ファイルシステム
- vaxisライブラリ（TTYプリティプリント）

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

## 関連画面

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

## 機能種別

情報表示 / CLI出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| default | bool | No | デフォルトキーバインドを表示するかどうか | デフォルト: false |
| docs | bool | No | アクションのドキュメントを表示するかどうか | デフォルト: false |
| plain | bool | No | フォーマットなしで出力するかどうか | デフォルト: false |

### 入力データソース

- コマンドライン: `ghostty +list-keybinds [オプション]`
- 設定ファイル（--defaultが指定されていない場合）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| トリガー | Trigger | キーの組み合わせ（修飾キー+キー） |
| アクション | Action | 実行されるアクション |
| テーブル名 | ?[]const u8 | キーテーブル名（該当する場合） |

### 出力先

- 標準出力（stdout）

## 処理フロー

### 処理シーケンス

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

2. 設定の読み込み
   └─ --default: デフォルト設定を使用
   └─ それ以外: Config.load()で設定ファイルを読み込み

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

4. キーバインドの収集
   └─ デフォルトバインディングの取得
   └─ キーテーブルの取得

5. ソート処理
   └─ ChordBinding.lessThanでソート

6. 出力
   └─ プリティプリント: vaxisを使用した色付き出力
   └─ プレーン: シンプルなテキスト出力
```

### フローチャート

```mermaid
flowchart TD
    A[+list-keybinds実行] --> B[引数パース]
    B --> C{--default?}
    C -->|Yes| D[Config.default]
    C -->|No| E[Config.load]
    D --> F{TTY && !plain?}
    E --> F
    F -->|Yes| G[prettyPrint]
    F -->|No| H[プレーン出力]
    G --> I[vaxis初期化]
    I --> J[バインディング収集]
    J --> K[ChordBinding.lessThanでソート]
    K --> L[色付き出力]
    L --> M[終了コード0]
    H --> N[formatEntryDocs]
    N --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-46-01 | デフォルト/設定切り替え | --defaultフラグでデフォルトキーバインドを表示 | --default指定時 |
| BR-46-02 | プリティプリント | TTY出力かつ--plainでない場合は色付き出力 | isTty() && !opts.plain |
| BR-46-03 | ソート順序 | キーバインドは以下の順序でソート: テーブルなし→テーブルあり、シーケンス長降順、修飾キー数降順 | 常時 |
| BR-46-04 | チェインサポート | マルチキーシーケンス（コード化）をサポート | 常時 |

### 計算ロジック

ChordBinding.lessThanによるソート:
1. テーブル名なしを優先
2. テーブル名ありの場合はテーブル名でソート
3. シーケンス長で降順ソート
4. 修飾キー数で降順ソート
5. 修飾キーの種類でソート
6. トリガーキーでソート

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定読み込みエラー | 設定ファイルのパースエラー | エラーを返す |

### リトライ仕様

リトライなし。

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

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

## パフォーマンス要件

- 瞬時に実行完了すること

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

- キーバインド情報は機密情報を含まない

## 備考

- vaxisライブラリを使用してターミナル上で色付き出力を行う
- マルチキーシーケンス（例: ctrl+a > b）をサポート
- キーテーブルによるモード切り替えをサポート

---

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

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

### 推奨読解順序

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

Options構造体とChordBinding構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | list_keybinds.zig | `src/cli/list_keybinds.zig` | Options構造体の定義（14-35行目） |
| 1-2 | list_keybinds.zig | `src/cli/list_keybinds.zig` | TriggerNode構造体（88-95行目） |
| 1-3 | list_keybinds.zig | `src/cli/list_keybinds.zig` | ChordBinding構造体（97-218行目） |

**読解のコツ**: ChordBindingはマルチキーシーケンスを表現するために、トリガーをリンクドリストで保持する。lessThan関数でソート順序が定義されている。

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

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

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

**主要処理フロー**:
1. **55-62行目**: 引数パース
2. **64行目**: 設定読み込み（default/load）
3. **72-81行目**: TTY検出と出力モード決定
4. **75行目**: プリティプリント呼び出し
5. **77-80行目**: プレーン出力（formatEntryDocs）

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

vaxisを使用した色付き出力を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | list_keybinds.zig | `src/cli/list_keybinds.zig` | prettyPrint関数（220-362行目） |
| 3-2 | list_keybinds.zig | `src/cli/list_keybinds.zig` | iterateBindings関数（364-435行目） |

**主要処理フロー**:
- **222-233行目**: vaxisとTTYの初期化
- **251-253行目**: デフォルトバインディングの収集
- **255-272行目**: キーテーブルの収集
- **275行目**: ソート実行
- **278-282行目**: 修飾キーごとのスタイル定義
- **285-359行目**: 各バインディングの出力

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

```
ghostty +list-keybinds [options]
    │
    └─ cli.list_keybinds.run
           │
           ├─ args.parse (Optionsへ)
           │
           ├─ Config.default / Config.load
           │
           └─ [TTY && !plain]
                  │
                  ├─ prettyPrint
                  │      ├─ vaxis.init
                  │      ├─ iterateBindings (デフォルト)
                  │      ├─ iterateBindings (キーテーブル)
                  │      ├─ ChordBinding.lessThan (ソート)
                  │      └─ vx.prettyPrint (出力)
                  │
                  └─ [else] formatEntryDocs
```

### データフロー図

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

コマンドライン ──────▶ Options解析 ────────▶ フラグ
     │                     │
     │                     ▼
設定ファイル ────────▶ Config.load/default ─▶ Keybinds
     │                     │
     │                     ▼
     │              iterateBindings
     │                     │
     │                     ▼
     │              ChordBinding[]
     │                     │
     │                     ▼
     │              sort(lessThan)
     │                     │
     │                     ▼
     └─────────────▶ prettyPrint/formatEntryDocs ─▶ stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_keybinds.zig | `src/cli/list_keybinds.zig` | ソース | キーバインド一覧コマンドの実装 |
| Binding.zig | `src/input/Binding.zig` | ソース | バインディングとアクションの定義 |
| Config.zig | `src/config/Config.zig` | ソース | 設定の読み込みとKeybindsの管理 |
| tui.zig | `src/cli/tui.zig` | ソース | TUI機能の共通ユーティリティ |
| vaxis | 外部ライブラリ | ライブラリ | ターミナルUI描画 |
