# 画面設計書 32-Annotated Source - Helpers

## 概要

本ドキュメントは、CoffeeScript v2のヘルパー関数モジュール（helpers.coffee）のソースコード解説ページ「Annotated Source - Helpers」の画面設計書です。Doccoツールによって生成された静的HTMLページとして、CoffeeScriptコンパイラ全体で共有されるユーティリティ関数群を詳細に解説しています。

### 本画面の処理概要

本画面は、CoffeeScriptコンパイラの共通ヘルパー関数モジュール（helpers.coffee）のソースコードを、注釈付きで閲覧できるドキュメントページです。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部で使用される共通ユーティリティ関数の実装を理解したい開発者向けに、文字列操作、配列操作、オブジェクト操作、ロケーションデータ管理、構文エラー処理などの基盤機能の詳細を提供します。Lexer、Rewriter、Nodesなど複数のモジュールから参照されるため、コンパイラ全体の理解に不可欠な基礎知識を習得できます。

**画面へのアクセス方法**：v2ドキュメントページ（docs/v2/index.html）からAnnotated Sourceセクションへ遷移し、「helpers.coffee」リンクをクリックしてアクセスします。または直接 docs/v2/annotated-source/helpers.html にアクセスします。

**主要な操作・処理内容**：
1. ソースコードセクション（右側）と注釈セクション（左側）の並列表示を閲覧
2. 「Jump To」メニューから他のソースファイル解説ページへ遷移
3. セクションアンカーリンク（#section-N）によるページ内ナビゲーション
4. ハイライトされたCoffeeScriptコードの閲覧

**画面遷移**：
- 遷移元：v2ドキュメントページ、Annotated Source - Index
- 遷移先：browser.html, cake.html, coffeescript.html, command.html, grammar.html, index.html, lexer.html, nodes.html, optparse.html, register.html, repl.html, rewriter.html, scope.html, sourcemap.html

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 54 | ユーティリティ関数 | 主機能 | ヘルパー関数helpers.coffeeのソースコード解説表示（v2） |
| 55 | 構文エラー処理 | 補助機能 | throwSyntaxErrorの解説を含む（v2） |
| 8 | Literate CoffeeScript対応 | 補助機能 | invertLiterate関数の解説を含む（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

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

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

| セクションNo | 解説内容 |
|-------------|---------|
| section-1 | モジュール概要：Lexer、Rewriter、Nodesで共有されるヘルパー関数群 |
| section-2 | starts関数：文字列先頭のマッチング |
| section-3 | ends関数：文字列末尾のマッチング |
| section-4-5 | repeat関数：O(log n)での文字列繰り返し |
| section-6 | compact関数：配列からfalsy値を除去 |
| section-7 | count関数：文字列内の出現回数カウント |
| section-8 | merge関数：オブジェクトマージ |
| section-9 | extend関数：シャローコピー |
| section-10 | flatten関数：配列のフラット化 |
| section-11 | del関数：オブジェクトからのキー削除 |
| section-12 | some関数：Array.some互換 |
| section-13 | invertLiterate関数：Literate CoffeeScriptからコード抽出 |
| section-14 | buildLocationData関数：Jisonロケーションデータのマージ |
| section-15 | extractAllCommentTokens関数：コメントトークン抽出 |
| section-16-19 | buildLocationHash、buildTokenDataDictionary関数 |
| section-20-22 | addDataToNode関数：AST ノードへのデータ追加 |
| section-23 | locationDataToString関数：ロケーションデータの文字列化 |
| section-24 | anonymousFileName関数：匿名ファイル名生成 |
| section-25 | baseFileName関数：拡張子除去 |
| section-26 | isCoffee関数：CoffeeScriptファイル判定 |
| section-27 | isLiterate関数：Literateファイル判定 |
| section-28-32 | throwSyntaxError、updateSyntaxError、syntaxErrorToString関数 |
| section-33 | nameWhitespaceCharacter関数：空白文字の名前付け |
| section-34-35 | unicodeCodePointToUnicodeEscapes、replaceUnicodeCodePointEscapes関数 |

## イベント仕様

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

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

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

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツールによって自動生成されたドキュメント
- CSSファイル（docco.css）によりスタイリングされている
- シンタックスハイライトはhighlight.jsを使用
- helpersモジュールはCoffeeScriptコンパイラ全体の基盤となるため、他のAnnotated Sourceページを理解する前に読んでおくことを推奨

---

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

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

### 推奨読解順序

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

