# 機能設計書 30-リガチャ（合字）サポート

## 概要

本ドキュメントは、Doom Emacsにおけるリガチャ（合字）サポート機能の設計を記述する。ligatureパッケージおよびprettify-symbols-modeを使用し、プログラミング用フォントの合字機能を活用して、`->`, `=>`, `!=`などの文字列を美しい合字として表示する。

### 本機能の処理概要

**業務上の目的・背景**：プログラミングフォント（Fira Code、JetBrains Mono等）は、コードの可読性を向上させるためのリガチャ（合字）機能を持つ。本機能により、これらのフォントのリガチャを有効化し、`->` を矢印として、`!=` を不等号として視覚的に表示できる。また、`+extra`フラグにより、`lambda`を`λ`として表示するなどのシンボル置換も可能。

**機能の利用シーン**：プログラミング時のコード可読性向上、関数型プログラミング言語でのラムダ式の視覚化、Org-modeでの引用符やブロック記号の美化。

**主要な処理内容**：
1. Harfbuzzを使用したフォントリガチャの有効化（ligatureパッケージ）
2. macOS emacs-macビルドでのmac-auto-operator-composition-mode使用
3. prettify-symbols-modeによるシンボル置換（+extraフラグ）
4. モードごとのリガチャ設定カスタマイズ

**関連システム・外部連携**：ligatureパッケージ、prettify-symbols-mode、Harfbuzz対応のEmacsビルド。

**権限による制御**：本機能は全ユーザーが利用可能であり、権限による制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | Ligatures | 主機能 | プログラミング用合字表示変換 |

## 機能種別

UI表示 / フォント処理 / シンボル置換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| +ligatures-extra-symbols | plist | No | シンボルキーと表示文字のマッピング | plistフォーマット |
| +ligatures-alist | alist | No | モードとリガチャリストのマッピング | alistフォーマット |
| +ligatures-extra-alist | alist | No | モードとシンボル置換リストのマッピング | alistフォーマット |
| +ligatures-extras-in-modes | list/symbol | No | 追加リガチャを有効にするモード | t、リスト、または(not mode1 mode2...) |

### 入力データソース

- バッファ内のソースコードテキスト
- モジュールフラグ（+extra）
- フォント設定（Harfbuzz対応フォント）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| リガチャ表示 | glyph | フォントリガチャによる合字表示 |
| シンボル表示 | text | prettify-symbolsによる置換文字表示 |

### 出力先

- バッファ内のテキスト表示

## 処理フロー

### 処理シーケンス

```
1. doom-init-ui-hookの実行
   └─ リガチャモードの有効化
2. 環境検出
   └─ macOS emacs-mac: mac-auto-operator-composition-mode
   └─ Harfbuzz対応: ligatureパッケージ
3. リガチャ設定の適用
   └─ +ligatures-alistに基づくモードごとの設定
4. 追加シンボル有効化（+extraフラグ）
   └─ after-change-major-mode-hookで+ligatures-init-extra-symbols-h呼び出し
   └─ prettify-symbols-mode有効化
```

### フローチャート

