# 機能設計書 71-探索モード

## 概要

本ドキュメントは、Nushellの探索モード（explore）機能の設計仕様を定義する。exploreコマンドは、構造化データをインタラクティブに探索するためのページャー機能を提供する。

### 本機能の処理概要

exploreコマンドは、パイプラインから受け取ったデータ（テーブル、レコード、リスト、バイナリデータなど）をターミナル上でインタラクティブに表示・操作するための機能である。`less`コマンドに似たページャー機能を提供し、大量のデータを効率的に閲覧・操作できる。

**業務上の目的・背景**：大規模なテーブルデータやネストされた構造化データを扱う際、単純なパイプライン出力では全体像を把握しにくい。探索モードを使用することで、データをスクロール、検索、フィルタリングしながらインタラクティブに分析できる。これにより、データ分析やデバッグ作業の効率が大幅に向上する。

**機能の利用シーン**：
- 大量のログデータやCSVファイルの内容を確認する場合
- ネストされたJSONデータの構造を理解する場合
- テーブルデータから特定の行や列を選択して値を取得する場合
- バイナリファイルの内容をHex形式で確認する場合

**主要な処理内容**：
1. パイプラインデータの受け取りと種別判定（テーブル、レコード、バイナリ等）
2. ターミナルを代替スクリーンモードに切り替え
3. データの種類に応じたView（RecordView、BinaryView、Preview等）の生成
4. ユーザー入力（カーソル移動、検索、コマンド入力）の処理
5. 画面のリアルタイムレンダリング（ratatuiライブラリ使用）
6. 終了時の値出力（peekモード使用時）

**関連システム・外部連携**：
- ratatuiライブラリ：ターミナルUIのレンダリング
- crosstermライブラリ：ターミナル制御（raw mode、代替スクリーン）
- nu-tableクレート：テーブル表示の書式設定

**権限による制御**：特になし。ターミナル操作権限のみ必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | レコードビュー | 主画面 | テーブル・レコードデータのインタラクティブ表示とナビゲーション |
| 5 | バイナリビュー | 主画面 | バイナリデータのHex dump形式表示 |
| 6 | プレビュー | 主画面 | テキストデータ・文字列値のプレビュー表示 |
| 7 | Tryビュー | 参照画面 | インタラクティブなコマンド入力・実行環境 |
| 8 | Nuコマンドビュー | 参照画面 | Nuコマンドのバックグラウンド実行と結果表示 |
| 9 | ヘルプ画面 | 参照画面 | Exploreのヘルプ情報表示 |

## 機能種別

データ探索・ビューア機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --head | Boolean | No | カラムヘッダーの表示/非表示（デフォルト: true） | true/false |
| --index (-i) | switch | No | リスト表示時に行インデックスを表示 | - |
| --tail (-t) | switch | No | ビューポートを末尾にスクロールして開始 | - |
| --peek (-p) | switch | No | 終了時にカーソル位置のセル値を出力 | - |

### 入力データソース

パイプライン入力から任意の型のデータを受け取る。主な対応型:
- Record: レコード形式のデータ
- List: リスト形式のデータ
- Table: テーブル形式のデータ
- Binary: バイナリデータ
- ByteStream: バイトストリーム

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| value | Any | peekモード時: カーソル位置のセル値、通常時: 空値 |

### 出力先

標準出力（ターミナル画面）およびパイプライン出力（peekモード使用時）

## 処理フロー

### 処理シーケンス

```
1. コマンド引数の解析
   └─ フラグ（head, index, tail, peek）の取得

2. 設定の構築
   └─ ExploreConfig, PagerConfigの生成
   └─ スタイル設定の取得

3. 入力データの種別判定
   └─ バイナリ: BinaryView生成
   └─ 空入力: ヘルプView表示
   └─ 単純値: Preview生成
   └─ テーブル/レコード: RecordView生成

4. Pagerの初期化と実行
   └─ raw modeの有効化
   └─ 代替スクリーンへの切り替え
   └─ イベントループの開始

5. ユーザー操作の処理
   └─ キー入力の監視
   └─ 画面の再描画
   └─ コマンド実行

6. 終了処理
   └─ raw modeの無効化
   └─ 通常スクリーンへの復帰
   └─ peek値の出力（該当時）
```

