# 画面設計書 20-Annotated Source - REPL

## 概要

本ドキュメントは、CoffeeScript v1のソースコード解説ページ「Annotated Source - REPL」の画面設計書である。Doccoを使用して自動生成されたドキュメントページで、repl.coffeeのソースコードとその解説を並列表示する。

### 本画面の処理概要

この画面は、CoffeeScriptの対話型実行環境（REPL: Read-Eval-Print Loop）を実装するrepl.coffeeのソースコードを、コメントと実装コードを並列表示する形式で解説するドキュメントページである。`coffee`コマンドを引数なしで実行した際、または`coffee -i`で起動されるインタラクティブシェルを提供する。

**業務上の目的・背景**：対話型開発環境の実装パターンを理解するために必要な画面である。Node.jsのREPLモジュールを拡張してCoffeeScript対応にする方法、マルチライン入力のサポート、コマンド履歴の管理など、実践的なREPL実装技術を学ぶことができる。言語開発やツール開発の参考となる。

**画面へのアクセス方法**：v1ドキュメントページ（docs/v1/index.html）のAnnotated Sourceセクション、またはAnnotated Source - Index（docs/v1/annotated-source/index.html）から「repl.coffee」リンクをクリックしてアクセスする。直接URL（docs/v1/annotated-source/repl.html）でもアクセス可能である。

**主要な操作・処理内容**：
1. ソースコードとコメントの並列表示を閲覧する
2. 「Jump To...」メニューから他のソースファイル解説ページへ遷移する
3. セクション番号リンク（pilcrow）をクリックして特定のコードセクションへの直接リンクを取得する
4. start、replDefaults、addMultilineHandler、addHistory等の解説を確認する

**画面遷移**：
- 遷移元: v1ドキュメント（docs/v1/index.html）、Annotated Source - Index（docs/v1/annotated-source/index.html）、他のAnnotated Sourceページ
- 遷移先: Jump Toメニューから他のすべてのAnnotated Sourceページ

**権限による表示制御**：本画面は静的HTMLファイルであり、認証・認可の仕組みは存在しない。すべてのユーザーが同一の内容を閲覧できる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 38 | CoffeeScript REPL | 主機能 | REPLモジュールrepl.coffeeのソースコード解説表示 |
| 39 | マルチラインサポート | 補助機能 | addMultilineHandlerの解説を含む |
| 40 | コマンド履歴 | 補助機能 | addHistoryの解説を含む |

## 画面種別

詳細（ドキュメント閲覧画面）

## URL/ルーティング

- URL: `/docs/v1/annotated-source/repl.html`
- 静的HTMLファイルとして配置

## 入出力項目

本画面は静的HTMLであり、ユーザー入力項目は存在しない。

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| - | - | - | - | 入力項目なし |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ページタイトル | テキスト | "repl.coffee" |
| ソースコード | HTML（ハイライト済み） | repl.coffeeの全ソースコード |
| コメント/解説 | HTML | 各コードセクションに対応する解説テキスト |
| Jump Toメニュー | リンクリスト | 他のソースファイルへのナビゲーション |
| セクションリンク | アンカーリンク | 各セクションへの直接リンク（#section-N形式） |

## イベント仕様

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

Jump Toリンクをクリックすると、対応するソースコード解説ページへ遷移する。

- イベントタイプ: クリック
- 対象要素: `#jump_to a.source`
- 処理内容: 指定されたHTMLファイルへのページ遷移

### 2-セクションリンククリック

各セクションの段落記号（pilcrow: &#182;）をクリックすると、そのセクションへの直接リンクがブラウザのURLバーに表示される。

- イベントタイプ: クリック
- 対象要素: `a.pilcrow`
- 処理内容: URLハッシュの変更（#section-N）

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

### 操作別データベース影響一覧

本画面は静的HTMLファイルであり、データベース操作は発生しない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベース操作なし |

## メッセージ仕様

本画面は静的HTMLであり、動的なメッセージ表示機能は存在しない。

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| - | - | - | - |

## 例外処理

