# 機能設計書 33-strformat

## 概要

本ドキュメントは、Nimプログラミング言語の文字列フォーマットモジュールである`strformat`モジュールの機能設計を記載する。strformatモジュールはPythonのf-stringsに着想を得た文字列補間・フォーマット機能を提供する。

### 本機能の処理概要

strformatモジュールは`fmt`マクロと`&`演算子を通じて、式の値を文字列に埋め込む機能を提供する。フォーマット指定子により、数値の表示形式や文字列の配置を制御できる。

**業務上の目的・背景**：文字列フォーマットはログ出力、ユーザーメッセージ生成、レポート作成など多くの場面で必要とされる。strformatモジュールは、Pythonのf-stringsライクな直感的な構文で、型安全な文字列補間を実現する。コンパイル時にフォーマット文字列が解析されるため、実行時のパフォーマンスも優れている。

**機能の利用シーン**：
- デバッグメッセージの生成
- ユーザー向けメッセージのフォーマット
- 数値データの整形出力
- ログファイルへの出力
- レポート・帳票の生成

**主要な処理内容**：
1. 文字列補間（`fmt"{expr}"`、`&"{expr}"`）
2. 標準フォーマット指定子の解析（幅、精度、配置、符号等）
3. 整数フォーマット（2進数、8進数、10進数、16進数）
4. 浮動小数点数フォーマット（固定小数点、指数表記）
5. 文字列フォーマット（配置、最大幅）
6. デバッグ文字列（`{expr=}`）
7. カスタムフォーマッタのサポート（formatValue）

**関連システム・外部連携**：macros, parseutils, unicodeモジュールをインポート。strutilsモジュールの一部機能を使用。

**権限による制御**：権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面には関連しない（ライブラリモジュール） |

## 機能種別

文字列フォーマット / マクロ処理 / データ変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| pattern | static string | Yes | フォーマットパターン文字列 | コンパイル時解析 |
| openChar | static char | No | 開始文字（デフォルト: '{'） | ':'以外 |
| closeChar | static char | No | 終了文字（デフォルト: '}'） | ':'以外 |

### 入力データソース

ソースコード上の文字列リテラルとスコープ内の式・変数。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| フォーマット結果 | string | フォーマット後の文字列 |

### 出力先

戻り値として呼び出し元に返される。

## 処理フロー

### 処理シーケンス

```
1. マクロ展開（コンパイル時）
   └─ フォーマット文字列を解析
2. 式の抽出
   └─ {...}内の式を抽出
3. フォーマット指定子の解析
   └─ :以降の指定子を解析
4. コード生成
   └─ formatValue呼び出しコードを生成
5. 実行時処理
   └─ 生成されたコードが文字列を構築
```

### フローチャート

