# 画面設計書 27-Annotated Source - Grammar (v2)

## 概要

本ドキュメントは、CoffeeScript v2の文法定義(grammar.coffee)のソースコード解説画面の設計仕様を定義する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの`grammar.coffee`モジュールのソースコードを解説形式で表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。grammar.coffeeはCoffeeScriptの構文規則を定義し、Jisonパーサー生成器に渡すルールを記述する。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部実装を理解したい開発者向けに、構文解析（パーシング）の規則定義を解説する。Grammar.coffeeはJisonのDSLを使用してCoffeeScriptの文法を定義し、パーサーテーブルを生成する。各ルールはトークンパターンとノード生成アクションで構成される。

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

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. Jison DSLの仕組み理解
4. 各文法ルール（Root、Body、Expression等）の理解

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | Grammar | 主機能 | 文法定義grammar.coffeeのソースコード解説表示（v2） |
| 15 | パーサー生成 | 補助機能 | Jisonパーサー生成の解説を含む（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

## 表示項目

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

### 主要文法ルール

| ルール名 | 説明 | 生成されるノード |
|----------|------|-----------------|
| Root | ルートルール | Root |
| Body | 文の集合 | Block |
| Line | 行（式または文） | - |
| Statement | 純粋な文 | Return, Import等 |
| Expression | 式 | 各種ノード |
| Code | 関数定義 | Code |
| Class | クラス定義 | Class |
| If | 条件分岐 | If |
| For | ループ | For |
| Operation | 演算 | Op |

## イベント仕様

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

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

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

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツールで自動生成されたドキュメント
- CoffeeScript 2.x系のソースコードを対象
- cake build:parserでlib/parser.jsが生成される
- JisonはLALR(1)パーサー生成器

---

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

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

### 推奨読解順序

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

Jison DSLのo関数とgrammarオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | grammar.coffee | `src/grammar.coffee` | o関数の定義 |
| 1-2 | grammar.coffee | `src/grammar.coffee` | grammarオブジェクトの構造 |

**読解のコツ**: o(patternString, action)の形式で、パターンにマッチしたときのアクションを定義。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | grammar.coffee | `src/grammar.coffee` | Rootルールが起点 |

**主要処理フロー**:
1. **Root**: 空またはBodyをラップ
2. **Body**: Line の繰り返し
3. **Line**: ExpressionまたはStatement
4. **Expression**: 各種式ノード

#### Step 3: 主要ルールを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | grammar.coffee | `src/grammar.coffee` | Expression - 式のルール |
| 3-2 | grammar.coffee | `src/grammar.coffee` | Code - 関数定義 |
| 3-3 | grammar.coffee | `src/grammar.coffee` | Class - クラス定義 |

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

```
CoffeeScript.nodes(tokens)
    |
    +-- parser.parse(tokens)
            |
            +-- grammar.Root
            |       |
            |       +-- grammar.Body
            |               |
            |               +-- grammar.Line
            |                       |
            |                       +-- grammar.Expression
            |                       |       |
            |                       |       +-- Value, Code, Class...
            |                       |
            |                       +-- grammar.Statement
            |                               |
            |                               +-- Return, Import...
            |
            +-- nodes.Root (AST)
```

### データフロー図

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

トークン配列         parser.parse()               AST (ノードツリー)
                  --------->
                             |
                             v
                    文法ルールマッチング
                             |
                             v
                    アクション実行（ノード生成）
                             |
                             v
                    Root.compile()   -----> JavaScript
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| grammar.coffee | `src/grammar.coffee` | ソース | 文法定義 |
| grammar.html | `docs/v2/annotated-source/grammar.html` | テンプレート | Docco生成HTML |
| parser.js | `lib/parser.js` | 生成物 | Jisonが生成したパーサー |
| nodes.coffee | `src/nodes.coffee` | ソース | ノードクラス定義 |
| lexer.coffee | `src/lexer.coffee` | ソース | トークン生成 |
| docco.css | `docs/v2/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
