# 帳票設計書 8-デバッガ ローカル変数一覧出力

## 概要

mrubyデバッガ(mrdb)のinfo localコマンドによるローカル変数の一覧表示に関する帳票設計書である。`dbgcmd_info_local`関数により実装される。

### 本帳票の処理概要

本帳票は、mrubyデバッガ(mrdb)のinfo localコマンドで、現在のスコープにおけるローカル変数の一覧を標準出力に表示する機能である。内部でRubyの`local_variables`メソッドを評価し、その結果を`$`番号付きで表示する。

**業務上の目的・背景**：デバッグセッション中に、現在のスコープで利用可能なローカル変数を把握し、個々の変数をprintコマンドで詳細に確認するための前段階として使用される。変数名の一覧を取得することで、デバッグ作業の効率化を図る。

**帳票の利用シーン**：mrdbデバッガのプロンプトでinfo localコマンドを実行した際に出力される。例: `(mrdb) info local`。

**主要な出力内容**：
1. 評価結果の連番（`$N = `形式）
2. ローカル変数名の一覧（local_variablesメソッドの戻り値）

**帳票の出力タイミング**：デバッガプロンプトでinfo localコマンドを入力した際に即時出力される。

**帳票の利用者**：mrubyアプリケーション開発者（デバッグ時）。

## 帳票種別

テキスト出力（stdoutへのデバッガコマンド結果）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | mrdbデバッガ | `(mrdb) info local` | info localコマンド実行 |

## 出力形式

### 基本仕様

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

### PDF固有設定

N/A

### Excel固有設定

N/A

## 帳票レイアウト

### レイアウト概要

```
$3 = [:x, :y, :z]
```

### ヘッダー部

N/A

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | 連番 | 評価結果の連番 | `mrdb->print_no` | `$%lu = ` | 可変 |
| 2 | ローカル変数一覧 | local_variablesの結果 | `mrb_debug_eval("local_variables", ...)` | inspect形式テキスト | 可変 |

### フッター部

N/A

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| デバッガセッション | mrdbデバッガが動作中であること | Yes |

### ソート順

N/A（local_variablesメソッドの出力順に依存）

### 改ページ条件

N/A

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| mrdb_state (構造体) | デバッガ状態 | デバッガセッション |

### テーブル別参照項目詳細

#### mrdb_state

| 参照項目（フィールド名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| print_no | 評価結果連番 | 常時 | unsigned long, インクリメント |
| dbg | デバッグコンテキスト | 常時 | mrb_debug_evalに渡す |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 連番 | `mrdb->print_no++` | なし | オーバーフロー時は1にリセット |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[info localコマンド入力] --> B[mrb_debug_eval local_variables呼び出し]
    B --> C[結果にNULL終端を追加]
    C --> D[printf で連番と結果を出力]
    D --> E[print_noインクリメント]
    E --> F[DBGST_PROMPT返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 評価エラー | mrb_debug_eval内で例外発生 | mrb_debug_evalの戻り値による | デバッグコンテキストを確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1回のコマンドで1件の結果 |
| 目標出力時間 | ミリ秒単位 |
| 同時出力数上限 | 1 |

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

- ローカル変数名が公開される。変数名に機密情報を含めない設計が推奨される。

## 備考

- info localコマンドはRubyの`local_variables`メソッドを内部的に評価する
- mrb_debug_evalの第5引数が1に設定されており、通常のprintコマンド（0）とは異なるモードで評価される
- 結果文字列にNULL終端を明示的に追加している（mrb_str_cat_lit "\0"）
- printコマンドと同様にprint_noが共有されインクリメントされる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mrdb.h | `mrbgems/mruby-bin-debugger/tools/mrdb/mrdb.h` | mrdb_state構造体: print_no, dbgフィールド |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cmdprint.c | `mrbgems/mruby-bin-debugger/tools/mrdb/cmdprint.c` | `dbgcmd_info_local`（56-71行目）: info localコマンドのメイン処理 |

**主要処理フロー**:
1. **58行目**: GCアリーナ保存
2. **60行目**: mrb_debug_eval("local_variables", 0, NULL, 1)で変数一覧を取得
3. **61行目**: 結果にNULL終端を追加
4. **62行目**: printfで`$N = 結果`を出力
5. **64-66行目**: print_noオーバーフロー処理
6. **68行目**: GCアリーナ復元

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

```
dbgcmd_info_local() [cmdprint.c:56]
    │
    ├─ mrb_debug_eval("local_variables") ← ローカル変数一覧取得
    ├─ mrb_str_cat_lit() ← NULL終端追加
    └─ printf("$%lu = %s\n") ← 結果出力
```

### データフロー図

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

info localコマンド ──▶ mrb_debug_eval() ──────────▶ stdout
                        ("local_variables")          │
                                                     ├─ $N =
                                                     └─ ローカル変数一覧
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cmdprint.c | `mrbgems/mruby-bin-debugger/tools/mrdb/cmdprint.c` | ソース | info localコマンド実装（dbgcmd_info_local関数） |
| mrdb.h | `mrbgems/mruby-bin-debugger/tools/mrdb/mrdb.h` | ヘッダー | mrdb_state構造体定義 |
| apiprint.h | `mrbgems/mruby-bin-debugger/tools/mrdb/apiprint.h` | ヘッダー | mrb_debug_eval関数宣言 |
