# 機能設計書 60-自動ペアリング

## 概要

本ドキュメントは、space-vimにおける自動ペアリング機能の設計を定義する。auto-pairsプラグインを利用した括弧、引用符等のペア文字自動補完機能を提供する。

### 本機能の処理概要

コーディング効率を向上させるため、括弧、引用符、角括弧などのペア文字を自動的に補完する機能を提供する。

**業務上の目的・背景**：プログラミングにおいて括弧（`()`、`{}`、`[]`）や引用符（`''`、`""`）は頻繁に使用される。開き括弧を入力するたびに閉じ括弧を手動で入力するのは非効率であり、タイプミスの原因にもなる。auto-pairsは開き括弧入力時に自動的に閉じ括弧を挿入し、カーソルをペアの中央に配置することで、効率的なコーディングを実現する。

**機能の利用シーン**：任意のプログラミング言語でコードを記述する際に自動的に有効化される。括弧、引用符を入力すると対応する閉じ文字が自動挿入され、カーソルがペアの中央に配置される。既存のペアを選択して別のペアで囲むことも可能。

**主要な処理内容**：
1. 開き括弧入力時の閉じ括弧自動挿入
2. 引用符入力時の対応引用符自動挿入
3. カーソル位置の自動調整（ペア中央配置）
4. ペア内でのBackspace時の両括弧削除
5. 遅延初期化による他プラグインとの互換性確保

**関連システム・外部連携**：auto-pairsプラグインとの連携。vim-clapとの干渉を避けるための遅延読み込み機構を実装。

**権限による制御**：特になし。レイヤー有効化によりすべての機能が利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Vimエディタ画面 | 主画面 | テキスト編集時の括弧自動補完 |

## 機能種別

編集支援 / 自動補完 / 入力効率化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| g:AutoPairsLoaded | Number | No | プラグインロード状態フラグ | 0または1 |

### 入力データソース

- ユーザーのキー入力（括弧、引用符等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ペア文字 | テキスト | 自動挿入された閉じ括弧/引用符 |
| カーソル位置 | 位置 | ペア中央への移動 |

### 出力先

- Vimエディタ画面（バッファ）

## 処理フロー

### 処理シーケンス

```
1. レイヤー読み込み
   └─ +programming/editingレイヤーが有効化される
2. プラグイン登録
   └─ auto-pairsがvim-plugにより登録される（遅延読み込み）
3. autocmd設定
   └─ CursorHold/CursorHoldI/InsertEnterイベントでロードトリガー設定
4. イベント発生
   └─ カーソル停止または挿入モード開始時にプラグインロード
5. 初期化
   └─ AutoPairsTryInit()で初期化実行
6. 自動補完動作
   └─ 開き括弧入力で閉じ括弧自動挿入
```

### フローチャート

```mermaid
flowchart TD
    A[Vim起動] --> B{editingレイヤー有効?}
    B -->|Yes| C[auto-pairs登録（遅延）]
    B -->|No| Z[終了]
    C --> D[autocmd設定]
    D --> E[待機]
    E --> F{CursorHold/InsertEnter?}
    F -->|Yes| G[TryInitAutoPairs呼び出し]
    F -->|No| E
    G --> H{プラグイン存在?}
    H -->|No| I[終了]
    H -->|Yes| J{既にロード済み?}
    J -->|Yes| K[AutoPairsTryInit実行]
    J -->|No| L[plug#load実行]
    L --> K
    K --> M[autocmd削除]
    M --> N[自動ペアリング有効]
    N --> O{開き括弧入力?}
    O -->|Yes| P[閉じ括弧挿入]
    O -->|No| N
    P --> Q[カーソルをペア中央に]
    Q --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-01 | レイヤー依存 | +programming/editingレイヤーの有効化が必要 | .spacevimファイルでレイヤー指定時 |
| BR-60-02 | 遅延読み込み | on: []で登録、イベントで遅延ロード | 他プラグイン干渉回避 |
| BR-60-03 | 初期化トリガー | CursorHold/CursorHoldI/InsertEnterで初期化 | autocmd設定 |
| BR-60-04 | 一度のみ初期化 | 初期化後にautocmd削除 | autocmd! spacevimAutoPairs |
| BR-60-05 | vim-clap互換 | vim-clapとの干渉を避ける設計 | packages.vimコメント |

### 計算ロジック

特になし

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

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

該当なし（データベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | プラグイン未インストール | vim-plugによるインストール未完了 | :PlugInstall実行 |
| - | プラグイン干渉 | vim-clapとの干渉 | auto-pairs無効化、coc-pairs使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 括弧入力からペア挿入：即時（10ms以下）
- プラグインロード：初回のみ、100ms以下

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

- 外部通信なし
- ローカルバッファ操作のみ

## 備考

- vim-clapと干渉する場合はauto-pairsを無効化し、coc-pairsを使用可能
- 言語固有のペア設定（例：Lispでの`'`処理）はファイルタイプ別に調整可能

