# 機能設計書 10-Kernelモジュール

## 概要

本ドキュメントは、mrubyのKernelモジュールの設計を記述する。全オブジェクトに共通するメソッド（p, print, raise等）を提供するモジュールである。

### 本機能の処理概要

KernelモジュールはRubyの全オブジェクトにミックスインされるモジュールであり、基本的なメソッド群（inspect, class, dup, clone, freeze, raise, respond_to?, is_a?, block_given?等）を定義する。Objectクラスにincludeされることで全オブジェクトで利用可能となる。

**業務上の目的・背景**：Rubyの設計では、全オブジェクトに共通するメソッドはKernelモジュールに定義される。これにより、Objectクラスの直接的なメソッド定義量を抑えつつ、全オブジェクトに基本メソッドを提供できる。

**機能の利用シーン**：オブジェクトのイントロスペクション（`class`, `is_a?`, `respond_to?`）、オブジェクトのコピー（`dup`, `clone`）、例外発生（`raise`）、ブロック判定（`block_given?`）、出力（`p`, `print`）、等値判定（`===`, `<=>`）。

**主要な処理内容**：
1. `mrb_func_basic_p()` - メソッドが基本C関数で実装されているか判定
2. `mrb_obj_inspect()` - オブジェクトの人間可読表現生成
3. `mrb_f_block_given_p_m()` - ブロック渡し判定
4. `mrb_f_raise()` - 例外発生
5. `obj_respond_to()` - メソッド応答判定
6. `mrb_obj_freeze()` / `mrb_obj_frozen()` - オブジェクトの凍結
7. ROMメソッドテーブルによる約28メソッドの定義

**関連システム・外部連携**：Objectクラス（include先）、VM（ブロック判定でコールスタック走査）、例外処理。

**権限による制御**：`raise`, `block_given?`, `iterator?`はprivateメソッドとして定義される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングにデータなし |

## 機能種別

オブジェクト基本メソッド提供

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| mrb | mrb_state* | Yes | mrubyインタプリタ状態 | NULLでないこと |
| self | mrb_value | Yes | レシーバオブジェクト | - |

### 入力データソース

Rubyプログラムからのメソッド呼び出し。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| mrb_value | mrb_value | 各メソッドの戻り値 |

### 出力先

呼び出し元への戻り値。

## 処理フロー

### 処理シーケンス

```
1. mrb_init_kernel() - Kernelモジュール初期化
   ├─ mrb_define_module_id(Kernel) - モジュール定義
   ├─ mrb_define_class_method_id(raise) - クラスメソッド定義
   ├─ MRB_MT_INIT_ROM(kernel_rom_entries) - ROMメソッドテーブル初期化
   └─ mrb_include_module(Object, Kernel) - ObjectにKernelをinclude
2. Kernelメソッド群
   ├─ mrb_obj_inspect() - inspect実装（インスタンス変数表示）
   ├─ mrb_f_block_given_p_m() - ブロック判定（コールスタック走査）
   ├─ mrb_f_raise() - 例外発生
   ├─ obj_respond_to() - メソッド応答判定
   └─ その他約20メソッド
```

### フローチャート

