# 画面設計書 17-Quickfix/Location List

## 概要

本ドキュメントは、space-vimにおけるQuickfix/Location List画面の設計を記述したものである。Vimビルトイン機能であるQuickfixリストおよびLocation Listの表示・操作について、space-vim固有の設定やキーバインドを含めて詳細に解説する。

### 本画面の処理概要

Quickfix/Location List画面は、コンパイルエラー、grep検索結果、LSP診断結果、構文チェック結果などの情報を一覧形式で表示し、該当箇所へのジャンプを可能にするウィンドウである。Quickfixリストはグローバルで1つ、Location Listはウィンドウごとに存在する。

**業務上の目的・背景**：開発作業において、コンパイルエラーの修正、コード検索結果の確認、構文エラーの対処など、複数の箇所を順番に処理する必要がある場面は多い。Quickfix/Location Listは、これらの情報を一元管理し、効率的なナビゲーションを提供することで、デバッグやリファクタリング作業の生産性を向上させる。

**画面へのアクセス方法**：
- `:copen` - Quickfixリストを開く
- `:lopen` - Location Listを開く
- 自動表示：コンパイル、grep、構文チェック後に自動で開く（設定による）
- `]q` / `[q` - Quickfixリスト内のナビゲーション
- `]l` / `[l` - Location List内のナビゲーション

**主要な操作・処理内容**：
1. **エラー・結果一覧表示**：ファイル名、行番号、内容を一覧表示
2. **該当箇所へのジャンプ**：Enterキーで選択項目の箇所にジャンプ
3. **リスト内ナビゲーション**：`]q`/`[q`または`]l`/`[l`でリスト内を移動
4. **リストのクローズ**：`q`キーで画面を閉じる
5. **asyncrun連携**：非同期コマンド実行結果の表示

**画面遷移**：
- エディタ画面 → Quickfix/Location List（`:copen`または自動表示）
- Quickfix/Location List → エディタ画面（項目選択でジャンプ）
- Quickfix/Location List → 画面クローズ（`q`キー）

**権限による表示制御**：本画面に権限による表示制御は存在しない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 67 | 非同期実行 | 遷移先機能 | asyncrun.vimによるコマンド実行結果の表示 |
| 41 | ALE連携 | 遷移先機能 | ALEによる構文エラー一覧の表示 |
| 32 | fzf連携 | 遷移先機能 | 検索結果からQuickfixリストへの遷移 |

## 画面種別

一覧画面（エラー・結果一覧）

## URL/ルーティング

Vimコマンドによるアクセス：
- `:copen` / `:cwindow` - Quickfixリストを開く
- `:lopen` / `:lwindow` - Location Listを開く
- `:cclose` / `:lclose` - リストを閉じる
- `:cnext` / `:cprev` - 次/前の項目へ移動
- `:lnext` / `:lprev` - Location Listの次/前の項目へ移動

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| エラーリスト | 入力（自動） | リスト | コンパイラ、リンター等からの出力 |
| 検索結果 | 入力（自動） | リスト | grep、vimgrep等からの出力 |
| 選択項目 | 出力 | 構造体 | ジャンプ先のファイル・行・カラム |

## 表示項目

### Quickfix/Location List ウィンドウ

| 表示項目 | データ型 | 説明 |
|----------|----------|------|
| ファイル名 | 文字列 | エラー・結果が存在するファイルパス |
| 行番号 | 数値 | 該当行番号 |
| カラム番号 | 数値 | 該当カラム位置（オプション） |
| 種別 | 文字列 | error/warning/info等 |
| メッセージ | 文字列 | エラー内容・検索マッチ内容 |

## イベント仕様

### 1-リスト表示

コンパイル、grep、構文チェック等の結果がQuickfixリストに格納されると、自動的にウィンドウが開く。

```
[トリガー] QuickFixCmdPost autocmd
        ↓
[spacevim/config.vim] s:OnQuickFixCmdPost()呼び出し
        ↓
[判定] qfウィンドウが未開かつリストに内容あり
        ↓
[実行] copen 8（高さ8行で開く）
```

### 2-リスト内ナビゲーション

`]q`で次のエラー、`[q`で前のエラーにジャンプする。

```
[ユーザー操作] ]q押下
        ↓
[qf.vim] spacevim#util#CycleQuickfix('cnext', 'cfirst')呼び出し
        ↓
[実行] :cnext（最後の場合は:cfirst）
        ↓
[カーソル移動] 該当ファイル・行にジャンプ + zz（中央配置）
```

### 3-項目選択ジャンプ

Quickfixウィンドウで項目を選択してEnterを押すと、その箇所にジャンプする。

```
[ユーザー操作] Quickfixウィンドウでカーソル移動 → Enter
        ↓
[Vim] 選択行の情報を取得
        ↓
[ジャンプ] 該当ファイル・行・カラムに移動
```

### 4-リストクローズ

`q`キーでQuickfix/Location Listウィンドウを閉じる。

