# 画面設計書 24-Ligatures

## 概要

本ドキュメントは、Doom EmacsのLigatures機能の画面設計について記述します。Ligaturesは、プログラミング用の合字（リガチャ）表示と、特定のキーワードを数学記号等に置換表示する機能を提供します。

### 本画面の処理概要

Ligaturesは、2つの主要な視覚的機能を提供します：（1）フォント合字機能により「->」を矢印記号に変換表示、（2）シンボル置換機能により「lambda」をλに変換表示。これらの機能はコードの可読性向上と美観改善を目的としています。

**業務上の目的・背景**：プログラミングにおいて、演算子や特殊な構文は複数文字の組み合わせで表現されることが多い（例：`->`, `=>`, `!=`, `<=>`）。これらを単一のグリフとして表示することで、コードの視認性を向上させ、数学的記法に近い直感的な表現を実現します。また、関数型プログラミング言語でのラムダ式など、数学的概念をより自然な記号で表示することで、コードの意図を明確にします。

**画面へのアクセス方法**：Ligaturesは自動的に動作するため、明示的な画面アクセスは不要です。以下の条件で自動的に有効化されます：
- Emacs 28以上でHarfbuzzサポートがある場合：ligature.elパッケージを使用
- macOSのemacs-macビルド：mac-auto-operator-composition-modeを使用
- +extraフラグ有効時：prettify-symbols-modeによる追加シンボル置換

**主要な操作・処理内容**：
1. バッファを開くとメジャーモードに応じた合字設定が適用される
2. composition-function-tableを通じてフォントの合字機能が有効化される
3. +extraフラグ有効時はprettify-symbols-alistが設定される
4. テキスト表示時に合字・シンボル置換が適用される
5. カーソルが右端に到達すると元の表示に戻る

**画面遷移**：Ligaturesは独立した画面ではなく、編集バッファ上で動作する視覚エフェクトです。他の画面への遷移機能はありません。

**権限による表示制御**：権限による制御はありません。fundamental-modeでは無効化されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 30 | リガチャ（合字）サポート | 主機能 | プログラミング用合字表示変換 |

## 画面種別

視覚エフェクト（文字表示変換）

## URL/ルーティング

N/A（Emacsバッファ上で動作するため、URLの概念なし）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|----------|------|
| +ligatures-alist | 入力 | alist | モードごとの合字文字列リスト |
| +ligatures-extra-symbols | 入力 | plist | シンボル名とUnicode文字の対応 |
| +ligatures-extra-alist | 入力 | alist | モードごとのシンボル置換設定 |
| +ligatures-extras-in-modes | 入力 | list/t | 追加シンボルを有効化するモード |
| prettify-symbols-alist | 出力 | alist | 実際に適用されるシンボル置換 |

## 表示項目

### フォント合字（prog-mode標準）

| 文字列 | 説明 |
|--------|------|
| `->`, `-->`, `->>` | 矢印系 |
| `<-`, `<--`, `<<-` | 逆矢印系 |
| `=>`, `==>`, `=>>` | 太矢印系 |
| `<=`, `<=>`, `<=<` | 比較/双方向矢印 |
| `!=`, `!==`, `=/=` | 不等号 |
| `===`, `==` | 等号 |
| `::`, `:::`, `::=` | コロン系 |
| `&&`, `||` | 論理演算子 |
| `##`, `###`, `####` | ハッシュ系 |
| `...`, `..` | ドット系 |

### シンボル置換（+extraフラグ有効時）

| キー | デフォルトシンボル | 説明 |
|------|-------------------|------|
| :lambda | λ | ラムダ式 |
| :def | f | 関数定義 |
| :composition | ∘ | 関数合成 |
| :map | ↦ | マップ/写像 |
| :null | ∅ | null/空集合 |
| :true | T | 真 |
| :false | F | 偽 |
| :int | Z | 整数 |
| :float | R | 実数 |
| :str | S | 文字列 |
| :bool | B | 論理型 |
| :list | L | リスト |
| :not | ¬ | 論理否定 |
| :in | ∈ | 所属 |
| :not-in | ∉ | 非所属 |
| :and | ∧ | 論理積 |
| :or | ∨ | 論理和 |
| :for | ∀ | 全称量化子 |
| :some | ∃ | 存在量化子 |
| :return | ⟼ | リターン |
| :yield | ⟻ | イールド |
| :union | ⋃ | 和集合 |
| :intersect | ∩ | 積集合 |
| :diff | ∖ | 差集合 |
| :tuple | ⨂ | タプル |
| :dot | • | ドット |

## イベント仕様

### 1-フォント合字の有効化

doom-init-ui-hookでglobal-ligature-modeが有効化されます。

**処理フロー**：
1. Emacsの初期化完了後、`doom-init-ui-hook` が発火
2. `global-ligature-mode` が有効化される
3. `+ligatures-alist` に基づいて各モードの合字設定が登録される
4. バッファ表示時に `ligature-set-ligatures` で設定された文字列が合字表示される

### 2-シンボル置換の有効化（+extraフラグ）

メジャーモード変更時にprettify-symbols-modeが設定されます。

**処理フロー**：
1. バッファのメジャーモードが変更される
2. `after-change-major-mode-hook` から `+ligatures-init-extra-symbols-h` が呼び出される
3. `+ligatures-extras-in-modes` でモードが許可されているか確認
4. `+ligatures-extra-alist` から該当モードのシンボル設定を取得
5. `prettify-symbols-alist` に設定を適用
6. `prettify-symbols-mode` を有効化

### 3-カーソル位置でのアンプリティファイ

