# 画面設計書 28-Annotated Source - Rewriter (v2)

## 概要

本ドキュメントは、CoffeeScript v2のトークン書き換え処理(rewriter.coffee)のソースコード解説画面の設計仕様を定義する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの`rewriter.coffee`モジュールのソースコードを解説形式で表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。rewriter.coffeeはLexerが生成したトークン列を整形し、暗黙の括弧・ブレースを追加する。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部実装を理解したい開発者向けに、トークン書き換え処理の仕組みを解説する。CoffeeScriptは多くの省略記法を許容するため、Rewriterがそれらを明示的な形式に変換する。例えば、関数呼び出しの括弧やオブジェクトリテラルのブレースを自動挿入する。

**画面へのアクセス方法**：v2 Annotated Sourceのインデックスページ(docs/v2/annotated-source/index.html)から「rewriter.coffee」リンクをクリック、またはURLを直接指定してアクセスする。

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. Rewriterクラスとrewriteメソッドの実装理解
4. 暗黙の括弧・ブレース挿入ロジックの理解

**画面遷移**：
- 遷移元：v2 Annotated Source Index、他のAnnotated Sourceページ
- 遷移先：browser.coffee、cake.coffee、coffeescript.coffee、command.coffee、grammar.coffee、helpers.coffee、index.coffee、lexer.coffee、nodes.coffee、optparse.coffee、register.coffee、repl.coffee、scope.litcoffee、sourcemap.litcoffee

**権限による表示制御**：なし（静的ドキュメントのため全ユーザーがアクセス可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | Rewriter | 主機能 | トークン書き換えrewriter.coffeeのソースコード解説表示（v2） |
| 12 | 暗黙の関数呼び出し | 補助機能 | addImplicitBracesAndParensの解説を含む（v2） |
| 13 | 暗黙のオブジェクトリテラル | 補助機能 | 暗黙のブレース追加処理の解説を含む（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

本画面は静的HTMLドキュメントのため、ユーザー入力項目はない。

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| タイトル | rewriter.coffee | h1テキスト |
| Jump Toメニュー | 他ソースファイルへの遷移リンク一覧 | ドロップダウンリスト |
| セクションリスト | ソースコード解説セクション | 2カラムレイアウト |
| 解説テキスト | 各セクションの解説文 | HTML段落 |
| ソースコード | 対応するCoffeeScriptコード | シンタックスハイライト付きpre |

### 主要メソッド

| メソッド名 | 説明 | 処理内容 |
|------------|------|---------|
| rewrite | メインエントリ | 各書き換えパスを順次実行 |
| removeLeadingNewlines | 先頭改行除去 | 最初のTERMINATOR削除 |
| closeOpenCalls | 関数呼び出し閉じ | CALL_END挿入 |
| closeOpenIndexes | インデックス閉じ | INDEX_END挿入 |
| normalizeLines | 行正規化 | 継続行処理 |
| tagPostfixConditionals | 後置条件タグ付け | if/unless後置 |
| addImplicitBracesAndParens | 暗黙の括弧/ブレース | ()と{}の自動挿入 |

## イベント仕様

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

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

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

各セクションの段落記号をクリックすると、そのセクションへのアンカーリンクがURLに設定される。

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

本画面は静的HTMLドキュメントであり、データベース操作は発生しない。

## メッセージ仕様

本画面は静的ドキュメントのため、動的メッセージは表示されない。

## 例外処理

静的HTMLファイルのため、以下のHTTPエラーのみ発生しうる：
- 404 Not Found: ファイルが見つからない場合
- 500 Internal Server Error: サーバー側の問題

## 備考

- Doccoツールで自動生成されたドキュメント
- CoffeeScript 2.x系のソースコードを対象
- Lexerから呼ばれ、パーサーに渡す前にトークン整形
- 複数パスで段階的にトークン変換

---

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

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

### 推奨読解順序

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

Rewriterが操作するトークン配列の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | rewriter.coffee | `src/rewriter.coffee` | トークン配列の構造 |

**読解のコツ**: トークンは[tag, value, locationData]形式、generatedフラグで生成トークンを識別。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | rewriter.coffee | `src/rewriter.coffee` | rewriteメソッドがエントリーポイント |

**主要処理フロー**:
1. **removeLeadingNewlines**: 先頭の改行トークン削除
2. **closeOpenCalls**: CALL_STARTにCALL_END対応
3. **closeOpenIndexes**: INDEX_STARTにINDEX_END対応
4. **normalizeLines**: 行の正規化
5. **tagPostfixConditionals**: 後置if/unless処理
6. **addImplicitBracesAndParens**: 暗黙の括弧/ブレース
7. **その他の整形処理**

#### Step 3: 暗黙の括弧/ブレース挿入を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | rewriter.coffee | `src/rewriter.coffee` | addImplicitBracesAndParens |

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

```
Lexer.tokenize()
    |
    +-- Rewriter.rewrite(@tokens)
            |
            +-- removeLeadingNewlines()
            |
            +-- closeOpenCalls()
            |
            +-- closeOpenIndexes()
            |
            +-- normalizeLines()
            |
            +-- tagPostfixConditionals()
            |
            +-- addImplicitBracesAndParens()
            |       |
            |       +-- 暗黙の CALL_START/CALL_END
            |       +-- 暗黙の {/}
            |
            +-- rescueStowawayComments()
            |
            +-- addLocationDataToGeneratedTokens()
            |
            +-- return @tokens
```

### データフロー図

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

Lexerからの              Rewriter.rewrite()             整形済み
トークン配列          --------->                      トークン配列
                                |
                                v
                       各パスで段階的変換
                                |
                                v
foo bar            ->    foo(bar)
a: 1               ->    {a: 1}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| rewriter.coffee | `src/rewriter.coffee` | ソース | トークン書き換え |
| rewriter.html | `docs/v2/annotated-source/rewriter.html` | テンプレート | Docco生成HTML |
| lexer.coffee | `src/lexer.coffee` | ソース | トークン生成・Rewriter呼び出し |
| helpers.coffee | `src/helpers.coffee` | ソース | ユーティリティ |
| docco.css | `docs/v2/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
