# 機能設計書 16-マクロシステム

## 概要

本ドキュメントは、Nimコンパイラにおけるマクロシステム（マジック関数処理）の設計仕様を記述する。この機能はコンパイラ組み込みのマジック関数および型特性の処理を担当する。

### 本機能の処理概要

マクロシステム（semmagic.nim）は、オーバーロード解決後のマジック関数呼び出しを処理する機能である。`addr`、`typeof`、`new`などのコンパイラ組み込み関数や、型特性（type traits）の評価を行う。

**業務上の目的・背景**：Nimには言語組み込みの特殊な関数（マジック関数）が存在し、これらは通常の関数呼び出しとは異なる特別な意味解析が必要である。例えば`addr`は左辺値を要求し、`typeof`はコンパイル時に型情報を取得する。これらの特殊処理を集約することで、セマンティック解析の一貫性と保守性を確保する。

**機能の利用シーン**：オーバーロード解決の後、選択された関数がマジック関数である場合に呼び出される。`addr x`、`sizeof(T)`、`typeof(expr)`、`new(ref T)`などの組み込み構文で使用される。また、型特性（`typeToString`、`arity`、`genericHead`等）の評価時にも使用される。

**主要な処理内容**：
1. マジック関数のディスパッチ（mAddr、mTypeOf、mNew等）
2. 型特性の評価
3. 特殊な引数要件のチェック（左辺値、定数式等）
4. コンパイル時情報の取得（instantiationInfo等）
5. 配列アクセスの特殊処理

**関連システム・外部連携**：オーバーロード解決（sigmatch.nim）の結果を受け取り、セマンティック解析（sem.nim）の一部として動作する。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | nimコンパイラメイン画面 | 補助機能 | マジック関数はセマンティック解析の一部 |

## 機能種別

コンパイラ組み込み処理 / 型特性評価

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| c | PContext | Yes | セマンティック解析コンテキスト | nil不可 |
| n | PNode | Yes | 関数呼び出しAST | nil不可 |
| magic | TMagic | Yes | マジック関数の種類 | 有効なTMagic値 |

### 入力データソース

- オーバーロード解決で選択された関数シンボル
- 関数呼び出しの引数AST

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 処理済みAST | PNode | マジック関数の評価結果 |
| 型情報 | PType | 型特性評価の結果 |

### 出力先

- 変換されたASTとして呼び出し元に返却

## 処理フロー

### 処理シーケンス

```
1. マジック種別の判定
   └─ TMagicの値で分岐
2. 引数の検証
   └─ 左辺値チェック、定数式評価等
3. 特殊処理の実行
   └─ マジックごとの処理
4. 結果ASTの構築
   └─ 型情報を含む変換済みAST
```

### フローチャート

```mermaid
flowchart TD
    A[magicsAfterOverloadResolution開始] --> B{magic種別判定}
    B -->|mAddr| C[semAddr: アドレス取得]
    B -->|mTypeOf| D[semTypeOf: 型取得]
    B -->|mNew| E[addDefaultFieldForNew]
    B -->|mArrGet| F[semArrGet: 配列アクセス]
    B -->|mArrPut| G[semArrPut: 配列代入]
    B -->|mTypeTrait| H[semTypeTraits: 型特性]
    B -->|その他| I[個別処理]
    C --> J[結果返却]
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-16-01 | 左辺値要求 | addr演算子は左辺値を要求 | mAddr |
| BR-16-02 | 型特性評価 | ジェネリックパラメータは評価を遅延 | tyGenericParam |
| BR-16-03 | コンパイル時評価 | instantiationInfo等はコンパイル時に評価 | mInstantiationInfo |

### 計算ロジック

- 型特性arity: `operand.len - ord(operand.kind==tyProc)` - プロシージャ型は戻り値を除外
- tupleLen: `operand.len` - タプルの要素数

## データベース操作仕様

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| errExprHasNoAddress | 値エラー | 左辺値でない式にaddr | エラーメッセージ表示 |
| errIntLiteralExpected | 引数エラー | 整数リテラルが必要な場所 | エラーメッセージ表示 |

## トランザクション仕様

該当なし。

## パフォーマンス要件

- マジック関数はコンパイル時のみ処理
- 型特性評価はコンパイル時に完結

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

- addr演算子はポインタを生成するため、メモリ安全性に注意

## 備考

- TMagic列挙型はast.nimで定義
- 型特性関数はtypetraitsモジュールと連携

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | semmagic.nim | `compiler/semmagic.nim` | ファイル先頭コメント（10-11行目）: 機能概要 |
| 1-2 | semmagic.nim | `compiler/semmagic.nim` | magicsAfterOverloadResolution()関数: メインエントリーポイント |

#### Step 2: 主要な処理関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | semmagic.nim | `compiler/semmagic.nim` | semAddr()関数（33-41行目）: アドレス取得処理 |
| 2-2 | semmagic.nim | `compiler/semmagic.nim` | semTypeOf()関数（43-66行目）: typeof処理 |
| 2-3 | semmagic.nim | `compiler/semmagic.nim` | evalTypeTrait()関数（185-268行目）: 型特性評価 |
| 2-4 | semmagic.nim | `compiler/semmagic.nim` | semArrGet()関数（74-103行目）: 配列アクセス |

#### Step 3: 型特性評価を詳しく理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | semmagic.nim | `compiler/semmagic.nim` | tyUserDefinedGenerics定数（156-157行目）: ジェネリック型分類 |
| 3-2 | semmagic.nim | `compiler/semmagic.nim` | 型特性case文（198-268行目）: 各特性の処理 |

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

```
magicsAfterOverloadResolution()
    │
    ├─ semAddr() [mAddr]
    │
    ├─ semTypeOf() [mTypeOf]
    │      └─ makeTypeDesc()
    │
    ├─ semArrGet() / semArrPut() [mArrGet/mArrPut]
    │      └─ semSubscript() / semAsgn()
    │
    ├─ semTypeTraits() [mTypeTrait]
    │      └─ evalTypeTrait()
    │
    └─ 各種magic固有処理
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| semmagic.nim | `compiler/semmagic.nim` | ソース | マジック関数処理（約703行） |
| ast.nim | `compiler/ast.nim` | ソース | TMagic列挙型定義 |
| sem.nim | `compiler/sem.nim` | ソース | セマンティック解析メイン（semmagic.nimをinclude） |
| typetraits.nim | `lib/pure/typetraits.nim` | 標準ライブラリ | 型特性関数定義 |