カーソルが記号の右端に到達すると元の表示に戻ります。

**処理フロー**：
1. カーソルがprettifyされた記号の右端に移動
2. `prettify-symbols-unprettify-at-point` の設定に従い
3. 一時的に元のテキスト表示に戻る

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

N/A（データベースを使用しない）

## メッセージ仕様

N/A（メッセージ表示なし）

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| fundamental-mode | 合字・シンボル置換を適用しない |
| Emacs 27以下 | ligature.elを使用せず、機能制限 |
| Harfbuzzなしビルド | composition-function-table方式が使用不可 |

## 備考

- Unicode Private Area の文字は使用不可（フォント間で互換性がないため）
- macOSのemacs-macビルドでは組み込みのmac-auto-operator-composition-modeを使用
- `set-ligatures!` マクロでモード固有のシンボル置換を設定可能
- `set-font-ligatures!` マクロでモード固有のフォント合字を設定可能
- Emacs 28以上でHarfbuzzサポートが必要

---

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

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

### 推奨読解順序

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

シンボル定義と合字リストが中心的なデータ構造です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.el | `modules/ui/ligatures/config.el` | `+ligatures-extra-symbols` の定義（行3-45） |
| 1-2 | config.el | `modules/ui/ligatures/config.el` | `+ligatures-alist` の定義（行47-64） |

**読解のコツ**: `+ligatures-extra-symbols` はplistで、キーワード（:lambda等）とUnicode文字の対応を定義。`+ligatures-alist` はalistで、メジャーモードと合字文字列リストの対応を定義。

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

UI初期化フックと、モード変更フックがエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.el | `modules/ui/ligatures/config.el` | 初期化処理（行128-165） |

**主要処理フロー**:
1. **行133**: `prettify-symbols-unprettify-at-point` を `'right-edge` に設定
2. **行135-136**: +extraフラグ有効時、`after-change-major-mode-hook` に `+ligatures-init-extra-symbols-h` を登録
3. **行138-145**: macOSのemacs-macビルド判定、`mac-auto-operator-composition-mode` を使用
4. **行147-165**: Emacs 28以上でHarfbuzz/compositeサポート時、ligature.elを使用

#### Step 3: シンボル初期化関数を理解する

+extraフラグ有効時のシンボル設定関数を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.el | `modules/ui/ligatures/config.el` | `+ligatures-init-extra-symbols-h` 関数（行103-125） |

**主要処理フロー**:
- **行103-125**: メジャーモードに応じたシンボル設定の適用
- **行112-118**: `+ligatures-extra-alist` から該当モードの設定を取得
- **行119-125**: `prettify-symbols-alist` に設定を追加し、`prettify-symbols-mode` を有効化

#### Step 4: カスタマイズAPIを理解する

`set-ligatures!` と `set-font-ligatures!` マクロの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | autoload/ligatures.el | `modules/ui/ligatures/autoload/ligatures.el` | APIマクロの実装（行1-86） |

**主要処理フロー**:
- **行8-49**: `set-ligatures!` - モード固有のシンボル置換を設定
- **行52-85**: `set-font-ligatures!` - モード固有のフォント合字を設定

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

```
Emacs起動
    │
    ├─ doom-init-ui-hook ─────────────────────────────────────┐
    │                                                          │
    │   ├─ macOS emacs-mac ────▶ mac-auto-operator-composition-mode
    │   │                                                      │
    │   └─ Emacs 28+ Harfbuzz ─▶ global-ligature-mode         │
    │                                  │                       │
    │                                  ▼                       │
    │                            ligature-set-ligatures       │
    │                            (+ligatures-alist適用)       │
    │                                                          │
    └─ after-change-major-mode-hook (+extra有効時) ───────────┤
                                                               │
        +ligatures-init-extra-symbols-h                       │
            │                                                  │
            ├─ +ligatures--enable-p 判定                      │
            │                                                  │
            ├─ +ligatures-extra-alist から設定取得            │
            │                                                  │
            └─ prettify-symbols-mode 有効化                   │
                                                               │
                        バッファ表示時 ◀──────────────────────┘
                             │
                             ▼
                    composition-function-table
                    または prettify-symbols-alist
                    による表示変換
```

### データフロー図

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

+ligatures-alist ───▶ ligature-set-ligatures ───▶ composition-function-table
       │                                                    │
       └─ ("->", "=>", "!=", ...)                          ▼
                                                   フォント合字表示

+ligatures-extra-symbols ───▶ set-ligatures! ───▶ +ligatures-extra-alist
       │                                                    │
       └─ (:lambda "λ", :def "f", ...)                     ▼
                                              prettify-symbols-alist
                                                            │
                                                            ▼
                                                   シンボル置換表示

prettify-symbols-unprettify-at-point ───▶ カーソル位置判定 ───▶ 元表示復元
       │
       └─ 'right-edge
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config.el | `modules/ui/ligatures/config.el` | ソース | メイン設定、シンボル/合字定義、初期化処理 |
| autoload/ligatures.el | `modules/ui/ligatures/autoload/ligatures.el` | ソース | set-ligatures!、set-font-ligatures! API |
| packages.el | `modules/ui/ligatures/packages.el` | 設定 | ligature.elパッケージの依存定義 |
| doctor.el | `modules/ui/ligatures/doctor.el` | ソース | 互換性チェック |
| README.org | `modules/ui/ligatures/README.org` | ドキュメント | モジュール説明書、設定例 |
| .doommodule | `modules/ui/ligatures/.doommodule` | 設定 | Doomモジュールメタデータ |
