# 帳票設計書 9-to text

## 概要

本ドキュメントは、Nushellの`to text`コマンドに関する設計書である。`to text`コマンドは、任意のNushellデータをプレーンテキスト形式に変換するデータ変換コマンドである。

### 本帳票の処理概要

`to text`コマンドは、Nushellのあらゆるデータ型を人間が読みやすいプレーンテキスト形式に変換する。リストの各要素は改行で区切られ、レコードはキー・バリュー形式で表示される。ストリーミング処理に対応しており、大量のデータも効率的に処理できる。

**業務上の目的・背景**：シェル環境では最終的にテキスト出力が必要になることが多い。パイプラインの最終段階でデータを人間が読める形式に変換したり、他のテキストベースのコマンドに渡したりする需要に応える。

**帳票の利用シーン**：
- パイプラインの最終出力としてのテキスト変換
- ログファイルへの出力
- 他のシェルコマンドへのパイプ渡し
- 単純なテキストレポートの生成
- データの可読性向上

**主要な出力内容**：
1. 各値の文字列表現
2. リスト要素の改行区切り出力
3. レコードのキー:値形式出力

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

**帳票の利用者**：Nushellユーザー、システム管理者

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

### 出力オプション

| オプション | 短縮形 | 説明 | デフォルト値 |
|-----------|--------|------|-------------|
| --no-newline | -n | 末尾の改行を追加しない | false |
| --serialize | -s | デシリアライズ不可能なNushell型をシリアライズ | false |

### 改行文字

| OS | 改行文字 |
|---|---------|
| Windows | \r\n (CRLF) |
| その他 | \n (LF) |

## 帳票レイアウト

### レイアウト概要

テキスト出力は入力データに応じた形式を持つ：

#### リスト形式
```
value1
value2
value3
```

#### レコード形式
```
key1: value1
key2: value2
```

#### ネストしたリスト
```
inner1, inner2
outer2
```

### 型変換マッピング

| No | Nushell型 | テキスト出力 | 備考 |
|----|-----------|-------------|------|
| 1 | Bool | "true" / "false" | to_string() |
| 2 | Int | 数値文字列 | to_string() |
| 3 | Float | 数値文字列 | ObviousFloat使用 |
| 4 | String | そのまま | 変換なし |
| 5 | Glob | そのまま | 変換なし |
| 6 | Date | RFC2822/3339 + HumanTime | 人間可読形式 |
| 7 | Duration | format_duration | 人間可読形式 |
| 8 | Filesize | to_string() | サイズ文字列 |
| 9 | Range | to_string() | 範囲表現 |
| 10 | Nothing | 空文字列 | "" |
| 11 | List | 要素をセパレータで結合 | デフォルト改行 |
| 12 | Record | "key: value"形式 | セパレータ区切り |
| 13 | Binary | デバッグ形式 | "{:?}" |
| 14 | CellPath | to_string() | パス表現 |
| 15 | Closure | ブロック内容（--serialize時）またはclosure_id | 条件分岐 |
| 16 | Error | デバッグ形式 | "{:?}" |
| 17 | Custom | to_base_valueで変換 | 再帰処理 |

## 出力条件

### 入力条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| 入力データ型 | Any（任意の型） | Yes |

### 末尾改行の条件

| 条件 | 末尾改行 |
|------|---------|
| --no-newline指定 | なし |
| Empty入力 | なし |
| 単一値 | なし（リスト/レコードが空でない場合のみあり） |
| リスト（要素あり） | あり |
| レコード（要素あり） | あり |

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

### 参照テーブル一覧

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

## 計算仕様

### 計算項目一覧

