# 通知設計書 6-errXExpected

## 概要

本ドキュメントは、Nimコンパイラにおけるエラー通知「errXExpected」の設計仕様を定義する。

### 本通知の処理概要

errXExpectedは、コンパイラが特定のトークン（記号、キーワードなど）を期待したが、異なるトークンが現れた場合に出力されるエラー通知である。構文解析（パース）フェーズおよび意味解析フェーズで使用される。

**業務上の目的・背景**：プログラミング言語には文法規則があり、特定の文脈では特定のトークンが期待される。例えば、関数定義の後には括弧が期待され、if文の後には条件式が期待される。期待されるトークンと実際のトークンが異なる場合、開発者に何が期待されていたかを明確に伝え、構文エラーの修正を支援する必要がある。

**通知の送信タイミング**：パーサーまたはセマンティックアナライザーが、特定のトークンを期待したが異なるトークンを検出した時点で発行される。parser.nimのeat関数、docgen.nimのRSTパース処理などから呼び出される。

**通知の受信者**：Nimソースコードをコンパイルしている開発者。構文エラーを修正する必要がある。

**通知内容の概要**：「'{期待されるトークン}' expected」という形式で出力される。$1プレースホルダーに期待されていたトークン（記号やキーワード）が挿入される。

**期待されるアクション**：開発者は、エラーメッセージで指摘された位置を確認し、期待されるトークン（記号、キーワードなど）を追加・修正することが期待される。

## 通知種別

コンパイラ標準出力/標準エラー出力（コンソール通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高（Error） |
| リトライ | なし |

### 送信先決定ロジック

コンパイラオプション`--stdout`が指定されている場合はstdoutに、それ以外はstderrに出力される。

## 通知テンプレート

### コンソール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | Nimコンパイラ |
| メッセージ種別 | Error |
| 形式 | テキスト |

### 本文テンプレート

```
{ファイル名}({行},{列}) Error: '{期待されるトークン}' expected
```

または実際のトークンも表示する場合：
```
{ファイル名}({行},{列}) Error: expected: '{期待}', but got: '{実際}'
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| $1 | 期待されるトークン | 呼び出し元から渡されるトークン名 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 構文解析処理 | eat関数トークン不一致 | p.tok.tokType != tokType | parser.nim |
| 意味解析処理 | タプルコンストラクタ期待 | 非タプル式 | semexprs.nim 2143行目 |
| 意味解析処理 | ブロック期待 | 非ブロック | semexprs.nim 2372行目 |
| RST処理 | meExpectedイベント | RSTパースエラー | docgen.nim 248行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | エラーのため常に出力される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[トークン読み込み] --> B{期待トークン?}
    B -->|一致| C[処理継続]
    B -->|不一致| D[エラーメッセージ生成]
    D --> E[localError/lexMessage呼び出し]
    E --> F[liMessage処理]
    F --> G[メッセージ出力]
    G --> H[エラーカウント増加]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（ファイルベースの処理）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 記号不足 | 括弧、コロン等が不足 | 期待される記号を追加 |
| キーワード誤り | 予約語の誤使用 | 正しいキーワードに修正 |
| 構文エラー | 文法規則違反 | ドキュメントを参照して修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

## セキュリティ考慮事項

- エラーメッセージにはソースコードの一部が含まれる可能性がある
- ファイルパス情報が含まれる
- ローカル開発環境での使用を想定

## 備考

- errXExpectedはエラー（Error）カテゴリに属する
- parser.nimのeat関数では、errGeneratedとしてより詳細なメッセージも使用される
- RSTパース時にはmeExpectedがerrXExpectedにマッピングされる
- 位置情報（行、列）が常に含まれる

---

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

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

### 推奨読解順序

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

errXExpected通知の基盤となるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lineinfos.nim | `compiler/lineinfos.nim` | TMsgKind列挙型でerrXExpectedの定義を確認（35行目） |
| 1-2 | lineinfos.nim | `compiler/lineinfos.nim` | MsgKindToStr配列でメッセージ文字列を確認（126行目） |

**読解のコツ**: errXExpectedは非致命的エラーセクションに定義されている。$1プレースホルダーに期待されるトークンが挿入される。

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

通知発行の起点となるファイル・関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | parser.nim | `compiler/parser.nim` | eat関数でのトークン期待処理（250-257行目） |
| 2-2 | semexprs.nim | `compiler/semexprs.nim` | タプルコンストラクタ期待エラー（2143行目） |
| 2-3 | semexprs.nim | `compiler/semexprs.nim` | ブロック期待エラー（2372行目） |
| 2-4 | docgen.nim | `compiler/docgen.nim` | RSTパースエラーのマッピング（248行目） |

**主要処理フロー**:
1. **parser.nim 250-257行目**: eat関数 - トークン一致確認、不一致時にlexMessage
2. **semexprs.nim 2143行目**: localError(conf, info, errXExpected, "tuple constructor")

#### Step 3: メッセージ出力処理を理解する

エラーメッセージの出力処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | msgs.nim | `compiler/msgs.nim` | localErrorテンプレート（635-636行目） |
| 3-2 | lexer.nim | `compiler/lexer.nim` | lexMessage関数 |

**主要処理フロー**:
- **parser.nim 256-257行目**: より詳細なメッセージ形式 "expected: '{expected}', but got: '{actual}'"
- **semexprs.nim 2143行目**: errXExpectedを直接使用

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

```
構文解析/意味解析
    │
    ├─ parser.nim::eat(p, tokType)
    │      │
    │      └─ p.tok.tokType != tokType
    │             │
    │             └─ lexMessage(p.lex, errGenerated, "expected: ...")
    │
    └─ semexprs.nim::semExpr
           │
           └─ 期待構造不一致
                  │
                  └─ localError(c.config, n.info, errXExpected, "tuple constructor")
                         │
                         └─ liMessage
                                │
                                └─ handleError
```

### データフロー図

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

現在のトークン ───▶ eat(p, tokType) ───────▶ 標準エラー出力
期待トークン        │                        "'{tokType}' expected"
                    ▼
               トークン比較
                    │
                    ▼
               lexMessage/localError
                    │
                    ▼
               liMessage
                    │
                    ▼
               handleError
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lineinfos.nim | `compiler/lineinfos.nim` | ソース | TMsgKind定義、メッセージ文字列定義 |
| parser.nim | `compiler/parser.nim` | ソース | eat関数（トークン期待処理） |
| semexprs.nim | `compiler/semexprs.nim` | ソース | 意味解析での期待エラー |
| docgen.nim | `compiler/docgen.nim` | ソース | RSTパースエラーのマッピング |
| msgs.nim | `compiler/msgs.nim` | ソース | localErrorテンプレート |
| lexer.nim | `compiler/lexer.nim` | ソース | lexMessage関数 |
