# 画面設計書 6-Tagbar（タグバー）

## 概要

本ドキュメントは、space-vimにおけるTagbar（タグバー）の画面設計について記載する。Tagbarはmajutsushi/tagbarプラグインにより提供されるシンボルビューア画面であり、現在のファイルのシンボル（関数、クラス、変数など）をサイドバーで一覧表示する。

### 本画面の処理概要

**業務上の目的・背景**：開発者がソースコードの構造を把握し、目的の関数やクラスへ素早くジャンプできるようにすることが目的である。大規模なソースファイルでは、スクロールしてコードを探すよりも、Tagbarでシンボル一覧を確認してジャンプする方が効率的である。ctagsをベースとしており、多くのプログラミング言語に対応している。

**画面へのアクセス方法**：以下の方法でTagbar画面にアクセスできる。
- `SPC t t`キーバインド：Tagbarトグル
- `F6`キー：Tagbarトグル
- `:TagbarToggle`コマンド

**主要な操作・処理内容**：
1. シンボル一覧のツリー表示
2. シンボルを選択してコード内の定義位置へジャンプ（`Enter`キー）
3. シンボルのプレビュー（`p`キー）
4. シンボルの折りたたみ/展開（`o`キー）
5. シンボルのソート順切替（`s`キー）
6. Tagbarウィンドウを閉じる（`q`キー）

**画面遷移**：
- エディタ画面 -> `SPC t t` -> Tagbar画面（サイドバー）
- Tagbar画面 -> シンボル選択 -> エディタ画面（シンボル定義位置）
- Tagbar画面 -> `q` -> エディタ画面（Tagbar閉じる）

**権限による表示制御**：特になし。ファイルタイプに応じたシンボル解析が行われる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 66 | タグ管理 | 主機能 | 現在のファイルのシンボル（関数、クラス、変数など）をサイドバー表示 |
| 20 | トグル操作(SPC t) | 補助機能 | SPC t tまたはF6でTagbarのトグル |
| 68 | ctags | 補助機能 | vim-gutentagsによる自動タグ生成との連携 |

## 画面種別

サイドバー / シンボルビュー

## URL/ルーティング

- トグルコマンド: `:TagbarToggle`
- キーバインド: `SPC t t`、`F6`

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 |
|--------|----------|---------|------|
| g:tagbar_sort | 入力（設定） | Number | ソート順（0=定義順） |
| g:tagbar_autofocus | 入力（設定） | Number | 開いた時に自動フォーカス（1） |
| 現在のバッファ | 入力 | Buffer | シンボル解析対象のバッファ |
| シンボル一覧 | 出力 | List | 解析されたシンボルのツリー |
| 選択シンボル位置 | 出力 | Number | ジャンプ先の行番号 |

## 表示項目

| 項目 | 表示内容 | 説明 |
|-----|---------|------|
| シンボルタイプ | function/class/variable等 | シンボルの種類 |
| シンボル名 | 関数名/クラス名/変数名 | シンボルの識別子 |
| スコープ | public/private/protected等 | 可視性（対応言語のみ） |
| 行番号 | 定義位置 | シンボルが定義されている行 |

## イベント仕様

### 1-TagbarToggle

`SPC t t`または`F6`押下時、`:TagbarToggle`コマンドが実行され、Tagbarサイドバーの表示/非表示を切り替える。

### 2-シンボルジャンプ

Tagbar内でシンボルを選択（`Enter`）すると、選択されたシンボルの定義位置にカーソルがジャンプする。

### 3-シンボルプレビュー

`p`キーでシンボルの定義位置をプレビュー表示する。カーソルはTagbar内に留まる。

### 4-自動更新

バッファを切り替えると、Tagbarは自動的に新しいバッファのシンボルを解析・表示する。

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

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

該当なし（シンボル解析のみ）

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|---------|
| エラー | Tagbar: Exuberant ctags not found | ctagsが未インストール時 |
| 情報 | Tagbar: No tags found | シンボルが見つからない時 |

## 例外処理

| 状態 | 処理 |
|------|------|
| ctagsが未インストール | エラーメッセージを表示 |
| 対応していないファイルタイプ | 空のTagbarを表示 |
| タグ生成に失敗 | エラーメッセージを表示 |

## 備考

- Tagbarプラグインは`majutsushi/tagbar`により提供される
- Universal Ctags（Exuberant Ctagsの後継）が推奨される
- `g:tagbar_sort = 0`でシンボルを定義順に表示（デフォルトはアルファベット順）
- `g:tagbar_autofocus = 1`でTagbarを開いた時に自動的にフォーカス
- 遅延読み込み（on-demand loading）が有効
- Vistaプラグインが代替として利用可能（LSPベース）

---

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

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

### 推奨読解順序

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

Tagbarの設定データ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.vim | `layers/+programming/programming/config.vim` | Tagbarの設定変数を確認 |

**読解のコツ**: `g:tagbar_*`で始まる設定変数がTagbarの動作を制御している。

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

プラグインのロードとキーマッピングの設定を理解する。

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

**主要処理フロー**:
1. **packages.vim 25行目**: Tagbarプラグインの遅延読み込み登録
2. **config.vim 68行目**: `g:tagbar_sort = 0`で定義順ソート設定
3. **config.vim 69行目**: `g:tagbar_autofocus = 1`で自動フォーカス設定
4. **config.vim 70-72行目**: F6とSPC t tのキーマッピング

#### Step 3: 関連プラグインを理解する

Vistaやgutentagsとの関係を理解する。

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

**主要処理フロー**:
- **27行目**: vista.vimプラグインの登録（Tagbarの代替）

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

```
<Leader>tt または F6 (nnoremap)
    │
    └─ :TagbarToggle コマンド
           │
           ├─ Tagbarプラグインロード（初回のみ）
           │
           └─ Tagbarサイドバー表示
                  │
                  ├─ ctags実行
                  │      │
                  │      └─ シンボル解析
                  │
                  └─ シンボル一覧表示
                         │
                         └─ [シンボル選択]
                                │
                                └─ 定義位置へジャンプ
```

### データフロー図

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

SPC t t / F6 ─────────▶ config.vim ───────────────▶ TagbarToggle
キー押下                  (キーマッピング)

現在のバッファ ───────▶ ctags ────────────────────▶ タグファイル生成
                        (シンボル解析)

タグファイル ─────────▶ tagbar.vim ───────────────▶ シンボル一覧表示
                        (解析・表示)

シンボル選択 ─────────▶ tagbar.vim ───────────────▶ 定義位置ジャンプ
                        (ジャンプ処理)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| packages.vim | `layers/+programming/programming/packages.vim` | ソース | プラグイン登録 |
| config.vim | `layers/+programming/programming/config.vim` | ソース | 設定・キーマッピング |
| tagbar | 外部プラグイン（majutsushi/tagbar） | プラグイン | Tagbar本体機能 |
| vista.vim | 外部プラグイン（liuchengxu/vista.vim） | プラグイン | LSPベースの代替 |
