# 機能設計書 73-mrubyコマンド

## 概要

本ドキュメントは、mrubyスクリプト実行コマンド（mruby）の設計について記述する。ファイル実行、ワンライナー実行、RiteBinary実行等をサポートするコマンドラインインタプリタである。

### 本機能の処理概要

mrubyコマンドは、Rubyソースファイル、コマンドライン文字列（-eオプション）、またはコンパイル済みバイナリ（.mrbファイル）を入力としてmrubyバイトコードを実行する。実行前のライブラリ読み込み（-r）、構文チェックのみモード（-c）、デバッグモード（-d）、詳細モード（-v）等のオプションを提供する。

**業務上の目的・背景**：mrubyで記述されたスクリプトをコマンドラインから実行するための標準的なインターフェースを提供する。CRubyのrubyコマンドに相当し、mrubyの基本的な実行環境として不可欠。

**機能の利用シーン**：mrubyスクリプトのバッチ実行、ワンライナーによる簡易処理、.mrbバイナリの実行、スクリプトの構文チェック、開発時のデバッグ実行。

**主要な処理内容**：
1. コマンドライン引数の解析（-b, -c, -d, -e, -r, -v等）
2. ARGV定数と$0/$DEBUG変数の設定
3. ライブラリファイルの事前読み込み（-r）
4. ソースファイル/文字列/バイナリの判別と読み込み・実行
5. 実行結果の出力と例外処理

**関連システム・外部連携**：標準入力、ファイルシステム、mruby-compilerによるパース・コード生成。

**権限による制御**：特になし。ファイルシステムのパーミッションに依存。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | コマンドラインツール。画面なし |

## 機能種別

コマンドラインインタプリタ / スクリプト実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| -b | フラグ | No | RiteBinary（.mrb）ファイルとして実行 | - |
| -c | フラグ | No | 構文チェックのみ（実行しない） | - |
| -d | フラグ | No | デバッグモード（$DEBUG=true） | - |
| -e command | 文字列 | No | ワンライナー実行（複数指定可） | 文字列が指定されていること |
| -r library | 文字列 | No | 事前ライブラリ読み込み（複数指定可） | ライブラリパスが指定されていること |
| -v | フラグ | No | バージョン表示後、詳細モードで実行 | - |
| --verbose | フラグ | No | 詳細モード | - |
| --version | フラグ | No | バージョン表示して終了 | - |
| --copyright | フラグ | No | 著作権表示して終了 | - |
| programfile | 文字列 | No | 実行するスクリプトファイル（"-"は標準入力） | - |
| arguments | 文字列列 | No | スクリプトに渡す引数 | - |

### 入力データソース

- コマンドライン引数
- Rubyソースファイル（.rb）
- RiteBinaryファイル（.mrb）
- 標準入力
- -eで指定される文字列

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 実行結果 | - | スクリプトの出力（標準出力/標準エラー） |
| 終了コード | int | EXIT_SUCCESS(0)またはEXIT_FAILURE(1) |

### 出力先

標準出力、標準エラー出力。

## 処理フロー

### 処理シーケンス

