# 帳票設計書 13-table

## 概要

本ドキュメントは、Nushellの`table`コマンドの設計仕様を定義する帳票設計書である。このコマンドは、データをテーブル形式でターミナルにレンダリング表示する機能を提供する。

### 本帳票の処理概要

`table`コマンドは、Nushellのパイプラインデータ（リスト、レコード、テーブル等）を視覚的に整形されたテーブル形式でターミナルに表示するコマンドである。複数のテーマ、展開モード、折りたたみモードをサポートし、大規模データのページング表示やカラム幅の自動調整機能を備えている。

**業務上の目的・背景**：コマンドラインでのデータ操作において、結果を人間が読みやすい形式で表示することは非常に重要である。`table`コマンドは、構造化データを美しく整形し、色付け、アイコン表示、クリッカブルリンクなどの視覚的な補助機能を提供することで、ユーザーのデータ理解を支援する。Nushellのデフォルト出力形式として、最も頻繁に使用されるコマンドの一つである。

**帳票の利用シーン**：パイプライン結果の確認、ファイル一覧の表示（`ls`出力）、データベースクエリ結果の確認、設定ファイルの内容確認、デバッグ時のデータ構造確認に利用される。

**主要な出力内容**：
1. 整形されたテーブル形式の文字列出力
2. LS_COLORSに基づくファイルパスの色付け
3. ネストされたデータ構造の展開表示
4. バイナリデータの16進ダンプ表示

**帳票の出力タイミング**：パイプライン内で`table`コマンドが実行されたとき、または暗黙的にパイプライン終端で呼び出されたとき、入力データがテーブル形式で出力される。

**帳票の利用者**：すべてのNushellユーザー

## 帳票種別

表示出力（Viewer）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Nushellコマンドライン | - | `table`コマンド実行、またはパイプライン終端 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（ANSI装飾付き） |
| 用紙サイズ | N/A（ターミナル幅に依存） |
| 向き | N/A |
| ファイル名 | N/A（標準出力） |
| 出力方法 | 標準出力（ターミナル表示） |
| 文字コード | UTF-8 |

### テーブル表示固有設定

| 項目 | 内容 |
|-----|------|
| デフォルト幅 | 80カラム（ターミナル幅取得失敗時） |
| サポートテーマ数 | 18種類 |
| ANSI色付け | 設定により有効/無効 |
| アイコン表示 | --iconsオプションで有効化 |

## 帳票レイアウト

### レイアウト概要

テーブルは以下の構造で表示される。

```
┌─────────────────────────────────────┐
│  #  │  column1  │  column2  │ ...  │  <- ヘッダー行
├─────────────────────────────────────┤
│  0  │  value1   │  value2   │ ...  │  <- データ行
│  1  │  value3   │  value4   │ ...  │
│ ... │    ...    │    ...    │ ...  │
└─────────────────────────────────────┘
```

### コマンドオプション

| No | オプション | 短縮形 | 型 | 説明 |
|----|-----------|-------|-----|------|
| 1 | --theme | -t | String | テーブルテーマを指定 |
| 2 | --index | -i | Any | インデックス列の表示制御（true/false/開始番号） |
| 3 | --width | -w | Int | 出力幅（ターミナルカラム数） |
| 4 | --expand | -e | Switch | 展開モード（ネストを展開） |
| 5 | --expand-deep | -d | Int | 展開の最大深度 |
| 6 | --flatten | - | Switch | 配列をフラット化 |
| 7 | --flatten-separator | - | String | フラット化時のセパレータ |
| 8 | --collapse | -c | Switch | 折りたたみモード |
| 9 | --abbreviated | -a | Int | 省略表示（上下N行のみ表示） |
| 10 | --list | -l | Switch | 利用可能テーマ一覧表示 |
| 11 | --icons | -o | Switch | ファイルパスにアイコン表示 |

### サポートテーマ一覧

