# 画面設計書 19-Indent Guides

## 概要

本ドキュメントは、Doom EmacsにおけるIndent Guides（インデントガイド）画面の設計仕様を定義するものである。indent-barsパッケージを利用したインデントレベルの視覚的表示について、その表示仕様、設定オプション、および互換性対応を記載する。

### 本画面の処理概要

Indent Guides画面は、コードのインデントレベルを縦線で視覚的に表示し、ネスト構造の把握を支援する機能である。

**業務上の目的・背景**：Pythonのようなインデントが意味を持つ言語や、深くネストされたコードブロックを編集する際、インデントレベルの把握は非常に重要である。本機能は、インデントレベルを視覚的なガイドラインで表示することで、コード構造の認識を支援し、インデントミスの防止に寄与する。従来のhighlight-indent-guidesパッケージからindent-barsへの移行により、パフォーマンスが大幅に改善されている。

**画面へのアクセス方法**：Doom Emacs起動後、ファイルを開くと自動的に`indent-bars-mode`が有効化される（`doom-first-buffer`フックと`after-change-major-mode-hook`により初期化）。

**主要な操作・処理内容**：
1. インデントレベルごとの縦線表示
2. Tree-sitterサポートによる正確なスコープ認識
3. 特定モードでの自動無効化（org-indent-mode等）
4. テーマ変更時のスタイル自動更新

**画面遷移**：Indent Guidesは編集バッファ上に重畳表示される。表示/非表示はバッファローカルなモードとして制御される。

**権限による表示制御**：本機能に権限による表示制御はない。全ユーザーが同一の機能を利用可能である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | インデントガイド表示 | 主機能 | インデントレベルの視覚的表示 |

## 画面種別

オーバーレイ（編集画面への視覚的補助）

## URL/ルーティング

Emacsモード: `indent-bars-mode`
表示位置: バッファ内のインデント位置

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| インデント幅 | 入力 | 整数 | バッファのインデント幅設定 |
| Tree-sitterツリー | 入力 | 構文木 | Tree-sitter有効時の構文解析結果 |
| ガイドライン | 出力 | ビットマップ/文字 | インデントを示す縦線 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|---------|------|
| インデントガイド | 各インデントレベル | 縦線（細い灰色線） |
| 空行ガイド | 空行 | コンテキストに応じたガイド表示（オプション） |

## イベント仕様

### 1-モード自動有効化

`after-change-major-mode-hook`により、メジャーモード変更時に`+indent-guides-init-maybe-h`が実行され、条件を満たすバッファで`indent-bars-mode`が有効化される。

### 2-抑制条件チェック

`+indent-guides-inhibit-functions`のフック関数が順次実行され、以下の条件でモードが無効化される：
- 特殊バッファ（`doom-special-buffer-p`）
- 一時バッファ（`doom-temp-buffer-p`）
- org-indent-mode有効時
- ein:notebook-mode（画像インライン表示）有効時
- 子フレーム（childframe）内

### 3-テーマ変更対応

`doom-load-theme-hook`により、テーマ変更時に`indent-bars-reset-styles`が実行され、スタイルが再計算される。

### 4-空行表示の修正

`indent-bars-display-on-blank-lines`使用時、`move-to-column`へのアドバイスにより、空行でのカーソル移動が正しく動作する（`+indent-guides--prevent-passing-newline-a`）。

## データベース更新仕様

本機能はデータベースを使用しない。表示はリアルタイムでバッファ内容から計算される。

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|--------------|--------------|---------|
| なし | - | インデントガイドはメッセージを表示しない |

## 例外処理

| 例外状態 | 処理内容 |
|---------|---------|
| fundamental-mode | モードを有効化しない |
| org-indent-mode | 仮想インデントと衝突するため無効化 |
| ein:notebook-mode | インライン画像表示と衝突するため無効化 |
| 子フレーム | 補完ポップアップ等では無効化 |
| magit-blame-mode | indent-bars-modeを自動無効化 |

