# 機能設計書 69-テーブル表示

## 概要

本ドキュメントは、Nushell におけるテーブル表示機能（nu-table クレート）の設計を記述する。構造化データをターミナル上で視覚的に分かりやすいテーブル形式で表示する。

### 本機能の処理概要

テーブル表示機能は、Nushell の構造化データ（レコード、リスト、テーブル）をターミナルの幅に合わせてフォーマットし、罫線や色付けを行って表示する。複数のテーマ、展開表示、折り畳み表示などをサポートする。

**業務上の目的・背景**：CLIツールにおいてデータを視覚的に分かりやすく表示することは、ユーザビリティの観点で重要である。本機能により、複雑なデータ構造も一目で把握できるようになる。

**機能の利用シーン**：
- コマンド出力のテーブル形式表示
- データの視覚的な確認・分析
- レポート形式でのデータ出力
- ネストしたデータの展開表示
- ターミナル幅に応じた自動調整

**主要な処理内容**：
1. `NuTable` - テーブルデータ構造の構築
2. `TableTheme` - テーブルの外観テーマ
3. `ExpandedTable` - 展開表示（table -e）
4. `CollapsedTable` - 折り畳み表示
5. `JustTable` - 標準テーブル表示

**関連システム・外部連携**：tabled クレートによるテーブルレンダリング。

**権限による制御**：特別な権限制御はなく、すべてのユーザーが使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | テーブル表示 | 主機能 | テーブル形式でのデータ表示 |

## 機能種別

データ表示 / レンダリング

## 入力仕様

### 入力パラメータ

#### NuTable

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| count_rows | usize | Yes | 行数 | - |
| count_cols | usize | Yes | 列数 | - |

#### TableOpts

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| config | Config | Yes | Nushell設定 | - |
| style_computer | StyleComputer | Yes | スタイル計算 | - |
| span | Span | Yes | スパン情報 | - |
| width | usize | Yes | ターミナル幅 | - |
| mode | TableMode | Yes | テーブルモード | - |
| index_offset | usize | Yes | インデックスオフセット | - |
| index_remove | bool | Yes | インデックス削除フラグ | - |

### 入力データソース

- **構造化データ**: Value（Record, List, Table）
- **設定**: Config（テーマ、インデント、トリム戦略）

## 出力仕様

### 出力データ

| 出力 | 型 | 説明 |
|------|-----|------|
| draw() | Option<String> | レンダリングされたテーブル文字列 |
| total_width() | usize | テーブルの総幅 |
| TableOutput | struct | テーブル構造と属性 |

### 出力先

ターミナル出力（標準出力）。

## 処理フロー

### 処理シーケンス