```mermaid
flowchart TD
    A[doom-init-ui-hook] --> B{環境検出}
    B -->|macOS emacs-mac| C[mac-auto-operator-composition-mode]
    B -->|Harfbuzz| D[global-ligature-mode]
    C --> E[リガチャ表示]
    D --> E
    F{+extraフラグ} -->|有効| G[after-change-major-mode-hook登録]
    G --> H[+ligatures-init-extra-symbols-h]
    H --> I[prettify-symbols-mode有効化]
    I --> J[シンボル置換表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-30-01 | macOS優先 | macOS emacs-macビルドではmac-auto-operator-composition-modeを優先 | fboundp 'mac-auto-operator-composition-mode |
| BR-30-02 | Harfbuzz必須 | ligatureパッケージはHarfbuzz対応のEmacsが必要 | HARFBUZZ in system-configuration-features |
| BR-30-03 | fundamental-mode除外 | fundamental-modeではextraシンボルを適用しない | major-mode = fundamental-mode |
| BR-30-04 | 右端unprettify | カーソルが右端に到達した時にシンボルを元に戻す | prettify-symbols-unprettify-at-point |
| BR-30-05 | プライベート領域除外 | Unicode Private Areaの文字は+ligatures-extra-symbolsに含めない | シンボル定義時 |

### 標準リガチャ（prog-mode）

以下のリガチャがprog-modeでデフォルト有効：
```
"|||>" "<|||" "<==>" "<!--" "####" "~~>" "***" "||=" "||>"
":::" "::=" "=:=" "===" "==>" "=!=" "=>>" "=<<" "=/=" "!=="
"!!." ">=>" ">>=" ">>>" ">>-" ">->" "->>" "-->" "---" "-<<"
... （多数）
```

### 追加シンボル（+extra）

| キー | シンボル | 用途 |
|-----|---------|------|
| :lambda | λ | ラムダ式 |
| :def | f | 関数定義 |
| :null | ∅ | null/nil |
| :true | T | 真値 |
| :false | F | 偽値 |
| :not | ¬ | 論理否定 |
| :and | ∧ | 論理積 |
| :or | ∨ | 論理和 |
| :for | ∀ | 全称量化子 |
| :return | ⟼ | 戻り値 |

### 計算ロジック

特になし

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

エラーケースは特になし（環境検出で適切なモードを選択）

### リトライ仕様

リトライ処理は実装されていない

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

該当なし

## パフォーマンス要件

- composition-function-tableによるフォントレベルの処理のため、パフォーマンス影響は軽微
- prettify-symbols-modeはバッファ表示時に処理

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

- 表示機能のみであり、セキュリティリスクなし

## 備考

- Emacs 28以上が推奨（ligatureパッケージの互換性）
- フォントがリガチャをサポートしている必要がある（Fira Code、JetBrains Mono等）
- Emacs 27以下ではリガチャが機能しない（フェイルセーフあり）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/ligatures/config.el` | リガチャ設定、シンボル定義 |
| 1-2 | packages.el | `modules/ui/ligatures/packages.el` | パッケージ依存定義 |

**読解のコツ**: 条件分岐（`cond`）でmacOS/Harfbuzz環境を判定している。`+ligatures-extra-symbols`のplistフォーマットを理解する。

**主要処理フロー**:
- **3-45行目**: `+ligatures-extra-symbols` - シンボルキーと文字のマッピング
- **47-61行目**: `+ligatures-alist` - モードごとのリガチャリスト
- **78-82行目**: `+ligatures-extra-alist` - モードごとのシンボル置換設定
- **95-101行目**: `+ligatures--enable-p` - 有効化判定関数
- **103-125行目**: `+ligatures-init-extra-symbols-h` - シンボルモード初期化
- **133行目**: prettify-symbols-unprettify-at-point設定
- **138-165行目**: 環境検出とリガチャモード有効化

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ligatures.el | `modules/ui/ligatures/autoload/ligatures.el` | set-ligatures!、set-font-ligatures!マクロ |

**主要処理フロー**:
- **8-49行目**: `set-ligatures!` - シンボル置換設定関数
- **52-85行目**: `set-font-ligatures!` - フォントリガチャ設定関数

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

```
doom-init-ui-hook
    │
    ├─ [macOS emacs-mac]
    │      └─ mac-auto-operator-composition-mode
    │
    └─ [Harfbuzz対応]
           │
           ├─ ligature-set-ligatures (+ligatures-alist)
           │
           └─ global-ligature-mode

after-change-major-mode-hook (+extra)
    │
    └─ +ligatures-init-extra-symbols-h
           │
           ├─ +ligatures-extra-alist (シンボル取得)
           │
           └─ prettify-symbols-mode
```

### データフロー図

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

+ligatures-alist ───▶ ligature-set-ligatures ───▶ composition-function-table
                                                       │
                                                       ▼
バッファテキスト ─────────────────────────────────▶ リガチャ表示

+ligatures-extra-symbols
       │
       ▼
+ligatures-extra-alist ───▶ prettify-symbols-alist ───▶ シンボル表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/ligatures/config.el` | ソース | メイン設定ファイル |
| packages.el | `modules/ui/ligatures/packages.el` | 設定 | パッケージ依存定義 |
| ligatures.el | `modules/ui/ligatures/autoload/ligatures.el` | ソース | カスタム関数定義 |
| doctor.el | `modules/ui/ligatures/doctor.el` | ソース | 診断スクリプト |
