# 帳票設計書 1-to csv

## 概要

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

### 本帳票の処理概要

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

**業務上の目的・背景**：CSVは最も広く使用されているデータ交換フォーマットの一つであり、Excelやデータベース、他のプログラミング言語との相互運用性を確保するために必要不可欠である。シェル環境でのデータ処理結果を外部システムやツールで利用可能な形式に変換する需要に応える。

**帳票の利用シーン**：
- データベースクエリ結果のエクスポート
- ログデータの整形と出力
- 設定ファイルの生成
- 他のシステムとのデータ連携
- レポート生成時のデータ出力

**主要な出力内容**：
1. ヘッダー行（カラム名、オプションで非表示可能）
2. データ行（各レコードの値をカンマ区切りで出力）
3. カスタムセパレータ対応（デフォルトはカンマ）

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

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

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

### 出力オプション

| オプション | 短縮形 | 説明 | デフォルト値 |
|-----------|--------|------|-------------|
| --separator | -s | 列区切り文字を指定 | ',' (カンマ) |
| --noheaders | -n | ヘッダー行を出力しない | false |
| --columns | なし | 出力するカラム名を順序指定で指定 | なし（全カラム） |

## 帳票レイアウト

### レイアウト概要

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

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

### ヘッダー部

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

### 明細部

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

## 出力条件

### 入力条件

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

### ソート順

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

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

### 参照テーブル一覧

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

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| セパレータ検証 | 入力文字が1文字かつASCIIか検証 | N/A | 複数文字の場合はエラー |

## 処理フロー

### 出力フロー

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| TypeMismatch | セパレータが1文字でない | "Expected a single separator char from --separator" | 1文字のセパレータを指定 |
| UnsupportedInput | table/record以外の入力 | "expected table or record" | 適切なデータ型を入力 |
| CantConvert | 変換不可能な値型 | "only simple values are supported for CSV output" | 単純な値型に変換 |
| IncorrectValue | セパレータが非ASCII | "separator must be an ASCII character" | ASCII文字を使用 |

## パフォーマンス要件

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

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

- 入力データはそのまま出力されるため、センシティブな情報が含まれる場合は注意が必要
- CSVインジェクション攻撃への対策として、特殊文字のエスケープはCSVライブラリ(csv crate)が処理

## 備考

- content_type メタデータは "text/csv" として設定される
- `\t`を指定するとタブ文字がセパレータとして使用される
- 内部的には`to_delimited_data`関数を共通利用している（TSVと共通）

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: RustのStructを確認し、各フィールドが何を設定するか把握する。

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

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

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

**主要処理フロー**:
1. **17-41行目**: シグネチャ定義（--separator, --noheaders, --columnsオプション）
2. **72-85行目**: runメソッドでオプション解析とto_csv関数呼び出し
3. **88-133行目**: to_csv関数でセパレータ検証とto_delimited_data呼び出し

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

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

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

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

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

```
ToCsv::run (csv.rs:72)
    │
    └─ to_csv (csv.rs:88)
           │
           ├─ セパレータ検証 (csv.rs:96-119)
           │
           └─ 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 ───▶ ToCsv::run ──────────────────▶ PipelineData::ByteStream
                              │                              │
                              ▼                              ▼
                        to_csv                         CSV形式文字列
                              │                        "col1,col2\n"
                              ▼                        "val1,val2\n"
                        to_delimited_data
                              │
                              ▼
                        ByteStream生成
                        (csv crateで変換)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| csv.rs | `crates/nu-command/src/formats/to/csv.rs` | ソース | to csvコマンドの実装 |
| 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関数 |