本画面は静的HTMLであり、アプリケーションレベルの例外処理は存在しない。
- HTTPレベル: 404 Not Found（ファイルが存在しない場合）
- HTTPレベル: 500 Internal Server Error（サーバー設定エラー等）

## 備考

- 本画面はDoccoツールによって自動生成されたHTMLファイルである
- ソースコードはsrc/repl.coffeeから生成される
- Node.jsのreplモジュールを基盤として使用
- command.coffeeから--interactive時に呼び出される
- スタイルシートはdocco.cssを使用
- v2系にも同様のページ（docs/v2/annotated-source/repl.html）が存在する

---

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

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

### 推奨読解順序

#### Step 1: 依存関係とデフォルト設定を理解する

REPLモジュールの初期化設定を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | repl.coffee | `src/repl.coffee` | 行1-6: 依存モジュールのインポート |
| 1-2 | repl.coffee | `src/repl.coffee` | 行11-16: `replDefaults`オブジェクト |
| 1-3 | repl.coffee | `src/repl.coffee` | `prompt`、`historyFile`、`eval`関数 |

**読解のコツ**: replDefaultsのeval関数は、入力をCoffeeScriptとしてコンパイル・実行する処理の中核である。

#### Step 2: eval関数を理解する

CoffeeScript入力の評価処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | repl.coffee | `src/repl.coffee` | 行17-69: eval関数の実装 |
| 2-2 | repl.coffee | `src/repl.coffee` | 入力のアンラップ処理 |
| 2-3 | repl.coffee | `src/repl.coffee` | AST操作による__変数への代入 |

**主要処理フロー**:
1. **入力正規化**: Node.js REPLのラップを解除
2. **トークン化**: `CoffeeScript.tokens(input)`
3. **AST生成**: `CoffeeScript.nodes(tokens)`
4. **__への代入ラップ**: 結果を`__`変数に格納
5. **コンパイル・実行**: `vm.runInContext`

#### Step 3: マルチラインとヒストリーを理解する

高度な機能の実装を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | repl.coffee | `src/repl.coffee` | 行77以降: `addMultilineHandler`関数 |
| 3-2 | repl.coffee | `src/repl.coffee` | `addHistory`関数 |
| 3-3 | repl.coffee | `src/repl.coffee` | `start`関数 - エントリーポイント |

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

```
repl.html (生成されたHTML)
    |
    +-- repl.coffee (ソースファイル)
           |
           +-- Node.js repl モジュール
           |      +-- nodeREPL.start()
           |
           +-- coffeescript.coffee
           |      +-- tokens()
           |      +-- nodes()
           |
           +-- nodes.coffee
           |      +-- Block, Assign, Value, Literal
           |
           +-- helpers.coffee
           |      +-- merge, updateSyntaxError
           |
           +-- vm (Node.js)
           |      +-- runInContext
           |      +-- runInThisContext
           |
           +-- fs (Node.js)
                  +-- readFileSync (履歴読込)
                  +-- appendFileSync (履歴保存)
```

### データフロー図

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

ユーザー入力       --->   replDefaults.eval()    --->   評価結果
(CoffeeScript)              |
       |                    +-- 入力アンラップ
       |                    +-- トークン化
       |                    +-- AST生成
       |                    +-- __代入ラップ
       |                    +-- コンパイル
       |                    +-- vm.runInContext
       |
       v
プロンプト: 'coffee> '
       |
       +-- 通常モード: 1行評価
       +-- マルチラインモード: 複数行蓄積

履歴ファイル       <-->   addHistory()           <-->   .coffee_history
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| repl.html | `docs/v1/annotated-source/repl.html` | 生成HTML | 本画面のHTMLファイル |
| repl.coffee | `src/repl.coffee` | ソース | REPL実装 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイル処理 |
| nodes.coffee | `src/nodes.coffee` | ソース | AST操作 |
| helpers.coffee | `src/helpers.coffee` | ソース | ヘルパー関数 |
| command.coffee | `src/command.coffee` | ソース | REPL起動元 |
| docco.css | `docs/v1/annotated-source/docco.css` | スタイル | ページスタイル定義 |