---

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

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

### 推奨読解順序

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

自動ペアリング機能はpackages.vim内で遅延読み込みロジックを含む。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+programming/editing/packages.vim` | 遅延読み込みロジックの確認 |

**読解のコツ**: `on: []`は空のトリガーリストを意味し、自動ロードを無効化。autocmdとfunction定義で独自の遅延ロード機構を実装。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | packages.vim | `layers/+programming/editing/packages.vim` | auto-pairs登録と遅延ロード |

**主要処理フロー**:
1. **9行目**: `MP 'jiangmiao/auto-pairs', { 'on': [] }` - auto-pairs登録（遅延読み込み）
2. **11-22行目**: `TryInitAutoPairs()`関数定義
   - **12行目**: プラグイン存在チェック
   - **15-17行目**: 未ロード時にplug#load実行
   - **18-20行目**: AutoPairsTryInit関数呼び出し
   - **21行目**: autocmd削除（一度のみ実行）
3. **24-27行目**: `spacevimAutoPairs` augroup定義
   - **26行目**: CursorHold/CursorHoldI/InsertEnterでTryInitAutoPairs呼び出し

#### Step 3: 関連設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+programming/editing/config.vim` | nerdcommenter等の他のediting機能設定 |

**主要処理フロー**:
- config.vimにはauto-pairs固有の設定はなく、nerdcommenter、vim-multiple-cursors、vim-swoopの設定のみ

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

```
.spacevim (ユーザー設定)
    │
    └─ Layer '+programming/editing' 有効化
           │
           └─ packages.vim
                  │
                  ├─ MP 'jiangmiao/auto-pairs' (遅延登録)
                  │
                  ├─ function TryInitAutoPairs()
                  │      │
                  │      ├─ has_key(g:plugs, 'auto-pairs') チェック
                  │      │
                  │      ├─ g:AutoPairsLoaded チェック
                  │      │
                  │      ├─ plug#load('auto-pairs')
                  │      │
                  │      ├─ AutoPairsTryInit()
                  │      │
                  │      └─ autocmd! spacevimAutoPairs
                  │
                  └─ augroup spacevimAutoPairs
                         │
                         └─ CursorHold/InsertEnter → TryInitAutoPairs()
```

### データフロー図

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

.spacevim ───▶ レイヤーシステム ───▶ プラグイン登録
                     │
                     ▼
              autocmd設定
                     │
                     ▼
CursorHold/InsertEnter ───▶ TryInitAutoPairs()
                     │
                     ▼
              plug#load('auto-pairs')
                     │
                     ▼
              AutoPairsTryInit()
                     │
                     ▼
開き括弧入力 ───▶ auto-pairs ───▶ 閉じ括弧挿入 + カーソル移動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+programming/editing/packages.vim` | 設定 | auto-pairs登録と遅延ロード |
| config.vim | `layers/+programming/editing/config.vim` | 設定 | 他のediting機能設定（auto-pairs設定なし） |
| LAYERS.md | `layers/LAYERS.md` | ドキュメント | レイヤー一覧とプラグイン情報 |
