# 帳票設計書 4-to yaml

## 概要

本ドキュメントは、Nushellの`to yaml`コマンドに関する設計書である。`to yaml`コマンドは、任意のNushellデータをYAML (YAML Ain't Markup Language) 形式のテキストに変換するデータ変換コマンドである。

### 本帳票の処理概要

`to yaml`コマンドは、Nushellのパイプラインで流れてくるあらゆるデータ型をYAML形式のテキストに変換する。YAMLは人間が読みやすい形式で、設定ファイルやデータシリアライゼーションに広く使用されている。

**業務上の目的・背景**：YAMLはKubernetes、Docker Compose、Ansible、CI/CDツールなど多くのDevOps関連ツールで標準的な設定ファイル形式として採用されている。Nushellで処理したデータをこれらのツールで利用可能な形式に変換する需要に応える。

**帳票の利用シーン**：
- Kubernetes設定ファイルの生成
- Docker Compose設定の出力
- Ansible Playbook用データの準備
- CI/CD設定ファイルの生成
- 人間が読みやすい形式でのデータ出力

**主要な出力内容**：
1. YAMLマッピング（レコードから変換）
2. YAMLシーケンス（リストから変換）
3. YAMLスカラー値（文字列、数値、真偽値など）

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

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

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

### 出力オプション

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

## 帳票レイアウト

### レイアウト概要

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

```
┌─────────────────────────────────────┐
│  YAML構造                           │
│  key1: value1                       │
│  key2:                              │
│    - item1                          │
│    - item2                          │
│  key3:                              │
│    nested: true                     │
└─────────────────────────────────────┘
```

### 型変換マッピング

| No | Nushell型 | YAML型 | 備考 |
|----|-----------|--------|------|
| 1 | Bool | Boolean | 真偽値 |
| 2 | Int | Number | 整数 |
| 3 | Float | Number | 浮動小数点 |
| 4 | String | String | 文字列 |
| 5 | Glob | String | 文字列 |
| 6 | Date | String | ISO形式文字列 |
| 7 | Duration | String | 文字列表現 |
| 8 | Filesize | Number | バイト数 |
| 9 | Nothing | Null | null値 |
| 10 | List | Sequence | 配列 |
| 11 | Record | Mapping | マップ |
| 12 | Binary | Sequence | バイト配列 |
| 13 | CellPath | Sequence | パス要素配列 |
| 14 | Closure | String/Null | --serialize時のみ文字列変換 |
| 15 | Range | Null | null出力 |
| 16 | Custom | Null | null出力 |

## 出力条件

### 入力条件

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

### 制約条件

| 条件名 | 説明 |
|-------|------|
| Closure | --serialize未指定時はNull |
| Range | Null出力 |
| Custom | Null出力 |
| Error | エラー伝播 |

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

### 参照テーブル一覧

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

## 計算仕様

### 計算項目一覧

本コマンドには計算処理は含まれない。型変換のみ実施。

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[入力データ受信] --> B[オプション解析]
    B --> C[Range展開]
    C --> D[Value取得]
    D --> E[value_to_yaml_value変換]
    E --> F[serde_yaml::to_string]
    F --> G{変換成功?}
    G -->|Yes| H[Value::string作成]
    G -->|No| I[CantConvertエラー]
    H --> J[メタデータ付与]
    J --> K[PipelineData返却]
    I --> K
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| CantConvert | YAML変換失敗 | "CantConvert to YAML" | 入力データを確認 |
| Error伝播 | Value::Error入力 | 元のエラーメッセージ | 元のエラーを解決 |

## パフォーマンス要件

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

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

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

## 備考

- content_type メタデータは "application/yaml" として設定される（RFC-9512準拠）
- serde_yamlクレートを使用してYAML変換を実施
- `to yml`コマンドは`to yaml`のエイリアス（同一の変換処理）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | yaml.rs | `crates/nu-command/src/formats/to/yaml.rs` | value_to_yaml_value関数での型マッピング（96-170行目） |

**読解のコツ**: match文でValue型ごとにserde_yaml::Value型への変換を確認する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | yaml.rs | `crates/nu-command/src/formats/to/yaml.rs` | ToYaml構造体とCommandトレイト実装（6-48行目） |
| 2-2 | yaml.rs | `crates/nu-command/src/formats/to/yaml.rs` | ToYml構造体（エイリアス）の実装（50-94行目） |

**主要処理フロー**:
1. **12-21行目**: シグネチャ定義（--serializeオプション）
2. **35-47行目**: runメソッドでオプション解析とYAML変換処理
3. **172-202行目**: to_yaml関数でYAML文字列生成

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

各型の変換ロジックを詳細に確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | yaml.rs | `crates/nu-command/src/formats/to/yaml.rs` | value_to_yaml_value関数（96-170行目） |

**主要処理フロー**:
- **101-112行目**: プリミティブ型の変換
- **114-123行目**: Recordの変換（Mapping）
- **124-132行目**: Listの変換（Sequence）
- **133-149行目**: Closureの変換（--serialize時のみ）
- **152-167行目**: Binary, CellPathの変換

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

```
ToYaml::run (yaml.rs:35)
    │
    ├─ input.try_expand_range() (yaml.rs:44)
    │
    └─ to_yaml (yaml.rs:46)
           │
           ├─ input.into_value() (yaml.rs:183)
           │
           ├─ value_to_yaml_value (yaml.rs:185)
           │      │
           │      ├─ プリミティブ型変換 (yaml.rs:101-112)
           │      │
           │      ├─ Record変換 (yaml.rs:114-123)
           │      │      │
           │      │      └─ value_to_yaml_value (再帰)
           │      │
           │      ├─ List変換 (yaml.rs:124-132)
           │      │      │
           │      │      └─ value_to_yaml_value (再帰)
           │      │
           │      └─ Closure変換 (yaml.rs:133-149)
           │
           └─ serde_yaml::to_string (yaml.rs:186)
```

### データフロー図

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

Value (Any型) ────────▶ ToYaml::run ─────────────────▶ PipelineData::Value
                              │                              │
                              ▼                              ▼
                        Range展開                      YAML形式文字列
                              │                        "key: value\n"
                              ▼
                        to_yaml
                              │
                              ▼
                        value_to_yaml_value
                        (型別変換)
                              │
                              ▼
                        serde_yaml::to_string
                              │
                              ▼
                        metadata付与
                        (application/yaml)
```

### 関連ファイル一覧

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