# 画面設計書 34-Annotated Source - Optparse

## 概要

本ドキュメントは、CoffeeScript v2のオプション解析モジュール（optparse.coffee）のソースコード解説ページ「Annotated Source - Optparse」の画面設計書です。Doccoツールによって生成された静的HTMLページとして、コマンドラインオプションパーサーの実装詳細を解説しています。

### 本画面の処理概要

本画面は、CoffeeScriptのコマンドラインオプション解析モジュール（optparse.coffee）のソースコードを、注釈付きで閲覧できるドキュメントページです。

**業務上の目的・背景**：CoffeeScriptのCLIツール（coffeeコマンド、cakeコマンド）で使用されるオプション解析機能の実装を理解したい開発者向けに、OptionParserクラスの構造、ルール構築、引数正規化、ヘルプ生成などの詳細を提供します。独自のCLIツールを作成する際の参考にもなります。

**画面へのアクセス方法**：v2ドキュメントページ（docs/v2/index.html）からAnnotated Sourceセクションへ遷移し、「optparse.coffee」リンクをクリックしてアクセスします。または直接 docs/v2/annotated-source/optparse.html にアクセスします。

**主要な操作・処理内容**：
1. ソースコードセクション（右側）と注釈セクション（左側）の並列表示を閲覧
2. 「Jump To」メニューから他のソースファイル解説ページへ遷移
3. セクションアンカーリンク（#section-N）によるページ内ナビゲーション
4. ハイライトされたCoffeeScriptコードの閲覧

**画面遷移**：
- 遷移元：v2ドキュメントページ、Annotated Source - Index
- 遷移先：browser.html, cake.html, coffeescript.html, command.html, grammar.html, helpers.html, index.html, lexer.html, nodes.html, register.html, repl.html, rewriter.html, scope.html, sourcemap.html

**権限による表示制御**：特になし（静的HTMLページのため、すべてのユーザーが同一の内容を閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | オプションパーサー | 主機能 | オプション解析optparse.coffeeのソースコード解説表示（v2） |

## 画面種別

詳細（ソースコード解説ドキュメント表示）

## URL/ルーティング

`docs/v2/annotated-source/optparse.html`

## 入出力項目

本画面は静的HTMLページのため、ユーザー入力項目はありません。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| - | - | - | - |

## 表示項目

| 項目名 | 説明 | 表示位置 |
|--------|------|----------|
| タイトル | "optparse.coffee" | ヘッダー部 |
| Jump Toメニュー | 他ソースファイルへのリンク一覧 | 右上ドロップダウン |
| セクション一覧 | コード解説セクション（17セクション） | メインコンテンツ |
| 注釈部 | 各セクションの解説テキスト | 左カラム |
| コード部 | シンタックスハイライト付きソースコード | 右カラム |

### 主要セクション内容

| セクションNo | 解説内容 |
|-------------|---------|
| section-1 | helpersからrepeat関数をインポート |
| section-2 | OptionParserクラスの概要と使用例 |
| section-3 | constructorメソッド：ルール宣言とバナーの初期化 |
| section-4-6 | parseメソッド：引数解析とオプションオブジェクト構築 |
| section-7 | helpメソッド：ヘルプテキスト生成 |
| section-8-10 | 正規表現定数（LONG_FLAG, SHORT_FLAG, MULTI_FLAG, OPTIONAL） |
| section-11-13 | buildRules関数：ルールリストとフラグ辞書の構築 |
| section-14 | buildRule関数：個別ルールオブジェクトの構築 |
| section-15-17 | normalizeArguments関数：マルチフラグ展開と位置引数処理 |

## イベント仕様

### 1-Jump Toメニュークリック

「Jump To」リンクをクリックするとドロップダウンメニューが展開され、他のソースファイル解説ページへのリンクが表示されます。リンクをクリックすると対象ページへ遷移します。

### 2-セクションアンカーリンククリック

各セクションの「#」リンクをクリックすると、そのセクションへのパーマリンクがURLハッシュに設定されます。

## データベース更新仕様

本画面は静的HTMLページのため、データベース操作はありません。

## メッセージ仕様

本画面にはユーザー操作に対するメッセージ表示機能はありません。

## 例外処理

本画面は静的HTMLページのため、アプリケーションレベルの例外処理はありません。HTTPレベルでの404エラー（ファイルが見つからない場合）はWebサーバーが処理します。

## 備考

- Doccoツールによって自動生成されたドキュメント
- CSSファイル（docco.css）によりスタイリングされている
- シンタックスハイライトはhighlight.jsを使用
- command.coffeeおよびcake.coffeeで使用される

---

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

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

### 推奨読解順序

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

オプションルールとパース結果の構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | optparse.coffee | `src/optparse.coffee` | buildRule関数（102-113行）でルールオブジェクトの構造を確認 |

**読解のコツ**: ルールオブジェクトはname, shortFlag, longFlag, description, hasArgument, isListプロパティを持つ。

#### Step 2: OptionParserクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | optparse.coffee | `src/optparse.coffee` | OptionParserクラス（14-70行） |

**主要処理フロー**:
1. **21-22行**: constructor - ルール宣言からルールリストを構築
2. **30-58行**: parse - 引数配列を解析してオプションオブジェクトを返却
3. **62-70行**: help - バナーとオプション一覧のヘルプテキストを生成

#### Step 3: ルール構築を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | optparse.coffee | `src/optparse.coffee` | buildRules関数（85-98行） |
| 3-2 | optparse.coffee | `src/optparse.coffee` | buildRule関数（102-113行） |

**主要処理フロー**:
- **85-98行**: buildRules - ルール宣言配列をルールリストとフラグ辞書に変換
- **102-113行**: buildRule - 個別のルール宣言をルールオブジェクトに変換

#### Step 4: 引数正規化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | optparse.coffee | `src/optparse.coffee` | normalizeArguments関数（115-165行） |

**主要処理フロー**:
- **115-165行**: normalizeArguments - マルチフラグ（-abc）の展開、オプション引数の処理、位置引数の分離

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

```
new OptionParser(switches, banner)
    |
    +-- buildRules(switches)
            |
            +-- buildRule(shortFlag, longFlag, description)
                    |
                    +-- LONG_FLAG, SHORT_FLAG, OPTIONAL正規表現でパース

optionParser.parse(args)
    |
    +-- normalizeArguments(args, flagDict)
    |       |
    |       +-- MULTI_FLAG正規表現でマルチフラグ展開
    |       +-- 位置引数の分離
    |
    +-- オプションオブジェクト構築
            |
            +-- options.arguments = positional

optionParser.help()
    |
    +-- バナーとルールリストからヘルプテキスト生成
```

### データフロー図

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

switches配列 -----------> buildRules --------------> ruleList, flagDict
                              |
                              v
                         OptionParser インスタンス

process.argv -----------> normalizeArguments -----> rules, positional
                              |
                              v
                         オプションオブジェクト構築
                              |
                              v
                         {compile: true, watch: true, arguments: [...]}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| optparse.coffee | `src/optparse.coffee` | ソース | オプション解析モジュール（166行） |
| optparse.html | `docs/v2/annotated-source/optparse.html` | テンプレート | 本画面のHTMLファイル |
| command.coffee | `src/command.coffee` | ソース | coffeeコマンド（optparse利用側） |
| cake.coffee | `src/cake.coffee` | ソース | cakeコマンド（optparse利用側） |
| helpers.coffee | `src/helpers.coffee` | ソース | repeat関数提供 |
| docco.css | `docs/v2/annotated-source/docco.css` | 設定 | スタイルシート |
