# 機能設計書 150-to_string

## 概要

本ドキュメントは、Hack Standard Library (HSL) の `Regex\to_string` 関数の機能設計を定義する。正規表現パターンを文字列として取得する関数である。

### 本機能の処理概要

**業務上の目的・背景**：正規表現パターンはHackの型システムでは`Pattern<T>`という特殊な型として扱われる。デバッグやログ出力、エラーメッセージの生成など、パターンを文字列として表示する必要がある場面がある。本機能は、Pattern型を単純な文字列に変換する手段を提供する。

**機能の利用シーン**：デバッグ出力、ログ記録、エラーメッセージへのパターン埋め込み、パターンの動的構築・検証など。

**主要な処理内容**：
1. Pattern<Match>を受け取る
2. そのまま文字列として返却

**関連システム・外部連携**：なし。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはUIを持たないライブラリ |

## 機能種別

ユーティリティ / 型変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| $pattern | Pattern<Match> | Yes | 文字列に変換するPCRE正規表現パターン | なし |

### 入力データソース

関数呼び出し時の引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | string | パターンの文字列表現（デリミタ、フラグを含む） |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. Pattern<Match>を受け取る
2. 文字列として返却
   └─ return $pattern
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Pattern を受け取る]
    B --> C[string として返却]
    C --> D[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-150-1 | 直接変換 | Patternをそのまま文字列として返却 | 常時 |
| BR-150-2 | デリミタ保持 | パターンのデリミタ（/など）は保持される | 常時 |
| BR-150-3 | フラグ保持 | パターンのフラグ（i, m, sなど）は保持される | 常時 |

### 計算ロジック

- 変換: `return $pattern` （型システム上はキャストが発生）

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

該当なし（データベース操作を行わない純粋関数）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | Pattern以外の型が渡された場合 | 静的型チェックにより防止 |

### リトライ仕様

該当なし

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

該当なし（データベース操作を行わない）

## パフォーマンス要件

- 時間計算量: O(1) - 単純な型変換
- 空間計算量: O(1) - 追加メモリなし

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

- 特別な考慮事項なし
- `[]`: 純粋コンテキストで実行可能

## 備考

- Hackの型システムでは`Pattern<T>`は特殊な型であり、直接文字列操作ができないため、この関数が必要
- exception.phpでもパターンを文字列化する際に同様のキャストが行われている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | regex.php | `src/regex/regex.php` | Pattern<Match>型の特性を確認 |

**読解のコツ**:
- `Pattern<T>`はPCRE正規表現パターンを表す特殊な文字列型
- `re"/pattern/flags"`リテラルで生成される
- 内部的には文字列だが、型システム上は別の型として扱われる

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | regex.php | `src/regex/regex.php` | to_string関数の定義（231-233行目） |

**主要処理フロー**:
1. **231行目**: `function to_string(Pattern<Match> $pattern)[]: string`
2. **232行目**: `return $pattern;`

この関数は非常にシンプルで、Pattern型を文字列型として返すだけ。Hackの型システムでは暗黙の変換が許可されているため、このような実装が可能。

#### Step 3: 関連する使用例を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | exception.php | `src/regex/exception.php` | パターンを文字列化する別の方法を確認（30-33行目） |

**参考コード（exception.php）**:
```hack
\HH\FIXME\UNSAFE_CAST<\HH\Lib\Regex\Pattern<shape(...)>, string>(
  $pattern,
  'Until we have a to_string() function',
)
```

このコメントは、to_string関数が存在する前の回避策を示している。現在はto_string関数を使用することで、型安全にパターンを文字列化できる。

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

```
Regex\to_string($pattern)
    |
    +-- return $pattern
            └─ Pattern<Match> を string として返却
```

### データフロー図

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

Pattern<Match> ───> 型変換（暗黙のキャスト） ───> string
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| regex.php | `src/regex/regex.php` | ソース | to_string関数の公開インターフェース |
| exception.php | `src/regex/exception.php` | ソース | パターンの文字列化の使用例 |
| RegexTest.php | `tests/regex/RegexTest.php` | テスト | to_string関数のテストケース |
