# バッチ設計書 56-imgui_lldb.py

## 概要

本ドキュメントは、LLDB用のImGuiデバッガー拡張Pythonスクリプトについて定義する設計書である。ImGuiのデータ構造をデバッガ内でわかりやすく表示するための合成子プロバイダーおよびサマリー機能を提供する。

### 本バッチの処理概要

このPythonスクリプトは、LLDB（Low Level Debugger）においてImGuiの各種データ型に対するカスタム表示フォーマッターを提供するデバッガ拡張機能である。LLDBはXcode、Android Studio、VS Code、C++Builder、CLion、Eclipse等で利用されるデバッガである。

**業務上の目的・背景**：ImGuiを使用したアプリケーションのデバッグ時、ImVector、ImSpan、ImRect等のImGui固有のデータ構造は標準のデバッガ表示では内容が理解しにくい。本スクリプトを導入することで、これらのデータ構造をデバッガ上でわかりやすく展開・表示でき、デバッグ効率が大幅に向上する。

**バッチの実行タイミング**：LLDBデバッグセッション開始時に手動またはlldbinit設定により自動ロードされる。

**主要な処理内容**：
1. ImVectorテンプレート型の合成子プロバイダー登録（Size/Capacity/要素展開）
2. ImSpanテンプレート型の合成子プロバイダー登録（Size/要素展開）
3. ImVec2/ImVec4のサマリー表示（x, y, z, w値の直接表示）
4. ImRectのサマリー表示（Min/Max座標およびSize計算値表示）
5. ImGuiWindowのサマリー表示（Name/Active/Child/Popup/Hidden状態表示）
6. enumフラグの展開表示サポート

**前後の処理との関連**：LLDBにロードされることで機能する。他のスクリプトとの依存関係はない。lldbinit設定により永続的な利用が可能。

**影響範囲**：デバッガの表示機能のみに影響。実行中のアプリケーションやソースコードには一切影響を与えない。

## バッチ種別

デバッガ拡張 / 開発支援ツール

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | デバッグセッション開始時 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動（command script import）またはlldbinit自動ロード |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| LLDB | LLDBデバッガが利用可能であること |
| Python | LLDBのPythonバインディングが有効であること |
| デバッグ対象 | ImGuiを使用したアプリケーションであること |

### 実行可否判定

- LLDBデバッグセッションが開始されていること
- `command script import <path-to-this-file>` が実行可能であること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| debugger | lldb.SBDebugger | Yes | - | LLDBデバッガオブジェクト（自動提供） |
| internal_dict | dict | Yes | - | 内部辞書（自動提供） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| デバッグ対象のメモリ | バイナリ | ImGui変数の実メモリ値 |
| LLDB型情報 | SBType | デバッグシンボルからの型情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| LLDBコンソール | テキスト | フォーマットされた変数表示 |
| IDEの変数ウィンドウ | 構造化データ | 合成子として展開された子要素 |

### 出力ファイル仕様

該当なし（デバッガ内での表示のみ）

## 処理フロー

### 処理シーケンス

```
1. モジュールロード
   └─ __lldb_init_module関数が自動呼び出し
2. カテゴリ作成
   └─ "imgui"カテゴリを作成/取得
3. 言語設定
   └─ C++言語を追加
4. 合成子プロバイダー登録
   └─ ImVector、ImSpanの正規表現パターンで登録
5. サマリー登録
   └─ ImVec2、ImVec4、ImRect、ImGuiWindowのサマリー登録
6. カテゴリ有効化
   └─ フォーマッターを有効化
```

### フローチャート

```mermaid
flowchart TD
    A[LLDBがスクリプトをロード] --> B[__lldb_init_module呼び出し]
    B --> C{imguiカテゴリ存在確認}
    C -->|存在しない| D[カテゴリ作成]
    C -->|存在する| E[既存カテゴリ使用]
    D --> F[C++言語追加]
    E --> G[型フォーマッター登録]
    F --> G
    G --> H[ImVector合成子登録]
    H --> I[ImSpan合成子登録]
    I --> J[ImVec2/4サマリー登録]
    J --> K[ImRect/ImGuiWindowサマリー登録]
    K --> L[カテゴリ有効化]
    L --> M[初期化完了]
```

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

### 操作別データベース影響一覧

該当なし（本スクリプトはデバッガ拡張であり、データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ImportError | lldbモジュールが見つからない | LLDBコンテキスト外での実行を避ける |
| - | 型不一致 | ImGui型が見つからない | デバッグシンボルの確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. スクリプトのパスを確認
2. LLDBのPythonバージョン互換性を確認
3. デバッグシンボルの存在確認

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

該当なし

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 変数参照ごと |
| 目標処理時間 | ミリ秒単位 |
| メモリ使用量上限 | 最小限 |

## 排他制御

Xcode（lldb-rpc-server）では各デバッグセッションごとにスクリプトがロードされるため、カテゴリの重複登録を避ける処理が実装されている。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| なし | - | ログ出力機能は未実装 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | - |

## 備考

### サポートする型とその表示形式

| 型 | 表示形式 | 例 |
|---|---------|---|
| ImVector<T> | Size=n Capacity=m + 子要素展開 | Size=5 Capacity=8 |
| ImSpan<T> | Size=n + 子要素展開 | Size=3 |
| ImVec2 | x=value y=value | x=100.0 y=200.0 |
| ImVec4 | x=value y=value z=value w=value | x=1.0 y=0.0 z=0.0 w=1.0 |
| ImRect | Min=(x, y) Max=(x, y) Size=(w, h) | Min=(0.0, 0.0) Max=(100.0, 50.0) Size=(100.0, 50.0) |
| ImGuiWindow | Name "name" Active n Child n Popup n Hidden n | Name "Debug" Active 1 Child 0 Popup 0 Hidden 0 |

### 使用方法

**一時的な使用**：
```
(lldb) command script import /path/to/imgui_lldb.py
```

**永続的な使用**（~/.lldbinit に追加）：
```
command script import /path/to/imgui_lldb.py
```

### 技術的詳細

- 正規表現パターン（`^ImVector<.+>$`等）を使用してテンプレート型をマッチング
- ArraySynthBaseクラスによる配列様コンテナの共通処理
- eTypeOptionCascadeフラグにより派生型にもフォーマッターを適用
- eTypeOptionFrontEndWantsDereferenceフラグによりポインタの自動参照解決
- get_active_enum_flags関数によるImGuiフラグ型のビットマスク解析