| No | テーマ名 | 説明 |
|----|---------|------|
| 1 | basic | 基本的な罫線 |
| 2 | compact | コンパクト表示 |
| 3 | compact_double | 二重線コンパクト |
| 4 | default | デフォルトテーマ |
| 5 | heavy | 太罫線 |
| 6 | light | 細罫線 |
| 7 | none | 罫線なし |
| 8 | reinforced | 強調罫線 |
| 9 | rounded | 角丸罫線 |
| 10 | thin | 極細罫線 |
| 11 | with_love | ハート装飾 |
| 12 | psql | PostgreSQL風 |
| 13 | markdown | Markdown形式 |
| 14 | dots | ドット罫線 |
| 15 | restructured | reStructuredText風 |
| 16 | ascii_rounded | ASCII角丸 |
| 17 | basic_compact | 基本コンパクト |
| 18 | single / double | 単線/二重線 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 入力データ | リスト、レコード、テーブル等 | Yes |
| ターミナル幅 | 表示幅の決定に使用 | No（自動検出） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| - | N/A（入力順序を維持） | - |

### 改ページ条件

- `$env.config.table.stream_page_size`で指定された行数ごとにバッチ出力
- `$env.config.table.batch_duration`で指定された時間経過でバッチ出力

## データベース参照仕様

### 参照テーブル一覧

N/A（入力パイプラインデータを表示）

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| カラム幅 | max(各セルの文字幅) | - | Unicode幅で計算 |
| 行数制限 | abbreviated * 2 + 1 | - | 省略表示時 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[table実行] --> B{--list?}
    B -->|Yes| C[テーマ一覧返却]
    B -->|No| D[CmdInput解析]
    D --> E{入力型判定}
    E -->|ByteStream Binary| F[pretty_hex_stream]
    E -->|ByteStream Other| G[そのまま出力]
    E -->|Value::List| H[handle_row_stream]
    E -->|ListStream| H
    E -->|Value::Record| I[handle_record]
    E -->|Value::Range| J[ListStreamに変換]
    E -->|Value::Custom| K[基本型に変換]
    E -->|Value::Error| L[エラー伝播]
    E -->|Other| M[そのまま出力]
    F --> N[出力]
    H --> O[PagingTableCreator]
    O --> P[バッチ処理]
    P --> N
    I --> Q[build_table_kv]
    Q --> N
    J --> H
    K --> A
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 幅不足 | テーブルがターミナル幅に収まらない | "Couldn't fit table into N columns!" | --widthで幅を指定、またはターミナルを拡大 |
| 無効なテーマ | 存在しないテーマ名を指定 | "can't convert string to theme" | --listでテーマ一覧を確認 |
| 無効なインデックス | 負の整数を--indexに指定 | "got a negative integer" | 0以上の整数を指定 |
| 値エラー | 入力にエラー値が含まれる | 元のエラーメッセージ | 入力データを確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 制限なし（ストリーミング対応） |
| ページサイズ | `$env.config.table.stream_page_size`（デフォルト設定依存） |
| バッチ時間 | `$env.config.table.batch_duration` |
| 同時出力数上限 | 1（シングルパイプライン） |

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

- ファイルパスのクリッカブルリンクはSSHセッションでは無効化
- OSC8エスケープシーケンスによるリンク機能は設定で制御可能
- ANSIカラーコードの出力は設定で無効化可能

## 備考

- 'index'という名前のカラムが存在する場合、それがインデックスとして使用される
- バイナリデータは自動的に16進ダンプ形式で表示される
- カスタム値は基本型に変換後、再帰的にtableコマンドで処理される

---

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

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

### 推奨読解順序

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

テーブル設定とビュー種別の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | table.rs | `crates/nu-command/src/viewers/table.rs` | TableConfig構造体（237-246行目） |
| 1-2 | table.rs | `crates/nu-command/src/viewers/table.rs` | TableView enum（270-279行目） |

**読解のコツ**: TableConfigの各フィールドがコマンドオプションに対応している。TableViewの3種類（General, Collapsed, Expanded）がテーブル表示モードを決定する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | table.rs | `crates/nu-command/src/viewers/table.rs` | Table構造体のCommand実装（37-214行目） |

