# 機能設計書 62-インラインコード評価

## 概要

本ドキュメントは、Doom Emacsにおけるインラインコード評価モジュールの機能設計を記述する。本モジュールはコードの選択範囲やバッファ全体を評価し、結果をオーバーレイまたはポップアップで表示する機能を提供する。

### 本機能の処理概要

インラインコード評価モジュールは、様々なプログラミング言語のコードを即座に実行し、その結果をエディタ内に表示する機能を提供する。quickrunパッケージを基盤とし、REPLとの連携やオーバーレイ表示などの拡張機能を追加している。

**業務上の目的・背景**：
開発作業において、コードスニペットの動作確認やデバッグは頻繁に行われる作業である。本モジュールにより、外部ターミナルやREPLを切り替えることなく、エディタ内で直接コードを評価して結果を確認できる。これにより開発者の作業効率が向上し、フィードバックループが短縮される。

**機能の利用シーン**：
- アルゴリズムの動作確認時、選択範囲のコードを即座に評価
- Emacs Lispのコンフィグ編集時、設定値の動作を即座に確認
- REPLを開いたまま、バッファから直接コードを送信
- 評価結果をコード置換として利用（計算結果の埋め込み等）

**主要な処理内容**：
1. バッファ全体または選択範囲の評価実行
2. 言語固有のランナーによる評価処理
3. 結果のオーバーレイ表示（+overlayフラグ時）
4. 結果のポップアップ表示（長い出力時）
5. REPLバッファへのコード送信
6. 評価結果によるコード置換

**関連システム・外部連携**：
- quickrun：多言語対応のコード実行エンジン
- eros：Emacs Lisp評価結果のオーバーレイ表示
- 各種REPL（python-shell、nodejs-repl等）

**権限による制御**：
本機能に権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | Corfu | 補助機能 | REPLからの補完候補取得 |
| 8 | Company | 補助機能 | REPLからの補完候補取得 |

## 機能種別

コード実行処理 / REPL連携 / 結果表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| beg | integer | Yes（範囲評価時） | 評価範囲の開始位置 | バッファ内の有効位置 |
| end | integer | Yes（範囲評価時） | 評価範囲の終了位置 | beg以上の値 |
| runner-major-mode | symbol | No | 評価に使用するメジャーモード | 有効なモードシンボル |
| inhibit-auto-execute-p | boolean | No | REPL送信時の自動実行抑制 | - |

### 入力データソース

- 現在のバッファ内容
- 選択範囲（リージョン）
- +eval-runners（言語固有ランナー定義）
- +eval-repls（REPL定義）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| output | string | 評価結果の文字列 |
| output-buffer | buffer | ポップアップ表示用バッファ |

### 出力先

- オーバーレイ（行末に表示、+overlay有効時）
- ポップアップバッファ（*doom eval*）
- REPLバッファ
- ミニバッファ

## 処理フロー

### 処理シーケンス

```
1. +eval/buffer-or-region コマンド呼び出し
   └─ リージョン有無の判定

2. 評価処理の実行
   ├─ REPL が開いている場合
   │   └─ +eval/send-region-to-repl
   ├─ +eval-runners に定義がある場合
   │   └─ 言語固有ランナーを実行
   └─ それ以外
       └─ quickrun で実行

3. 結果の表示
   ├─ 4行未満 & +overlay 有効
   │   └─ +eval-display-results-in-overlay
   └─ 4行以上 or +overlay 無効
       └─ +eval-display-results-in-popup
```

### フローチャート

