# 帳票設計書 2-to tsv

## 概要

本ドキュメントは、Nushellの`to tsv`コマンドに関する設計書である。`to tsv`コマンドは、テーブルデータまたはレコードデータをTSV (Tab-Separated Values) 形式のテキストに変換するデータ変換コマンドである。

### 本帳票の処理概要

`to tsv`コマンドは、Nushellのパイプラインで流れてくるテーブルデータやレコードデータを、タブ区切りのTSV形式テキストに変換する。

**業務上の目的・背景**：TSVはCSVと並んで広く使用されているデータ交換フォーマットであり、特にデータ内にカンマが含まれる場合に有用である。スプレッドシートやデータベースツールとの連携、コピー＆ペーストによるデータ転送など、多様な用途に対応する。

**帳票の利用シーン**：
- Excelへのデータ貼り付け
- データベースへのバルクインポート
- テキストエディタでのデータ編集
- 他システムとのデータ連携
- ログデータの整形出力

**主要な出力内容**：
1. ヘッダー行（カラム名、オプションで非表示可能）
2. データ行（各レコードの値をタブ区切りで出力）

**帳票の出力タイミング**：パイプライン処理において`to tsv`コマンドが実行されたとき

**帳票の利用者**：Nushellユーザー、システム管理者、データエンジニア

## 帳票種別

データ変換出力（テキスト形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | Nushell CLI | コマンドライン | `to tsv` コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | TSV (テキスト) |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | パイプラインで`save`コマンドと組み合わせて指定 |
| 出力方法 | 標準出力またはファイル保存 |
| 文字コード | UTF-8 |

### 出力オプション

| オプション | 短縮形 | 説明 | デフォルト値 |
|-----------|--------|------|-------------|
| --noheaders | -n | ヘッダー行を出力しない | false |
| --columns | なし | 出力するカラム名を順序指定で指定 | なし（全カラム） |

## 帳票レイアウト

### レイアウト概要

TSV出力は以下の構造を持つ：

```
┌─────────────────────────────────────┐
│  ヘッダー行（オプション）            │
│  column1<TAB>column2<TAB>column3    │
├─────────────────────────────────────┤
│  データ行                            │
│  value1<TAB>value2<TAB>value3       │
│  value4<TAB>value5<TAB>value6       │
│  ...                                │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | カラム名 | 入力データのカラム名 | Value::Record / Value::List | タブ区切り文字列 |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | データ値 | 各カラムの値 | Value各種 | 文字列変換後の値 | 可変 |

## 出力条件

### 入力条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 入力データ型 | table または record | Yes |

### ソート順

ソート機能は`to tsv`コマンド自体には含まれない。必要に応じて前段で`sort-by`コマンドを使用する。

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

### 参照テーブル一覧

本コマンドはデータベースを直接参照しない。パイプラインから受け取るデータを処理する。

## 計算仕様

### 計算項目一覧

本コマンドには計算処理は含まれない。

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[入力データ受信] --> B[オプション解析]
    B --> C[入力データ型確認]
    C -->|table/record| D[カラム決定]
    C -->|その他| E[UnsupportedInputエラー]
    D --> F{--columns指定?}
    F -->|Yes| G[指定カラムを使用]
    F -->|No| H[全カラムを検出]
    G --> I{--noheaders?}
    H --> I
    I -->|No| J[ヘッダー行出力]
    I -->|Yes| K[データ行出力開始]
    J --> K
    K --> L[各行をTSV形式で出力]
    L --> M[ByteStream返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| UnsupportedInput | table/record以外の入力 | "expected table or record" | 適切なデータ型を入力 |
| CantConvert | 変換不可能な値型 | "only simple values are supported for TSV output" | 単純な値型に変換 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 制限なし（ストリーミング処理） |
| 目標出力時間 | リアルタイムストリーミング |
| 同時出力数上限 | N/A |

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

- 入力データはそのまま出力されるため、センシティブな情報が含まれる場合は注意が必要
- タブ文字のエスケープはCSVライブラリ(csv crate)が処理

## 備考

- content_type メタデータは "text/tab-separated-values" として設定される
- CSVコマンドとは異なり、セパレータは固定（タブ文字）
- 内部的には`to_delimited_data`関数を共通利用している（CSVと共通）

---

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

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

### 推奨読解順序

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

まず、Nushellの値型と変換後のTSV文字列の関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | delimited.rs | `crates/nu-command/src/formats/to/delimited.rs` | ToDelimitedDataArgs構造体でTSV出力の設定を定義（70-78行目） |

**読解のコツ**: CSVとTSVでは同じ構造体を使用し、separatorフィールドのみが異なる。

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

`to tsv`コマンドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tsv.rs | `crates/nu-command/src/formats/to/tsv.rs` | ToTsv構造体とCommandトレイト実装（10-74行目） |

**主要処理フロー**:
1. **17-35行目**: シグネチャ定義（--noheaders, --columnsオプション）
2. **61-73行目**: runメソッドでオプション解析とto_tsv関数呼び出し
3. **76-99行目**: to_tsv関数でセパレータをタブ文字に設定しto_delimited_data呼び出し

#### Step 3: 共通変換ロジックを理解する

CSV/TSV共通の区切り文字データ変換ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | delimited.rs | `crates/nu-command/src/formats/to/delimited.rs` | to_delimited_data関数の実装（80-185行目） |

**主要処理フロー**:
- **109-120行目**: 入力データ型の検証（List/Record/ListStream）
- **124-138行目**: カラム決定ロジック
- **147-182行目**: ByteStreamでのTSV出力生成

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

```
ToTsv::run (tsv.rs:61)
    │
    └─ to_tsv (tsv.rs:76)
           │
           ├─ Spanned { item: '\t' } 設定 (tsv.rs:83-86)
           │
           └─ to_delimited_data (delimited.rs:80)
                  │
                  ├─ 入力データ型検証 (delimited.rs:109-120)
                  │
                  ├─ カラム決定 (delimited.rs:124-138)
                  │      │
                  │      └─ merge_descriptors (nu-cmd-base)
                  │
                  └─ ByteStream生成 (delimited.rs:147-182)
                         │
                         └─ csv::WriterBuilder (外部クレート)
```

### データフロー図

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

Value::List/Record ───▶ ToTsv::run ──────────────────▶ PipelineData::ByteStream
                              │                              │
                              ▼                              ▼
                        to_tsv                         TSV形式文字列
                        (sep='\t')                     "col1\tcol2\n"
                              │                        "val1\tval2\n"
                              ▼
                        to_delimited_data
                              │
                              ▼
                        ByteStream生成
                        (csv crateで変換)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tsv.rs | `crates/nu-command/src/formats/to/tsv.rs` | ソース | to tsvコマンドの実装 |
| delimited.rs | `crates/nu-command/src/formats/to/delimited.rs` | ソース | CSV/TSV共通の変換ロジック |
| mod.rs | `crates/nu-command/src/formats/to/mod.rs` | ソース | toモジュールの公開定義 |
| mod.rs | `crates/nu-cmd-base/src/formats/to/mod.rs` | ソース | merge_descriptors関数 |