**主要処理フロー**:
1. **54-110行目**: シグネチャ定義（各オプションの宣言）
2. **112-135行目**: run関数（--list判定、CmdInput解析、handle_table_command呼び出し）
3. **137-213行目**: examplesによる使用例定義

#### Step 3: 入力タイプ別処理を理解する

入力データの型に応じた処理分岐を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | table.rs | `crates/nu-command/src/viewers/table.rs` | handle_table_command関数（455-505行目） |

**主要処理フロー**:
- **459-461行目**: バイナリByteStreamの16進ダンプ処理
- **472-478行目**: Value::Listのストリーム処理への変換
- **479-481行目**: ListStreamの処理
- **483-486行目**: Value::Recordの処理
- **492-494行目**: Value::Customの基本型変換

#### Step 4: ストリーム処理を理解する

大規模データのページング処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | table.rs | `crates/nu-command/src/viewers/table.rs` | PagingTableCreator構造体（910-920行目） |
| 4-2 | table.rs | `crates/nu-command/src/viewers/table.rs` | Iterator実装（965-1030行目） |

**主要処理フロー**:
- **972-986行目**: バッチ収集（省略モードまたは通常モード）
- **1019-1021行目**: テーブル構築と行オフセット更新

#### Step 5: テーブル構築を理解する

nu-tableクレートとの連携を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | lib.rs | `crates/nu-table/src/lib.rs` | エクスポートされる型の確認 |

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

```
Table::run (table.rs:112)
    │
    ├─ list_themes判定 → supported_table_modes()
    │
    └─ CmdInput::parse()
           │
           └─ handle_table_command() (table.rs:455)
                  │
                  ├─ ByteStream(Binary) → pretty_hex_stream()
                  │
                  ├─ Value::List → handle_row_stream()
                  │       │
                  │       └─ PagingTableCreator
                  │               │
                  │               ├─ stream_collect() / stream_collect_abbreviated()
                  │               │
                  │               └─ build_table_batch()
                  │                       │
                  │                       ├─ JustTable::table()
                  │                       ├─ ExpandedTable::build_list()
                  │                       └─ CollapsedTable::build()
                  │
                  ├─ Value::Record → handle_record()
                  │       │
                  │       └─ build_table_kv()
                  │               │
                  │               ├─ JustTable::kv_table()
                  │               ├─ ExpandedTable::build_map()
                  │               └─ CollapsedTable::build()
                  │
                  └─ Value::Custom → to_base_value() → 再帰
```

### データフロー図

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

PipelineData ───▶ 型判定
                     │
         ┌──────────┼──────────┐
         ▼          ▼          ▼
     ByteStream   List/     Record
     (Binary)    Stream
         │          │          │
         ▼          ▼          ▼
  pretty_hex   PagingTable  build_
    _stream     Creator     table_kv
         │          │          │
         ▼          ▼          ▼
     16進       バッチ      KVテーブル
     ダンプ      処理        構築
         │          │          │
         └──────────┴──────────┘
                     │
                     ▼
              TableOutput
                     │
                     ▼
           maybe_strip_color()
                     │
                     ▼
                ByteStream ───▶ 標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| table.rs | `crates/nu-command/src/viewers/table.rs` | ソース | tableコマンドの実装 |
| lib.rs | `crates/nu-table/src/lib.rs` | ソース | nu-tableクレートのエントリーポイント |
| table.rs | `crates/nu-table/src/table.rs` | ソース | NuTable構造体の実装 |
| table_theme.rs | `crates/nu-table/src/table_theme.rs` | ソース | テーブルテーマ定義 |
| general.rs | `crates/nu-table/src/types/general.rs` | ソース | JustTable実装 |
| expanded.rs | `crates/nu-table/src/types/expanded.rs` | ソース | ExpandedTable実装 |
| collapse.rs | `crates/nu-table/src/types/collapse.rs` | ソース | CollapsedTable実装 |
| common.rs | `crates/nu-table/src/common.rs` | ソース | 共通ユーティリティ |
| table.rs | `crates/nu-command/tests/commands/table.rs` | テスト | テストケース |
