# 機能設計書 77-Emacs Lispサポート

## 概要

本ドキュメントは、Doom EmacsにおけるEmacs Lisp開発サポート機能について記述する。Emacs自体の拡張言語であるEmacs Lispの編集、評価、デバッグ、テストなど、Emacsプラグイン開発に必要な包括的な開発環境を提供する。

### 本機能の処理概要

**業務上の目的・背景**：Emacs Lispは Emacsの設定および拡張に使用される言語である。Doom Emacsユーザーは自身の設定ファイルや独自のパッケージを作成することが多く、効率的なElispプログラミング環境が必要となる。本モジュールは強力なフォント化、評価機能、デバッグ支援、テストフレームワーク統合を提供する。

**機能の利用シーン**：
- Doom Emacs設定ファイル（config.el等）の編集
- Elisp関数/変数の定義確認とドキュメント参照
- コードの対話的評価とデバッグ
- buttercupによるユニットテスト
- パッケージ開発

**主要な処理内容**：
1. elisp-modeによる基本編集機能
2. 拡張フォント化（Doom固有構文、定義済みシンボルのハイライト）
3. helpfulによる強化ヘルプシステム
4. macrostepによるマクロ展開の視覚化
5. buttercupによるテストフレームワーク統合
6. elisp-demosによる関数使用例の表示
7. flycheck-packageによるパッケージメタデータ検証
8. ielmによるREPL環境

**関連システム・外部連携**：特になし（Emacs内蔵機能）

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Elispソースバッファ | 主画面 | Elispファイルの編集 |
| - | *ielm*バッファ | 結果表示画面 | REPL実行結果 |
| - | *Help*バッファ | 結果表示画面 | 関数/変数ドキュメント |
| - | *Buttercup*バッファ | 結果表示画面 | テスト結果 |

## 機能種別

言語サポート / 開発環境統合

## 入力仕様

### 入力パラメータ

本モジュールにはモジュールフラグなし。

### 入力データソース

- Elispファイル（*.el）
- Doomscriptファイル
- lisp-data-mode対象ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 評価結果 | テキスト | eval-region, eval-defun等の結果 |
| ドキュメント | バッファ | helpful-*による詳細ヘルプ |
| テスト結果 | バッファ | buttercup実行結果 |

### 出力先

