# 機能設計書 126-正規表現

## 概要

本ドキュメントは、KShootManiaにおける正規表現マッチング・置換機能の設計を記述する。mod_regexp.asモジュールにより、正規表現パターンによる文字列マッチングと置換処理を提供する。

### 本機能の処理概要

本機能は、HSP3の拡張モジュールとして正規表現(Regular Expression)によるパターンマッチングと置換機能を提供する。kshootmania.hspとkshooteditor.hspの両方でインクルードされ、主に譜面エディタでの文字列解析に使用される。

**業務上の目的・背景**：譜面エディタにおいて、KSH形式の譜面データ内の特定パターンを検索・抽出する必要がある。HSP3の標準文字列関数(instr, strmid等)だけでは複雑なパターンマッチングに対応できないため、正規表現モジュールが必要となる。

**機能の利用シーン**：
- 譜面エディタ(kshooteditor.hsp)での`#define`記法の解析（match関数）
- 譜面データ内のパラメータ行からのキー・値の抽出
- 文字列パターンの検索・マッチング全般

**主要な処理内容**：
1. match: 正規表現パターンマッチング（グループキャプチャ対応）
2. 正規表現による文字列の検索・抽出処理

**関連システム・外部連携**：mod_regexp.asモジュール（HSP3用正規表現モジュール）。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主機能 | 譜面データの正規表現パターン解析(kshooteditor.hsp) |

## 機能種別

データ変換処理（正規表現マッチング・置換）

## 入力仕様

### 入力パラメータ

#### match関数

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 対象文字列 | str | Yes | マッチング対象の文字列 | なし |
| パターン | str | Yes | 正規表現パターン文字列 | 有効な正規表現であること |
| グループ指定 | 各種 | No | キャプチャグループの指定 | なし |
| フラグ | int | No | マッチングオプション | なし |

### 入力データソース

プログラム内の文字列変数（譜面データ、ユーザー定義パラメータ等）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| match戻り値 | str | マッチした文字列（キャプチャグループ指定時はグループの内容） |

### 出力先

呼び出し元モジュールの変数

## 処理フロー

### 処理シーケンス

```
1. 正規表現パターンの準備
   └─ パターン文字列を受け取る
2. 対象文字列に対するマッチング実行
   └─ 正規表現エンジンによるパターンマッチ
3. マッチ結果の返却
   └─ マッチした文字列またはキャプチャグループの内容を返す
   └─ マッチしない場合は空文字列を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[正規表現パターン受取]
    B --> C[対象文字列受取]
    C --> D[正規表現マッチング実行]
    D --> E{マッチした?}
    E -->|Yes| F[マッチ文字列/グループを返却]
    E -->|No| G[空文字列を返却]
    F --> H[終了]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-126-01 | グループキャプチャ | ()で囲んだ部分をキャプチャグループとして抽出可能 | match関数使用時 |
| BR-126-02 | 空文字列返却 | マッチしない場合は空文字列""を返す | マッチ失敗時 |

### 計算ロジック

正規表現エンジンの内部実装に依存。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パターンエラー | 不正な正規表現パターン | 呼び出し元で結果を確認 |
| - | マッチなし | パターンに一致する文字列がない | 空文字列が返却される |

### リトライ仕様

リトライ処理なし。

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

該当なし。

## パフォーマンス要件

正規表現パターンの複雑さに依存。単純なパターンであれば高速に動作する。バックトラッキングが多いパターンではパフォーマンス低下の可能性がある。

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

- ReDoS(正規表現によるサービス拒否)攻撃のリスクは低い（ユーザー入力パターンではなくプログラム内蔵パターンのため）

## 備考

- mod_regexp.asファイルはプロジェクトルートに配置されているが、リポジトリ内には含まれていない（gitignore等により除外されている可能性がある）
- kshootmania.hsp 163行目で `#include "mod_regexp.as"` としてインクルード
- kshooteditor.hsp 40行目で `#include "mod_regexp.as"` としてインクルード
- 確認できた使用箇所はkshooteditor.hsp 13827行目の`match(buf2,"\n,(.*)=(.*)",,1)`のみ
- HSP3の標準モジュールまたはサードパーティモジュールとして提供されている正規表現機能

---

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

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

### 推奨読解順序

#### Step 1: モジュールのインクルード箇所を確認する

mod_regexp.asの読み込み元を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | mod_regexp.asのインクルード(163行目) |
| 1-2 | kshooteditor.hsp | `kshooteditor.hsp` | mod_regexp.asのインクルード(40行目) |

**読解のコツ**: mod_regexp.asはHSP3用の正規表現モジュールであり、`match`関数などを提供する。HSP3の標準配布に含まれるモジュールまたはサードパーティモジュールであり、プロジェクト固有のソースコードではない。

#### Step 2: 使用箇所を理解する

match関数の実際の使用例を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | match関数の呼び出し(13827行目) |

**主要処理フロー**:
1. **13827行目**: `if(match(buf2,"\n,(.*)=(.*)",,1)=""):break` - 改行+カンマで始まる「キー=値」パターンのマッチング
   - パターン: `\n,(.*)=(.*)` - 改行、カンマ、キー部分(グループ1)、=、値部分(グループ2)
   - 空文字列が返された場合(マッチなし)はループを抜ける

#### Step 3: strrep(文字列置換)との関連を理解する

正規表現モジュール以外の文字列操作機能との使い分けを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | strrep(HSP3標準命令)による文字列置換の使用例(918-931行目等) |

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

```
kshooteditor.hsp (40行目: #include "mod_regexp.as")
    |
    +-- match関数 (13827行目)
            |
            +-- [mod_regexp.as内部] 正規表現エンジン
                    |
                    +-- パターンコンパイル
                    +-- マッチング実行
                    +-- グループキャプチャ返却

kshootmania.hsp (163行目: #include "mod_regexp.as")
    |
    +-- (直接的な呼び出し箇所は確認されていない)
    +-- strrep (HSP3標準: 正規表現ではない文字列置換)
```

### データフロー図

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

対象文字列(buf2) --------> match関数 ----------------------> マッチ文字列
  + 正規表現パターン         |                              または空文字列
  ("\n,(.*)=(.*)")           +-- 正規表現マッチング
                            +-- グループキャプチャ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mod_regexp.as | `mod_regexp.as` | ソース | 正規表現モジュール本体（ファイルはリポジトリに含まれていない可能性あり） |
| kshootmania.hsp | `kshootmania.hsp` | ソース | mod_regexp.asのインクルード元(163行目) |
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | mod_regexp.asのインクルード元(40行目)、match関数の使用箇所(13827行目) |
