# 帳票設計書 10-to nuon

## 概要

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

### 本帳票の処理概要

`to nuon`コマンドは、Nushellのあらゆるデータ型をNUON形式のテキストに変換する。NUONはNushell固有のデータシリアライゼーションフォーマットであり、JSONに似ているが、Nushellのネイティブデータ型（日時、ファイルサイズ、期間など）をより自然に表現できる。

**業務上の目的・背景**：NUONはNushellで処理したデータを永続化したり、設定ファイルとして保存したり、他のNushellセッションと共有したりするためのフォーマットである。JSONと異なり、Nushellのすべてのデータ型を損失なく表現できる。

**帳票の利用シーン**：
- Nushellデータの永続化保存
- 設定ファイルの生成
- データのシリアライゼーション
- Nushellスクリプト間のデータ共有
- プラグインレジストリファイルの生成

**主要な出力内容**：
1. NUONレコード（Nushellレコードから変換）
2. NUON配列（リストから変換）
3. NUONスカラー値（日時、期間、ファイルサイズなど含む）

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

**帳票の利用者**：Nushellユーザー、Nushellプラグイン開発者

## 帳票種別

データ変換出力（Nushell固有形式）

## 利用画面

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

## 出力形式

### 基本仕様

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

### 出力オプション

| オプション | 短縮形 | 説明 | デフォルト値 |
|-----------|--------|------|-------------|
| --raw | -r | 空白を削除（-i, -tを上書き） | false |
| --indent | -i | インデント幅（スペース数） | なし |
| --tabs | -t | インデントにタブを使用（タブ数） | なし |
| --serialize | -s | デシリアライズ不可能なNushell型をシリアライズ | false |
| --raw-strings | なし | 引用符やバックスラッシュを含む文字列にraw string構文を使用 | false |

## 帳票レイアウト

### レイアウト概要

NUON出力はNushellの構文に準拠した形式を持つ：

#### コンパクト形式（--raw）
```
{date:2000-01-01T00:00:00+00:00,data:[1,[2,3],4.56]}
```

#### インデント形式
```
{
  date: 2000-01-01T00:00:00+00:00,
  data: [
    1,
    [
      2,
      3
    ],
    4.56
  ]
}
```

### NUON特有の型表現

| No | Nushell型 | NUON表現例 | 備考 |
|----|-----------|-----------|------|
| 1 | Date | 2000-01-01T00:00:00+00:00 | ISO 8601形式 |
| 2 | Duration | 1hr 30min | 人間可読形式 |
| 3 | Filesize | 1.5 MiB | 単位付き |
| 4 | Binary | 0x[01 02 03] | 16進数表記 |
| 5 | Range | 1..10 | 範囲構文 |
| 6 | Record | {key: value} | Nushellレコード構文 |
| 7 | List | [1, 2, 3] | Nushellリスト構文 |
| 8 | String | "text" | ダブルクォート |
| 9 | Raw String | r#'text'# | --raw-strings時 |

## 出力条件

### 入力条件

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

### 出力スタイル優先順位

| 優先度 | 条件 | 適用スタイル |
|-------|------|-------------|
| 1 | --raw指定 | Raw（空白なし） |
| 2 | --tabs指定 | タブインデント |
| 3 | --indent指定 | スペースインデント |
| 4 | なし | Default（コンパクト） |

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

### 参照テーブル一覧

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

## 計算仕様

### 計算項目一覧

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

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[入力データ受信] --> B[オプション解析]
    B --> C[スタイル決定]
    C --> D{--raw?}
    D -->|Yes| E[ToStyle::Raw]
    D -->|No| F{--tabs?}
    F -->|Yes| G[ToStyle::Tabs]
    F -->|No| H{--indent?}
    H -->|Yes| I[ToStyle::Spaces]
    H -->|No| J[ToStyle::Default]
    E --> K[ToNuonConfig作成]
    G --> K
    I --> K
    J --> K
    K --> L[nuon::to_nuon呼び出し]
    L --> M{変換成功?}
    M -->|Yes| N[Value::string作成]
    M -->|No| O[Value::error作成]
    N --> P[メタデータ付与]
    O --> P
    P --> Q[PipelineData返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| ShellError | NUON変換失敗 | nuonクレートのエラーメッセージ | 入力データを確認 |

## パフォーマンス要件

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

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

- 入力データはそのまま出力されるため、センシティブな情報が含まれる場合は注意が必要
- NUONはNushellで直接実行可能なため、信頼できないソースからのNUONファイルの読み込みには注意が必要

## 備考

- content_type メタデータは "application/x-nuon" として設定される
- nuonクレートを使用してNUON変換を実施
- `from nuon`コマンドで読み戻し可能
- --raw-stringsは引用符やバックスラッシュを含む文字列をr#'...'#形式で出力

---

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

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

### 推奨読解順序

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

まず、出力スタイルの設定構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | nuon.rs | `crates/nu-command/src/formats/to/nuon.rs` | ToNuon構造体（5行目） |
| 1-2 | nuonクレート | 外部依存 | nuon::ToStyle列挙型、ToNuonConfig構造体 |

**読解のコツ**: nuonクレートのToStyleとToNuonConfigがどのように組み立てられるか確認する。

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

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

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

**主要処理フロー**:
1. **11-42行目**: シグネチャ定義（--raw, --indent, --tabs, --serialize, --raw-stringsオプション）
2. **48-88行目**: runメソッドでオプション解析とnuon::to_nuon呼び出し

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

スタイル決定と変換処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nuon.rs | `crates/nu-command/src/formats/to/nuon.rs` | スタイル決定ロジック（62-70行目） |
| 3-2 | nuon.rs | `crates/nu-command/src/formats/to/nuon.rs` | ToNuonConfig作成（75-79行目） |
| 3-3 | nuon.rs | `crates/nu-command/src/formats/to/nuon.rs` | nuon::to_nuon呼び出しと結果処理（81-87行目） |

**主要処理フロー**:
- **62-70行目**: オプションからToStyleを決定（Raw > Tabs > Spaces > Default）
- **75-79行目**: ToNuonConfigの構築（style, span, serialize_types, raw_strings）
- **81-87行目**: 変換成功時はValue::string、失敗時はValue::errorを返却

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

```
ToNuon::run (nuon.rs:48)
    │
    ├─ オプション解析
    │      │
    │      ├─ --raw -> ToStyle::Raw
    │      ├─ --tabs -> ToStyle::Tabs(t)
    │      ├─ --indent -> ToStyle::Spaces(i)
    │      └─ none -> ToStyle::Default
    │
    ├─ input.into_value()
    │
    ├─ ToNuonConfig作成
    │      │
    │      ├─ .style(style)
    │      ├─ .span(Some(span))
    │      ├─ .serialize_types(serialize_types)
    │      └─ .raw_strings(raw_strings)
    │
    └─ nuon::to_nuon (外部クレート)
           │
           ├─ 成功時: Value::string
           │
           └─ 失敗時: Value::error
```

### データフロー図

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

Value (Any型) ────────▶ ToNuon::run ─────────────────▶ PipelineData::Value
                              │                              │
                              ▼                              ▼
                        スタイル決定                   NUON形式文字列
                        (Raw/Tabs/Spaces/Default)     "{key: value, ...}"
                              │
                              ▼
                        ToNuonConfig作成
                              │
                              ▼
                        nuon::to_nuon
                        (nuonクレート)
                              │
                              ▼
                        metadata付与
                        (application/x-nuon)
```

### 関連ファイル一覧

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