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

## 概要

本ドキュメントは、CoffeeScript v2のREPL（Read-Eval-Print Loop）モジュール（repl.coffee）のソースコード解説ページ「Annotated Source - REPL」の画面設計書です。Doccoツールによって生成された静的HTMLページとして、対話型CoffeeScript環境の実装詳細を解説しています。

### 本画面の処理概要

本画面は、CoffeeScriptの対話型シェル（REPL）を実装するrepl.coffeeのソースコードを、注釈付きで閲覧できるドキュメントページです。

**業務上の目的・背景**：CoffeeScriptのREPL環境の内部動作を理解したい開発者向けに、Node.js REPLの拡張、マルチライン入力、コマンド履歴、トップレベルawaitサポートなどの実装詳細を提供します。独自のREPL拡張や、CoffeeScriptの学習環境構築の参考になります。

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

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

## 関連機能

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

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

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

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

| セクションNo | 解説内容 |
|-------------|---------|
| 冒頭 | 外部依存関係（fs, path, vm, nodeREPL, CoffeeScript, helpers） |
| 中盤 | replDefaults：デフォルト設定（prompt, historyFile, eval関数） |
| 中盤 | runInContext関数：グローバル/ローカルコンテキストでの実行 |
| 中盤 | addMultilineHandler関数：Ctrl-Vによるマルチライン入力 |
| 中盤 | addHistory関数：コマンド履歴の保存と読み込み |
| 終盤 | module.exports.start関数：REPL起動処理 |

## イベント仕様

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

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

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

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツールによって自動生成されたドキュメント
- CSSファイル（docco.css）によりスタイリングされている
- シンタックスハイライトはhighlight.jsを使用
- Node.js 6以上が必要（start関数内で確認）

---

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

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

### 推奨読解順序

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

REPLの設定とコンテキストの構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | repl.coffee | `src/repl.coffee` | replDefaultsオブジェクト（11-69行）の構造を確認 |

**読解のコツ**: replDefaultsはprompt, historyFile, historyMaxInputSize, eval関数を持つ。eval関数がCoffeeScriptコードの評価を担当。

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

module.exports.start関数がREPL起動のエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | repl.coffee | `src/repl.coffee` | module.exports.start関数（174-220行）の構造を把握 |

**主要処理フロー**:
1. **176-180行**: Node.jsバージョンチェック（6以上必須）
2. **182-183行**: CoffeeScript.register()とprocess.argv設定
3. **184-211行**: --transpileオプション時のBabel設定
4. **212行**: nodeREPL.start()でREPL起動
5. **214行**: prelude実行（--require指定時）
6. **216行**: addMultilineHandler追加
7. **217行**: addHistory追加（historyFile指定時）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | repl.coffee | `src/repl.coffee` | replDefaults.eval関数（17-69行） |

**主要処理フロー**:
- **19-25行**: Node.js REPLの入力ラッパー除去
- **28行**: nodesモジュールから必要なASTクラスをrequire
- **32-42行**: トークン化と不要トークンの除去
- **43-51行**: AST構築とクロージャラッピング（top-level await対応）
- **52行**: コンパイルとコンテキスト内実行
- **60-65行**: 非同期結果のawait処理

#### Step 4: マルチライン入力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | repl.coffee | `src/repl.coffee` | addMultilineHandler関数（77-127行） |

**主要処理フロー**:
- **77-86行**: multilineオブジェクトの初期化
- **89-99行**: lineイベントのプロキシ
- **102-127行**: Ctrl-Vキー処理によるマルチラインモード切替

#### Step 5: コマンド履歴を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | repl.coffee | `src/repl.coffee` | addHistory関数（130-168行） |

**主要処理フロー**:
- **132-148行**: 履歴ファイルの読み込みとrepl.historyへの設定
- **150-156行**: lineイベントで履歴ファイルへの書き込み
- **159-160行**: SIGINT/exitイベントでのファイルクローズ
- **163-167行**: .historyコマンドの追加

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

```
module.exports.start(opts)
    |
    +-- CoffeeScript.register()
    |
    +-- nodeREPL.start(opts)
    |       |
    |       +-- replDefaults.eval(input, context, filename, cb)
    |               |
    |               +-- CoffeeScript.tokens(input)
    |               +-- CoffeeScript.nodes(tokens)
    |               +-- ast.compile({bare: yes, ...})
    |               +-- runInContext(js, context, filename)
    |
    +-- addMultilineHandler(repl)
    |       |
    |       +-- inputStream.on('keypress', ...)
    |       +-- repl.on('line', ...)
    |
    +-- addHistory(repl, filename, maxSize)
            |
            +-- fs.readSync / fs.writeSync
            +-- repl.addListener('line', ...)
```

### データフロー図

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

ユーザー入力 -----------> replDefaults.eval -----> CoffeeScript評価
                              |
                              v
                         tokens -> nodes -> compile
                              |
                              v
                         runInContext (vm.runIn*)
                              |
                              v
                         コールバック(cb)で結果返却
                              |
                              v
                         REPL表示（__変数に代入）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| repl.coffee | `src/repl.coffee` | ソース | REPLモジュール（220行） |
| repl.html | `docs/v2/annotated-source/repl.html` | テンプレート | 本画面のHTMLファイル |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイルAPI（repl利用） |
| nodes.coffee | `src/nodes.coffee` | ソース | ASTノード（repl内で直接使用） |
| helpers.coffee | `src/helpers.coffee` | ソース | merge, updateSyntaxError関数 |
| command.coffee | `src/command.coffee` | ソース | --interactive時にREPL起動 |
| docco.css | `docs/v2/annotated-source/docco.css` | 設定 | スタイルシート |
