# 機能設計書 62-マルチカーソル

## 概要

本ドキュメントは、space-vimにおけるマルチカーソル機能の設計について記載する。vim-multiple-cursorsプラグインによる複数カーソルを使った同時編集機能を提供する。

### 本機能の処理概要

マルチカーソル機能は、複数の位置に同時にカーソルを配置し、一度の入力で複数箇所を同時編集できる機能を提供する。同じテキストパターンを複数箇所で変更する際に、繰り返し操作を省略できる。

**業務上の目的・背景**：プログラミングにおいて、変数名のリネームや同一パターンの一括変更は頻繁に発生する作業である。従来の方法では置換コマンド(`:s/old/new/g`)を使用するが、確認しながら変更したい場合や、部分的に変更したい場合には不向きである。マルチカーソル機能により、視覚的に確認しながら複数箇所を同時に編集でき、柔軟性と安全性が向上する。

**機能の利用シーン**：
- 変数名やシンボル名を複数箇所で同時に変更する場合
- 同じ形式のコードブロックを複数箇所に追加する場合
- CSV等のデータで同一列の値を一括編集する場合
- HTMLの属性を複数のタグで同時に変更する場合

**主要な処理内容**：
1. `<C-j>` - 現在の単語と同じ単語を次に検索し、カーソルを追加
2. `<C-k>` - 前のカーソル位置に戻る
3. `<C-x>` - 現在位置をスキップして次を検索
4. `<Esc>` - マルチカーソルモードを終了

**関連システム・外部連携**：terryma/vim-multiple-cursorsプラグインにより全機能が提供される。space-vimの+programming/editingレイヤーの一部として自動的にインストールされる。

**権限による制御**：特になし。すべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | テキストエディタ全般 | 主画面 | 編集中のテキストに対してマルチカーソル操作を実行 |

## 機能種別

テキスト編集操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 検索対象単語 | String | Yes（自動） | カーソル下の単語が自動的に検索対象となる | なし |

### 入力データソース

キーボード入力（ノーマルモード/ビジュアルモードのコマンド）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変更後テキスト | String | 複数カーソル位置で同時に編集されたテキスト |

### 出力先

編集中のバッファ（テキストファイル）

## 処理フロー

### 処理シーケンス

```
1. カーソルを検索対象の単語に配置
   └─ または、ビジュアルモードでテキストを選択

2. <C-j>でマルチカーソルモード開始
   └─ 現在の単語が選択され、次の同一単語を検索

3. 追加のカーソル配置
   └─ <C-j>で次を追加、<C-k>で戻る、<C-x>でスキップ

4. 編集モードに入る
   └─ c/s/i/a等の編集コマンドを入力

5. テキスト入力
   └─ すべてのカーソル位置で同時に入力が反映

6. <Esc>で終了
   └─ マルチカーソルモード終了、通常モードに戻る
```

### フローチャート

```mermaid
flowchart TD
    A[カーソルを単語に配置] --> B[Ctrl+jでマルチカーソル開始]
    B --> C{次の同一単語を検索}
    C -->|見つかった| D[カーソルを追加]
    C -->|見つからない| E[検索終了]
    D --> F{操作選択}
    F -->|Ctrl+j| C
    F -->|Ctrl+k| G[前のカーソルに戻る]
    F -->|Ctrl+x| H[現在位置をスキップ]
    F -->|編集コマンド| I[編集モード]
    G --> F
    H --> C
    I --> J[テキスト入力]
    J --> K{Esc押下?}
    K -->|Yes| L[マルチカーソル終了]
    K -->|No| J
    E --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 単語境界検索 | デフォルトでは単語境界を考慮した検索を行う | <C-j>での検索時 |
| BR-02 | ビジュアル選択対応 | ビジュアルモードで選択したテキストを検索対象にできる | ビジュアルモードから開始時 |
| BR-03 | 編集の同期 | すべてのカーソル位置で同じ編集が同時に適用される | 編集モード中 |

### 計算ロジック

特になし（テキスト操作のみ）

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

該当なし（ファイルバッファ操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 検索結果なし | 同一単語がバッファ内に存在しない | 現在の単語のみが選択された状態で編集可能 |

### リトライ仕様

特になし（undo/redoで操作の取り消し・再実行が可能）

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

Vimのundo履歴に1操作として記録される。`u`コマンドで元に戻すことが可能。

## パフォーマンス要件

即時実行（ユーザーが知覚できる遅延なし）。大量のカーソル数になるとパフォーマンスが低下する可能性あり。

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

特になし

## 備考

- space-vimではデフォルトのキーバインディングを変更している（<C-n>から<C-j>等へ）
- deopleteやcoc.nvim等の補完プラグインと干渉する場合がある
- vim-clapのauto-pairsと干渉する可能性があり、注意が必要

---

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

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

### 推奨読解順序

#### Step 1: プラグイン登録を理解する

vim-multiple-cursorsプラグインがどのように登録されているかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+programming/editing/packages.vim` | vim-multiple-cursorsの登録方法を確認 |

