# 機能設計書 19-ジャンプ操作(SPC j)

## 概要

本ドキュメントは、space-vimにおけるジャンプ操作機能（SPC j）の設計仕様を記述する。SPCキーに続いて「j」を押下することで、EasyMotionによるジャンプ操作（文字、行、単語単位でのジャンプ）を提供する機能である。

### 本機能の処理概要

ジャンプ操作機能は、vim-easymotionプラグインと連携し、画面上の任意の位置への高速ジャンプを実現する。通常のVim移動（f/t/w/b等）は近距離移動に限られるが、EasyMotionを使用することで画面上のどの位置にも少ないキーストロークでジャンプできる。

**業務上の目的・背景**：Vimでの移動は効率的だが、画面の離れた位置への移動は複数のキーストロークが必要になる。EasyMotionを使用することで、目的の位置に視覚的なヒントが表示され、そのヒント文字を入力するだけでジャンプできる。これにより、編集作業の効率が大幅に向上する。

**機能の利用シーン**：
- 画面上の特定の文字にジャンプしたい場合（SPC j j）
- 画面上の特定の2文字の組み合わせにジャンプしたい場合（SPC j J）
- 画面上の特定の行にジャンプしたい場合（SPC j l）
- 画面上の特定の単語にジャンプしたい場合（SPC j w）
- 前方/後方の単語にジャンプしたい場合（SPC j f / SPC j b）
- JSONの整形を行いたい場合（SPC j F）

**主要な処理内容**：
1. SPC j j：任意の文字へジャンプ（easymotion-bd-f）
2. SPC j J：2文字指定でジャンプ（easymotion-overwin-f2）
3. SPC j l：行単位でジャンプ（easymotion-bd-jk）
4. SPC j w：単語単位で双方向ジャンプ（easymotion-bd-w）
5. SPC j f：前方の単語にジャンプ（easymotion-prefix w）
6. SPC j b：後方の単語にジャンプ（easymotion-prefix F）
7. SPC j F：JSONフォーマット（python -m json.tool）

**関連システム・外部連携**：
- vim-easymotion：高速ジャンプの基盤プラグイン
- Python（json.tool）：JSONフォーマット用

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | EasyMotionはオーバーレイ表示であり、独立した画面はない |

## 機能種別

ナビゲーション / ジャンプ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| キーシーケンス | String | Yes | SPC j に続くキー入力 | 定義済みキーのみ受付 |
| 検索文字 | Char | Yes（j/J使用時） | ジャンプ先を指定する文字 | - |
| ヒント文字 | Char | Yes | EasyMotionが表示するヒント文字 | - |

### 入力データソース

- ユーザーキー入力
- 画面上のテキスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ヒントオーバーレイ | UI | ジャンプ先のヒント文字表示 |
| カーソル移動 | Vim状態 | ジャンプ先へのカーソル移動 |

### 出力先

- Vim画面（ヒントオーバーレイ）
- Vimカーソル位置

## 処理フロー

### 処理シーケンス

```
1. SPC j キー入力
   └─ which-keyによるサブキー一覧表示
2. サブキー入力に応じた処理分岐
   ├─ j:  1文字指定（ユーザーに文字入力を促す）
   ├─ J:  2文字指定（ユーザーに2文字入力を促す）
   ├─ l:  行ジャンプ（即座にヒント表示）
   ├─ w:  単語ジャンプ（即座にヒント表示）
   ├─ f:  前方単語ジャンプ
   ├─ b:  後方単語ジャンプ
   └─ F:  JSONフォーマット
3. EasyMotionヒント表示
4. ユーザーによるヒント文字入力
5. ジャンプ実行
```

### フローチャート

