# 帳票設計書 21-バージョン文字列

## 概要

libuvライブラリのバージョンを"x.y.z"形式の文字列として返却する帳票（API出力）の設計書である。`uv_version_string()`関数により、コンパイル時に決定されたバージョン情報を人間可読な文字列形式で取得する。

### 本帳票の処理概要

本帳票は、libuvライブラリのバージョン番号を"MAJOR.MINOR.PATCH"形式の文字列として出力する機能を提供する。リリース版では"x.y.z"形式、開発版（プレリリース版）では"x.y.z-suffix"形式の文字列を返却する。

**業務上の目的・背景**：libuvを利用するアプリケーションがランタイム時にリンクされているlibuvのバージョンを確認するために必要である。バージョン互換性の検証、デバッグ情報の出力、ログ記録などの場面でバージョン文字列が活用される。コンパイル時のヘッダバージョンとランタイムのライブラリバージョンの不一致を検出するためにも重要な機能である。

**帳票の利用シーン**：アプリケーション起動時のバージョン確認、ログ出力へのバージョン情報付加、バージョン互換性チェック、デバッグ情報出力時のライブラリバージョン特定、CLIツールの--versionオプション実装時などに利用される。

**主要な出力内容**：
1. メジャーバージョン番号（UV_VERSION_MAJOR）
2. マイナーバージョン番号（UV_VERSION_MINOR）
3. パッチバージョン番号（UV_VERSION_PATCH）
4. サフィックス文字列（非リリース版の場合、例: "dev"）

**帳票の出力タイミング**：任意のタイミングで`uv_version_string()`関数を呼び出すことにより出力される。同期関数であり、即座に結果が返却される。

**帳票の利用者**：libuvを利用するアプリケーション開発者、Node.jsランタイム、組み込みシステム開発者、デバッグツール開発者。

## 帳票種別

情報取得（バージョン情報文字列出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | CLIまたはAPI呼び出し | N/A（C言語API） | `uv_version_string()` 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | 文字列（const char*） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（メモリ上の文字列） |
| 出力方法 | 関数戻り値として返却 |
| 文字コード | ASCII |

### 出力文字列フォーマット

| 条件 | 形式 | 例 |
|-----|------|-----|
| リリース版（UV_VERSION_IS_RELEASE=1） | "MAJOR.MINOR.PATCH" | "1.52.1" |
| 開発版（UV_VERSION_IS_RELEASE=0） | "MAJOR.MINOR.PATCH-SUFFIX" | "1.52.1-dev" |

## 帳票レイアウト

### レイアウト概要

本帳票は単一の文字列値として出力される。構造化されたレイアウトは持たない。

```
┌─────────────────────────────────────┐
│  バージョン文字列                      │
│  "MAJOR.MINOR.PATCH[-SUFFIX]"       │
└─────────────────────────────────────┘
```

### 出力項目

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | バージョン文字列 | libuvのバージョンを表す文字列 | UV_VERSION_STRING マクロ（コンパイル時展開） | "MAJOR.MINOR.PATCH" または "MAJOR.MINOR.PATCH-SUFFIX" |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| なし | パラメータ不要。常に現在のバージョン文字列を返却 | N/A |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| N/A | N/A | N/A |

### 改ページ条件

N/A（単一文字列出力のため改ページなし）

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

### 参照テーブル一覧

本帳票はデータベースを参照しない。コンパイル時にヘッダファイルから埋め込まれたマクロ定数を使用する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| N/A | N/A | N/A |

### データ取得元（マクロ定数）

| マクロ名 | 定義ファイル | 値（現在） | 用途 |
|---------|-------------|-----------|------|
| UV_VERSION_MAJOR | `include/uv/version.h` | 1 | メジャーバージョン番号 |
| UV_VERSION_MINOR | `include/uv/version.h` | 52 | マイナーバージョン番号 |
| UV_VERSION_PATCH | `include/uv/version.h` | 1 | パッチバージョン番号 |
| UV_VERSION_IS_RELEASE | `include/uv/version.h` | 0 | リリースフラグ（0=開発版, 1=リリース版） |
| UV_VERSION_SUFFIX | `include/uv/version.h` | "dev" | バージョンサフィックス |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| UV_VERSION_STRING_BASE | UV_STRINGIFY(MAJOR) "." UV_STRINGIFY(MINOR) "." UV_STRINGIFY(PATCH) | N/A | プリプロセッサマクロによる文字列結合 |
| UV_VERSION_STRING | UV_VERSION_IS_RELEASE ? UV_VERSION_STRING_BASE : UV_VERSION_STRING_BASE "-" UV_VERSION_SUFFIX | N/A | リリース版/開発版で出力を切替 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_version_string 呼び出し] --> B[UV_VERSION_STRING マクロを返却]
    B --> C{UV_VERSION_IS_RELEASE?}
    C -->|1: リリース版| D["MAJOR.MINOR.PATCH を返却"]
    C -->|0: 開発版| E["MAJOR.MINOR.PATCH-SUFFIX を返却"]
    D --> F[終了]
    E --> F
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| なし | 本関数はエラーを返さない | N/A | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（固定値） |
| 目標出力時間 | 即座（コンパイル時定数を返すのみ） |
| 同時出力数上限 | 制限なし（スレッドセーフ） |

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