**読解のコツ**: `MP`マクロはspace-vim独自のプラグイン登録関数。

**主要処理フロー**:
1. **3行目**: `MP 'terryma/vim-multiple-cursors'` でプラグインを登録

#### Step 2: キーバインディング設定を理解する

space-vimでカスタマイズされたキーバインディングを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+programming/editing/config.vim` | キーマッピングの設定を確認 |

**主要処理フロー**:
- **11行目**: `" vim-multiple-cursors {` セクション開始
- **12行目**: `let g:multi_cursor_next_key='<C-j>'` - 次のカーソル追加キー
- **13行目**: `let g:multi_cursor_prev_key='<C-k>'` - 前のカーソルに戻るキー
- **14行目**: `let g:multi_cursor_skip_key='<C-x>'` - スキップキー
- **15行目**: `let g:multi_cursor_quit_key='<Esc>'` - 終了キー
- **16行目**: `" }` セクション終了

#### Step 3: レイヤーマニフェストを確認する

レイヤー全体の構成を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | LAYERS.md | `layers/LAYERS.md` | editingレイヤーに含まれるプラグイン一覧を確認 |

**主要処理フロー**:
- **44行目**: editingレイヤーにvim-multiple-cursorsが含まれることを確認

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

```
space-vim起動
    │
    └─ spacevim#bootstrap()
           │
           └─ +programming/editing レイヤー読み込み
                  │
                  ├─ packages.vim
                  │      └─ MP 'terryma/vim-multiple-cursors'
                  │
                  ├─ config.vim
                  │      └─ キーマッピング設定
                  │             ├─ g:multi_cursor_next_key = '<C-j>'
                  │             ├─ g:multi_cursor_prev_key = '<C-k>'
                  │             ├─ g:multi_cursor_skip_key = '<C-x>'
                  │             └─ g:multi_cursor_quit_key = '<Esc>'
                  │
                  └─ vim-plug によるプラグインロード
                         │
                         └─ vim-multiple-cursors 初期化
```

### データフロー図

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

カーソル下の単語         vim-multiple-cursors           選択された単語を
     +            ───▶   プラグイン処理    ───▶         ハイライト表示
   <C-j>

同一単語の検索           vim-multiple-cursors           追加カーソルを
     +            ───▶   プラグイン処理    ───▶         配置・表示
   <C-j>

編集コマンド             vim-multiple-cursors           すべてのカーソル
  (c/s/i/a)       ───▶   プラグイン処理    ───▶         位置で同時編集
  + テキスト入力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+programming/editing/packages.vim` | 設定 | プラグイン登録 |
| config.vim | `layers/+programming/editing/config.vim` | 設定 | キーマッピング設定 |
| LAYERS.md | `layers/LAYERS.md` | ドキュメント | レイヤー一覧 |
| vim-multiple-cursors | 外部プラグイン（terryma/vim-multiple-cursors） | プラグイン | 機能本体 |
