# 機能設計書 76-テキスト整列

## 概要

本ドキュメントは、space-vimの+vim/text-alignレイヤーが提供するtabularによるテキスト整列機能について、その設計と実装を詳細に記述する。

### 本機能の処理概要

**業務上の目的・背景**：
コードや文書において、特定の文字（=、:、|等）でテキストを揃えることは、可読性を大幅に向上させる。手動でスペースを挿入して整列させる作業は煩雑であり、変更のたびに再調整が必要となる。tabularプラグインは、正規表現パターンに基づいてテキストを自動的に整列させることで、この作業を効率化する。

**機能の利用シーン**：
- 変数の代入文を=で揃えたい場合
- JSONやYAMLのキー・値を:で揃えたい場合
- Markdownのテーブルを|で揃えたい場合
- 関数の引数リストを,で揃えたい場合
- =>（ハッシュロケット）で揃えたい場合

**主要な処理内容**：
1. tabularプラグインの遅延読み込み（Tabularizeコマンド実行時）
2. Leaderキーによる整列コマンドのマッピング
3. 正規表現パターンに基づくテキスト整列処理
4. ノーマルモード・ビジュアルモード両対応

**関連システム・外部連携**：
- 外部プラグイン: godlygeek/tabular
- vim-which-keyとの連携（キーバインディングヒント表示）

**権限による制御**：
本機能に権限による制御は存在しない。+vim/text-alignレイヤーを有効化することで全ユーザーが利用可能となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Which-Key（キーバインド表示画面） | 補助機能 | SPC aキー押下後のキーバインドヒント表示 |

## 機能種別

エディタ補助機能 / テキスト整形

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 整列パターン | String | Yes | 整列に使用する文字/正規表現 | 有効な正規表現 |
| 対象範囲 | Range | Yes | 整列対象の行範囲 | 選択範囲またはカレント段落 |

### 入力データソース

- ユーザーのキーボード入力（Leader a + サブコマンド）
- ビジュアルモードでの範囲選択
- 現在のバッファ内容（整列対象テキスト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 整列済みテキスト | String | パターンで揃えられたテキスト |

### 出力先

- 現在のバッファ（インプレース編集）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがLeader a + サブコマンドを押下
   └─ またはビジュアルモードで範囲選択後にコマンド実行
2. Tabularizeコマンドが実行される
   └─ 遅延読み込みでプラグインがロードされる
3. 指定パターンでテキストを解析
   └─ 各行のパターン位置を特定
4. 適切なスペースを挿入して整列
   └─ バッファ内容を更新
```

### フローチャート

```mermaid
flowchart TD
    A[Leader a + サブコマンド] --> B{遅延読み込み済み?}
    B -->|No| C[tabularプラグインロード]
    B -->|Yes| D[対象範囲特定]
    C --> D
    D --> E[パターン解析]
    E --> F[整列位置計算]
    F --> G[スペース挿入]
    G --> H[バッファ更新]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-1 | 遅延読み込み | Tabularizeコマンド実行時にプラグインをロード | 初回コマンド実行時 |
| BR-76-2 | ノーマル/ビジュアル | 両モードでマッピングを定義 | 常時 |
| BR-76-3 | 正規表現サポート | \zsなどのVim正規表現を使用可能 | Tabularizeコマンド |

### 計算ロジック

- 各行でパターンの位置を検出
- 最も右にあるパターン位置に合わせてスペースを挿入
- \zs（ゼロ幅マッチ）を使用することで、パターン文字の後ろに揃えることも可能

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

本機能にデータベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パターン未検出 | 指定パターンが対象範囲に存在しない | 別のパターンを指定 |
| - | 無効な正規表現 | 正規表現構文エラー | 正しい正規表現を指定 |

### リトライ仕様

本機能にリトライ処理は存在しない。

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

本機能はUndoで元に戻すことが可能。複数行の整列は1つのUndo単位として扱われる。

## パフォーマンス要件

- 遅延読み込みにより起動時間への影響を最小化
- 大量の行を対象としても即座に処理（テキスト処理のみ）

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

本機能はテキスト編集のみであり、セキュリティ上の考慮事項は特になし。

## 備考

- tabularはgodlygeek氏が開発・メンテナンスしている外部プラグイン
- vim-easy-alignとの違い：tabularはコマンドベース、easy-alignはインタラクティブ

---

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

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

### 推奨読解順序

#### Step 1: パッケージ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | packages.vim | `layers/+vim/text-align/packages.vim` | プラグイン登録と遅延読み込み条件 |

**読解のコツ**: `{ 'on': 'Tabularize' }`はTabularizeコマンド実行時のみプラグインをロードする遅延読み込み設定。

**主要処理フロー**:
- **1行目**: `MP 'godlygeek/tabular', { 'on': 'Tabularize' }` - Tabularizeコマンドでの遅延読み込み

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config.vim | `layers/+vim/text-align/config.vim` | 整列コマンドのキーマッピング |

**読解のコツ**: 各マッピングは`:Tabularize /パターン<CR>`を実行する。`\zs`は「ここからマッチ開始」を意味するVim正規表現。

**主要処理フロー**:
- **2-3行目**: `<Leader>a&` - &で整列
- **4-5行目**: `<Leader>a=` - =で整列（最初の=のみ）
- **6-7行目**: `<Leader>a=>` - =>（ハッシュロケット）で整列
- **8-9行目**: `<Leader>a:` - :で整列
- **10-11行目**: `<Leader>a::` - :の後ろで整列
- **12-13行目**: `<Leader>a,` - ,で整列
- **14-15行目**: `<Leader>a,,` - ,の後ろで整列
- **16-17行目**: `<Leader>a|` - |で整列（Markdownテーブル用）

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

```
~/.spacevim（ユーザー設定）
    │
    └─ Layer('+vim/text-align')
           │
           ├─ packages.vim
           │      └─ MP 'godlygeek/tabular'（Tabularizeコマンドで遅延ロード）
           │
           └─ config.vim
                  ├─ <Leader>a& → :Tabularize /&
                  ├─ <Leader>a= → :Tabularize /^[^=]*\zs=
                  ├─ <Leader>a=> → :Tabularize /=>
                  ├─ <Leader>a: → :Tabularize /:
                  ├─ <Leader>a:: → :Tabularize /:\zs
                  ├─ <Leader>a, → :Tabularize /,
                  ├─ <Leader>a,, → :Tabularize /,\zs
                  └─ <Leader>a| → :Tabularize /|
```

### データフロー図

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

選択範囲 +         ───▶  パターン解析           ───▶  整列済みテキスト
Leader a + 文字                ↓
                         位置計算
                               ↓
                         スペース挿入
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+vim/text-align/packages.vim` | ソース | プラグイン登録と遅延読み込み設定 |
| config.vim | `layers/+vim/text-align/config.vim` | ソース | キーマッピング定義 |
| leader.vim | `core/autoload/spacevim/map/leader.vim` | ソース | Leaderキーマッピングの説明定義 |