ヘルパー関数が操作する主要なデータ構造（ロケーションデータ、トークン、ASTノード）を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | helpers.coffee | `src/helpers.coffee` | ロケーションデータ（first_line, first_column等）の構造を確認 |

**読解のコツ**: buildLocationData関数（96-109行）でロケーションデータの構造を把握する。

#### Step 2: 基本ユーティリティ関数を理解する

文字列・配列・オブジェクト操作の基本関数を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | helpers.coffee | `src/helpers.coffee` | starts, ends, repeat, compact, count, merge, extend, flatten関数 |

**主要処理フロー**:
1. **6-7行**: starts関数 - 文字列先頭のマッチング
2. **10-12行**: ends関数 - 文字列末尾のマッチング
3. **15-22行**: repeat関数 - O(log n)の効率的な文字列繰り返し
4. **25-26行**: compact関数 - 配列からfalsy値を除去
5. **29-33行**: count関数 - 部分文字列の出現回数カウント
6. **38-39行**: merge関数 - オブジェクトマージ
7. **42-45行**: extend関数 - シャローコピー
8. **49-50行**: flatten関数 - Array.flat(Infinity)を使用

#### Step 3: Literate CoffeeScript処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helpers.coffee | `src/helpers.coffee` | invertLiterate関数（67-92行） |

**主要処理フロー**:
- **67-92行**: Markdownテキストからコードブロックを抽出し、非コード部分をコメント化

#### Step 4: ロケーションデータ管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | helpers.coffee | `src/helpers.coffee` | buildLocationData, addDataToNode, locationDataToString関数 |

**主要処理フロー**:
- **96-109行**: buildLocationData - 2つのロケーションデータをマージ
- **150-166行**: addDataToNode - ASTノードにロケーションとコメントを追加
- **175-183行**: locationDataToString - デバッグ用の文字列変換

#### Step 5: 構文エラー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | helpers.coffee | `src/helpers.coffee` | throwSyntaxError, updateSyntaxError, syntaxErrorToString関数 |

**主要処理フロー**:
- **213-223行**: throwSyntaxError - SyntaxErrorを生成してスロー
- **227-233行**: updateSyntaxError - 既存エラーにソース情報追加
- **235-266行**: syntaxErrorToString - 標準形式のエラーメッセージ生成（ファイル名:行:列: error: メッセージ形式）

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

```
[他モジュールからの呼び出し]
        |
        +-- coffeescript.coffee
        |       |
        |       +-- helpers.updateSyntaxError
        |       +-- helpers.count
        |       +-- helpers.anonymousFileName
        |       +-- helpers.extractAllCommentTokens
        |
        +-- lexer.coffee
        |       |
        |       +-- helpers.starts
        |       +-- helpers.count
        |       +-- helpers.invertLiterate
        |       +-- helpers.isLiterate
        |
        +-- nodes.coffee
        |       |
        |       +-- helpers.flatten
        |       +-- helpers.merge
        |       +-- helpers.del
        |       +-- helpers.addDataToNode
        |       +-- helpers.attachCommentsToNode
        |
        +-- command.coffee
                |
                +-- helpers.extend
                +-- helpers.baseFileName
                +-- helpers.isCoffee
                +-- helpers.isLiterate
```

### データフロー図

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

文字列 -----------------> starts/ends --------------> boolean
文字列, n --------------> repeat -------------------> 繰り返し文字列
配列 -------------------> compact/flatten ----------> 加工済み配列
オブジェクト ------------> merge/extend ------------> マージ済みオブジェクト

Literate CS ------------> invertLiterate -----------> 通常CS文字列

first, last loc --------> buildLocationData --------> マージ済みloc
エラー, コード ---------> throwSyntaxError ---------> SyntaxError (throw)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| helpers.coffee | `src/helpers.coffee` | ソース | ヘルパー関数モジュール（326行） |
| helpers.html | `docs/v2/annotated-source/helpers.html` | テンプレート | 本画面のHTMLファイル |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | メインモジュール（helpers利用側） |
| lexer.coffee | `src/lexer.coffee` | ソース | 字句解析器（helpers利用側） |
| nodes.coffee | `src/nodes.coffee` | ソース | ASTノード（helpers利用側） |
| rewriter.coffee | `src/rewriter.coffee` | ソース | トークン書き換え（helpers利用側） |
| command.coffee | `src/command.coffee` | ソース | CLIコマンド（helpers利用側） |
| docco.css | `docs/v2/annotated-source/docco.css` | 設定 | スタイルシート |