```
[ユーザー操作] q押下
        ↓
[qf.vim] :cclose | :lclose実行
        ↓
[画面更新] Quickfix/Location Listウィンドウが閉じる
```

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

本画面は表示・ナビゲーション専用であり、データの更新は行わない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| QF001 | 情報 | (N of M) | 現在のエラー位置を表示 |
| QF002 | エラー | E553: No more items | 最後の項目で:cnext実行時 |
| QF003 | エラー | E42: No Errors | 空のQuickfixリストで操作時 |

## 例外処理

| 例外状態 | 対処 | ユーザーへの通知 |
|---------|------|-----------------|
| 空のリスト | 操作を中断 | E42エラーメッセージ |
| 最後の項目で次へ | 循環ナビゲーション | 最初の項目に戻る |
| ファイルが存在しない | ジャンプ失敗 | エラーメッセージ |

## 備考

- Quickfix/Location ListはVimビルトイン機能である
- space-vimでは`]q`/`[q`と`]l`/`[l`のナビゲーションキーバインドが設定されている
- CycleQuickfix関数により、リスト末端で最初に戻る循環ナビゲーションを実現
- Quickfixウィンドウでは`nowrap`が設定され、長い行も折り返さない
- QuickFixCmdPost autocmdで自動的にウィンドウが開く設定がある

---

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

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

### 推奨読解順序

#### Step 1: ファイルタイプ設定を理解する

まず、Quickfixバッファ用の設定がどのように行われているかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | qf.vim | `core/ftplugin/qf.vim` | Quickfixバッファ固有のキーバインドと設定 |

**読解のコツ**: `ftplugin`ディレクトリ内のファイルは、対応するファイルタイプのバッファで自動的に読み込まれる。

**主要処理フロー**:
1. **1行目**: `nnoremap <silent> ]q ...` - 次のQuickfix項目へジャンプ
2. **2行目**: `nnoremap <silent> [q ...` - 前のQuickfix項目へジャンプ
3. **5行目**: `nnoremap <silent> ]l ...` - 次のLocation List項目へジャンプ
4. **6行目**: `nnoremap <silent> [l ...` - 前のLocation List項目へジャンプ
5. **8行目**: `nnoremap <silent> <buffer> q :cclose<bar>:lclose<CR>` - qで閉じる
6. **11行目**: `setlocal nowrap` - 折り返しなし設定

#### Step 2: ナビゲーション関数を理解する

循環ナビゲーションを実現するユーティリティ関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | util.vim | `core/autoload/spacevim/util.vim` | CycleQuickfix関数の実装 |

**主要処理フロー**:
1. **207-215行目**: `spacevim#util#CycleQuickfix(action, fallback)`
   - try-catchでcnext/cprevを実行
   - 失敗時（リスト末端）はfallback（cfirst/clast）を実行
   - 最後にzzで中央配置

#### Step 3: 自動オープン設定を理解する

QuickFixCmdPost autocmdによる自動オープン設定を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+distributions/spacevim/config.vim` | QuickFixCmdPost autocmd設定 |

**主要処理フロー**:
1. **49-54行目**: `s:OnQuickFixCmdPost()`関数
   - qfウィンドウが開いていない かつ リストに内容がある場合
   - `copen 8`で高さ8行のウィンドウを開く
2. **91行目**: `autocmd QuickFixCmdPost * call s:OnQuickFixCmdPost()`

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

```
Quickfix関連操作
    │
    ├─ ]q / [q キー押下（qf.vim）
    │      │
    │      └─ spacevim#util#CycleQuickfix()
    │             ├─ :cnext / :cprev 実行
    │             ├─ 失敗時 :cfirst / :clast
    │             └─ zz（中央配置）
    │
    ├─ q キー押下（qf.vim）
    │      │
    │      └─ :cclose | :lclose
    │
    └─ QuickFixCmdPost autocmd
           │
           └─ s:OnQuickFixCmdPost()
                  └─ copen 8（条件付き）
```

### データフロー図

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

:make / :grep ──▶ Vim ────────────────▶ Quickfixリスト
                          │
                          └─▶ QuickFixCmdPost autocmd
                                 └─▶ copen 8

]q 押下 ─────────▶ CycleQuickfix() ───▶ 次の項目にジャンプ
                          │
                          └─▶ cnext + zz

Enter 押下 ──────▶ Vim ────────────────▶ 選択項目にジャンプ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| qf.vim | `core/ftplugin/qf.vim` | ソース | Quickfixバッファ固有設定・キーバインド |
| util.vim | `core/autoload/spacevim/util.vim` | ソース | CycleQuickfix関数（循環ナビゲーション） |
| config.vim | `layers/+distributions/spacevim/config.vim` | ソース | QuickFixCmdPost autocmd（自動オープン） |
| 画面一覧.csv | `docs/code-to-docs/画面一覧/画面一覧.csv` | データ | 画面No.17の定義 |
