# 帳票設計書 7-to toml

## 概要

本ドキュメントは、Nushellの`to toml`コマンドに関する設計書である。`to toml`コマンドは、レコードデータをTOML (Tom's Obvious, Minimal Language) 形式のテキストに変換するデータ変換コマンドである。

### 本帳票の処理概要

`to toml`コマンドは、Nushellのレコードデータ（またはクロージャ）をTOML形式のテキストに変換する。TOMLは設定ファイル形式として広く使用されており、人間が読みやすく編集しやすい形式である。

**業務上の目的・背景**：TOMLはRustのCargo.toml、Python のpyproject.toml、Hugo設定ファイルなど、多くのプロジェクトで標準的な設定ファイル形式として採用されている。Nushellで生成したデータを設定ファイルとして出力する需要に応える。

**帳票の利用シーン**：
- Cargo.toml等のプロジェクト設定ファイル生成
- アプリケーション設定ファイルの出力
- 構成管理ツール用設定の生成
- 設定データのエクスポート
- 人間が読みやすい形式でのデータ保存

**主要な出力内容**：
1. TOMLテーブル（レコードから変換）
2. TOML配列（リストから変換）
3. TOMLスカラー値（文字列、数値、真偽値、日時など）

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

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

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

### 出力オプション

| オプション | 短縮形 | 説明 | デフォルト値 |
|-----------|--------|------|-------------|
| --serialize | -s | デシリアライズ不可能なNushell型をシリアライズ | false |

## 帳票レイアウト

### レイアウト概要

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

```
┌─────────────────────────────────────┐
│  TOML構造                           │
│  key1 = "value1"                    │
│  key2 = 123                         │
│                                     │
│  [section]                          │
│  nested_key = true                  │
│                                     │
│  [[array_of_tables]]                │
│  item = "first"                     │
└─────────────────────────────────────┘
```

### 型変換マッピング

| No | Nushell型 | TOML型 | 備考 |
|----|-----------|--------|------|
| 1 | Bool | Boolean | 真偽値 |
| 2 | Int | Integer | 整数 |
| 3 | Float | Float | 浮動小数点 |
| 4 | String | String | 文字列 |
| 5 | Glob | String | 文字列 |
| 6 | Date | Datetime | TOML日時形式 |
| 7 | Duration | String | 文字列表現 |
| 8 | Filesize | Integer | バイト数 |
| 9 | Nothing | String | "<Nothing>" |
| 10 | List | Array | 配列 |
| 11 | Record | Table | テーブル |
| 12 | Binary | Array | バイト配列 |
| 13 | CellPath | Array | パス要素配列 |
| 14 | Closure | String | ブロック内容（--serialize時）またはclosure_id |
| 15 | Range | String | "<Range>" |
| 16 | Custom | String | "<Custom Value>" |

## 出力条件

### 入力条件

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

### 制約条件

| 条件名 | 説明 |
|-------|------|
| String入力 | エラー（TOMLトップレベルはテーブル必須） |
| List入力 | エラー（TOMLトップレベルはテーブル必須） |
| Error伝播 | Value::Errorはエラー伝播 |

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

### 参照テーブル一覧

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

## 計算仕様

### 計算項目一覧

| 項目名 | 処理 | 備考 |
|-------|------|------|
| 日時変換 | chronoからtoml::Datetimeへ変換 | 年・月・日・時・分・秒・タイムゾーン |
| タイムゾーン | UTCからのオフセット分に変換 | i16分単位 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[入力データ受信] --> B[オプション解析]
    B --> C[value_to_toml_value変換]
    C --> D{トップレベル型確認}
    D -->|Record/Closure| E[helper関数で再帰変換]
    D -->|その他| F[UnsupportedInputエラー]
    E --> G{変換結果が単一テーブル配列?}
    G -->|Yes| H[テーブルを展開]
    G -->|No| I[そのまま使用]
    H --> J[toml::to_string_pretty]
    I --> J
    J --> K{変換成功?}
    K -->|Yes| L[Value::string作成]
    K -->|No| M[CantConvertエラー]
    L --> N[メタデータ付与]
    N --> O[PipelineData返却]
    M --> O
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| UnsupportedInput | String入力 | "is not valid top-level TOML" | recordでラップ |
| UnsupportedInput | List入力 | "is not valid top-level TOML" | recordでラップ |
| CantConvert | TOML変換失敗 | "CantConvert to TOML" | 入力データを確認 |
| Error伝播 | Value::Error入力 | 元のエラーメッセージ | 元のエラーを解決 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | メモリ制限内 |
| 目標出力時間 | データサイズに依存 |
| 同時出力数上限 | N/A |

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

- 入力データはそのまま出力されるため、センシティブな情報が含まれる場合は注意が必要
- TOMLの特殊文字はtomlクレートが適切にエスケープ

## 備考

- content_type メタデータは "text/x-toml" として設定される
- tomlクレートを使用してTOML変換を実施
- pretty形式（整形済み）で出力

---

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

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

### 推奨読解順序

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

まず、Nushellの各Value型とTOML型のマッピングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | toml.rs | `crates/nu-command/src/formats/to/toml.rs` | helper関数での型マッピング（52-111行目） |
| 1-2 | toml.rs | `crates/nu-command/src/formats/to/toml.rs` | to_toml_datetime関数（199-234行目） |

**読解のコツ**: chronoの日時型からTOML固有のDatetime型への変換ロジックを確認する。

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

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

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

**主要処理フロー**:
1. **13-22行目**: シグネチャ定義（--serializeオプション）
2. **36-47行目**: runメソッドでオプション解析とto_toml関数呼び出し

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

各型の変換ロジックと出力フローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | toml.rs | `crates/nu-command/src/formats/to/toml.rs` | to_toml関数（175-197行目） |
| 3-2 | toml.rs | `crates/nu-command/src/formats/to/toml.rs` | value_to_toml_value関数（156-173行目） |
| 3-3 | toml.rs | `crates/nu-command/src/formats/to/toml.rs` | toml_into_pipeline_data関数（127-154行目） |

**主要処理フロー**:
- **156-173行目**: トップレベル型検証（Record/Closureのみ許可）
- **175-197行目**: 変換結果が単一テーブル配列の場合の展開処理
- **127-154行目**: TOML文字列への変換とメタデータ付与

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

```
ToToml::run (toml.rs:36)
    │
    └─ to_toml (toml.rs:175)
           │
           ├─ value_to_toml_value (toml.rs:156)
           │      │
           │      └─ helper (toml.rs:52)
           │             │
           │             ├─ プリミティブ型変換 (toml.rs:57-65)
           │             │
           │             ├─ Record変換 (toml.rs:66-72)
           │             │      │
           │             │      └─ helper (再帰)
           │             │
           │             ├─ List変換 (toml.rs:73-75)
           │             │      │
           │             │      └─ toml_list (toml.rs:113)
           │             │             │
           │             │             └─ helper (再帰)
           │             │
           │             ├─ Date変換 (toml.rs:62)
           │             │      │
           │             │      └─ to_toml_datetime (toml.rs:199)
           │             │
           │             └─ Closure変換 (toml.rs:76-92)
           │
           └─ toml_into_pipeline_data (toml.rs:127)
                  │
                  └─ toml::to_string_pretty
```

### データフロー図

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

Value::Record ────────▶ ToToml::run ─────────────────▶ PipelineData::Value
                              │                              │
                              ▼                              ▼
                        to_toml                        TOML形式文字列
                              │                        "key = \"value\"\n"
                              ▼
                        value_to_toml_value
                        (トップレベル検証)
                              │
                              ▼
                        helper
                        (型別変換)
                              │
                              ▼
                        toml::to_string_pretty
                              │
                              ▼
                        metadata付与
                        (text/x-toml)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| toml.rs | `crates/nu-command/src/formats/to/toml.rs` | ソース | to tomlコマンドの実装 |
| mod.rs | `crates/nu-command/src/formats/to/mod.rs` | ソース | toモジュールの公開定義 |
| toml (crate) | 外部依存 | ライブラリ | TOML出力ライブラリ |
| chrono (crate) | 外部依存 | ライブラリ | 日時処理ライブラリ |