```
1. テーブル構造の構築
   └─ NuTable::new() で空テーブル作成
   └─ insert() / insert_value() でセル追加

2. スタイル設定
   └─ set_theme() でテーマ設定
   └─ set_header_style() / set_data_style() でスタイル設定
   └─ set_indent() でパディング設定

3. 幅調整
   └─ table_truncate() でターミナル幅に合わせて調整
   └─ 列の切り詰め/省略

4. レンダリング
   └─ draw() で文字列に変換
   └─ tabled クレートによるテーブル構築
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[NuTable構築]
    B --> C[データ挿入]
    C --> D[スタイル設定]
    D --> E{幅調整が必要?}
    E -->|Yes| F[列切り詰め]
    E -->|No| G[そのまま]
    F --> H[トレイル列追加]
    G --> I[テーブル構築]
    H --> I
    I --> J[テーマ適用]
    J --> K[罫線描画]
    K --> L[文字列生成]
    L --> M[Option<String>返却]
    M --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 幅調整 | ターミナル幅を超える場合は列を切り詰め | draw() |
| BR-002 | トレイル列 | 省略された列は "..." で表示 | 列切り詰め時 |
| BR-003 | トリム戦略 | wrap または truncate で内容を調整 | セル内容が長い場合 |
| BR-004 | ヘッダー位置 | header_on_border で罫線上にヘッダー表示可能 | 設定時 |
| BR-005 | フッター | with_footer でヘッダーをフッターにも複製 | 設定時 |

### 計算ロジック

- **幅計算**: `get_total_width2()` で罫線を含む総幅を計算
- **列切り詰め**: `truncate_columns_by_content()` または `truncate_columns_by_columns()` で実行
- **幅閾値**: ターミナル幅120未満は内容優先、120以上は列数優先

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| None返却 | 表示不可 | テーブルがターミナルに収まらない | 幅を広げるか列を減らす |

### リトライ仕様

リトライは不要。

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

本機能はトランザクション管理を行わない。

## パフォーマンス要件

- 幅計算はキャッシュされる
- 大量行のテーブルでもストリーミング処理で効率的
- tabled クレートによる最適化されたレンダリング

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

- 特別なセキュリティ考慮事項なし

## 備考

- 17種類のテーマをサポート（basic, thin, light, psql, markdown, dots など）
- ANSI エスケープシーケンスによる色付け対応
- Unicode 文字幅の正確な計算

---

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

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

### 推奨読解順序

#### Step 1: ライブラリ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lib.rs | `crates/nu-table/src/lib.rs` | エクスポート一覧 |

**主要処理フロー**:
- **11-17行目**: 公開型のエクスポート（NuTable, TableTheme, ExpandedTable 等）

#### Step 2: NuTable 構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | table.rs | `crates/nu-table/src/table.rs` | NuTable 実装 |

**主要処理フロー**:
- **46-55行目**: NuTable 構造体定義（data, widths, heights, styles, config）
- **57-85行目**: new() コンストラクタ（デフォルト設定）
- **101-117行目**: insert(), insert_value() でセル追加
- **189-203行目**: insert_style() でスタイル設定
- **252-266行目**: set_theme(), set_trim(), set_strategy()
- **295-297行目**: draw() でレンダリング
- **420-430行目**: build_table() メイン処理
- **463-483行目**: table_truncate() で幅調整
- **536-557行目**: draw_table() 最終レンダリング
- **828-1009行目**: truncate_columns_by_content() 列切り詰め

#### Step 3: テーマを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | table_theme.rs | `crates/nu-table/src/table_theme.rs` | TableTheme 実装 |

**主要処理フロー**:
- **7-10行目**: TableTheme 構造体（base, full）
- **20-22行目**: basic() - ASCII テーマ
- **24-26行目**: thin() - モダンテーマ
- **35-37行目**: psql() - PostgreSQL スタイル
- **39-41行目**: markdown() - Markdown テーブル
- **114-122行目**: rounded() - 角丸テーマ
- **178-180行目**: none() - 罫線なし

#### Step 4: 表示タイプを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | types/mod.rs | `crates/nu-table/src/types/mod.rs` | TableOutput, TableOpts |
| 4-2 | types/expanded.rs | `crates/nu-table/src/types/expanded.rs` | ExpandedTable 実装 |

**主要処理フロー（mod.rs）**:
- **14-24行目**: TableOutput 構造体
- **41-51行目**: TableOpts 構造体
- **80-88行目**: has_index() でインデックス有無判定

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

```
NuTable
    │
    ├─ new() - テーブル作成
    │
    ├─ insert() / insert_value() - データ追加
    │
    ├─ set_theme() - テーマ設定
    │      └─ TableTheme::basic() / thin() / rounded() 等
    │
    ├─ set_*_style() - スタイル設定
    │
    └─ draw() - レンダリング
           └─ build_table()
                  └─ table_truncate()
                         └─ maybe_truncate_columns()
                  └─ remove_header_if()
                  └─ table_insert_footer_if()
                  └─ draw_table()
                         └─ Builder::from_vec().build()
                         └─ load_theme()
                         └─ truncate_table()
                         └─ table.to_string()
```

### データフロー図

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

Vec<Vec<Text>> ───────▶ NuTable ─────────────────────────▶ String
                              │
                              ├─ 幅計算
                              │
                              ├─ 列切り詰め
                              │      └─ truncate_columns_by_content()
                              │      └─ truncate_columns_by_columns()
                              │
                              ├─ テーマ適用
                              │      └─ TableTheme
                              │
                              └─ tabled でレンダリング
                                     └─ Table::to_string()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lib.rs | `crates/nu-table/src/lib.rs` | ソース | ライブラリエントリ |
| table.rs | `crates/nu-table/src/table.rs` | ソース | NuTable 実装 |
| table_theme.rs | `crates/nu-table/src/table_theme.rs` | ソース | テーマ定義 |
| types/mod.rs | `crates/nu-table/src/types/mod.rs` | ソース | TableOutput, TableOpts |
| types/expanded.rs | `crates/nu-table/src/types/expanded.rs` | ソース | ExpandedTable 実装 |
| types/collapse.rs | `crates/nu-table/src/types/collapse.rs` | ソース | CollapsedTable 実装 |
| types/general.rs | `crates/nu-table/src/types/general.rs` | ソース | JustTable 実装 |
| common.rs | `crates/nu-table/src/common.rs` | ソース | 共通ユーティリティ |
| util.rs | `crates/nu-table/src/util.rs` | ソース | ユーティリティ関数 |
