# 帳票設計書 4-list-keybinds

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータの `list-keybinds` コマンドが出力するキーバインド一覧の設計書です。

### 本帳票の処理概要

`list-keybinds` コマンドは、現在設定されているまたはデフォルトのキーバインドを一覧形式で標準出力に表示するCLIリストです。TTY出力時はカラー付きの整形出力、パイプ時はプレーンテキスト出力となります。

**業務上の目的・背景**：ユーザーがGhosttyで利用可能なキーバインドを確認し、カスタマイズの参考にしたり、現在の設定を確認したりするために必要です。キーバインドのトラブルシューティングやドキュメント作成にも利用されます。

**帳票の利用シーン**：
- 現在設定されているキーバインドの確認
- デフォルトのキーバインド設定の確認
- キーバインドカスタマイズ前の現状把握
- キーバインド設定のドキュメント出力

**主要な出力内容**：
1. キートリガー（修飾キー + メインキー）
2. アクション名
3. コードバインド（複数キーシーケンス対応）
4. キーテーブル名（テーブルバインド時）

**帳票の出力タイミング**：`ghostty +list-keybinds` コマンド実行時

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

## 帳票種別

CLIリスト（テキスト形式 / カラー整形出力対応）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `ghostty +list-keybinds` | コマンド実行 |
| - | CLI | `ghostty +list-keybinds --default` | デフォルト設定出力 |
| - | CLI | `ghostty +list-keybinds --plain` | プレーン出力 |

## 出力形式

### 基本仕様

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

### 端末出力固有設定

| 項目 | 内容 |
|-----|------|
| ハイパーリンク | 無 |
| カラー出力 | 有（TTY時、各修飾キーに色分け） |
| インタラクティブ | 無 |

### カラースキーム（TTY時）

| 要素 | カラー | ANSIインデックス |
|------|--------|-----------------|
| super修飾キー | 赤 | 1 |
| ctrl修飾キー | 緑 | 2 |
| alt修飾キー | 黄 | 3 |
| shift修飾キー | 青 | 4 |
| アクション引数 | マゼンタ | 5 |
| コード区切り | シアン | 6 |
| テーブル名 | グレー | 8 |

## 帳票レイアウト

### レイアウト概要

キーバインドは1行1エントリで、キートリガーとアクションがスペースで区切られて出力されます。

```
┌─────────────────────────────────────┐
│  [修飾キー +] キー    アクション      │
│  [修飾キー +] キー    アクション:引数  │
│  table/[修飾キー +] キー  アクション   │
│  ...                                │
└─────────────────────────────────────┘
```

### ヘッダー部

ヘッダーはありません。

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | テーブル名 | キーテーブル名（該当時） | keybinds.tables | "{table_name}/" |
| 2 | 修飾キー | super/ctrl/alt/shift | trigger.mods | "{mod} + " |
| 3 | メインキー | キー名 | trigger.key | "{key}" |
| 4 | コード区切り | 複数キーシーケンス時 | chord | "  >  " |
| 5 | アクション名 | 実行されるアクション | binding.action | "{action}" |
| 6 | アクション引数 | アクションのパラメータ | binding.action | ":{argument}" |

### フッター部

フッターはありません。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| --default | デフォルト設定を表示 | No |
| --docs | ドキュメント付き出力（未実装） | No |
| --plain | プレーン出力を強制 | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | デフォルトバインド優先 | デフォルト > テーブル |
| 2 | コードシーケンス長 | 長い方が先 |
| 3 | 修飾キー数 | 多い方が先 |
| 4 | 修飾キー種別 | int値順 |
| 5 | キーコード | 昇順 |
| 6 | テーブル名 | 昇順（テーブル内） |

### 改ページ条件

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

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

### 参照テーブル一覧

データベース参照はありません。設定ファイルとデフォルト設定を使用します。

### データ取得元詳細

