# 機能設計書 83-フィル・パディング

## 概要

本ドキュメントは、Nushellのフィル（fill）コマンドの機能設計について記述する。このコマンドは、テキストや数値に対してパディング（空白や指定文字での埋め込み）を行い、指定幅に揃える機能を提供する。

### 本機能の処理概要

fillコマンドは、入力値（整数、浮動小数点数、文字列、ファイルサイズ）を指定された幅に拡張し、指定された文字で埋め込む機能を提供する。左揃え、右揃え、中央揃え等のアライメント指定が可能で、出力は常に文字列型となる。

**業務上の目的・背景**：データ表示の整形において、桁揃えやパディングは重要な役割を果たす。数値の0パディング（001, 002, ...）、テキストの左右揃え、罫線文字での整形など、視覚的に見やすい出力を生成するためにこの機能が必要となる。シェル環境での出力整形をNushellネイティブに行えることで、外部ツールへの依存を減らせる。

**機能の利用シーン**：数値の0埋め表示、テキストの固定幅整形、テーブル表示前の値整形、ファイル名の連番生成時、罫線文字による装飾的な表示など、表示整形が必要なあらゆる場面で利用される。

**主要な処理内容**：
1. 入力パラメータ（幅、アライメント、埋め込み文字）の解析
2. 入力値の文字列化
3. 現在の表示幅の計算（Unicode対応）
4. アライメントに従った左右パディング量の決定
5. 埋め込み文字での拡張と結果出力

**関連システム・外部連携**：なし（スタンドアロン機能）

**権限による制御**：なし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIコマンドとして実行 |

## 機能種別

データ変換 / 書式整形

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --width (-w) | Int | No | 出力幅（デフォルト: 1） | 正の整数 |
| --alignment (-a) | String | No | アライメント（left/right/middle/middleright） | 指定値のみ |
| --character (-c) | String | No | 埋め込み文字（デフォルト: スペース） | 任意の文字 |
| rest | CellPath | No | 変換対象のセルパス | - |

### 入力データソース

- パイプライン入力（Int, Float, String, Filesize, またはそれらのリスト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (出力) | String | パディング済み文字列 |

### 出力先

標準出力（パイプライン出力）

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの解析
   └─ width, alignment, characterの取得
2. アライメント設定の決定
   └─ 文字列からFillAlignment列挙型へ変換
3. 入力値の文字列化
   └─ 型に応じた文字列変換
4. 表示幅の計算
   └─ print_positionsを使用したUnicode対応幅計算
5. パディング量の決定
   └─ 目標幅と現在幅の差分をアライメントで分配
6. 埋め込み処理と出力
   └─ 左右にパディング文字を追加
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ解析]
    B --> C{入力型判定}
    C -->|Int| D[数値を文字列化]
    C -->|Float| D
    C -->|String| E[そのまま使用]
    C -->|Filesize| F[バイト数を文字列化]
    D --> G[表示幅計算]
    E --> G
    F --> G
    G --> H{幅 >= 目標幅?}
    H -->|Yes| I[そのまま返却]
    H -->|No| J{アライメント}
    J -->|Left| K[右側にパディング]
    J -->|Right| L[左側にパディング]
    J -->|Middle| M[両側にパディング（左優先）]
    J -->|MiddleRight| N[両側にパディング（右優先）]
    K --> O[結果出力]
    L --> O
    M --> O
    N --> O
    I --> O
    O --> P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-83-01 | 幅超過時 | 入力が目標幅以上の場合はそのまま返却 | 常時 |
| BR-83-02 | デフォルト幅 | 未指定時は幅1 | width未指定時 |
| BR-83-03 | デフォルト文字 | 未指定時はスペース | character未指定時 |
| BR-83-04 | デフォルトアライメント | 未指定時は左揃え | alignment未指定時 |
| BR-83-05 | 中央揃え奇数差分 | 差分が奇数の場合、Middleは左に多く、MiddleRightは右に多く | Middle/MiddleRight使用時 |

### 計算ロジック

**パディング量計算**:
```
diff = target_width - current_width
Left:        left_pad = 0,      right_pad = diff
Right:       left_pad = diff,   right_pad = 0
Middle:      left_pad = diff/2, right_pad = diff - diff/2
MiddleRight: left_pad = diff - diff/2, right_pad = diff/2
```

## データベース操作仕様

該当なし（メモリ内処理のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| OnlySupportsThisInputType | 非対応入力 | int/filesize/float/string以外の入力 | 対応型に変換して使用 |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし（純粋関数的処理）

## パフォーマンス要件

- 単一値処理はO(n) - nは出力幅
- リスト処理はO(m*n) - mは要素数、nは最大出力幅

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

特になし

## 備考

- print_positions crateを使用してUnicode文字の表示幅を正しく計算
- 全角文字等の表示幅が2の文字にも対応

---

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

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

### 推奨読解順序

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

fillコマンドで使用するデータ構造とアライメント設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | fill.rs | `crates/nu-command/src/conversions/fill.rs` | Arguments構造体とFillAlignment列挙型 |

**読解のコツ**:
- **9-14行目**: Arguments構造体でパラメータを保持
- **22-28行目**: FillAlignment列挙型で4種類のアライメントを定義

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | fill.rs | `crates/nu-command/src/conversions/fill.rs` | Fillコマンドの実装 |

**主要処理フロー**:
1. **30-96行目**: Commandトレイトの実装とシグネチャ定義
2. **137-145行目**: runメソッドからfill関数への委譲
3. **148-184行目**: fill関数でのパラメータ解析とoperate呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | fill.rs | `crates/nu-command/src/conversions/fill.rs` | action関数とpad関数 |

**主要処理フロー**:
- **186-204行目**: action関数での型別処理
- **206-217行目**: fill_float, fill_int関数
- **218-222行目**: fill_string関数
- **224-256行目**: pad関数でのコアパディングロジック
- **228行目**: print_positionsによる表示幅計算
- **240-245行目**: アライメントによるパディング量決定

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

```
Fill::run()
    │
    └─ fill()
           │
           ├─ call.get_flag() / call.rest()
           │      └─ パラメータ解析
           │
           └─ operate(action, args, input, ...)
                  │
                  └─ action(&Value, &Arguments, Span)
                         │
                         ├─ match input型
                         │      ├─ Value::Int => fill_int()
                         │      ├─ Value::Float => fill_float()
                         │      ├─ Value::String => fill_string()
                         │      └─ Value::Filesize => fill_int()
                         │
                         └─ pad(s, width, char, alignment, truncate)
                                │
                                ├─ print_positions(s).count()
                                │      └─ 表示幅計算
                                │
                                └─ パディング文字の追加
```

### データフロー図

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

数値/文字列 ───▶ 文字列化 ───▶ 幅計算 ───▶ パディング ───▶ 文字列
    1              "1"          1文字        "00001"       "00001"
  (width=5, char='0', align=right)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fill.rs | `crates/nu-command/src/conversions/fill.rs` | ソース | fillコマンドの主実装 |
| mod.rs | `crates/nu-command/src/conversions/mod.rs` | ソース | conversionsモジュールのエクスポート |
