mruby 逆引きリファレンス (落丁版) (💣💣💣)

個人的な、ちょっとアレをするにはどうするんだったっけ? を編纂したものです。主に C 言語からの利用視点となっています。

dearblue の雑記帳の扱いとなっているため、理想となる逆引き辞典のような記述にはなっておりません。

中には mruby 開発者たちが見たら「その方法は間違いだし危険だからやめて」と悲鳴を上げるようなモノが含まれている可能性が1㍉くらいあります。

***正確性が怪しかったり推奨されなかったりするものだと胸を張って主張する項目には、💣をつけておきます。複数あったらより危険だということです。***その上で当文書の題名を確認してもらうと……ニヤリ。

mruby-1.4 が対象と思いきや、mruby-1.3 や 1.2 向けの記述が混じっています。

当文書を参考にしたことで星間戦争を引き起こす原因を作ったとしても、責任は負いません。

保険適用外。公共の場に持ち出すと真っ先に狙撃されます。[もう何も怖くない](https://www.google.co.jp/images?q=魔法少女まどか☆マギカ+もう何も怖くない)。


## mruby の作成

REF:

  * (日本語) <http://forum.mruby.org/docs/index.html>
  * (英語) <https://github.com/mruby/mruby/blob/1.4.0/doc/guides/compile.md>
  * (英語) <https://github.com/mruby/mruby/blob/1.4.0/doc/guides/mrbconf.md>

### mruby 最短ビルド方法

前提: すでに GCC 系のコンパイラ、ruby および git がインストールされていること。

```
$ git clone https://github.com/mruby/mruby.git mruby
$ cd mruby
$ ruby minirake
```

で、``bin/mruby`` が動作できる形で作成される。

### ビルド設定を色々いじりたい

``build_config.rb`` を編集する。

### 異なるビルド設定ファイルを指定したい

環境変数 ``MRUBY_CONFIG`` で任意のファイル名・パスに変更することが出来る。

何も指定しない場合は、mruby のソースコードのトップディレクトリに置かれた ``build_config.rb`` が使われる。

```shell
$ export MRUBY_CONFIG=custom_build.rb
$ rake -f ~/mruby-1.3/Rakefile
```

*詳細は <https://github.com/mruby/mruby/blob/1.4.0/doc/guides/compile.md> と <https://github.com/mruby/mruby/blob/1.4.0/doc/guides/mrbconf.md> を確認。*

### Fixnum の範囲を変更したい

``build_config.rb`` で ``conf.cc.defines`` に ``MRB_INT16`` や ``MRB_INT32`` (mruby-1.4 で追加)、``MRB_INT64`` を追加する。

(mruby-1.4 以前) 何も指定しない場合は、``MRB_INT32`` 相当の設定となる (``MRB_INT32`` 自体は存在しない)。

(mruby-1.4 から) 何も指定しない場合は、``sizeof(void *)`` を含めることのできる最小の整数型が選択される。

```ruby
MRuby::Build.new do |conf|
  conf.cc.defines << "MRB_INT64"
end
```

  * NOTE: 整数値の最小値・最大値は C では ``MRB_INT_MIN`` / ``MRB_INT_MAX`` で確認する。
  * NOTE: ``mrb_str_buf_new()`` や ``mrb_str_resize()`` などで指定できる capacity 値は、``(sizeof(size_t) - 1)`` か ``(MRB_INT_MAX - 1)`` の小さい方が上限となる。

### mrb_value の表現方法を変更したい

``build_config.rb`` で ``conf.cc.defines`` に ``MRB_NAN_BOXING`` または ``MRB_WORD_BOXING`` を追加する。

両方とも指定しない場合は、``MRB_NO_BOXING`` 相当となる ( ``MRB_NO_BOXING`` 自体は存在しない)。

```ruby
MRuby::Build.new do |conf|
  conf.cc.defines << "MRB_WORD_BOXING"
end
```

(mruby-1.4 以前) ruby の VALUE と同等にしたい場合は、``MRB_WORD_BOXING`` と、必要であれば ``MRB_INT64`` も定義する。
(mruby-1.4 以降) ruby の VALUE と同等にしたい場合は、``MRB_WORD_BOXING`` を定義する。

```ruby
MRuby::Build.new do |conf|
  conf.cc.defines << "MRB_WORD_BOXING"
  conf.cc.defines << "MRB_INT64" if [nil].pack("P").bytesize > 4
end
```

REF:

  * [include/mruby/boxing_no.h](https://github.com/mruby/mruby/blob/1.4.0/include/mruby/boxing_no.h) (``MRB_NO_BOXING`` 相当の実体)
  * [include/mruby/boxing_nan.h](https://github.com/mruby/mruby/blob/1.4.0/include/mruby/boxing_nan.h) (``MRB_NAN_BOXING`` の実体)
  * [include/mruby/boxing_word.h](https://github.com/mruby/mruby/blob/1.4.0/include/mruby/boxing_word.h) (``MRB_WORD_BOXING`` の実体)
  * [include/mruby/value.h](https://github.com/mruby/mruby/blob/1.4.0/include/mruby/value.h) (boxing_XXX.h の include 元)

### テストしたい

``conf.enable_test`` を記述する。

```ruby
MRuby::Build.new do |conf|
  conf.enable_test
end
```

``test/*.rb`` を作っておくと、``host/bin/mrbtest`` でテスト結果を確認できるようになる。

### C++ が混ざっている場合

mruby のビルドシステムは C++ のコードが混ざっていると判断すると、C++ の例外機構 (try-cache-throw) のための構成を自動で有効にする。

利用者が手動で有効にしたい場合、`build_config.rb` に `conf.enable_cxx_exception` を記述する。

```ruby
MRuby::Build.new do |conf|
  conf.enable_cxx_exception
end
```

もっと強力に、C のコードも問答無用で C++ としてコンパイルしたい場合のために `conf.enable_cxx_abi` も用意されている。

もし何らかの事情があって `conf.enable_cxx_exception` されると困る場合は `conf.disable_cxx_exception` を記述する。
これはすべての `conf.enable_cxx_exception` や `conf.gem` に先立って記述しなければならない。

### ライブラリの追加方法 (MRuby::Build#gem)

*<https://github.com/mruby/mruby/blob/1.4.0/doc/guides/mrbgems.md> も確認するべし。*

mruby の拡張ライブラリは mrbgems として管理されている。mruby に標準で付属するものだけではなく、第三者が公開しているものを利用することも可能。

```ruby
MRuby::Build.new do |conf|
  # mruby に標準で付属しているものを指定
  gem core: "mruby-print"

  # https://github.com/mruby/mgem-list に登録されたものを指定
  gem mgem: "mruby-print"

  # github にあるものを指定
  gem github: "mruby/mruby-print"

  # bitbucket にあるものを指定
  gem bitbucket: "mruby/mruby-print"

  # git で取得可能なものを指定
  gem git: "https://github.com/mruby/mruby-print.git"

  # 自分のコンピュータのみに存在する、オレオレ mgem を指定
  gem "/home/mruby/mrbgems/mruby-print"
end
```

## mrbgem.rake

mruby gem パッケージとして必要となる情報が記述されたファイル。中身は ruby スクリプト。

*詳細は <https://github.com/mruby/mruby/blob/1.4.0/doc/guides/mrbgems.md> にまとまってる。*


## オブジェクト全般

### C の型

  * mruby コンテキスト :: ``mrb_state`` (ポインタとして使う)
  * 整数型 :: ``mrb_int``
  * 浮動小数点数型 :: ``mrb_float``
  * 真偽値型 :: ``mrb_bool``
  * オブジェクト型 :: ``mrb_value``

### データタイプ一覧

```c
/* include/mruby/value.h */
    96: enum mrb_vtype {
    97:   MRB_TT_FALSE = 0,   /*   0 */

    99:   MRB_TT_TRUE,        /*   2 */
   100:   MRB_TT_FIXNUM,      /*   3 */
   101:   MRB_TT_SYMBOL,      /*   4 */

   103:   MRB_TT_FLOAT,       /*   6 */
   104:   MRB_TT_CPTR,        /*   7 */
   105:   MRB_TT_OBJECT,      /*   8 */
   106:   MRB_TT_CLASS,       /*   9 */
   107:   MRB_TT_MODULE,      /*  10 */
   108:   MRB_TT_ICLASS,      /*  11 */
   109:   MRB_TT_SCLASS,      /*  12 */
   110:   MRB_TT_PROC,        /*  13 */
   111:   MRB_TT_ARRAY,       /*  14 */
   112:   MRB_TT_HASH,        /*  15 */
   113:   MRB_TT_STRING,      /*  16 */
   114:   MRB_TT_RANGE,       /*  17 */
   115:   MRB_TT_EXCEPTION,   /*  18 */
   116:   MRB_TT_FILE,        /*  19 */
   117:   MRB_TT_ENV,         /*  20 */
   118:   MRB_TT_DATA,        /*  21 */
   119:   MRB_TT_FIBER,       /*  22 */
   120:   MRB_TT_ISTRUCT,     /*  23 */

/* 以下は利用者が使用する場合は特に注意が必要なデータタイプ (たぶん) */
    98:   MRB_TT_FREE,        /*   1 */
   102:   MRB_TT_UNDEF,       /*   5 */
   121:   MRB_TT_BREAK,       /*  24 */
   122:   MRB_TT_MAXDEFINE    /*  25 */

   123: };
```

### データタイプの確認

```c
/* include/mruby/object.h */
mrb_bool mrb_immediate_p(mrb_value obj);

/* include/mruby/value.h */
mrb_bool mrb_fixnum_p(mrb_value obj);
mrb_bool mrb_undef_p(mrb_value obj);
mrb_bool mrb_nil_p(mrb_value obj);
mrb_bool mrb_bool(mrb_value obj);
mrb_bool mrb_float_p(mrb_value obj);
mrb_bool mrb_symbol_p(mrb_value obj);
mrb_bool mrb_array_p(mrb_value obj);
mrb_bool mrb_string_p(mrb_value obj);
mrb_bool mrb_hash_p(mrb_value obj);
mrb_bool mrb_cptr_p(mrb_value obj);
mrb_bool mrb_exception_p(mrb_value obj);
```

### オブジェクトタイプの特徴 (クラスではないことに注意)

※mruby-1.4 を対象としている。

| タイプ名 | クラス | C の型 | 即値か [^immediate] | ファイナライザの設置 | インスタンス変数の保持 | 備考 |
| ---- | ---- | ---- | ---- | ---- | ---- | ---- |
| MRB_TT_FALSE | NilClass / FalseClass | mrb_bool | はい | 不可 | 不可 |
| MRB_TT_TRUE | TrueClass | mrb_bool | はい | 不可 | 不可 |
| MRB_TT_FIXNUM | Fixnum | mrb_int | はい | 不可 | 不可 |
| MRB_TT_SYMBOL | Symbol | mrb_sym | はい | 不可 | 不可 |
| MRB_TT_FLOAT | Float | mrb_float | はい | 不可 | 不可 |
| MRB_TT_CPTR | Object | 任意 | はい | 不可 | 不可 | 任意のポインタをカプセル化する |
| MRB_TT_OBJECT | 任意 | struct RObject | いいえ | 不可 | 可 |
| MRB_TT_CLASS | 任意 | struct RClass | いいえ | 不可 | 可 |
| MRB_TT_MODULE | 任意 | struct RClass | いいえ | 不可 | 可 |
| MRB_TT_ICLASS | 任意 | struct RClass | いいえ | 不可 | 不可 |
| MRB_TT_SCLASS | 任意 | struct RClass | いいえ | 不可 | 可 |
| MRB_TT_PROC | 任意 | struct RProc | いいえ | 不可 | 不可 |
| MRB_TT_ARRAY | 任意 | struct RArray | いいえ | 不可 | 不可 |
| MRB_TT_HASH | 任意 | struct RHash | いいえ | 不可 | 可 |
| MRB_TT_STRING | 任意 | struct RString | いいえ | 不可 | 不可 |
| MRB_TT_RANGE | 任意 | struct RRange | いいえ | 不可 | 不可 |
| MRB_TT_EXCEPTION | 任意 | struct RException | いいえ | 不可 | 可 |
| MRB_TT_FILE | 任意 | ? | いいえ | 不可 | 不可 |
| MRB_TT_ENV | 任意 | struct REnv | いいえ | 不可 | 不可 |
| MRB_TT_DATA | 任意 | struct RData | いいえ | 可 | 可 | 任意のポインタをカプセル化する |
| MRB_TT_FIBER | 任意 | struct RFiber | いいえ | 不可 | 不可 |
| MRB_TT_ISTRUCT | 任意 | struct RIstruct | いいえ | 不可 | 不可 | 3ワード領域を自由に利用可能 |

[^immediate]: 即値は GC 対象にはならない。また、GC の対象外であり、かつアリーナを消費することもない。ただしクラスは固定されるため、シングルトンクラスを持つことが出来ない。

### 値

```c
/* include/mruby/value.h */
MRB_INLINE mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f);
mrb_value mrb_cptr_value(struct mrb_state *mrb, void *p);
mrb_value mrb_obj_value(void *p);
MRB_INLINE mrb_value mrb_nil_value(void);
MRB_INLINE mrb_value mrb_false_value(void);
MRB_INLINE mrb_value mrb_true_value(void);
mrb_value mrb_bool_value(mrb_bool boolean);
mrb_value mrb_undef_value(void);
```

### インスタンス変数

```c
/* include/mruby/variable.h */
void mrb_iv_set(mrb_state *mrb, mrb_value obj, mrb_sym sym, mrb_value v);
mrb_value mrb_iv_get(mrb_state *mrb, mrb_value obj, mrb_sym sym);
mrb_bool mrb_iv_defined(mrb_state *mrb, mrb_value obj, mrb_sym sym);
mrb_value mrb_iv_remove(mrb_state *mrb, mrb_value obj, mrb_sym sym);
void mrb_iv_copy(mrb_state *mrb, mrb_value dst, mrb_value src);
```

インスタンス変数を利用できるオブジェクトタイプ (クラスではなく mrb_type のこと) は、``MRB_TT_OBJECT`` ``MRB_TT_CLASS`` ``MRB_TT_MODULE`` ``MRB_TT_SCLASS`` ``MRB_TT_HASH`` ``MRB_TT_DATA`` ``MRB_TT_EXCEPTION`` に限定される。

REF: <https://github.com/mruby/mruby/blob/1.4.0/src/variable.c#L222>

### オブジェクトの生成

通常は ``mrb_obj_new()`` を使う。

初期化 (``.initialize``) を伴わない、オブジェクトの確保のみを行いたい場合は ``mrb_obj_alloc()`` がある。

```c
/* include/mruby.h */
MRB_API mrb_value mrb_obj_new(mrb_state *mrb, struct RClass *c, mrb_int argc, const mrb_value *argv);
MRB_API struct RBasic *mrb_obj_alloc(mrb_state*, enum mrb_vtype, struct RClass*);
```

### オブジェクトの入れ物が同じかどうかを確認する

``mrb_obj_eq()`` を使う。``mrb_obj_equal()`` は mruby-1.3 の時点では同じ同じだが、『temporary definition』となっているため、将来的に異なる可能性がある。

```c
/* include/mruby.h */
MRB_API mrb_bool mrb_obj_eq(mrb_state*, mrb_value, mrb_value);
MRB_API mrb_bool mrb_obj_equal(mrb_state*, mrb_value, mrb_value);
```

### オブジェクの内容物まで比較して等価かどうかを確認する

``mrb_equal()`` を使うと、``.==`` メソッドによる比較が行われる。

``mrb_eql()`` を使うと、``.eql?`` メソッドによる比較が行われる。

```c
/* include/mruby.h */
MRB_API mrb_bool mrb_equal(mrb_state *mrb, mrb_value obj1, mrb_value obj2);
MRB_API mrb_bool mrb_eql(mrb_state *mrb, mrb_value obj1, mrb_value obj2);
```

### mrb_state 毎のグローバル変数として使う方法 (💣)

mruby の実行環境は mrb_state 毎に分離されるため、一つのプロセスの中で複数の mrb_state を持つ場合にグローバル変数を用いることが事実上出来ないことが稀によくある。

そんな時は ``mrb_gv_set()`` で設定し、``mrb_gv_get()`` で取得、``mrb_gv_remove()`` で削除できる。この時のグローバル変数名を ``$`` 以外で始めれば mruby 空間からは隠蔽されるので都合がいい (💣:検証だけは済ませた)。

``mrb_XXX_gem_init()`` と ``mrb_XXX_gem_final()`` で初期化と後始末を行える。この際には ``mrb_cptr_value()`` と ``mrb_cptr()`` が役に立ちそうだ。

```c
/* mruby/variable.h */
mrb_value mrb_gv_get(mrb_state * mrb, mrb_sym sym);
void mrb_gv_set(mrb_state * mrb, mrb_sym sym, mrb_value val);
void mrb_gv_remove(mrb_state * mrb, mrb_sym sym);
```


## ヒープメモリの管理

```c
/* mruby/include/mruby.h */
MRB_API void *mrb_malloc(mrb_state *, size_t);         /* メモリが確保できない場合は RuntimeError 例外が発生する */
MRB_API void *mrb_calloc(mrb_state *, size_t, size_t); /* 上に同じ */
MRB_API void *mrb_realloc(mrb_state *, void *, size_t); /* 上に同じ */
MRB_API void *mrb_malloc_simple(mrb_state *, size_t);  /* メモリが確保できない場合は NULL を返す */
MRB_API void *mrb_realloc_simple(mrb_state *, void *, size_t); /* 上に同じ */
MRB_API void mrb_free(mrb_state *, void *);
```

NOTE: `mrb_malloc_simple()` / `mrb_realloc_simple()` 関数の使用は推奨されない。


## GC

### GC アリーナ

参考 (と言うか必読): [mrubyのmrb_gc_arena_save\(\)/mrb_gc_arena_restore\(\)の使い方 - Matzにっき\(2013-07-31\)](http://www.rubyist.net/~matz/20130731.html#p01)

```c
/* include/mruby.h */
MRB_API int mrb_gc_arena_save(mrb_state*);
MRB_API void mrb_gc_arena_restore(mrb_state*,int);
MRB_API void mrb_gc_protect(mrb_state *mrb, mrb_value obj);
```

特に繰り返し処理中にオブジェクトをその度に生成させているような場合は必須。

```c
int ai = mrb_gc_arena_save(mrb); /* 変数名の ai は arena index を意味する */
mrb_value str;

while (めちゃくちゃループ) {
    str = mrb_str_new_cstr(mrb, "ほげほげ");

    /* str を面白可笑しくいじる */

    mrb_gc_arena_restore(mrb, ai); /* アリーナ領域を ai に復帰 */
}

/*
 * 最後の str だけはどうしても必要だった!
 * mrb_gc_arena_restore() 直後なら GC が実行されないので、チャンスは今だけ!
 */
mrb_gc_protect(mrb, str);

/* str を面白可笑しくいじる */

/* やっぱ str はいらねーや (場合によっては省略できる) */
mrb_gc_arena_restore(mrb, ai);
```


## メソッド

### メソッドを呼ぶ

```c
/* mruby/include/mruby.h */
MRB_API mrb_value mrb_funcall(mrb_state*, mrb_value, const char*, mrb_int,...);
MRB_API mrb_value mrb_funcall_argv(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*);
MRB_API mrb_value mrb_funcall_with_block(mrb_state*, mrb_value, mrb_sym, mrb_int, const mrb_value*, mrb_value);
```

### 呼ばれた時のメソッド名を知りたい

``mrb_get_mid()`` で取得できる。

```c
mrb_sym mid = mrb_get_mid(mrb);
```

mruby-1.2 以前には存在しないので、``mrb_state`` から直接釣り上げる。

```c
mrb_sym mid = mrb->c->ci->mid;
```

### 引数を取得したい

登録された関数が mruby 空間からメソッドとして呼び出された場合、引数の取得は ``mrb_get_args()`` を使う。
この時渡す ``format`` には文字列を与えることとなり、その詳細は <https://mruby.org/docs/api/headers/mruby.h.html#mrb_args_format-typedef> あるいは <https://github.com/mruby/mruby/blob/1.4.0/src/class.c#L571-L600> を参照されたい。

他には引数長を取得するだけの ``mrb_get_argc()`` がある。

引数の配列としてのポインタを取得する ``mrb_get_argv()`` もあるが、NULL を返す場合があるため、``mrb_get_args(mrb, "*", &argv, &argc)`` [^get-argv] を使ったほうが好ましい。

[^get-argv]: main 関数などの引数の並び (``argc, argv``) とは逆になっている (``&argv, &argc``) ので注意。

```c
/* 1.4.0:include/mruby.h */
MRB_API mrb_int mrb_get_args(mrb_state *mrb, mrb_args_format format, ...);
MRB_API mrb_int mrb_get_argc(mrb_state *mrb);
MRB_API mrb_value* mrb_get_argv(mrb_state *mrb);
```

### Method

```c
/* include/mruby.h */
MRB_API void mrb_define_method(mrb_state *mrb, struct RClass *cla, const char *name, mrb_func_t func, mrb_aspec aspec);
MRB_API void mrb_define_class_method(mrb_state *, struct RClass *, const char *, mrb_func_t, mrb_aspec);
MRB_API void mrb_define_singleton_method(mrb_state*, struct RObject*, const char*, mrb_func_t, mrb_aspec);
MRB_API void mrb_define_alias(mrb_state *mrb, struct RClass *klass, const char *name1, const char *name2);
MRB_API void mrb_undef_method(mrb_state*, struct RClass*, const char*);
MRB_API void mrb_undef_class_method(mrb_state*, struct RClass*, const char*);

/* include/mruby/class.h */
MRB_API void mrb_define_method_raw(mrb_state*, struct RClass*, mrb_sym, mrb_method_t);
MRB_API void mrb_define_method_id(mrb_state *mrb, struct RClass *c, mrb_sym mid, mrb_func_t func, mrb_aspec aspec);
MRB_API void mrb_alias_method(mrb_state *mrb, struct RClass *c, mrb_sym a, mrb_sym b);
MRB_API mrb_method_t mrb_method_search(mrb_state*, struct RClass*, mrb_sym);
MRB_API mrb_method_t mrb_method_search_vm(mrb_state*, struct RClass**, mrb_sym);

/* include/mruby/proc.h */
void MRB_METHOD_FROM_FUNC(mrb_method_t &method, mrb_func_t func); /* 実体はマクロ */
void MRB_METHOD_FROM_PROC(mrb_method_t &method, struct RProc *proc); /* 実体はマクロ */
```

NOTE: ``mrb_define_method()`` 系の ``aspec`` 引数は飾り (※mruby-1.4 現在)。引数の確認は ``func`` が呼ばれて ``mrb_get_args()`` を通して行う (``mrb_get_args()`` に関しては[引数を取得したい](#引数を取得したい)を参照されたい)。


### Proc

```c
/* include/mruby/proc.h */
struct RProc *mrb_proc_ptr(mrb_value v); /* 実体はマクロ */
struct RProc *mrb_proc_new(mrb_state *mrb, mrb_irep *irep);
struct RProc *mrb_closure_new(mrb_state *mrb, mrb_irep *irep);
void mrb_proc_copy(struct RProc *a, struct RProc *b);
MRB_API struct RProc *mrb_proc_new_cfunc(mrb_state *mrb, mrb_func_t func);
MRB_API struct RProc *mrb_closure_new_cfunc(mrb_state *mrb, mrb_func_t func, int nlocals);
MRB_API struct RProc *mrb_proc_new_cfunc_with_env(mrb_state *mrb, mrb_func_t func, mrb_int nenv, const mrb_value *env);
MRB_API mrb_value mrb_proc_cfunc_env_get(mrb_state *mrb, mrb_int idx);
mrb_value mrb_cfunc_env_get(mrb_state *mrb, mrb_int idx); /* 実体はマクロ; mrb_proc_cfunc_env_get の別名 */
mrb_bool MRB_PROC_CFUNC_P(struct RProc *p); /* 実体はマクロ */
mrb_func_t MRB_PROC_CFUNC(struct RProc *p); /* 実体はマクロ */
```

``mrb_proc_new_cfunc_with_env()`` で Proc に関連付けられた値は、``mrb_define_method_raw()`` によって登録された Proc がメソッド呼び出しされ、その中で ``mrb_cfunc_env_get()`` することで受け取ることが出来る。

※``mrb_closure_new_cfunc()`` は ``nlocals`` の分だけ領域を確保するだけで ``mrb_proc_new_cfunc_with_env()`` と同じ。env へ値を代入させる手順はちょっと込み入ってるし、利用場面はない?

### Yield するには?

`mrb_yield()` または `mrb_yield_argv()` を使う。ただし @yukihiro_matz さんは [C コードからの利用を避けたい](https://github.com/mruby/mruby/pull/3701#issuecomment-308422578) としている (勝手な想像をすると、ファイバーとの兼ね合い?)


## 整数値 (Integer / Fixnum)

データタイプは ``MRB_TT_FIXNUM``。

データタイプの確認は ``mrb_bool mrb_fixnum_p(mrb_value obj)`` で行える。

最小値・最大値は ``MRB_INT_MIN`` と ``MRB_INT_MAX`` で確認する。

mruby は ruby と異なり、標準では多倍長整数が扱えない。

第三者による mruby-bignum が利用できるかもしれない。

### mruby の値から C の整数値に変換する

``mrb_int()`` を使う。オブジェクトが Fixnum であることを保証している場合は ``mrb_fixnum()`` が使える。

```c
/* include/mruby.h */
mrb_int mrb_int(mrb_state *, mrb_value); /* 実体はマクロ */

/* include/mruby/boxing_XXX.h */
mrb_int mrb_fixnum(mrb_value); /* 実体はマクロ */
```

### C の整数値から mruby の値に変換する

``mrb_fixnum_value()`` を使う。

```c
/* include/mruby/value.h */
MRB_INLINE mrb_value mrb_fixnum_value(mrb_int i);
```


## 実数値 (Float)

実体は ``double`` だが、``build_config.rb`` の ``conf.cc.defines`` に ``MRB_USE_FLOAT`` を追加することで ``float`` にすることが出来る。

C の型は ``mrb_float``。

```c
/* include/mruby.h (実体は include/mruby/boxing_XXX.h) */
mrb_float mrb_float(mrb_value obj); /* 実体はマクロ */

/* include/mruby/value.h */
MRB_INLINE mrb_value mrb_float_value(struct mrb_state *mrb, mrb_float f);
mrb_bool mrb_float_p(mrb_value obj); /* 実体はマクロ */
```


## シンボル (Symbol)

C の型は ``mrb_sym``。データタイプは ``MRB_TT_SYMBOL``。

```c
/* 1.4.0:include/mruby.h */
MRB_API const char *mrb_sym2name(mrb_state*,mrb_sym);
MRB_API const char *mrb_sym2name_len(mrb_state*,mrb_sym,mrb_int*);
MRB_API mrb_value mrb_sym2str(mrb_state*,mrb_sym);

/* 1.4.0:include/mruby/value.h */
mrb_bool mrb_symbol_p(mrb_value); /* 実体はマクロ */
static inline mrb_value mrb_symbol_value(mrb_sym i);

/* 1.4.0:include/mruby.h (実体は include/mruby/boxing_XXX.h) */
mrb_sym mrb_symbol(mrb_value obj); /* 実体はマクロ */
```

### C の文字列をシンボルに変換したい

```c
/* 1.4.0:include/mruby.h */
MRB_API mrb_sym mrb_intern_cstr(mrb_state*,const char*);
MRB_API mrb_sym mrb_intern(mrb_state*,const char*,size_t);
MRB_API mrb_sym mrb_intern_static(mrb_state*,const char*,size_t);
MRB_API mrb_sym mrb_intern_str(mrb_state*,mrb_value);
mrb_sym mrb_intern_lit(mrb_state*,const char*); /* 実体はマクロ */
MRB_API mrb_sym mrb_obj_to_sym(mrb_state *mrb, mrb_value name);
```

基本的に ``mrb_intern_cstr()`` を使う。
文字列オブジェクト (``MRB_TT_STRING`` のこと) であることが保証されていれば ``mrb_intern_str()`` が使える。

リテラル文字列であれば ``mrb_intern_lit()`` を用いることで、ヒープメモリの確保とメモリ間コピーがされなくなるため美味しい思いが出来る。
同様の理由で static const な文字列であることが明らかであれば ``mrb_intern_static()`` を用いることができる。

ただしリテラル文字列でない文字列を ``mrb_intern_lit()`` や ``mrb_intern_static()`` に与えると、大泣きする羽目になるので注意。

ポインタの先が何なのか判断できない場合は、安全のために ``mrb_intern_cstr()`` を使うべき。


## mruby の真偽値

```c
/* include/mruby/value.h */
mrb_bool mrb_bool(mrb_value obj); /* 実体はマクロ */
mrb_bool mrb_test(mrb_value obj); /* 実体はマクロ */
```


## クラス・モジュール

```c
/* include/mruby/value.h */
static inline mrb_value mrb_obj_value(struct RClass *p);

/* include/mruby/class.h */
struct RClass *mrb_class_ptr(mrb_value); /* 実体はマクロ */
```

### クラスの定義

```c
MRB_API struct RClass *mrb_define_class(mrb_state *mrb, const char *name, struct RClass *super);
MRB_API struct RClass * mrb_define_class_under(mrb_state *mrb, struct RClass *outer, const char *name, struct RClass *super);
```

```c
struct RClass *superklass = ...;
const char *klassname = ...;

struct RClass *klass = mrb_define_class(mrb, name, superklass);
```

モジュールやクラスの内部に定義する場合は次の通り。

```c
struct RClass *superklass = ...;
const char *klassname = ...;
struct RClass *outerklass = ...;

struct RClass *klass = mrb_define_class_under(mrb, outerklass, name, superklass);
```

### クラス名を取得する

オブジェクトがクラス・モジュールであれば ``mrb_class_name()`` を使う。

インスタンスのクラス名を得たい場合は ``mrb_obj_classname()`` を使う。

```c
/* include/mruby.h */
MRB_API const char *mrb_class_name(mrb_state *mrb, struct RClass* klass);
MRB_API const char *mrb_obj_classname(mrb_state *mrb, mrb_value obj);
```

### C の文字列からクラス・モジュールを取得する

```c
MRB_API struct RClass *mrb_class_get(mrb_state *mrb, const char *name);
MRB_API struct RClass *mrb_class_get_under(mrb_state *mrb, struct RClass *outer, const char *name);
```

``name`` 引数には ``::`` を含めることが出来ないため、一つ一つを辿っていく必要がある。

```c
#define DIG_CLASS(mrb, ...)                                             \
    adig_class(mrb,                                                     \
        sizeof((const char *[]){ __VA_ARGS__ }) / sizeof(const char *), \
        (const char *[]){ __VA_ARGS__ })                                \

static mrb_value
adig_class(mrb_state *mrb, size_t n, const char *names[])
{
    struct RClass *klass = mrb->object_class;
    for (size_t i = 0; i < n; i ++) {
        klass = mrb_class_get_under(mrb, klass, names[i]);
    }
    return klass;
}
```

### スーパークラス (継承元クラス) の取得

```c
struct RClass *RCLASS_SUPER(mrb_value klass);
```

ただし、``klass`` オブジェクトはクラスオブジェクトでなければならない。

あるいは:

```c
struct RClass *klass = ...;
struct RClass *super = klass->super;
```

### クラス・モジュールの定義の確認

```c
mrb_bool mrb_class_defined(mrb_state *mrb, const char *name);
mrb_bool mrb_class_defined_under(mrb_state *mrb, struct RClass *outer, const char *name);
```

### クラスのインスタンスかどうかの確認

```c
/* include/mruby.h */
mrb_bool mrb_obj_is_kind_of(mrb_state *mrb, mrb_value obj, struct RClass *c);
```


## 文字列

データタイプは ``MRB__TT_STRING``。C における実体は [``struct RString``](https://github.com/mruby/mruby/blob/1.4.0/include/mruby/string.h#L21-L35) で、ポインタとして扱う。

```c
/* 1.4.0:include/mruby/value.h */
mrb_bool mrb_string_p(mrb_value); /* 実体はマクロ */

struct RString *mrb_str_ptr(mrb_value); /* 実体はマクロ */
struct RString *RSTRING(mrb_value);     /* 実体はマクロ */
```

### 文字列を生成する方法・文字列に変換する方法

```c
/* include/mruby.h */
MRB_API mrb_value mrb_str_new(mrb_state *mrb, const char *p, size_t len);
MRB_API mrb_value mrb_str_new_cstr(mrb_state*, const char*);
MRB_API mrb_value mrb_str_new_static(mrb_state *mrb, const char *p, size_t len);
mrb_value mrb_str_new_lit(mrb_state*, const char*); /* 実体はマクロ */

MRB_API mrb_value mrb_any_to_s(mrb_state *mrb, mrb_value obj);

/* include/mruby/string.h */
MRB_API mrb_value mrb_str_new_capa(mrb_state *mrb, size_t capa);
MRB_API mrb_value mrb_str_buf_new(mrb_state *mrb, size_t capa);
MRB_API mrb_value mrb_str_dup(mrb_state *mrb, mrb_value str);
MRB_API mrb_value mrb_ptr_to_str(mrb_state *, void*);
MRB_API mrb_value mrb_obj_as_string(mrb_state *mrb, mrb_value obj);
MRB_API mrb_value mrb_str_to_str(mrb_state *mrb, mrb_value str);

/* include/mruby/numeric.h */
MRB_API mrb_value mrb_fixnum_to_str(mrb_state *mrb, mrb_value x, mrb_int base);
MRB_API mrb_value mrb_float_to_str(mrb_state *mrb, mrb_value x, const char *fmt);
```

判断早見表 (あくまで目安)

 1. 文字列オブジェクトに変換するデータがまだない
     1. 一定の領域を予約した空文字列が欲しい
         1. 予約した領域を拡大させる予定がある → ``mrb_str_buf_new()`` を使う
         2. 予約領域はそのまま・予約領域を拡大させるかはまだわからない → ``mrb_str_new_capa()`` を使う
     2. 空文字列が欲しい → ``mrb_str_new(mrb, NULL, 0)`` を使う
 2. mruby のオブジェクトを変換したい
     1. クラスとオブジェクト ID を組み合わせた表記にしたい → ``mrb_any_to_s()`` を使う
     2. オブジェクト ID を整形して文字列にしたい → ``mrb_ptr_to_str()`` を使う
     3. mruby の文字列オブジェクトをコピーしたい → ``mrb_str_dup()`` を使う
     4. 整数オブジェクトや浮動小数点数オブジェクトを変換したい → ``mrb_fixnum_to_str()`` または ``mrb_float_to_str()`` 辺りを使うといいかもしれない
     5. mruby の任意のオブジェクトを文字列にしたい → ``mrb_str_to_str()`` を使う
 3. C の文字列を変換したい
     1. リテラル文字列である → ``mrb_str_new_lit()`` を使う
     2. static const な文字列である → ``mrb_str_new_static()`` を使う
     3. どちらでもない・判断できない → ``mrb_str_new_cstr()`` を使う
 4. バイナリデータ、または文字列か判断できないデータを文字列オブジェクトにしたい → ``mrb_str_new()`` を使う
 5. それ以外 → 変換処理を自作するか ``/dev/null`` に突っ込む

----

NOTE:

  * `mrb_str_new_lit()` と `mrb_str_new_static()` の特徴と注意は?
    `mrb_intern_lit()`、`mrb_intern_static()` と同様、メモリの節約が出来ると同時にメモリ間コピーがないため CPU 資源・電力の節約にもつながる。
    またリテラル文字列・static const 文字列両方に当てはまらない場合は使うと、ここぞという時に泣く羽目になるのも同じ。
  * `mrb_obj_as_string()` は `mrb_str_to_str()` と何が違う?
    `mrb_obj_as_string()` はうまく文字列オブジェクトへ変換できない場合に最終手段として `mrb_any_to_s()` し、必ず文字列オブジェクトに変換する (が、望まない形となるかもしれない)。
    その点 `mrb_str_to_str()` は最終手段がなくてコケる (例外を起こす) ようになっている。

### C の文字列を取り出す

[mruby の String から C 言語の文字列を取り出す正しい方法 - Qiita](https://qiita.com/tsahara@github/items/b2a442af95ac893e10a1) に詳しく書かれている。

```c
/* 1.4.0:include/mruby/string.h */
char *RSTR_PTR(struct RString *); /* 実体はマクロ */
char *RSTRING_PTR(mrb_value);     /* 実体はマクロ */
char *RSTRING_END(mrb_value);     /* 実体はマクロ */
MRB_API const char *mrb_string_value_cstr(mrb_state *mrb, mrb_value *ptr);
MRB_API const char *mrb_string_value_ptr(mrb_state *mrb, mrb_value str);
```


## C のポインタ・構造体

```c
/* mruby/include/mruby/data.h */
typedef struct mrb_data_type {
  /** data type name */
  const char *struct_name;

  /** data type release function pointer */
  void (*dfree)(mrb_state *mrb, void*);
} mrb_data_type;

MRB_API struct RData *mrb_data_object_alloc(mrb_state *mrb, struct RClass *klass, void *datap, const mrb_data_type *type);
MRB_API void mrb_data_check_type(mrb_state *mrb, mrb_value, const mrb_data_type*);
MRB_API void *mrb_data_get_ptr(mrb_state *mrb, mrb_value, const mrb_data_type*);
MRB_API void *mrb_data_check_get_ptr(mrb_state *mrb, mrb_value, const mrb_data_type*);

#define Data_Wrap_Struct(mrb,klass,type,ptr)
#define Data_Make_Struct(mrb,klass,strct,type,sval,data)
#define Data_Get_Struct(mrb,obj,type,sval)
#define DATA_GET_PTR(mrb,obj,dtype,type)
#define DATA_PTR(d)
#define DATA_TYPE(d)
```

```c
struct RData *Data_Wrap_Struct(mrb_state *mrb, struct RClass *klass, const mrb_data_type *type, void *ptr);
void Data_Make_Struct(mrb_state *mrb, struct RClass *klass, TYPE_NAME, const mrb_data_type *type, USER_TYPE *&sval, struct RData *&data);
void Data_Get_Struct(mrb_state *mrb, mrb_value obj, const mrb_data_type *type, USER_TYPE *&sval);
USER_TYPE *DATA_GET_PTR(mrb_state *mrb, mrb_value obj, const mrb_data_type *dtype, TYPE_NAME);
```

### ***(注意) 利用者定義の構造体には mrb_value を保持させてはならない***

正確に言うと保持させること自体は可能だが、それだけだとそのオブジェクトは GC のマーク対象とはならないため、mruby の GC フェーズで回収対象となる。

紐付けるためには、``mrb_iv_set()`` / ``mrb_iv_get()`` を使ってやり取りする。

この事は [issues#2605](https://github.com/mruby/mruby/issues/2605) で説明があり、世代別/インクリメンタル GC との相性を理由としている。

構造体にもオブジェクトを保持させる場合は ``mrb_iv_set()`` で紐付けしたオブジェクトと整合性を保つ (構造体とインスタンス変数の両方で同じオブジェクトとなる) ようにする。

### 一時的にポインタをラッピングしたい

``mrb_data_object_alloc()`` を用いるまでもないが、一時的にポインタを mrb_value として扱う必要がある場合は ``mrb_cptr`` / ``mrb_cptr_value`` を利用する。

``mrb_rescue()`` や ``mrb_ensure()`` などで活躍。

mruby の GC が free したり、mrb_data_type で確認したりするための仕組みがないため、簡易な ``mrb_data_object_alloc()`` として代わりに使うべきではない。

GC 対象外。アリーナを消費しない。インスタンス変数の保持不可。クラスを持てない (ゆえに特異メソッドも持てない)。

```c
void *anyptr = ...;
mrb_value ptrobj = mrb_cptr_value(mrb, anyptr);

...そびえる関数の壁...

void *gotptr = mrb_cptr(ptrobj);
```

NOTE: mruby 空間に持ち出すことは可能だが、一度でも自分の手を離れた ``MRB_TT_CPTR`` オブジェクトはそれが本当に自分が流したオブジェクトなのか確認できないし、スコープ外・解放済みとなっている場合があるため触るべきではない。

### Inline Structures (mruby-1.3+)

3ワード分 (``sizeof(void *) * 3``) だけ確保されたメモリ領域を、利用者の都合で好き勝手にいじり回せるオブジェクト。

仕組みとしては RString の組み込みデータと同じ。ただしデータ長は変更できない。

[include/mruby/istruct.h](https://github.com/mruby/mruby/blob/1.4.0/include/mruby/istruct.h#L13) に記述のある通り、インスタンス変数の保持は不可。

``mrb_value`` を3ワード分のメモリ領域に置いたとしても GC のマーク対象外になる。

ファイナライザは利用不可。

```c
/* mrb_obj_alloc() を使って生オブジェクトを生成 */
struct RIstruct *objp = (struct RIstruct *)mrb_obj_alloc(mrb, MRB_TT_ISTRUCT, 任意のクラス);

/* inline_data は char の配列として定義されている */
memset(o->inline_data, -1, sizeof(o->inline_data));
```

```c
/* include/mruby/istruct.h */
#define ISTRUCT_DATA_SIZE (sizeof(void*) * 3)
struct RIstruct *RISTRUCT(mrb_value obj); /* 実体はマクロ */
char *ISTRUCT_PTR(mrb_value obj);         /* 実体はマクロ */
MRB_INLINE mrb_int mrb_istruct_size(void);
MRB_INLINE void *mrb_istruct_ptr(mrb_value object);
MRB_INLINE void mrb_istruct_copy(mrb_value dest, mrb_value src);
```


## ハッシュ (Hash)

### ハッシュオブジェクトの生成

```c
mrb_value mrb_hash_new(mrb_state *mrb);
mrb_value mrb_hash_new_capa(mrb_state*, int capacity);
```


## 例外処理・大域脱出 (💣)

```c
/* 1.4.0:include/mruby.h */
MRB_API struct RClass * mrb_exc_get(mrb_state *mrb, const char *name);
MRB_API mrb_value mrb_exc_new(mrb_state *mrb, struct RClass *c, const char *ptr, size_t len);
MRB_API mrb_noreturn void mrb_exc_raise(mrb_state *mrb, mrb_value exc);
extern struct RClass *E_RUNTIME_ERROR;      /* 実体はマクロ */
extern struct RClass *E_TYPE_ERROR;         /* 実体はマクロ */
extern struct RClass *E_ARGUMENT_ERROR;     /* 実体はマクロ */
extern struct RClass *E_INDEX_ERROR;        /* 実体はマクロ */
extern struct RClass *E_RANGE_ERROR;        /* 実体はマクロ */
extern struct RClass *E_NAME_ERROR;         /* 実体はマクロ */
extern struct RClass *E_NOMETHOD_ERROR;     /* 実体はマクロ */
extern struct RClass *E_SCRIPT_ERROR;       /* 実体はマクロ */
extern struct RClass *E_SYNTAX_ERROR;       /* 実体はマクロ */
extern struct RClass *E_LOCALJUMP_ERROR;    /* 実体はマクロ */
extern struct RClass *E_REGEXP_ERROR;       /* 実体はマクロ */
extern struct RClass *E_FROZEN_ERROR;       /* 実体はマクロ */
extern struct RClass *E_NOTIMP_ERROR;       /* 実体はマクロ */
extern struct RClass *E_FLOATDOMAIN_ERROR;  /* 実体はマクロ */
extern struct RClass *E_KEY_ERROR;          /* 実体はマクロ */
extern struct RClass *E_FIBER_ERROR;        /* 実体はマクロ */

/* 1.4.0:include/mruby/error.h */
struct RException *mrb_exc_ptr(mrb_value);  /* 実体はマクロ */
MRB_API void mrb_sys_fail(mrb_state *mrb, const char *mesg);
MRB_API mrb_value mrb_exc_new_str(mrb_state *mrb, struct RClass* c, mrb_value str);
mrb_value mrb_exc_new_str_lit(mrb_state*, struct RClass*, const char *);  /* 実体はマクロ */
MRB_API mrb_value mrb_make_exception(mrb_state *mrb, mrb_int argc, const mrb_value *argv);
MRB_API mrb_value mrb_exc_backtrace(mrb_state *mrb, mrb_value exc);
MRB_API mrb_value mrb_get_backtrace(mrb_state *mrb);
MRB_API mrb_noreturn void mrb_no_method_error(mrb_state *mrb, mrb_sym id, mrb_value args, const char *fmt, ...);
MRB_API mrb_value mrb_f_raise(mrb_state*, mrb_value);
```

- - - -

関連するヘッダに `include/mruby/throw.h` があるが、これは内部実装用であるため触るべきではない。

これに関して @take_cheeze さんからコメントの引用を許可頂きました。ありがとうございます。

> `mruby/throw.h` は内部実装用のヘッダなので、C++と使う予定があるなら絶対に使わないでください。
> C側では必ず　`mrb_exc_raise` などで例外をとばし、 `mrb_protect` で例外を捕捉してください。
> `mruby/throw.h` を使っている `mrbgem`　は移植性が低いので個人的に非推奨扱いです。

### 例外を発生させる

```c
/* include/mruby.h */
MRB_API mrb_noreturn void mrb_raise(mrb_state *mrb, struct RClass *c, const char *msg);
MRB_API mrb_noreturn void mrb_raisef(mrb_state *mrb, struct RClass *c, const char *fmt, ...);
```

例外クラスとテキストメッセージを指定するだけならば ``mrb_raise()`` で十分。

文字列に任意の値を埋め込みたい場合は ``mrb_raisef()`` を使う。ただし ``rb_raise`` とは異なり、``printf`` フォーマットは mruby オブジェクトを意味する ``%S`` のみが有効であることに注意。

```c
mrb_value obj1 = ...;
mrb_value obj2 = ...;
mrb_raisef(mrb, E_RUNTIME_ERROR, "error for %S and %S", obj1, obj2);
```

### 例外の対応処理をするには

``mruby-error`` パッケージが必要。

```c
/* 1.4.0:include/mruby/error.h */
MRB_API mrb_value mrb_protect(mrb_state *mrb, mrb_func_t body, mrb_value data, mrb_bool *state);
MRB_API mrb_value mrb_ensure(mrb_state *mrb, mrb_func_t body, mrb_value b_data, mrb_func_t ensure, mrb_value e_data);
MRB_API mrb_value mrb_rescue(mrb_state *mrb, mrb_func_t body, mrb_value b_data, mrb_func_t rescue, mrb_value r_data);
MRB_API mrb_value mrb_rescue_exceptions(mrb_state *mrb, mrb_func_t body, mrb_value b_data, mrb_func_t rescue, mrb_value r_data, mrb_int len, struct RClass **classes);
```

  * ``mrb_protect()`` は利用者によって与えられた ``body`` 関数で発生した例外 (大域脱出) を捕まえて、戻り値として返す。
  * ``mrb_ensure()`` は利用者によって与えられた ``body`` 関数を抜けた場合に必ず ``ensure`` 関数を呼ぶ。
  * ``mrb_rescue()`` および ``mrb_rescue_exceptions()`` は利用者によって与えられた ``body`` 関数で例外が起きた場合 ``rescue`` 関数を呼ぶ。

### 特定の例外だけを握りつぶしつつ共通の後始末を行いたい

`mruby-error` mrbgem パッケージが必要。

`mrb_ensure()` と `mrb_rescue_exceptions()` を組み合わせる。

二つの関数を組み合わせた関数 `protect_exceptions()` のサンプルコードは次の通り。

```c
struct protect_exc_try
{
  mrb_func_t body;
  const mrb_value *b_data;
  mrb_func_t rescue;
  const mrb_value *r_data;
  mrb_int len;
  struct RClass **classes;
};

static mrb_value
protect_exc_try(mrb_state *mrb, mrb_value arg)
{
  struct protect_exc_try *p = (struct protect_exc_try *)mrb_cptr(arg);

  return mrb_rescue_exceptions(mrb, p->body, *p->b_data, p->rescue, *p->r_data, p->len, p->classes);
}

mrb_value
protect_exceptions(mrb_state *mrb,
                   mrb_func_t body, mrb_value b_data,
                   mrb_func_t rescue, mrb_value r_data,
                   mrb_func_t ensure, mrb_value e_data,
                   mrb_int len, struct RClass **classes)
{
  if (ensure) {
    if (rescue) {
      struct protect_exc_try arg = { body, &b_data, rescue, &r_data, len, classes };

      return mrb_ensure(mrb, protect_exc_try, mrb_cptr_value(mrb, &arg), ensure, e_data);
    } else {
      return mrb_ensure(mrb, body, b_data, ensure, e_data);
    }
  } else if (rescue) {
    return mrb_rescue_exceptions(mrb, body, b_data, rescue, r_data, len, classes);
  } else {
    return body(b_data);
  }
}
```

### mrb_protect() で大域脱出を捕捉し、後処理を終えたら再搬送したい (💣💣💣💣💣)

[あぼーん](https://qiita.com/dearblue/items/d4adadd411593538177e/revisions/0?type=preview#mrb_protect-%E3%81%A7%E5%A4%A7%E5%9F%9F%E8%84%B1%E5%87%BA%E3%82%92%E6%8D%95%E6%8D%89%E3%81%97%E5%BE%8C%E5%87%A6%E7%90%86%E3%82%92%E7%B5%82%E3%81%88%E3%81%9F%E3%82%89%E5%86%8D%E6%90%AC%E9%80%81%E3%81%97%E3%81%9F%E3%81%84-)

### ``mrb_rescue()`` や ``mrb_rescue_exceptions()`` で再搬送させるようなことは出来ない (💣💣💣💣💣)

[あぼーん](https://qiita.com/dearblue/items/d4adadd411593538177e/revisions/0?type=preview#mrb_rescue-%E3%82%84-mrb_rescue_exceptions-%E3%81%A7%E5%86%8D%E6%90%AC%E9%80%81%E3%81%95%E3%81%9B%E3%82%8B%E3%82%88%E3%81%86%E3%81%AA%E3%81%93%E3%81%A8%E3%81%AF%E5%87%BA%E6%9D%A5%E3%81%AA%E3%81%84-)


## テスト

テスト環境のみで利用可能な ``FIXNUM_MAX``、``FIXNUM_MIN``、``FIXNUM_BIT``、``FLOAT_TOLERANCE`` 定数が用意される。

テストコードのファイルは ``test/`` に書いておくと、mruby のビルドスクリプトが勝手に探ってくれるようになっている。

``test/*.rb`` では主に次のメソッドを使う (``git grep 'def assert' test/assert.rb`` が役立つ)。

  * ``assert``
  * ``assert_true``
  * ``assert_false``
  * ``assert_equal``
  * ``assert_not_equal``
  * ``assert_nil``
  * ``assert_include``
  * ``assert_not_include``
  * ``assert_raise``
  * ``assert_nothing_raised``
  * ``assert_kind_of``
  * ``assert_float``

``test/*.c`` には ``src/*.c`` と同様に色々出来る。ただし ``void mrb_XXX_gem_test(mrb_state *mrb)`` 関数がテスト前に呼び出されるようになっている。

``mrbgem.rake`` でさわれるテスト時の設定は次の通り。

```
MRuby::Gem::Specification#add_test_dependency
MRuby::Gem::Specification#test_objs
MRuby::Gem::Specification#test_rbfiles
MRuby::Gem::Specification#test_args
MRuby::Gem::Specification#test_preload
```


## トラブルシューティング・バッドノウハウ

### MRB_INT16 + conf.enable_test で作成した bin/mrbtest が失敗する

```shell
$ host-int16/bin/mrbtest
mrbtest - Embeddable Ruby Test

ArgumentError: string (10000000) too big for integer
zsh: abort      host-int16/bin/mrbtest
```

みたいな状況にある場合、``mruby-bin-mrbc`` を追加してみる。

```ruby
MRuby::Build.new("host-int16") do |conf|
  conf.cc.defines = %w(MRB_INT16)
  conf.gem core: "mruby-bin-mrbc"
  conf.gem core: "mruby-bin-mruby"
  conf.enable_test
end
```


### MRB_NAN_BOXING を定義して構築した bin/mruby が SEGV や ABORT を起こす、

``build_config.rb`` に ``mruby-bin-mrbc`` を追加してみる。

```ruby
MRuby::Build.new("host-nan-boxing") do |conf|
  conf.cc.defines = %w(MRB_NAN_BOXING)
  conf.gem core: "mruby-bin-mrbc"
  conf.gem core: "mruby-bin-mruby"
end
```

### mrb_int の範囲で処理を分ける時、MRB_INT16 や MRB_INT64 と #if defined で行わない

``MRB_INT_MAX`` や ``MRB_INT_MIN`` で行うべき。

これは、``MRB_WORD_BOXING`` が定義されている時の予防となる。
この場合、整数値の有効ビットが C よりも1ビット少なくなるため、``#if defined`` に頼ると値の桁落ちが発生して不可解なエラーに悩まされることにつながる。

### 追加した mgem の include ディレクトリが探索対象とならない場合の対策

``build_config.rb`` で ``conf.gem`` した mgem は include パスに含まれない。

``mrbgem.rake`` で ``spec.add_dependency`` を指定することで、その mgem 内でのみ利用可能となる。

### 非公開・未公開 mgem を add_dependency で指定できない場合の対策

``mrbgem.rake`` の ``spec.add_dependency`` で指定可能なのは github や bitbucket で git リポジトリに置かれたもの、[mgem-list](https://github.com/mruby/mgem-list) に登録されたもの、``build_config.rb`` の ``conf.gem`` で ``conf.gem`` によって指定したものとなる。

そのため、ローカルディレクトっリのみにある mgem を指定したいならば、``build_config.rb`` の ``conf.gem`` で パッケージのディレクトリを指定し、依存する mgem の ``mrbgem.rake`` の ``spec.add_dependency`` でその***パッケージ名***を指定する。

### `gem core: "mruby-print"` したのに `Kernel#printf` が動作しない

`build_config.rb` に記述された `gem core: "mruby-print"` の***前へ*** `gem core: "mruby-sprintf"` を追加する。

```ruby:build_config.rb
MRuby::Build.new do |conf|
  gem core: "mruby-sprintf"
  gem core: "mruby-print"
end
```

#### `mruby-sprintf` と `mruby-print` の順番が重要

逆になっていると悲しいことが起きる。

悲劇が起きる設定例:

```ruby:build_config.rb
MRuby::Build.new do |conf|
  gem core: "mruby-print"   ## 順番が逆!
  gem core: "mruby-sprintf"
end
```

悲劇:

```
### print + sprintf は動作するのに……
$ host/bin/mruby -e 'print sprintf("%d\n", 100)'
100

### printf は動作しない!
$ host/bin/mruby -e 'printf("%d\n", 100)'
trace (most recent call last):
	[0] -e:1
-e:1: printf not available (NotImplementedError)
```


## 未整理

### mrb_rd_data_p ってなんぞや?

```c
/* 1.4.0:include/mruby/value.h */
static inline mrb_bool mrb_ro_data_p(const char *p); /* 通常では実体がマクロ */
```

渡されたポインタが static const であるかどうかを確認する関数。通常では `mrb_ro_data_p()` は偽を返すだけ。

[1.4.0:include/mruby/value.h](https://github.com/mruby/mruby/blob/1.4.0/include/mruby/value.h#L275-L305) を見ると、`conf.defines << "MRB_USE_ETEXT_EDATA"` した時に、テキストセグメントに含まれていれば真を返す関数となる (必要であれば `conf.defines << "MRB_NO_INIT_ARRAY_START"` を定義することが出来る)。

全ての環境でそのまま利用できるわけではない[^windows-have-not-etext]。

[^windows-have-not-etext]: mingw32 (Windows 向け) でコンパイル・リンクを試したら `_etext` シンボルが存在しないとしてリンクエラーとなった。

`mrb_str_new_cstr()` / `mrb_intern_cstr()` にリテラル文字列を渡しても `mrb_str_new_lit()` / `mrb_intern_lit()` と同じように扱われるため、特に小さい組み込み機器で mruby を動作させたい場合は (必要であれば `_etext` の独自実装と共に) 積極的に使っていくと美味しいかもしれない。

  * [Linux Man page of END](https://linuxjm.osdn.jp/html/LDP_man-pages/man3/etext.3.html)
  * [FreeBSD On-line Manual of "etext"](http://www.jp.freebsd.org/cgi/mroff.cgi?subdir=man&man=etext&dir=jpman-11.0.2%2Fman#toc)
  * [ARM コンパイラ armlinkユーザガイド : 10.4.3 glibc との SysV 互換性を確保するために定義されるシンボル定義](http://infocenter.arm.com/help/topic/com.arm.doc.dui0474lj/pge1362066045758_00009.html)

### 書式文字列

```c
/* include/mruby.h */
MRB_API mrb_value mrb_format(mrb_state *mrb, const char *format, ...);
```

フォーマット指定子は mruby のオブジェクトを意味する ``%S`` のみが利用できる。

### どうしても ``sprintf`` みたいな書式を使いたい

mruby に付属の ``mruby-sprintf`` は mruby 空間のみでしか利用できない。

そのため ``mrb_funcall()`` 経由で ``Kernel#sprintf`` を呼び出す。

```c
mrb_value format = mrb_str_new_cstr(mrb, "%s, %d");
mrb_value str = mrb_str_new_cstr(mrb, "ほにゃらら");
mrb_value num = mrb_fixnum_value(123456789);
mrb_value str;
str = mrb_funcall(mrb, mrb->object_class, mrb_intern_cstr(mrb, "sprintf"), 3, format, str, num);
```

#### 直接関数を呼び出す (💣💣💣)

おい見ろよ! ``mrbgems/mruby-sprintf/src/sprintf.c`` で定義されている ``mrb_str_format()`` 関数は ``static`` 修飾されてねえぞ! なんて都合がいいんだ!

プロトタイプ宣言がされたインクルードファイルがないから、自分で宣言しちまえば利用できるじゃん!

```c
/* mrbgems/mruby-sprintf/src/sprintf.c */
mrb_value mrb_str_format(mrb_state *mrb, mrb_int argc, const mrb_value *argv, mrb_value fmt);
```

本来の ``sprintf()`` のような可変長引数ではないし ``va_list`` も使えないため完全に置き換えられないが、それなりに事足りそうだ。

怒られないように、バレないように、こっそり使おう (💣💣💣)。


## REFERENCES

  * <https://github.com/mruby/mruby> (英語)
  * <http://forum.mruby.org/docs/index.html> (日本語)
  * <http://mruby.org/docs/> (英語)
  * [mrubyのmrb_gc_arena_save\(\)/mrb_gc_arena_restore\(\)の使い方 - Matzにっき\(2013-07-31\)](http://www.rubyist.net/~matz/20130731.html#p01)
  * [mruby で C 言語の構造体をラップしたオブジェクトを作る正しい方法 - Qiita](https://qiita.com/tsahara@github/items/86610a696f8ca792db45)
  * [mruby の String から C 言語の文字列を取り出す正しい方法 - Qiita](https://qiita.com/tsahara@github/items/b2a442af95ac893e10a1)
  * [最近のmrubyでC++を使ったmrbgemを作る時の注意事項的な何か - Qiita](https://qiita.com/kjunichi/items/ec87ca81557cb93e3b4f)
  * [mruby Cheat Sheet - Qiita](https://qiita.com/qtakamitsu/items/28672f546d53d04932ea)
  * <https://syucream.github.io/mrubook/> (日本語)
  * [mruby Advent Calendar 2015 - Qiita](https://qiita.com/advent-calendar/2015/mruby)
  * [mruby Advent Calendar 2016 - Qiita](https://qiita.com/advent-calendar/2016/mruby)
  * [mruby Advent Calendar 2017 - Qiita](https://qiita.com/advent-calendar/2017/mruby)


## LICENSING

  * <a rel="license" href="https://creativecommons.org/licenses/by/4.0/deed.ja"><img alt="クリエイティブ・コモンズ・ライセンス" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/80x15.png" /> この文書は引用されたものを除き クリエイティブ・コモンズ 表示 4.0 国際 ライセンスの下に提供されています。</a>
  * <a rel="license" href="https://creativecommons.org/publicdomain/zero/1.0/deed.ja"><img src="https://licensebuttons.net/p/zero/1.0/80x15.png" style="border-style: none;" alt="CC0" /> この文書に含まれるサンプルコードは引用されたものを除き クリエイティブ・コモンズ ゼロ ライセンスの下に提供されています。</a>