# 機能設計書 2-VT端末パーサー

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける端末制御シーケンス（CSI、OSC、DCS、APC等）を解析する「VT端末パーサー」機能の設計を記述する。

### 本機能の処理概要

VT端末パーサーは、PTYから受信したバイトストリームを状態機械（ステートマシン）を用いて解析し、端末制御シーケンスを識別・抽出する。vt100.netで定義されたDEC ANSIパーサーの状態機械をベースに実装されている。

**業務上の目的・背景**：端末エミュレータが正しく動作するためには、受信したバイトストリームから制御シーケンスと通常の文字を正確に識別する必要がある。VT100/VT220互換の端末として動作するために、ECMA-48およびDEC固有の制御シーケンスを正確に解析することが求められる。

**機能の利用シーン**：
- シェルやアプリケーションがカーソル移動コマンド（CSI H等）を送信した場合
- TUIアプリケーションが画面クリア（CSI 2J）を要求した場合
- アプリケーションがOSCシーケンスでタイトル変更を要求した場合
- DCSシーケンスでSixelグラフィックスを送信する場合
- Kitty拡張プロトコルを使用する場合

**主要な処理内容**：
1. バイトごとの状態機械遷移処理
2. 中間文字（intermediate characters）の収集
3. パラメータの蓄積と解析
4. CSI/OSC/DCS/ESC/APCコマンドのディスパッチ
5. UTF-8マルチバイト文字のデコード

**関連システム・外部連携**：
- Terminal構造体への状態更新要求
- OSCパーサー（osc.zig）との連携
- 端末モード管理（modes.zig）との連携

**権限による制御**：特になし。パーサーは純粋なデータ解析機能であり、権限制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | 端末制御シーケンスの解析結果を画面に反映 |

## 機能種別

データ解析 / 状態機械処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| c | u8 | Yes | 処理対象の1バイト | 0x00-0xFF |

### 入力データソース

- PTYからのバイトストリーム（1バイトずつ処理）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| actions | [3]?Action | 最大3つのアクション（exit, transition, entry） |
| action.print | u21 | 画面に描画する文字（Unicodeコードポイント） |
| action.execute | u8 | 実行するC0/C1制御文字 |
| action.csi_dispatch | CSI | CSIコマンド情報 |
| action.osc_dispatch | osc.Command | OSCコマンド情報 |
| action.esc_dispatch | ESC | ESCコマンド情報 |
| action.dcs_hook/put/unhook | DCS | DCSコマンド情報 |
| action.apc_start/put/end | void/u8 | APCコマンド情報 |

### 出力先

- Terminalハンドラへのアクション通知

## 処理フロー

### 処理シーケンス

```
1. next(c)呼び出し
   └─ 入力バイトcを受け取る

2. 状態遷移テーブル参照
   └─ table[c][current_state]から(next_state, action)を取得

3. Exit Action生成
   └─ 現在の状態から離れる際のアクション
   └─ osc_string: osc_dispatch生成
   └─ dcs_passthrough: dcs_unhook生成
   └─ sos_pm_apc_string: apc_end生成

4. Transition Action実行
   └─ print: 文字出力アクション生成
   └─ execute: C0/C1実行アクション生成
   └─ collect: 中間文字を蓄積
   └─ param: パラメータ値を蓄積
   └─ csi_dispatch: CSIコマンド生成
   └─ osc_put: OSCパーサーにデータ送信
   └─ esc_dispatch: ESCコマンド生成

5. Entry Action生成
   └─ escape/dcs_entry/csi_entry: clear()で状態リセット
   └─ osc_string: OSCパーサーリセット
   └─ dcs_passthrough: dcs_hook生成

6. 状態更新
   └─ self.state = next_state
```

### フローチャート