### フローチャート

```mermaid
flowchart TD
    A[explore コマンド開始] --> B{入力データの種別判定}
    B -->|バイナリ| C[BinaryView 生成]
    B -->|空入力| D[ヘルプView 表示]
    B -->|単純値| E[Preview 生成]
    B -->|テーブル/レコード| F[RecordView 生成]

    C --> G[Pager 初期化]
    D --> G
    E --> G
    F --> G

    G --> H[raw mode 有効化]
    H --> I[代替スクリーン切替]
    I --> J[イベントループ]

    J --> K{ユーザー入力}
    K -->|移動| L[カーソル移動処理]
    K -->|検索| M[検索処理]
    K -->|コマンド| N[内部コマンド実行]
    K -->|終了| O[終了処理]

    L --> P[画面再描画]
    M --> P
    N --> P
    P --> J

    O --> Q[raw mode 無効化]
    Q --> R{peek モード?}
    R -->|Yes| S[カーソル位置の値を出力]
    R -->|No| T[空値を出力]
    S --> U[終了]
    T --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-71-1 | 入力判定 | バイナリデータはBinaryViewで表示 | 入力がBinaryまたはByteStreamの場合 |
| BR-71-2 | 空入力 | 空入力時はヘルプ画面を表示 | カラムとデータが両方空の場合 |
| BR-71-3 | peek出力 | peekフラグ設定時のみカーソル位置の値を出力 | --peekフラグが指定された場合 |
| BR-71-4 | tailモード | tail指定時は末尾からスクロール | --tailフラグが指定された場合 |

### 計算ロジック

ページサイズの計算:
```
page_size = 画面高さ - 3 (ステータスバー) - 3 (ヘッダー表示時)
```

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

該当なし（本機能はデータベースを使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | GenericError | ターミナル初期化失敗 | エラーメッセージを含むValue::errorを返却 |
| - | GenericError | 内部コマンド実行失敗 | ステータスバーにエラーを表示 |

### リトライ仕様

リトライは行わない。エラー発生時はターミナルを元の状態に戻して終了する。

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

該当なし

## パフォーマンス要件

- 画面リフレッシュレート: 約4回/秒（250ms間隔）
- 大規模データでもスムーズなスクロールを実現するため、遅延評価とウィンドウ表示を採用

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

- ターミナル制御のためraw modeを使用するが、終了時に必ず元の状態に復帰
- 入力データはメモリ上で処理され、ファイルへの書き込みは行わない

## 備考

- 内部コマンド（:help, :quit, :expand, :try, :nu, :table）でビューの切り替えが可能
- viライクなキーバインド（h,j,k,l）をサポート
- `/`または`?`で検索モードに入り、`n`/`N`で次/前の検索結果に移動

---

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

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

### 推奨読解順序

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

まず、Pagerの設定とViewの基本構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config.rs | `crates/nu-explore/src/explore/config.rs` | ExploreConfigの構造（テーブル設定、スタイル設定） |
| 1-2 | mod.rs (views) | `crates/nu-explore/src/explore/views/mod.rs` | Viewトレイトの定義と各Viewの役割 |

**読解のコツ**: ExploreConfigはNushell設定ファイルの`$env.config.explore`から構築される。Viewトレイトの`draw`、`handle_input`、`exit`メソッドが中核。

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

処理の起点となるExploreコマンドの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | command.rs | `crates/nu-explore/src/explore/command.rs` | Exploreコマンドの引数定義とrunメソッド |

**主要処理フロー**:
1. **61-64行目**: フラグ（head, index, tail, peek）の取得
2. **66-72行目**: 設定とスタイルの構築
3. **79-87行目**: PagerConfigの生成
4. **89行目**: run_pager関数の呼び出し

#### Step 3: Pager処理層を理解する

入力データの種別判定とPagerの実行。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | mod.rs | `crates/nu-explore/src/explore/mod.rs` | run_pager関数でのデータ種別判定 |
| 3-2 | pager/mod.rs | `crates/nu-explore/src/explore/pager/mod.rs` | Pager構造体とイベントループ |

**主要処理フロー**:
- **37-48行目** (mod.rs): バイナリデータの判定とBinaryView生成
- **50-66行目** (mod.rs): テーブル/レコードデータのRecordView生成
- **90-129行目** (pager/mod.rs): Pager::run - ターミナル初期化とUIレンダリング
- **183-290行目** (pager/mod.rs): render_ui - イベントループのメイン処理

#### Step 4: View実装を理解する

RecordViewの詳細実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | views/record/mod.rs | `crates/nu-explore/src/explore/views/record/mod.rs` | RecordViewの状態管理とレンダリング |

**主要処理フロー**:
- **28-37行目**: RecordView構造体の定義（layer_stack、mode、orientation等）
- **188-233行目**: View::draw - テーブルウィジェットの描画
- **235-285行目**: View::handle_input - キー入力処理
- **484-570行目**: CursorMoveHandlerトレイトの実装

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

```
Explore::run (command.rs)
    │
    ├─ run_pager (mod.rs)
    │      │
    │      ├─ binary_view / create_record_view / help_view
    │      │
    │      └─ Pager::run (pager/mod.rs)
    │             │
    │             ├─ enable_raw_mode / EnterAlternateScreen
    │             │
    │             └─ render_ui
    │                    │
    │                    ├─ View::draw (各種View)
    │                    │      └─ TableWidget::render (table_widget.rs)
    │                    │
    │                    ├─ handle_events
    │                    │      └─ View::handle_input
    │                    │
    │                    └─ draw_info (status_bar, cmd_bar)
    │
    └─ 終了時: disable_raw_mode / LeaveAlternateScreen