```mermaid
flowchart TD
    A[mrb_init_kernel] --> B[Kernelモジュール定義]
    B --> C[raiseをクラスメソッドとして定義]
    C --> D[ROMメソッドテーブル初期化]
    D --> E[ObjectにKernelをinclude]
    E --> F[全オブジェクトでKernelメソッド利用可能]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ObjectへのKernel include | ObjectクラスにKernelモジュールがincludeされ全オブジェクトで利用可能 | 初期化時 |
| BR-02 | private メソッド | raise, block_given?, iterator?はprivateメソッド | MRB_MT_PRIVATEフラグ |
| BR-03 | respond_to_missing? | respond_to?でメソッドが見つからない場合にrespond_to_missing?を呼び出す | respond_to?実行時 |
| BR-04 | 再帰検出 | inspectメソッドで再帰呼び出しを検出しループ防止 | inspect時 |

### 計算ロジック

特になし。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| RuntimeError | デフォルト例外 | raise引数なしまたは文字列のみ | 例外処理の実装 |
| 任意の例外 | 指定例外 | raiseに例外クラスとメッセージを指定 | 例外処理の実装 |

### リトライ仕様

リトライ機構なし。

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

該当なし

## パフォーマンス要件

- mrb_func_basic_pによる基本実装チェックで不要なメソッド呼び出しを回避
- ROMメソッドテーブルによるメモリ効率の向上

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

- private メソッド（raise等）の可視性制御
- freeze/frozen?によるオブジェクト不変性の保証

## 備考

- kernel.cは718行
- kernel_rom_entriesに約28メソッドがROM定義されている
- `HAVE_MRUBY_IO_GEM`未定義時のみp, printメソッドがKernelに定義される（IO gem存在時はIO gem側で定義）
- ISO 15.3.1準拠のメソッド番号がコメントに記載されている

---

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

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

### 推奨読解順序

#### Step 1: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kernel.c | `src/kernel.c` | mrb_init_kernel()（703-718行目）: モジュール定義、ROMテーブル初期化、Objectへのinclude |
| 1-2 | kernel.c | `src/kernel.c` | kernel_rom_entries[]（669-701行目）: 約28メソッドのROM定義 |

**読解のコツ**: MRB_MT_ENTRYマクロはC関数・シンボル・引数仕様をひとつのエントリにまとめる。MRB_MT_PRIVATEフラグでprivateメソッドを示す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kernel.c | `src/kernel.c` | mrb_func_basic_p()（23-37行目）: メソッドが基本C関数かチェック |
| 2-2 | kernel.c | `src/kernel.c` | mrb_obj_inspect()（103-116行目）: インスタンス変数付きinspect |

**主要処理フロー**:
- **26-27行目**: mrb_func_basic_pでクラス→メソッド探索→関数ポインタ比較
- **106-113行目**: inspectでmrb_iv_foreachによるインスタンス変数走査

#### Step 3: 主要メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kernel.c | `src/kernel.c` | mrb_f_block_given_p_m()（273-332行目）: コールスタック走査によるブロック判定 |
| 3-2 | kernel.c | `src/kernel.c` | mrb_f_raise()（510-536行目）: 例外発生（0-2引数対応） |
| 3-3 | kernel.c | `src/kernel.c` | obj_respond_to()（590-606行目）: メソッド応答判定 |
| 3-4 | kernel.c | `src/kernel.c` | mrb_obj_freeze()（356-367行目）: オブジェクト凍結 |

**主要処理フロー**:
- **276-327行目**: block_given?でci走査→proc→env→block判定
- **517-534行目**: raiseで引数数に応じたRuntimeError/指定例外の発生
- **597-603行目**: respond_toでrespond_to_missing?フォールバック

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

```
mrb_init_kernel()
    │
    ├─ mrb_define_module_id(Kernel) ─── モジュール定義
    ├─ mrb_define_class_method_id(raise) ─── クラスメソッド
    ├─ MRB_MT_INIT_ROM(kernel_rom_entries) ─── ROMテーブル
    └─ mrb_include_module(Object, Kernel) ─── Object include

mrb_f_raise()
    │
    ├─ [引数0] mrb_raise(E_RUNTIME_ERROR, "")
    ├─ [引数1: String] mrb_raise(E_RUNTIME_ERROR, msg)
    └─ [引数1-2] mrb_make_exception() → mrb_exc_raise()

mrb_obj_inspect()
    │
    ├─ mrb_obj_basic_to_s_p() ─── to_sがデフォルト?
    └─ mrb_iv_foreach(inspect_i) ─── インスタンス変数走査
```

### データフロー図

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

self ────────────────────▶ mrb_obj_inspect()            ──▶ "#<Class:0x...>"
(argc, argv) ────────────▶ mrb_f_raise()               ──▶ 例外発生 (noreturn)
(sym, priv) ─────────────▶ obj_respond_to()             ──▶ true/false
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kernel.c | `src/kernel.c` | ソース | Kernelモジュール本体（718行） |
| object.c | `src/object.c` | ソース | mrb_obj_freeze等の実装（Kernelメソッドの一部） |
| error.c | `src/error.c` | ソース | mrb_raise, mrb_make_exception等 |
| class.c | `src/class.c` | ソース | mrb_define_module, mrb_include_module |
| variable.c | `src/variable.c` | ソース | mrb_iv_foreach等（インスタンス変数操作） |
| print.c | `src/print.c` | ソース | mrb_p等の出力関数 |
