# 機能設計書 44-option関数

## 概要

本ドキュメントは、Cakefileでコマンドラインオプションを定義するためのoption関数の設計を記載する。

### 本機能の処理概要

option関数は、Cakefileにおいてコマンドラインオプションを定義するためのグローバル関数である。ショートフラグ（-o形式）、ロングフラグ（--output形式）、および説明を受け取り、内部のswitches配列に登録する。登録されたオプションは、cakeコマンド実行時にOptionParserによってパースされ、タスクのaction関数に渡されるoptionsオブジェクトに格納される。

**業務上の目的・背景**：ビルドタスクの実行時に、コンパイル対象ディレクトリの指定や詳細出力モードの有効化など、動的にパラメータを指定したいケースがある。option関数により、Cakefileでカスタムオプションを宣言的に定義でき、ユーザーはcakeコマンド実行時に`--output dir`のような形式でパラメータを渡せるようになる。

**機能の利用シーン**：
- ビルド出力先ディレクトリを指定するオプションを定義するとき
- デバッグモードやverboseモードのフラグを定義するとき
- 環境（development/production）を指定するオプションを定義するとき
- タスクに渡すカスタムパラメータを定義するとき

**主要な処理内容**：
1. ショートフラグ（letter）、ロングフラグ（flag）、説明（description）を受け取る
2. switches配列に[letter, flag, description]形式の配列を追加
3. 登録されたオプションはcake実行時にOptionParserで処理される

**関連システム・外部連携**：
- Cakeタスクランナー（cake.coffee）
- OptionParser（optparse.coffee）
- task関数（オプション値の受け渡し先）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Annotated Source - Cake | 補助機能 | オプション定義関数の解説を含む |
| 38 | Annotated Source - Cake | 補助機能 | オプション定義関数の解説を含む（v2） |

## 機能種別

設定定義 / オプション登録

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| letter | string | Yes | ショートオプション（例: '-o'） | 先頭がハイフンの文字列 |
| flag | string | Yes | ロングオプション（例: '--output [DIR]'） | 先頭が--の文字列。値を取る場合は[PLACEHOLDER]を含む |
| description | string | Yes | オプションの説明。ヘルプ表示時に使用 | 文字列 |

### 入力データソース

Cakefile内でのoption関数呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| switches[n] | array | [letter, flag, description]形式の配列 |

### 出力先

内部のswitches配列（モジュールスコープ）

## 処理フロー

### 処理シーケンス

```
1. オプション情報の配列化
   └─ [letter, flag, description]配列を作成

2. switches配列への追加
   └─ switches.push()で末尾に追加

3. OptionParser初期化時に参照
   └─ cake実行時にnew optparse.OptionParser(switches)で使用
```

### フローチャート

```mermaid
flowchart TD
    A[option関数呼び出し] --> B["配列作成: [letter, flag, description]"]
    B --> C["switches.push(配列)"]
    C --> D[終了]

    E[cake コマンド実行] --> F[Cakefile実行]
    F --> G[option呼び出し複数回]
    G --> H["new OptionParser(switches)"]
    H --> I[oparse.parse でオプション解析]
    I --> J[task.action に options を渡す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | オプションフォーマット | ロングフラグは--で始まり、値を取る場合は[NAME]形式のプレースホルダーを含む | 全オプション |
| BR-02 | ヘルプ表示 | 引数なしでcakeを実行した場合、登録されたオプションのヘルプも表示 | switches.lengthが0より大きい場合 |
| BR-03 | 値の格納 | パースされたオプション値はoptionsオブジェクトのプロパティとして格納 | cake実行時 |

### 計算ロジック

option関数の実装（cake.coffee 37-38行目）:
```coffeescript
option: (letter, flag, description) ->
  switches.push [letter, flag, description]
```

OptionParserでのオプション形式例:
```coffeescript
# --output VALUE 形式（値を取るオプション）
option '-o', '--output [DIR]', 'output directory'

# --verbose 形式（フラグオプション）
option '-v', '--verbose', 'enable verbose output'
```

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

本機能ではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | なし | option関数自体はエラーを発生させない | - |

不正なフォーマットのオプションが定義された場合のエラーは、OptionParser.parse実行時に発生する可能性がある。

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- オプション登録は即時完了（O(1)の計算量）
- Cakefile読み込み時に全オプションが一度に登録される

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

- オプション値はユーザー入力であるため、タスク内で使用する際は適切なバリデーションを行うこと
- ファイルパスを受け取るオプションでは、パストラバーサルに注意

## 備考

- option関数はhelpers.extendによってglobalオブジェクトに追加されるため、Cakefile内ではrequireなしで使用可能
- OptionParserの詳細な動作はoptparse.coffeeを参照
- 定義されたオプションは引数なしで`cake`を実行した際のヘルプに表示される

---

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

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

### 推奨読解順序

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

option関数が使用するswitches配列の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | cake.coffee | `src/cake.coffee` | switches変数の定義（22行目） |

**読解のコツ**: `switches = []` は空配列の初期化。各オプションは `[letter, flag, description]` 形式の配列として格納される。

#### Step 2: option関数の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cake.coffee | `src/cake.coffee` | option関数の定義（37-38行目） |

**主要処理フロー**:
- **37行目**: `option: (letter, flag, description) ->` - 関数定義
- **38行目**: `switches.push [letter, flag, description]` - 配列への追加

#### Step 3: OptionParserとの連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cake.coffee | `src/cake.coffee` | OptionParser初期化（54行目） |
| 3-2 | cake.coffee | `src/cake.coffee` | ヘルプ表示時のswitches参照（72行目） |

**主要処理フロー**:
- **54行目**: `oparse = new optparse.OptionParser switches` - switchesを渡してOptionParser初期化
- **72行目**: `console.log oparse.help() if switches.length` - オプションがある場合ヘルプを表示

#### Step 4: OptionParserの内部を理解する（任意）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | optparse.coffee | `src/optparse.coffee` | OptionParserクラスの実装 |

**読解のコツ**: OptionParserはswitches配列を解析し、正規表現でコマンドライン引数とマッチングしてoptionsオブジェクトを構築する。

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

```
Cakefile
    │
    └─ option '-o', '--output [DIR]', 'output directory'
           │
           └─ global.option (cake.coffee:37)
                  │
                  └─ switches.push [letter, flag, description]

cake コマンド実行
    │
    └─ exports.run (cake.coffee:49)
           │
           ├─ new optparse.OptionParser(switches) (54行目)
           │       │
           │       └─ switches配列からオプションルールを構築
           │
           └─ oparse.parse(args) (57行目)
                   │
                   └─ options オブジェクト生成 → task.action(options)
```

### データフロー図

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

Cakefile ─▶ option(letter, flag, description)
                      │
                      └─▶ switches.push([...])
                                │
                                ▼
                          switches配列
                                │
cake実行 ────────────────────▶ OptionParser(switches)
                                     │
                                     ▼
コマンドライン引数 ───────────▶ oparse.parse(args)
                                     │
                                     ▼
                               options オブジェクト
                                     │
                                     ▼
                          task.action(options) ──▶ タスク実行
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cake.coffee | `src/cake.coffee` | ソース | option関数の実装、switches配列の管理 |
| optparse.coffee | `src/optparse.coffee` | ソース | OptionParserクラス（オプション解析） |
| helpers.coffee | `src/helpers.coffee` | ソース | extend関数（globalへの登録に使用） |
| Cakefile | プロジェクトルート | 設定 | ユーザーがoption関数を呼び出すファイル |