```

### データフロー図

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

PipelineData ───▶ run_pager ───▶ Pager::run ───▶ PipelineData
  │                   │              │                │
  │                   ▼              ▼                │
  │              View生成       イベントループ        │
  │              - RecordView   - キー入力監視        │
  │              - BinaryView   - 画面描画            │
  │              - Preview      - コマンド実行        │
  │                                                   │
  └──────────── peek_value (--peek時) ────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lib.rs | `crates/nu-explore/src/lib.rs` | ソース | クレートのエントリーポイント |
| command.rs | `crates/nu-explore/src/explore/command.rs` | ソース | Exploreコマンド定義 |
| mod.rs | `crates/nu-explore/src/explore/mod.rs` | ソース | run_pager関数、View生成 |
| config.rs | `crates/nu-explore/src/explore/config.rs` | ソース | ExploreConfig構造体 |
| pager/mod.rs | `crates/nu-explore/src/explore/pager/mod.rs` | ソース | Pager構造体、イベントループ |
| pager/events.rs | `crates/nu-explore/src/explore/pager/events.rs` | ソース | UIイベント処理 |
| pager/status_bar.rs | `crates/nu-explore/src/explore/pager/status_bar.rs` | ソース | ステータスバーウィジェット |
| pager/command_bar.rs | `crates/nu-explore/src/explore/pager/command_bar.rs` | ソース | コマンドバーウィジェット |
| views/mod.rs | `crates/nu-explore/src/explore/views/mod.rs` | ソース | Viewトレイト定義 |
| views/record/mod.rs | `crates/nu-explore/src/explore/views/record/mod.rs` | ソース | RecordView実装 |
| views/record/table_widget.rs | `crates/nu-explore/src/explore/views/record/table_widget.rs` | ソース | テーブルウィジェット |
| views/binary/mod.rs | `crates/nu-explore/src/explore/views/binary/mod.rs` | ソース | BinaryView実装 |
| views/preview.rs | `crates/nu-explore/src/explore/views/preview.rs` | ソース | Preview実装 |
| views/try.rs | `crates/nu-explore/src/explore/views/try.rs` | ソース | TryView実装 |
| commands/mod.rs | `crates/nu-explore/src/explore/commands/mod.rs` | ソース | 内部コマンド定義 |
| commands/help.rs | `crates/nu-explore/src/explore/commands/help.rs` | ソース | :helpコマンド |
| registry/mod.rs | `crates/nu-explore/src/explore/registry/mod.rs` | ソース | コマンドレジストリ |