```
1. mrb_open() で mruby VM を初期化
2. parse_args() でコマンドライン引数を解析
3. ARGV定数を設定、$DEBUG/$0を設定
4. mrb_ccontext_new() でコンパイルコンテキストを生成
5. -r ライブラリを順次読み込み
6. プログラムを読み込み・実行
   ├─ .mrbファイル → mrb_load_irep_file_cxt
   ├─ ソースファイル → mrb_load_detect_file_cxt
   └─ -e文字列 → mrb_load_string_cxt
7. 例外チェックとエラー表示
8. cleanup() でリソース解放
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[mrb_open]
    B --> C[parse_args]
    C --> D{解析成功?}
    D -->|No| E[終了 EXIT_FAILURE]
    D -->|Yes| F[ARGV/$DEBUG/$0設定]
    F --> G[-rライブラリ読み込み]
    G --> H{入力種別}
    H -->|.mrb| I[mrb_load_irep_file_cxt]
    H -->|ファイル| J[mrb_load_detect_file_cxt]
    H -->|-e文字列| K[mrb_load_string_cxt]
    I --> L{例外発生?}
    J --> L
    K --> L
    L -->|Yes| M[エラー表示]
    L -->|No| N{-c指定?}
    N -->|Yes| O[Syntax OK]
    N -->|No| P[正常終了]
    M --> E
    O --> P
    P --> Q[cleanup]
    Q --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-73-1 | 自動バイナリ判定 | 拡張子.mrbのファイルは自動的にRiteBinaryとして読み込む | -bオプション未指定でも拡張子で判定 |
| BR-73-2 | -e複数指定 | -eオプションは複数回指定可能で、改行で連結される | 複数の-eが指定された場合 |
| BR-73-3 | 標準入力 | ファイル名"-"または未指定時は標準入力から読み取り | programfile未指定時 |
| BR-73-4 | UTF-8変換 | 引数と-e文字列はlocaleからUTF-8に変換される | mrb_utf8_from_locale使用 |
| BR-73-5 | Windowsバイナリモード | Windowsでは標準入力をバイナリモードに設定 | _WIN32定義時 |

### 計算ロジック

特になし。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| EXIT_FAILURE | 初期化失敗 | mrb_openが失敗した場合 | エラー表示して終了 |
| EXIT_FAILURE | ファイルオープン失敗 | プログラムファイルが開けない場合 | エラーメッセージ表示 |
| EXIT_FAILURE | -e引数なし | -eの後にコードが指定されていない場合 | "No code specified for -e"表示 |
| EXIT_FAILURE | 実行時例外 | スクリプト実行中に例外が発生した場合 | mrb_print_errorでバックトレース表示 |

### リトライ仕様

リトライは不要。

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

該当なし。

## パフォーマンス要件

特に定義されていない。

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

- MRB_NO_STDIO定義時はコンパイルエラーとなる（標準入出力が必須）

## 備考

- mrb_load_detect_file_cxtはファイル先頭のマジックナンバーでバイナリ/ソースを自動判別する
- no_return_valueフラグにより、メインプログラムの戻り値は不要とされる

---

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

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

### 推奨読解順序

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

コマンドライン引数を保持する構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mruby.c | `mrbgems/mruby-bin-mruby/tools/mruby/mruby.c` | struct _args定義（22-35行目） |
| 1-2 | mruby.c | `mrbgems/mruby-bin-mruby/tools/mruby/mruby.c` | struct options定義（37-43行目） |

**読解のコツ**: _args構造体のビットフィールド（fname, mrbfile, check_syntax等）はメモリ効率化のため。libv/libcは-rオプションで指定されたライブラリの動的配列。

#### Step 2: エントリーポイント（main関数）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | mruby.c | `mrbgems/mruby-bin-mruby/tools/mruby/mruby.c` | main関数（276-380行目） |

**主要処理フロー**:
1. **279行目**: mrb_openでVM初期化
2. **291行目**: parse_argsで引数解析
3. **298-306行目**: ARGV定数生成とUTF-8変換
4. **309-313行目**: コンパイルコンテキスト設定
5. **326-344行目**: -rライブラリの読み込みループ
6. **351-362行目**: プログラムの読み込みと実行（入力種別で分岐）
7. **366-375行目**: 例外チェック・エラー出力

#### Step 3: 引数解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | mruby.c | `mrbgems/mruby-bin-mruby/tools/mruby/mruby.c` | parse_args関数（145-257行目） |
| 3-2 | mruby.c | `mrbgems/mruby-bin-mruby/tools/mruby/mruby.c` | options_opt関数（87-122行目） |

**主要処理フロー**:
- **154行目**: options_optでオプション文字列を順次取得
- **155-226行目**: 各オプション（b/c/d/e/h/r/v等）の処理
- **230-256行目**: プログラムファイル名の決定とARGV設定

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

```
main
    ├─ mrb_open
    ├─ parse_args
    │   ├─ options_init
    │   ├─ options_opt (ループ)
    │   └─ options_arg (引数取得)
    ├─ mrb_ary_new_capa (ARGV作成)
    ├─ mrb_ccontext_new
    ├─ [ライブラリ読み込み]
    │   ├─ mrb_load_irep_file_cxt (.mrb)
    │   └─ mrb_load_detect_file_cxt (自動判別)
    ├─ [プログラム実行]
    │   ├─ mrb_load_irep_file_cxt (.mrb)
    │   ├─ mrb_load_detect_file_cxt (ファイル)
    │   └─ mrb_load_string_cxt (-e文字列)
    ├─ mrb_print_error (例外時)
    └─ cleanup
        ├─ fclose
        ├─ mrb_free
        └─ mrb_close
```

### データフロー図

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

コマンドライン引数 ──▶ parse_args ──────────▶ _args構造体
                          │
ファイル/stdin ────▶ mrb_load_*_cxt ────▶ 実行結果
                          │
-e文字列 ──────────▶ mrb_load_string_cxt ─▶ 実行結果
                          │
                     例外チェック ──────────▶ エラー出力(stderr)
                          │
                     cleanup ──────────────▶ 終了コード(0/1)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mruby.c | `mrbgems/mruby-bin-mruby/tools/mruby/mruby.c` | ソース | mrubyコマンドのメイン実装 |
| mrbgem.rake | `mrbgems/mruby-bin-mruby/mrbgem.rake` | 設定 | gem定義ファイル |
| mruby.rb | `mrbgems/mruby-bin-mruby/bintest/mruby.rb` | テスト | 統合テスト |
