# 画面設計書 25-Annotated Source - Lexer (v2)

## 概要

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

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの`lexer.coffee`モジュールのソースコードを解説形式で表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。lexer.coffeeはソースコードをトークン列に変換する字句解析を担当する。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部実装を理解したい開発者向けに、字句解析（レキシング）の仕組みを解説する。Lexerクラスはソースコードを読み取り、識別子、文字列、数値、演算子などのトークンに分解する。各トークンには位置情報（行番号、列番号）が付与され、これはエラーメッセージやソースマップ生成に使用される。

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

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. Lexerクラスとtokenizeメソッドの実装理解
4. 各種トークナイザ（identifierToken、stringToken等）の理解

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | Lexer | 主機能 | 字句解析器lexer.coffeeのソースコード解説表示（v2） |
| 9 | 文字列補間処理 | 補助機能 | matchWithInterpolationsの解説を含む（v2） |
| 10 | JSXトークン処理 | 補助機能 | jsxTokenの解説を含む（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

## 表示項目

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

### 主要解説セクション

| セクション | 内容 | 対応する主要処理 |
|------------|------|-----------------|
| 概要 | Lexerの役割とトークン形式 | [tag, value, locationData] |
| Lexerクラス | クラス定義と主要メソッド | exports.Lexer |
| tokenize | メイントークン化メソッド | tokenize(code, opts) |
| clean | コード前処理 | BOM除去、改行正規化 |
| identifierToken | 識別子トークン | 変数名、キーワード |
| stringToken | 文字列トークン | 'string', "string" |
| numberToken | 数値トークン | 整数、浮動小数点 |
| jsxToken | JSXトークン | <Component /> |
| regexToken | 正規表現トークン | /pattern/ |
| literalToken | リテラルトークン | 演算子、括弧等 |

## イベント仕様

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

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

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

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツールで自動生成されたドキュメント
- CoffeeScript 2.x系のソースコードを対象
- lexer.coffeeはコンパイラの中で最初に実行される処理
- Rewriterと連携してトークン列を最終形に整形

---

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

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

### 推奨読解順序

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

Lexerが生成するトークンの形式: [tag, value, locationData]を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lexer.coffee | `src/lexer.coffee` | トークン形式の定義を理解 |

**読解のコツ**: locationDataは{first_line, first_column, last_line, last_column}の構造でJison互換形式。

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

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

**主要処理フロー**:
1. **tokenize開始**: オプション初期化、状態変数リセット
2. **cleanメソッド**: BOM除去、改行正規化、literate処理
3. **メインループ**: while @chunk = code[i..]
4. **各トークナイザ呼び出し**: identifierToken, stringToken等
5. **Rewriter実行**: 最終トークン列整形

#### Step 3: 各トークナイザを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | lexer.coffee | `src/lexer.coffee` | identifierToken - 識別子とキーワード |
| 3-2 | lexer.coffee | `src/lexer.coffee` | stringToken - 文字列リテラル |
| 3-3 | lexer.coffee | `src/lexer.coffee` | numberToken - 数値リテラル |

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

```
CoffeeScript.tokens(code)
    |
    +-- Lexer.tokenize(code, opts)
            |
            +-- clean(code)  # 前処理
            |
            +-- while @chunk = code[i..]
            |       |
            |       +-- identifierToken()
            |       +-- commentToken()
            |       +-- whitespaceToken()
            |       +-- lineToken()
            |       +-- stringToken()
            |       +-- numberToken()
            |       +-- jsxToken()
            |       +-- regexToken()
            |       +-- jsToken()
            |       +-- literalToken()
            |
            +-- closeIndentation()
            |
            +-- Rewriter.rewrite(@tokens)
```

### データフロー図

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

CoffeeScript       Lexer.tokenize()            トークン配列
ソースコード    --------->                   --------->
                          |
                          v
                   clean() - 前処理
                          |
                          v
               各トークナイザ実行
                          |
                          v
               Rewriter.rewrite()  -----> 最終トークン配列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lexer.coffee | `src/lexer.coffee` | ソース | 字句解析器の実装 |
| lexer.html | `docs/v2/annotated-source/lexer.html` | テンプレート | Docco生成HTML |
| rewriter.coffee | `src/rewriter.coffee` | ソース | トークン書き換え |
| helpers.coffee | `src/helpers.coffee` | ソース | ユーティリティ関数 |
| docco.css | `docs/v2/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