- 返却される文字列はstaticな読み取り専用メモリ上に配置されるため、呼び出し元による書き換えは不可能である
- バージョン情報自体に機密性はないため、特段のアクセス制御は不要である

## 備考

- `uv_version_string()`はスレッドセーフである（読み取り専用のstatic文字列を返すため）
- 関連API: `uv_version()`（No.20）は同じバージョン情報を16進数エンコードされた整数値（`UV_VERSION_HEX`）として返却する
- 現在のバージョンは 1.52.1-dev である
- UV_VERSION_HEX の計算式: `(MAJOR << 16) | (MINOR << 8) | PATCH`

---

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

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

### 推奨読解順序

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

バージョン文字列は構造体ではなく、プリプロセッサマクロにより定義される定数文字列である。まずバージョン番号を定義するヘッダファイルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | version.h | `include/uv/version.h` | UV_VERSION_MAJOR/MINOR/PATCH の値、UV_VERSION_IS_RELEASE フラグ、UV_VERSION_HEX の計算式（行33-41） |

**読解のコツ**: `UV_VERSION_HEX`マクロはビットシフトによりMAJOR/MINOR/PATCHを1つの整数に結合する。この値は`uv_version()`で使用され、`uv_version_string()`とは別の表現形式である。

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

`uv_version_string()`関数はversion.cで定義される単純な関数である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | version.c | `src/version.c` | UV_STRINGIFY マクロ（行24-25）、UV_VERSION_STRING_BASE の構成（行27-29）、リリース版/開発版の切替ロジック（行31-35）、uv_version_string() 関数本体（行43-45） |

**主要処理フロー**:
1. **行24-25**: `UV_STRINGIFY` / `UV_STRINGIFY_HELPER` マクロにより数値を文字列リテラルに変換
2. **行27-29**: `UV_VERSION_STRING_BASE` として "MAJOR.MINOR.PATCH" 形式の文字列を構成
3. **行31-35**: `UV_VERSION_IS_RELEASE` の値に応じて、サフィックスを付加するかどうかを決定
4. **行43-45**: `uv_version_string()` が `UV_VERSION_STRING` マクロの展開結果を返却

#### Step 3: 公開ヘッダでのAPI宣言を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv.h | `include/uv.h` | uv_version_string() の外部宣言（行276）、version.h のインクルード（行55） |

**主要処理フロー**:
- **行55**: `#include "uv/version.h"` によりバージョンマクロが読み込まれる
- **行276**: `UV_EXTERN const char* uv_version_string(void);` として公開APIが宣言される

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

```
uv_version_string()          [src/version.c:43]
    |
    +-- UV_VERSION_STRING     [src/version.c:31-35]  (プリプロセッサマクロ)
         |
         +-- UV_VERSION_STRING_BASE  [src/version.c:27-29]
         |    |
         |    +-- UV_STRINGIFY(UV_VERSION_MAJOR)   [include/uv/version.h:33]
         |    +-- UV_STRINGIFY(UV_VERSION_MINOR)   [include/uv/version.h:34]
         |    +-- UV_STRINGIFY(UV_VERSION_PATCH)   [include/uv/version.h:35]
         |
         +-- UV_VERSION_SUFFIX   [include/uv/version.h:37]  (非リリース版のみ)
```

### データフロー図

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

（入力なし）  ───> version.c                ───> const char* "1.52.1-dev"
                  UV_VERSION_STRING
                  マクロの展開結果を返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| version.h | `include/uv/version.h` | ヘッダ | バージョン番号マクロ定義（MAJOR/MINOR/PATCH/IS_RELEASE/SUFFIX/HEX） |
| version.c | `src/version.c` | ソース | uv_version() / uv_version_string() の実装 |
| uv.h | `include/uv.h` | ヘッダ | 公開APIの宣言、version.h のインクルード |