| 取得元 | 用途 | 取得方法 |
|-------|------|---------|
| Config.load | ユーザー設定 | 設定ファイル読み込み |
| Config.default | デフォルト設定 | コンパイル時デフォルト |
| config.keybind | キーバインド設定 | Config構造体 |
| keybinds.tables | キーテーブル | Config構造体 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| widest_chord | 最長コード幅計算 | - | 出力整形用 |
| widest_table_prefix | 最長テーブルプレフィックス | - | 出力整形用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[オプション解析]
    B --> C{--default指定?}
    C -->|Yes| D[Config.default読み込み]
    C -->|No| E[Config.load読み込み]
    D --> F[stdoutライター初期化]
    E --> F
    F --> G{TTYかつ--plain未指定?}
    G -->|Yes| H[prettyPrint処理]
    G -->|No| I[formatEntryDocs処理]
    H --> J[バインド収集・ソート]
    J --> K[カラー付き出力]
    I --> L[プレーン出力]
    K --> M[バッファフラッシュ]
    L --> M
    M --> N[終了コード0を返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 設定読み込み失敗 | 設定ファイル不正 | エラー返却 | プロセス終了 |
| 出力失敗 | stdoutへの書き込みエラー | なし（エラー返却） | プロセス終了 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数十〜数百バインド |
| 目標出力時間 | 即時（1秒未満） |
| 同時出力数上限 | N/A |

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

- 設定ファイルの読み取り権限が必要
- 出力にはキーバインド情報のみ含まれる
- 機密情報は含まれない

## 備考

- TTY時はvaxisライブラリを使用したカラー出力
- Unicode mode 2027を有効化してUnicode文字を正しく表示
- コードバインド（複数キーシーケンス）もサポート

---

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

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

### 推奨読解順序

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

キーバインドの構造と設定形式を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | list_keybinds.zig | `src/cli/list_keybinds.zig` | Options構造体（14-35行目） |
| 1-2 | list_keybinds.zig | `src/cli/list_keybinds.zig` | ChordBinding構造体（97-218行目）とソートロジック |
| 1-3 | Binding.zig | `src/input/Binding.zig` | Binding.Trigger, Binding.Action定義 |

**読解のコツ**: ChordBindingはコードバインド（複数キーシーケンス）を表現する内部構造です。lessThan関数がソート順を決定します。

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

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

**主要処理フロー**:
1. **55-62行目**: オプション解析
2. **64行目**: Config読み込み（--defaultで分岐）
3. **72-75行目**: TTY判定とprettyPrint呼び出し
4. **76-81行目**: プレーン出力処理

#### Step 3: カラー出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 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行目） |

**主要処理フロー**:
1. **221-247行目**: vaxis初期化とUnicodeモード設定
2. **251-275行目**: バインド収集（デフォルト+テーブル）
3. **275行目**: ソート実行
4. **277-282行目**: カラースタイル定義
5. **285-359行目**: 各バインドの出力処理

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

```
ghostty (main)
    │
    └─ Action.run (ghostty.zig:99)
           │
           └─ list_keybinds.run (list_keybinds.zig:54)
                  │
                  ├─ args.parse (オプション解析)
                  │
                  ├─ Config.default/Config.load (設定読み込み)
                  │
                  └─ prettyPrint / formatEntryDocs
                         │
                         ├─ vaxis.init (TTY時)
                         │
                         ├─ iterateBindings (バインド収集)
                         │      │
                         │      └─ ChordBinding構築
                         │
                         ├─ std.mem.sort (ソート)
                         │
                         └─ vx.prettyPrint (出力)
```

### データフロー図

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

設定ファイル ───▶ Config.load()
                      │
               または │
                      │
デフォルト設定 ───▶ Config.default()
                      │
                      ▼
              config.keybind取得
                      │
                      ▼
              iterateBindings()
                      │
    ┌─────────────────┼─────────────────┐
    ▼                 ▼                 ▼
default          tables           ChordBinding
bindings         bindings         構築
    │                 │                 │
    └────────▶ バインド一覧 ◀───────────┘
                      │
                      ▼
                   ソート
                      │
         ┌────────────┴────────────┐
         ▼                         ▼
    prettyPrint              formatEntryDocs
    (カラー出力)              (プレーン出力)
         │                         │
         └────────────┬────────────┘
                      │
                      ▼
                  stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| list_keybinds.zig | `src/cli/list_keybinds.zig` | ソース | メイン処理 |
| ghostty.zig | `src/cli/ghostty.zig` | ソース | Actionディスパッチャー |
| args.zig | `src/cli/args.zig` | ソース | 引数解析ユーティリティ |
| tui.zig | `src/cli/tui.zig` | ソース | TUI共通機能 |
| Config.zig | `src/config/Config.zig` | ソース | 設定管理 |
| Binding.zig | `src/input/Binding.zig` | ソース | キーバインド定義 |