| 項目名 | 処理 | 備考 |
|-------|------|------|
| Date変換 | RFC2822/RFC3339 + HumanTime | 年が0-9999の範囲外でRFC3339 |
| Float変換 | ObviousFloat | 小数点表示を明確化 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[入力データ受信] --> B[オプション解析]
    B --> C{入力タイプ判定}
    C -->|Empty| D[空文字列返却]
    C -->|Value| E[local_into_string変換]
    C -->|ListStream| F[ストリーミング処理]
    C -->|ByteStream| G[そのまま通過]
    E --> H{末尾改行追加?}
    H -->|Yes| I[改行追加]
    H -->|No| J[そのまま]
    I --> K[メタデータ付与]
    J --> K
    F --> L[ByteStream生成]
    L --> K
    G --> K
    D --> K
    K --> M[PipelineData返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| IoError | ByteStream書き込み失敗 | I/Oエラーメッセージ | I/O問題を解決 |

## パフォーマンス要件

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

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

- 入力データはそのまま出力されるため、センシティブな情報が含まれる場合は注意が必要
- エスケープ処理は行われない（プレーンテキスト出力のため）

## 備考

- content_type メタデータは "text/plain" として設定される
- ListStreamはByteStreamに変換されてストリーミング出力
- chrono_humanizeクレートを使用して日時を人間可読形式で表示

---

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

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

### 推奨読解順序

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

まず、各Value型からテキストへの変換ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | text.rs | `crates/nu-command/src/formats/to/text.rs` | LINE_ENDING定数（8-12行目） |
| 1-2 | text.rs | `crates/nu-command/src/formats/to/text.rs` | local_into_string関数（158-231行目） |

**読解のコツ**: LINE_ENDINGがOS依存で切り替わることと、各Value型のmatch分岐を確認する。

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

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

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

**主要処理フロー**:
1. **22-36行目**: シグネチャ定義（--no-newline, --serializeオプション）
2. **42-129行目**: runメソッドで入力タイプ別処理

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

各PipelineDataタイプの処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | text.rs | `crates/nu-command/src/formats/to/text.rs` | Empty処理（55-56行目） |
| 3-2 | text.rs | `crates/nu-command/src/formats/to/text.rs` | Value処理（57-72行目） |
| 3-3 | text.rs | `crates/nu-command/src/formats/to/text.rs` | ListStream処理（73-125行目） |
| 3-4 | text.rs | `crates/nu-command/src/formats/to/text.rs` | ByteStream処理（126-128行目） |

**主要処理フロー**:
- **55-56行目**: Empty入力は空文字列を返却
- **57-72行目**: 単一Valueはlocal_into_stringで変換
- **73-125行目**: ListStreamはByteStreamに変換してストリーミング
- **126-128行目**: ByteStreamはメタデータのみ更新

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

```
ToText::run (text.rs:42)
    │
    ├─ [PipelineData::Empty]
    │      │
    │      └─ Value::string("") 返却
    │
    ├─ [PipelineData::Value]
    │      │
    │      └─ local_into_string (text.rs:158)
    │             │
    │             ├─ Bool/Int/Float変換
    │             │
    │             ├─ Date変換 (RFC2822/3339 + HumanTime)
    │             │
    │             ├─ List再帰変換
    │             │
    │             ├─ Record再帰変換
    │             │
    │             └─ Custom -> to_base_value -> 再帰
    │
    ├─ [PipelineData::ListStream]
    │      │
    │      └─ ByteStream::from_iter / from_fn
    │             │
    │             └─ local_into_string (各要素)
    │
    └─ [PipelineData::ByteStream]
           │
           └─ そのまま通過（メタデータ更新のみ）
```

### データフロー図

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

Value (Any型) ────────▶ ToText::run ─────────────────▶ PipelineData
                              │                              │
                              ▼                              ▼
                        入力タイプ判定              text/plain文字列
                              │                        or ByteStream
                              │
                        ┌─────┴─────┐
                        │           │
                        ▼           ▼
                   Value/Empty   ListStream
                        │           │
                        ▼           ▼
                local_into_string  ByteStream変換
                (型別変換)        (ストリーミング)
                        │           │
                        └─────┬─────┘
                              │
                              ▼
                        update_metadata
                        (text/plain)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| text.rs | `crates/nu-command/src/formats/to/text.rs` | ソース | to textコマンドの実装 |
| mod.rs | `crates/nu-command/src/formats/to/mod.rs` | ソース | toモジュールの公開定義 |
| chrono_humanize (crate) | 外部依存 | ライブラリ | 日時の人間可読表示 |
| nu_utils::ObviousFloat | 内部依存 | ユーティリティ | Float表示の明確化 |