```mermaid
flowchart TD
    A[+eval/buffer-or-region] --> B{リージョン有効?}
    B -->|Yes| C[+eval/region]
    B -->|No| D[+eval/buffer]
    C --> E{REPL開いている?}
    D --> E
    E -->|Yes| F[REPLにコード送信]
    E -->|No| G{+eval-runners定義あり?}
    G -->|Yes| H[言語固有ランナー実行]
    G -->|No| I[quickrun実行]
    F --> J[結果取得]
    H --> J
    I --> J
    J --> K{出力4行以上?}
    K -->|Yes| L[ポップアップ表示]
    K -->|No| M{+overlay有効?}
    M -->|Yes| N[オーバーレイ表示]
    M -->|No| L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ポップアップ閾値 | 出力が4行以上の場合はポップアップ表示 | +eval-popup-min-lines = 4 |
| BR-02 | REPLの優先使用 | REPLが開いている場合はREPLを優先 | get-buffer-window で REPL検出時 |
| BR-03 | Emacs Lisp特別処理 | Emacs Lispはquickrunではなく専用ランナーを使用 | quickrun--command-key = "emacs" |
| BR-04 | REPL永続化 | :persist t 指定のREPLはウィンドウ閉じても維持 | plist-get +eval-repl-plist :persist |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | REPL未オープン | REPLが存在しない状態でREPL送信 | "No REPL open" エラー表示 |
| - | ランナー未定義 | 対応言語のランナーが存在しない | quickrunにフォールバック |
| - | 評価エラー | コード実行時のエラー | エラーメッセージを結果として表示 |

### リトライ仕様

リトライは行わない。

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

該当なし。

## パフォーマンス要件

- 評価結果の表示は評価完了後即座に行う
- オーバーレイ表示のタイムアウトは eros-eval-result-duration に従う

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

- 任意のコードが実行されるため、信頼できないコードの評価に注意
- シェルコマンドの実行を含む言語では特に注意が必要

## 備考

- +overlayモジュールフラグでオーバーレイ表示を有効化
- erosパッケージはEmacs Lisp専用のオーバーレイ表示を提供

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | settings.el | `modules/tools/eval/autoload/settings.el` | +eval-repls と +eval-runners のデータ構造 |

**読解のコツ**:
- `+eval-repls`：`(major-mode . (command &rest plist))` 形式のalist
- `+eval-runners`：`(major-mode . function)` 形式のalist

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | eval.el | `modules/tools/eval/autoload/eval.el` | +eval/buffer-or-region コマンド（149-158行目） |

**主要処理フロー**:
1. **149-158行目**: リージョン有無を判定し、+eval/region または +eval/buffer を呼び出し
2. **113-132行目**: +eval/buffer の実装、quickrun との連携
3. **135-138行目**: +eval/region の実装

#### Step 3: 評価処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | eval.el | `modules/tools/eval/autoload/eval.el` | +eval-region-as-major-mode（76-105行目） |

**主要処理フロー**:
- **87-93行目**: REPLが開いている場合の処理分岐
- **94-105行目**: ランナーまたはquickrunによる評価

#### Step 4: 結果表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | eval.el | `modules/tools/eval/autoload/eval.el` | +eval-display-results（56-73行目） |
| 4-2 | eval.el | `modules/tools/eval/autoload/eval.el` | +eval-display-results-in-overlay（24-53行目） |
| 4-3 | eval.el | `modules/tools/eval/autoload/eval.el` | +eval-display-results-in-popup（4-21行目） |

**主要処理フロー**:
- **56-73行目**: 出力行数・幅によるポップアップ/オーバーレイの判定
- **24-53行目**: erosを使用したオーバーレイ表示
- **4-21行目**: *doom eval* バッファへのポップアップ表示

#### Step 5: REPL管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | repl.el | `modules/tools/eval/autoload/repl.el` | +eval-repl-buffers と REPL管理 |
| 5-2 | repl.el | `modules/tools/eval/autoload/repl.el` | +eval/send-region-to-repl（142-181行目） |

**主要処理フロー**:
- **3-4行目**: +eval-repl-buffers ハッシュテーブル（プロジェクト×モードでREPL管理）
- **11-49行目**: +eval--ensure-in-repl-buffer でREPLの取得・作成
- **142-181行目**: REPLへのコード送信、行ごとにRET送信

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

```
+eval/buffer-or-region
    │
    ├─ +eval/region
    │      └─ +eval-region-as-major-mode
    │             │
    │             ├─ [REPL開いている場合]
    │             │      └─ :send-region or +eval/send-region-to-repl
    │             │
    │             ├─ [+eval-runners定義あり]
    │             │      └─ 言語固有ランナー
    │             │
    │             └─ [それ以外]
    │                    └─ quickrun-region
    │
    └─ +eval/buffer
           └─ [同様の分岐]
                  └─ quickrun

結果表示:
+eval-display-results
    │
    ├─ [4行以上 or 幅超過]
    │      └─ +eval-display-results-in-popup
    │
    └─ [4行未満 & +overlay]
           └─ +eval-display-results-in-overlay
                  └─ eros--make-result-overlay
```

### データフロー図

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

バッファ/リージョン ───▶ +eval-region-as-major-mode ───▶ 評価結果(string)
                              │                              │
                              ▼                              ▼
                     ┌────────────────┐              +eval-display-results
                     │ quickrun      │                      │
                     │ or ランナー   │              ┌───────┴───────┐
                     │ or REPL       │              ▼               ▼
                     └────────────────┘        オーバーレイ     ポップアップ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/tools/eval/config.el` | ソース | メイン設定、quickrun/eros設定 |
| eval.el | `modules/tools/eval/autoload/eval.el` | ソース | 評価コマンド、結果表示 |
| repl.el | `modules/tools/eval/autoload/repl.el` | ソース | REPL管理、コード送信 |
| settings.el | `modules/tools/eval/autoload/settings.el` | ソース | set-repl-handler!, set-eval-handler! |
| evil.el | `modules/tools/eval/autoload/evil.el` | ソース | Evil連携 |
| packages.el | `modules/tools/eval/packages.el` | 設定 | 依存パッケージ定義 |