```mermaid
flowchart TD
    A[SPC j 入力] --> B{サブキー?}
    B -->|j| C[1文字入力待ち]
    B -->|J| D[2文字入力待ち]
    B -->|l| E[行ヒント表示]
    B -->|w| F[単語ヒント表示]
    B -->|f| G[前方単語ヒント]
    B -->|b| H[後方単語ヒント]
    B -->|F| I[JSONフォーマット]
    C --> J[マッチ箇所にヒント表示]
    D --> J
    E --> K[全行にヒント表示]
    F --> L[全単語にヒント表示]
    G --> M[前方単語にヒント表示]
    H --> N[後方単語にヒント表示]
    J --> O[ヒント文字入力]
    K --> O
    L --> O
    M --> O
    N --> O
    O --> P[ジャンプ実行]
    I --> Q[現在行をJSON整形]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | EasyMotion連携 | ジャンプ操作はvim-easymotionを使用 | +vim/better-motionレイヤー有効時 |
| BR-002 | オーバーウィンドウ | nモードでは複数ウィンドウにまたがるジャンプが可能 | overwin系マッピング使用時 |
| BR-003 | 双方向検索 | SPC j j / SPC j w は前方・後方両方を検索 | bd系マッピング使用時 |
| BR-004 | JSONフォーマット | SPC j F は現在行をpythonで整形 | Pythonがインストールされている場合 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | マッチなし | 指定文字が画面上にない | ヒントが表示されない |
| - | Python未インストール | SPC j FでPythonがない | エラーメッセージ表示 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ヒント表示は即時（50ミリ秒以内）
- ジャンプ実行は即時

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

該当なし

## 備考

- quick-scopeプラグインも+vim/better-motionレイヤーに含まれ、f/t移動のヒント表示を提供
- SPC SPC でEasyMotionプレフィックスにもアクセス可能

---

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

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

### 推奨読解順序

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

ジャンプ操作のキーマッピング定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | leader.vim | `core/autoload/spacevim/map/leader.vim` | s:leader_map['j']の構造を理解 |

**読解のコツ**: ジャンプ操作はEasyMotionプラグインのマッピングを参照している。

**主要データ構造**:
- **112行目**: `let s:leader_map['j'] = {` - ジャンプ操作グループ開始
- **113行目**: `'name' : '+jump/json'` - グループ名
- **114行目**: `'j' : 'easymotion-goto-char'` - 1文字ジャンプ
- **115行目**: `'J' : 'easymotion-goto-char-2'` - 2文字ジャンプ
- **116行目**: `'l' : 'jump-linewise'` - 行ジャンプ
- **117行目**: `'w' : 'jump-to-word-bidirectional'` - 単語双方向ジャンプ
- **118行目**: `'f' : 'jump-forward-wordwise'` - 前方単語ジャンプ
- **119行目**: `'b' : 'jump-backword-wordwise'` - 後方単語ジャンプ
- **120行目**: `'F' : [':execute line(".")."!python -m json.tool"', ...]` - JSONフォーマット

#### Step 2: EasyMotion設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+vim/better-motion/config.vim` | EasyMotionキーマッピング |

**主要処理フロー**:
- **10行目**: `map <Leader><Leader> <Plug>(easymotion-prefix)` - EasyMotionプレフィックス
- **14-15行目**: `map <Leader>jj <Plug>(easymotion-bd-f)` - 1文字ジャンプ
- **18行目**: `nmap <Leader>jJ <Plug>(easymotion-overwin-f2)` - 2文字ジャンプ
- **21-22行目**: `map <Leader>jl <Plug>(easymotion-bd-jk)` - 行ジャンプ
- **25-26行目**: `map <Leader>jw <Plug>(easymotion-bd-w)` - 単語ジャンプ
- **28行目**: `map <Leader>jf <Plug>(easymotion-prefix)w` - 前方単語
- **29行目**: `map <Leader>jb <Plug>(easymotion-prefix)F` - 後方単語
- **32行目**: quick-scope設定

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

```
SPC j キー入力
    │
    ├─ SPC j j
    │      └─ <Plug>(easymotion-bd-f)
    │             └─ vim-easymotion bd-f モーション
    │                    └─ 入力文字のマッチ箇所にヒント表示
    │
    ├─ SPC j J
    │      └─ <Plug>(easymotion-overwin-f2)
    │             └─ vim-easymotion overwin-f2 モーション
    │                    └─ 複数ウィンドウにまたがる2文字検索
    │
    ├─ SPC j l
    │      └─ <Plug>(easymotion-bd-jk)
    │             └─ vim-easymotion bd-jk モーション
    │                    └─ 全行にヒント表示
    │
    ├─ SPC j w
    │      └─ <Plug>(easymotion-bd-w)
    │             └─ vim-easymotion bd-w モーション
    │                    └─ 全単語先頭にヒント表示
    │
    ├─ SPC j f
    │      └─ <Plug>(easymotion-prefix)w
    │             └─ 前方単語にヒント表示
    │
    ├─ SPC j b
    │      └─ <Plug>(easymotion-prefix)F
    │             └─ 後方単語にヒント表示
    │
    └─ SPC j F
           └─ :execute line(".")."!python -m json.tool"
                  └─ 現在行をpythonでJSON整形
```

### データフロー図

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

ユーザーキー入力 ────▶ which-keyディスパッチ ───▶ サブキー選択UI
    │                       │
    ▼                       ▼
SPC j + サブキー ────▶ EasyMotion起動 ──────────▶ ヒントオーバーレイ
    │                       │
    ▼                       ▼
検索文字入力 ────────▶ マッチ箇所検索 ──────────▶ ヒント文字割り当て
    │                       │
    ▼                       ▼
ヒント文字入力 ──────▶ ジャンプ実行 ────────────▶ カーソル移動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| leader.vim | `core/autoload/spacevim/map/leader.vim` | ソース | ジャンプ操作キーマッピング定義 |
| config.vim | `layers/+vim/better-motion/config.vim` | 設定 | EasyMotionキーマッピング |
| packages.vim | `layers/+vim/better-motion/packages.vim` | 設定 | vim-easymotionプラグイン登録 |