## 備考

- indent-barsパッケージを使用（highlight-indent-guidesの高速代替）
- macOSではビットマップが遅いためキャラクターモードを優先
- pgtk（Emacs 30未満）ではクラッシュ防止のためキャラクターモードを優先
- ガイドラインの幅は0.15（細い線）
- 色はfont-lock-comment-faceをベースに0.425ブレンド
- 現在のインデント深度ハイライトは無効化（パフォーマンス優先）
- tree-sitterモジュール有効時はtree-sitterサポートが自動有効化

---

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

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

### 推奨読解順序

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

インデントガイドの設定変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/indent-guides/config.el` | 3-9行目: カスタム変数定義 |

**読解のコツ**: `+indent-guides-`プレフィックスの変数がDoom独自設定、`indent-bars-`プレフィックスがindent-barsパッケージ設定。

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

モードの初期化処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/indent-guides/config.el` | 15-27行目: 初期化関数定義 |

**主要処理フロー**:
1. **17行目**: `doom-first-buffer`フックで起動
2. **19-21行目**: `+indent-guides-startup-h`で`after-change-major-mode-hook`に追加
3. **23-27行目**: `+indent-guides-init-maybe-h`で条件判定してモード有効化

#### Step 3: パッケージ設定を理解する

indent-barsの詳細設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/indent-guides/config.el` | 29-50行目: パッケージ設定 |

**主要処理フロー**:
- **30行目**: tree-sitterサポートの条件付き有効化
- **31-40行目**: キャラクターモードの選択条件（macOS, pgtk）
- **43-47行目**: ガイドラインのスタイル設定
- **50行目**: 現在深度ハイライトの無効化

#### Step 4: 抑制条件を理解する

特定条件でのモード無効化を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | config.el | `modules/ui/indent-guides/config.el` | 57-75行目: 抑制関数定義 |

**主要処理フロー**:
- **60-62行目**: 特殊/一時バッファの判定
- **64-65行目**: org-indent-modeの判定
- **67-70行目**: ein:notebook-modeの判定
- **73-75行目**: 子フレームの判定

#### Step 5: 互換性対応を理解する

他のパッケージとの互換性対応を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | config.el | `modules/ui/indent-guides/config.el` | 77-117行目: 互換性アドバイス |

**主要処理フロー**:
- **83-92行目**: 空行でのカーソル移動修正
- **97-99行目**: magit-blame-modeでの無効化
- **101-117行目**: lsp-ui-peekとの互換性対応

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

```
doom-first-buffer
    │
    └─ +indent-guides-startup-h
           └─ add-hook 'after-change-major-mode-hook
                  └─ +indent-guides-init-maybe-h
                         │
                         ├─ [fundamental-mode] → スキップ
                         │
                         ├─ +indent-guides-inhibit-functions
                         │      ├─ +indent-guides-in-special-buffers-p
                         │      ├─ +indent-guides-in-org-indent-mode-p
                         │      ├─ +indent-guides-in-ein-notebook-p
                         │      └─ +indent-guides-in-childframe-p
                         │
                         └─ indent-bars-mode +1

doom-load-theme-hook
    └─ indent-bars-reset-styles

magit-blame-disable-modes
    └─ indent-bars-mode (無効化)

move-to-column (アドバイス)
    └─ +indent-guides--prevent-passing-newline-a
           └─ 空行での改行処理
```

### データフロー図

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

バッファテキスト     ───▶ インデント解析         ───▶ ガイドライン位置

major-mode          ───▶ +indent-guides-        ───▶ モード有効/無効
                         init-maybe-h

tree-sitter         ───▶ スコープ解析           ───▶ 精密なガイド
(オプション)

テーマ変更          ───▶ indent-bars-           ───▶ スタイル更新
                         reset-styles
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/indent-guides/config.el` | ソース | メイン設定ファイル、indent-bars設定 |
| packages.el | `modules/ui/indent-guides/packages.el` | 設定 | パッケージ依存関係定義 |