- ミニバッファ: 簡易評価結果
- *ielm*バッファ: REPL出力
- *Help*/*helpful*バッファ: ドキュメント
- *Buttercup*バッファ: テスト結果

## 処理フロー

### 処理シーケンス

```
1. Elispファイルを開く
   └─ emacs-lisp-mode が起動
2. フォント化拡張
   └─ +emacs-lisp-highlight-vars-and-faces によるハイライト
3. 非パッケージモード判定
   └─ +emacs-lisp-non-package-mode でリンター設定調整
4. コード評価
   └─ eval-* 関数群による評価
```

### フローチャート

```mermaid
flowchart TD
    A[Elispファイルを開く] --> B[emacs-lisp-mode起動]
    B --> C[フォント化拡張]
    C --> D{パッケージファイル?}
    D -->|Yes| E[標準リンター設定]
    D -->|No| F[+emacs-lisp-non-package-mode]
    E --> G[編集作業]
    F --> G
    G --> H{操作選択}
    H -->|評価| I[eval-*関数]
    H -->|デバッグ| J[edebug-*関数]
    H -->|ヘルプ| K[helpful-*関数]
    H -->|テスト| L[buttercup-run-*]
    I --> M[結果表示]
    J --> M
    K --> M
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 非パッケージ判定 | provide文がない、.doommoduleファイルがある、テーマディレクトリ外 | flycheck/flymake有効時 |
| BR-02 | リンター警告抑制 | 非パッケージファイルではfree-vars, noruntime, unresolvedを抑制 | +emacs-lisp-non-package-mode有効時 |
| BR-03 | outline-regexp | `[ \t]*;;;(;*\**) [^ \t\n]` パターンでアウトライン折りたたみ | outline-minor-mode有効時 |
| BR-04 | tab-width | Emacs組み込みファイル互換のためtab-width=8 | emacs-lisp-mode有効時 |
| BR-05 | テストファイル判定 | `/test[/-].+\.el$` パターンでテストファイル判定 | buttercup-minor-mode, +emacs-lisp-ert-mode |

### 計算ロジック

**plistインデント改善**:
- `+emacs-lisp--calculate-lisp-indent-a` によるクォート/バッククォートリストのインデント改善
- map!マクロなどのplist引数の適切なインデント

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | error | eval-region中にエラー発生 | "ERROR: ..." 形式でエラーメッセージ表示 |

### リトライ仕様

リトライ機能なし

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

トランザクション管理なし

## パフォーマンス要件

- `+emacs-lisp-highlight-vars-and-faces` と `+emacs-lisp--calculate-lisp-indent-a` はdoom-compile-functionsでバイトコンパイル
- 大規模ファイルでのフォント化パフォーマンス向上

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

- eval-* 関数は任意のコードを実行するため、信頼できるコードのみ評価推奨

## 備考

- helpful パッケージは describe-* 関数を置き換え、より詳細な情報を提供
- elisp-demos は関数ドキュメントに使用例を追加表示
- straight.el との統合でパッケージ変更を追跡

---

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

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

### 推奨読解順序

#### Step 1: 設定変数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/lang/emacs-lisp/config.el` | +emacs-lisp-* 変数群 |

**読解のコツ**: `+emacs-lisp-enable-extra-fontification` などの変数がカスタマイズポイント。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/lang/emacs-lisp/config.el` | elisp-mode の use-package! 設定 |

**主要処理フロー**:
1. **3-20行目**: 設定変数定義
2. **31-148行目**: elisp-mode設定
3. **34-52行目**: REPL、評価、lookup、docsetsの設定
4. **80-81行目**: plistインデント改善のadvice設定
5. **108-114行目**: フォント化拡張

#### Step 3: 自動ロード関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | autoload/emacs-lisp.el | `modules/lang/emacs-lisp/autoload/emacs-lisp.el` | 主要関数群 |

**主要処理フロー**:
- **9-38行目**: `+emacs-lisp-eval` - 評価ハンドラ
- **103-107行目**: `+emacs-lisp-lookup-definition` - 定義ジャンプ
- **119-149行目**: `+emacs-lisp-lookup-documentation` - ドキュメント表示
- **386-412行目**: `+emacs-lisp-non-package-mode` - リンター設定
- **420-453行目**: `+emacs-lisp-highlight-vars-and-faces` - フォント化

#### Step 4: 補助パッケージを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/lang/emacs-lisp/config.el` | helpful, buttercup, macrostep設定 |

**主要処理フロー**:
- **150-177行目**: ielm REPL設定
- **189-192行目**: flycheck-package設定
- **195-223行目**: elisp-demos設定
- **226-244行目**: buttercup設定
- **247-331行目**: helpful設定

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

```
emacs-lisp-mode
    │
    ├─ set-repl-handler! → +emacs-lisp/open-repl → ielm
    │
    ├─ set-eval-handler! → +emacs-lisp-eval
    │      └─ eval-region → +eval-display-results
    │
    ├─ set-lookup-handlers!
    │      ├─ +emacs-lisp-lookup-definition → elisp-def / doom/help-modules
    │      └─ +emacs-lisp-lookup-documentation → helpful-* / doom/help-modules
    │
    ├─ フォント化
    │      └─ +emacs-lisp-highlight-vars-and-faces
    │
    ├─ outline-minor-mode
    │
    ├─ highlight-quoted-mode
    │
    ├─ +emacs-lisp-non-package-mode
    │      ├─ +emacs-lisp--flymake-non-package-mode
    │      └─ +emacs-lisp--flycheck-non-package-mode
    │
    ├─ buttercup-minor-mode (テストファイル)
    │      └─ +emacs-lisp/buttercup-run-*
    │
    └─ macrostep-expand
```

### データフロー図

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

Elispソースファイル ───▶ emacs-lisp-mode ──────────▶ シンタックスハイライト
        │                      │
評価対象コード ────────────────┼──▶ +emacs-lisp-eval ──▶ 評価結果（ミニバッファ）
        │                      │
シンボル名 ────────────────────┼──▶ helpful-* ─────────▶ *helpful*バッファ
        │                      │
テストファイル ────────────────┴──▶ buttercup-run-* ──▶ *Buttercup*バッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/lang/emacs-lisp/config.el` | ソース | モジュール設定、パッケージ統合 |
| autoload/emacs-lisp.el | `modules/lang/emacs-lisp/autoload/emacs-lisp.el` | ソース | 評価、lookup、フォント化関数 |
| autoload/helpful.el | `modules/lang/emacs-lisp/autoload/helpful.el` | ソース | helpfulバッファナビゲーション |
| packages.el | `modules/lang/emacs-lisp/packages.el` | ソース | 依存パッケージ定義 |