```mermaid
flowchart TD
    A[next(c)呼び出し] --> B[状態遷移テーブル参照]
    B --> C{状態が変化?}
    C -->|Yes| D[Exit Action生成]
    C -->|No| E[Transition Action実行]
    D --> E
    E --> F{actionタイプ}
    F -->|print| G[printアクション生成]
    F -->|execute| H[executeアクション生成]
    F -->|collect| I[中間文字蓄積]
    F -->|param| J[パラメータ蓄積]
    F -->|csi_dispatch| K[CSIアクション生成]
    F -->|osc_put| L[OSCパーサーへ送信]
    F -->|esc_dispatch| M[ESCアクション生成]
    G --> N{状態が変化?}
    H --> N
    I --> N
    J --> N
    K --> N
    L --> N
    M --> N
    N -->|Yes| O[Entry Action生成]
    N -->|No| P[状態更新]
    O --> P
    P --> Q[アクション配列を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | vt100.net準拠 | 状態遷移はvt100.netのDEC ANSIパーサー仕様に準拠 | すべての状態遷移 |
| BR-002 | コロン区切り許容 | CSIパラメータでコロン(:)を区切り文字として許容（SGRコマンド用） | csi_param状態 |
| BR-003 | 最大中間文字数 | 中間文字は最大4文字まで（UTF-8デコード兼用） | collect時 |
| BR-004 | 最大パラメータ数 | CSIパラメータは最大24個まで | param蓄積時 |
| BR-005 | コロン区切り制限 | コロン区切りはmコマンド(SGR)のみ許可 | csi_dispatch時 |

### 計算ロジック

- パラメータ蓄積: `param_acc = param_acc * 10 + (c - '0')`
- 飽和加算を使用してオーバーフロー防止

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

本機能はデータベースを使用しない。すべての状態はメモリ内の構造体で管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-001 | 中間文字オーバーフロー | 中間文字が4文字を超えた | 警告ログを出力し無視 |
| E-002 | パラメータオーバーフロー | パラメータが24個を超えた | 追加パラメータを無視 |
| E-003 | 不正なコロン区切り | mコマンド以外でコロン区切りが使用された | 警告ログを出力しアクションを無視 |

### リトライ仕様

パーサーはリトライ機構を持たない。不正な入力は無視して処理を継続する。

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

トランザクション処理は使用しない。各バイトは即座に処理される。

## パフォーマンス要件

- 1バイトあたりの処理時間: 数十ナノ秒以下
- インライン最適化による高速処理
- comptime生成の状態遷移テーブルによる高速ルックアップ

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

- バッファオーバーフロー防止（MAX_INTERMEDIATE、MAX_PARAMS制限）
- 飽和演算によるパラメータオーバーフロー防止
- 不正なシーケンスは無視して処理継続

## 備考

- 状態遷移テーブルはコンパイル時に生成される（comptime）
- vt100.netの仕様からの逸脱はparse_table.zigのコメントに記載

---

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

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

### 推奨読解順序

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

パーサーの状態とアクションの型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Parser.zig | `src/terminal/Parser.zig` | State enum、TransitionAction enum、Action union |
| 1-2 | Parser.zig | `src/terminal/Parser.zig` | CSI、ESC、DCS構造体の定義 |

**読解のコツ**: `Action`はタグ付きunionで、各バリアントが異なるアクションタイプを表す。`CSI.SepList`はビットセットでセミコロン/コロンの区切り位置を記録する。

#### Step 2: 状態遷移テーブルを理解する

コンパイル時に生成される状態遷移テーブルの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | parse_table.zig | `src/terminal/parse_table.zig` | Transition構造体、genTable関数 |
| 2-2 | parse_table.zig | `src/terminal/parse_table.zig` | anywhere transitions、各状態の遷移定義 |

**主要処理フロー**:
- **1-10行目**: ファイルの概要コメント（vt100.net準拠、SGR用コロン対応）
- **44-156行目**: `genTable()` - 状態遷移テーブルの生成
- **56-86行目**: anywhere transitions - どの状態からでも遷移可能な共通ルール

#### Step 3: パーサーのメインロジックを理解する

next()関数とdoAction()関数の処理フローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Parser.zig | `src/terminal/Parser.zig` | next()関数 - バイト処理のエントリーポイント |
| 3-2 | Parser.zig | `src/terminal/Parser.zig` | doAction()関数 - 各アクションの実行 |

**主要処理フロー**:
- **248-311行目**: `next()` - 状態遷移テーブル参照、Exit/Transition/Entryアクション生成
- **324-406行目**: `doAction()` - アクションタイプごとの処理実装
- **333-362行目**: paramアクション - パラメータの蓄積処理
- **367-396行目**: csi_dispatchアクション - CSIコマンドの生成

#### Step 4: 補助的なパーサー機能を理解する

OSCパーサーとの連携を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | osc.zig | `src/terminal/osc.zig` | OSCコマンドの定義とパーサー |
| 4-2 | osc/parsers.zig | `src/terminal/osc/parsers.zig` | 各種OSCコマンドのパーサー |

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

```
Parser.next(c)
    |
    +-- table[c][state] 参照
    |      |
    |      +-- Transition{state, action} 取得
    |
    +-- Exit Action (状態離脱時)
    |      +-- osc_parser.end() (osc_string状態から離脱)
    |      +-- dcs_unhook生成 (dcs_passthrough状態から離脱)
    |      +-- apc_end生成 (sos_pm_apc_string状態から離脱)
    |
    +-- doAction(action, c)
    |      +-- print: Action{.print = c}
    |      +-- execute: Action{.execute = c}
    |      +-- collect: self.collect(c)
    |      +-- param: パラメータ蓄積
    |      +-- csi_dispatch: CSI構造体生成
    |      +-- osc_put: osc_parser.next(c)
    |      +-- esc_dispatch: ESC構造体生成
    |
    +-- Entry Action (状態進入時)
    |      +-- clear() (escape/dcs_entry/csi_entry進入)
    |      +-- osc_parser.reset() (osc_string進入)
    |      +-- dcs_hook生成 (dcs_passthrough進入)
    |
    +-- state更新
```

### データフロー図

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

バイト(u8) ──────> Parser.next()
                       |
                       v
              状態遷移テーブル参照
                       |
                       v
              [3]?Action 生成 ───────> [Exit Action]
                       |                    |
                       |                    v
                       |              osc_dispatch / dcs_unhook / apc_end
                       |
                       +─────────────> [Transition Action]
                       |                    |
                       |                    v
                       |              print / execute / csi_dispatch / esc_dispatch
                       |
                       +─────────────> [Entry Action]
                                            |
                                            v
                                      dcs_hook / 状態クリア
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Parser.zig | `src/terminal/Parser.zig` | ソース | VTパーサーのメインロジック |
| parse_table.zig | `src/terminal/parse_table.zig` | ソース | 状態遷移テーブルのcomptime生成 |
| osc.zig | `src/terminal/osc.zig` | ソース | OSCコマンド定義とパーサー |
| osc/parsers.zig | `src/terminal/osc/parsers.zig` | ソース | 各種OSCコマンドパーサー |
| csi.zig | `src/terminal/csi.zig` | ソース | CSIコマンド定義 |
| dcs.zig | `src/terminal/dcs.zig` | ソース | DCSコマンド処理 |
| apc.zig | `src/terminal/apc.zig` | ソース | APCコマンド処理 |
| ansi.zig | `src/terminal/ansi.zig` | ソース | ANSI制御コード定義 |