```mermaid
flowchart TD
    A[フォーマット文字列] --> B[マクロ展開]
    B --> C{文字の解析}
    C -->|通常文字| D[そのまま追加]
    C -->|開始文字| E[式の抽出]
    E --> F{フォーマット指定子あり?}
    F -->|Yes| G[指定子解析]
    F -->|No| H[デフォルトフォーマット]
    G --> I[formatValue呼び出し生成]
    H --> I
    D --> J[結果文字列]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | エスケープ | {{は{に、}}は}に変換 | フォーマット文字列 |
| BR-02 | デバッグ形式 | {expr=}は"expr=値"に展開 | =がある場合 |
| BR-03 | 生文字列 | fmtはraw string literalとして扱われる | fmt使用時 |

### 計算ロジック

標準フォーマット指定子の文法:
```
[[fill]align][sign][#][0][minimumwidth][.precision][type]
```

- `fill`: パディング文字
- `align`: `<`（左寄せ）, `>`（右寄せ）, `^`（中央寄せ）
- `sign`: `+`（常に符号）, `-`（負のみ）, ` `（正は空白）
- `#`: 代替形式（0x, 0b, 0o接頭辞）
- `0`: ゼロパディング
- `minimumwidth`: 最小幅
- `precision`: 精度（浮動小数点の小数点以下桁数）
- `type`: `b`(2進), `d`(10進), `o`(8進), `x/X`(16進), `e/E`(指数), `f/F`(固定小数点), `g/G`(汎用)

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

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

### テーブル別操作詳細

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ValueError | Exception | 無効なフォーマット指定子 | 指定子の修正 |
| - | コンパイルエラー | 閉じ括弧の欠落 | 構文の修正 |
| - | コンパイルエラー | 式の解析失敗 | 式の修正 |

### リトライ仕様

リトライは不要。コンパイル時エラーで対処。

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

トランザクション管理は不要。

## パフォーマンス要件

- コンパイル時にフォーマット文字列を解析するため、実行時オーバーヘッドが最小
- 結果文字列は事前に容量を推定して確保（newStringOfCap）

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

- フォーマット文字列はコンパイル時に固定されるため、フォーマット文字列インジェクションのリスクは低い
- ユーザー入力をフォーマット文字列として使用することはできない（コンパイル時定数のため）

## 備考

`fmt`はraw string literalとして扱われるため、`\n`などのエスケープシーケンスは解釈されない。エスケープシーケンスを使用する場合は`&`演算子を使用すること。

---

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

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

### 推奨読解順序

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

フォーマット指定子を表す構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | strformat.nim | `lib/pure/strformat.nim` | StandardFormatSpecifier型（358-368行目） |

**読解のコツ**: StandardFormatSpecifierは解析されたフォーマット指定子の各要素を保持する。fill, align, sign, alternateForm等のフィールドがある。

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

モジュール冒頭のドキュメントとマクロ定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | strformat.nim | `lib/pure/strformat.nim` | モジュールドキュメント（10-323行目） |
| 2-2 | strformat.nim | `lib/pure/strformat.nim` | fmtマクロ定義（746-788行目） |

**主要処理フロー**:
1. **772-774行目**: `fmt`テンプレート - パターンとデフォルト区切り文字で内部マクロを呼び出し
2. **776-788行目**: `&`テンプレート - fmtのエイリアス

#### Step 3: フォーマット指定子解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | strformat.nim | `lib/pure/strformat.nim` | parseStandardFormatSpecifier（432-480行目） |

**主要処理フロー**:
- **442-451行目**: align文字の解析（<, >, ^）
- **453-455行目**: sign文字の解析（+, -, 空白）
- **457-459行目**: 代替形式フラグの解析（#）
- **461-463行目**: ゼロパディングの解析
- **465-472行目**: 最小幅と精度の解析

#### Step 4: formatValue実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | strformat.nim | `lib/pure/strformat.nim` | formatValue（整数）（493-519行目） |
| 4-2 | strformat.nim | `lib/pure/strformat.nim` | formatValue（浮動小数点）（569-593行目） |
| 4-3 | strformat.nim | `lib/pure/strformat.nim` | formatValue（文字列）（595-629行目） |

**主要処理フロー**:
- **493-519行目**: 整数のフォーマット（基数変換、パディング）
- **569-593行目**: 浮動小数点のフォーマット（精度、指数表記）
- **595-629行目**: 文字列のフォーマット（配置、切り詰め）

#### Step 5: マクロ実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | strformat.nim | `lib/pure/strformat.nim` | strformatImpl（645-744行目） |

**主要処理フロー**:
- **652-660行目**: 結果変数の初期化
- **662-737行目**: フォーマット文字列の解析ループ
- **678-703行目**: 式の抽出とデバッグ形式（=）の処理
- **714-725行目**: formatValue呼び出しの生成

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

```
fmt / & マクロ
    │
    └─ strformatImpl (内部マクロ)
           │
           ├─ parseExpr (式の解析)
           │
           └─ formatValue (各型用)
                  │
                  ├─ formatInt (整数フォーマット)
                  │
                  ├─ formatFloat (浮動小数点フォーマット)
                  │
                  └─ alignString (文字列配置)
```

### データフロー図

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

fmt"{x} is {y:>5}"  ───▶  マクロ展開（コンパイル時）  ───▶  コード生成
                                   │
                                   ▼
                           [生成されたコード]
                           var res = newStringOfCap(...)
                           formatValue(res, x, "")
                           res.add(" is ")
                           formatValue(res, y, ">5")
                           res
                                   │
                                   ▼
                           [実行時]              ───▶  "42 is    7"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| strformat.nim | `lib/pure/strformat.nim` | ソース | メインモジュール、fmt/&マクロ、formatValue |
| macros.nim | `lib/core/macros.nim` | ソース | マクロ処理基盤 |
| parseutils.nim | `lib/pure/parseutils.nim` | ソース | 解析ユーティリティ |
| unicode.nim | `lib/pure/unicode.nim` | ソース | Unicode文字列処理（runeLen等） |
| strutils.nim | `lib/pure/strutils.nim` | ソース | 文字列操作（formatBiggestFloat等） |
