diff options
Diffstat (limited to 'README.EXT')
| -rw-r--r-- | README.EXT | 1060 |
1 files changed, 0 insertions, 1060 deletions
diff --git a/README.EXT b/README.EXT deleted file mode 100644 index fb041bca9b..0000000000 --- a/README.EXT +++ /dev/null @@ -1,1060 +0,0 @@ -.\" README.EXT - -*- Text -*- created at: Mon Aug 7 16:45:54 JST 1995 - -This document explains how to make extention modules for Ruby. - -1．Basic knowledge - -In C, variables have types and data do not have types. In contrast, -Ruby variables do not have static type and data themselves have -types. So, data need to be converted across the languages. - -Data in Ruby represented C type `VALUE'. Each VALUE data have its -data-type. - -To retrieve an C data from the VALUE, you need to: - - (1) Identify VALUE's data type - (2) Convert VALUE into C data - -Converting to wrong data type may cause serious promblems. - - -1.1 Data-types - -Ruby interpreter has data-types as below: - - T_NIL nil - T_OBJECT ordinaly object - T_CLASS class - T_MODULE module - T_FLOAT floating point number - T_STRING string - T_REGEXP regular expression - T_ARRAY array - T_FIXNUM Fixnum(31bit integer) - T_HASH assosiative array - T_STRUCT (Ruby) structure - T_BIGNUM multi precision integer - T_TRUE true - T_FALSE false - T_DATA data - -Otherwise, there are several other types used internally: - - T_ICLASS - T_MATCH - T_VARMAP - T_SCOPE - T_NODE - -Most of the types are represented by C structures. - -1.2 Check Data Type of the VALUE - -The macro TYPE() defined in ruby.h shows data-type of the VALUE. -TYPE() returns the constant number T_XXXX described above. To handle -data-types, the code will be like: - - switch (TYPE(obj)) { - case T_FIXNUM: - /* process Fixnum */ - break; - case T_STRING: - /* process String */ - break; - case T_ARRAY: - /* process Array */ - break; - default: - /* raise exception */ - Fail("not valid value"); - break; - } - -There is the data-type check function. - - void Check_Type(VALUE value, int type) - -It raises an exception, if the VALUE does not have the type specified. - -There are faster check-macros for fixnums and nil. - - FIXNUM_P(obj) - NIL_P(obj) - -1.3 Convert VALUE into C data - -データタイプがT_NIL, T_FALSE, T_TRUEである時，データはそれぞ -れnil, false, trueです．このデータタイプのオブジェクトはひと -つずつしか存在しません． - -データタイプがT_FIXNUMの時，これは31bitのサイズを持つ整数で -す．FIXNUMをCの整数に変換するためにはマクロ「FIX2INT()」を使 -います．それから，FIXNUMに限らずRubyのデータを整数に変換する -「NUM2INT()」というマクロがあります．このマクロはデータタイ -プのチェック無しで使えます(整数に変換できない場合には例外が -発生する)． - -それ以外のデータタイプは対応するCの構造体があります．対応す -る構造体のあるVALUEはそのままキャスト(型変換)すれば構造体の -ポインタに変換できます． - -構造体は「struct RXxxxx」という名前でruby.hで定義されていま -す．例えば文字列は「struct RString」です．実際に使う可能性が -あるのは文字列と配列くらいだと思います． - -ruby.hでは構造体へキャストするマクロも「RXXXXX()」(全部大文 -字にしたもの)という名前で提供されています(例: RSTRING())． - -例えば，文字列strの長さを得るためには「RSTRING(str)->len」と -し，文字列strをchar*として得るためには「RSTRING(str)->ptr」 -とします．配列の場合には，それぞれ「RARRAT(str)->len」， -「RARRAT(str)->ptr」となります． - -Rubyの構造体を直接アクセスする時に気をつけなければならないこ -とは，配列や文字列の構造体の中身は参照するだけで，直接変更し -ないことです．直接変更した場合，オブジェクトの内容の整合性が -とれなくなって，思わぬバグの原因になります． - -1.4 Convert C data into VALUE - -VALUEの実際の構造は - - * FIXNUMの場合 - - 1bit右シフトして，LSBを立てる． - - * その他のポインタの場合 - - そのままVALUEにキャストする． - -となっています．よって，LSBをチェックすればVALUEがFIXNUMかど -うかわかるわけです(ポインタのLSBが立っていないことを仮定して -いる)． - -ですから，FIXNUM以外のRubyのオブジェクトの構造体は単にVALUE -にキャストするだけでVALUEに変換出来ます．ただし，任意の構造 -体がVALUEにキャスト出来るわけではありません．キャストするの -はRubyの知っている構造体(ruby.hで定義されているstruct RXxxx -のもの)だけにしておいてください． - -FIXNUMに関しては変換マクロを経由する必要があります．Cの整数 -からVALUEに変換するマクロは以下のものがあります．必要に応じ -て使い分けてください． - - INT2FIX() もとの整数が31bit以内に収まる時 - INT2NUM() 任意の整数からVALUEへ - -INT2NUM()は整数がFIXNUMの範囲に収まらない場合，Bignumに変換 -してくれます(が，少し遅い)． - -1.5 Manipulate Ruby data - -先程も述べた通り，Rubyの構造体をアクセスする時に内容の更新を -行うことは勧められません．で，Rubyのデータを操作する時には -Rubyが用意している関数を用いてください． - -ここではもっとも使われるであろう文字列と配列の生成/操作を行 -い関数をあげます(全部ではないです)． - - String funtions - - str_new(char *ptr, int len) - - Creates a new Ruby string. - - str_new2(char *ptr) - - Creates a new Ruby string from C string. This is equivalent to - str_new(ptr, strlen(ptr)). - - str_cat(VALUE str, char *ptr, int len) - - Appends len bytes data from ptr to the Ruby string. - - Array functions - - ary_new() - - Creates an array with no element. - - ary_new2(int len) - - Creates an array with no element, with allocating internal buffer - for len elements. - - ary_new3(int n, ...) - - Creates an n-elements array from arguments. - - ary_new4(int n, VALUE *elts) - - Creates an n-elements array from C array. - - ary_push(VALUE ary, VALUE val) - ary_pop(VALUE ary) - ary_shift(VALUE ary) - ary_unshift(VALUE ary, VALUE val) - ary_entry(VALUE ary, int idx) - - Array operations. The first argument to each functions must be an - array. They may dump core if other types given. - -2. Extend Ruby with C - -原理的にRubyで書けることはCでも書けます．RubyそのものがCで記 -述されているんですから，当然といえば当然なんですけど．ここで -はRubyの拡張に使うことが多いだろうと予測される機能を中心に紹 -介します． - -2.1 Add new features to Ruby - -Rubyで提供されている関数を使えばRubyインタプリタに新しい機能 -を追加することができます．Rubyでは以下の機能を追加する関数が -提供されています． - - * クラス，モジュール - * メソッド，特異メソッドなど - * 定数 - -では順に紹介します． - -2.1.1 Class/module definition - -クラスやモジュールを定義するためには，以下の関数を使います． - - VALUE rb_define_class(char *name, VALUE super) - VALUE rb_define_module(char *name) - -これらの関数は新しく定義されたクラスやモジュールを返します． -メソッドや定数の定義にこれらの値が必要なので，ほとんどの場合 -は戻り値を変数に格納しておく必要があるでしょう． - -2.1.2 Method/singleton method definition - -メソッドや特異メソッドを定義するには以下の関数を使います． - - void rb_define_method(VALUE class, char *name, - VALUE (*func)(), int argc) - - void rb_define_singleton_method(VALUE object, char *name, - VALUE (*func)(), int argc) - - -念のため説明すると「特異メソッド」とは，その特定のオブジェク -トに対してだけ有効なメソッドです．RubyではよくSmalltalkにお -けるクラスメソッドとして，クラスに対する特異メソッドが使われ -ます． - -これらの関数の argcという引数はCの関数へ渡される引数の数(と -形式)を決めます．argcが正の時は関数に引き渡す引数の数を意味 -します．16個以上の引数は使えません(が，要りませんよね，そん -なに)． - -argcが負の時は引数の数ではなく，形式を指定したことになります． -argcが-1の時は引数を配列に入れて渡されます．argcが-2の時は引 -数はRubyの配列として渡されます． - -メソッドを定義する関数はもう二つあります．ひとつはprivateメ -ソッドを定義する関数で，引数はrb_define_method()と同じです． - - void rb_define_private_method(VALUE class, char *name, - VALUE (*func)(), int argc) - -privateメソッドとは関数形式でしか呼び出すことの出来ないメソッ -ドです． - -もうひとつはモジュール関数を定義するものです．モジュール関数 -とはモジュールの特異メソッドであり，同時にprivateメソッドで -もあるものです．例をあげるとMathモジュールのsqrt()などがあげ -られます．このメソッドは - - Math.sqrt(4) - -という形式でも - - include Math - sqrt(4) - -という形式でも使えます．モジュール関数を定義する関数は以下の -通りです． - - void rb_define_module_function(VALUE module, char *name, - VALUE (*func)(), int argc) - -関数的メソッド(Kernelモジュールのprivaet method)を定義するた -めの関数は以下の通りです． - - void rb_define_global_function(char *name, VALUE (*func)(), int argc) - - -2.1.3 Constant definition - -拡張モジュールが必要な定数はあらかじめ定義しておいた方が良い -でしょう．定数を定義する関数は二つあります． - - void rb_define_const(VALUE class, char *name, VALUE val) - void rb_define_global_const(char *name, VALUE val) - -前者は特定のクラス/モジュールに属する定数を定義するもの，後 -者はグローバルな定数を定義するものです． - -2.2 Use Ruby features from C - -既に『1.5 Rubyのデータを操作する』で一部紹介したような関数を -使えば，Rubyの機能を実現している関数を直接呼び出すことが出来 -ます． - -# このような関数の一覧表はいまのところありません．ソースを見 -# るしかないですね． - -それ以外にもRubyの機能を呼び出す方法はいくつかあります． - -2.2.1 Rubyのプログラムをevalする - -CからRubyの機能を呼び出すもっとも簡単な方法として，文字列で -与えられたRubyのプログラムを評価する関数があります． - - VALUE rb_eval_string(char *str) - -この評価は現在の環境で行われます．つまり，現在のローカル変数 -などを受け継ぎます． - -2.2.2 ID or Symbol - -Cから文字列を経由せずにRubyのメソッドを呼び出すこともできま -す．その前に，Rubyインタプリタ内でメソッドや変数名を指定する -時に使われているIDについて説明しておきましょう． - -IDとは変数名，メソッド名を表す整数です．Rubyの中では - - :識別子 - -でアクセスできます．Cからこの整数を得るためには関数 - - rb_intern(char *name) - -を使います．また一文字の演算子はその文字コードがそのままシン -ボルになっています． - -2.2.3 Invoke Ruby method from C - -Cから文字列を経由せずにRubyのメソッドを呼び出すためには以下 -の関数を使います． - - VALUE rb_funcall(VALUE recv, ID mid, int argc, ...) - -この関数はオブジェクトrecvのmidで指定されるメソッドを呼び出 -します． - -2.2.4 変数/定数を参照/更新する - -Cから関数を使って参照・更新できるのは，クラス定数，インスタ -ンス変数です．大域変数は一部のものはCの大域変数としてアクセ -スできます．ローカル変数を参照する方法は公開していません． - -オブジェクトのインスタンス変数を参照・更新する関数は以下の通 -りです． - - VALUE rb_ivar_get(VALUE obj, ID id) - VALUE rb_ivar_set(VALUE obj, ID id, VALUE val) - -idはrb_intern()で得られるものを使ってください． - -クラス定数を参照するには以下の関数を使ってください． - - VALUE rb_const_get(VALUE obj, ID id) - -クラス定数を新しく定義するためには『2.1.3 定数定義』で紹介さ -れている関数を使ってください． - -3. Informatin sharing between Ruby and C - -C言語とRubyの間で情報を共有する方法について解説します． - -3.1 Ruby constant that Cから参照できるRubyの定数 - -Following Ruby constants can be referred from C. - - TRUE - FALSE - -Boolean values. FALSE is false in the C also (i.e. 0). - - Qnil - -Ruby nil in C scope. - -3.2 Global variables shared between C and Ruby - -CとRubyで大域変数を使って情報を共有できます．共有できる大域 -変数にはいくつかの種類があります．そのなかでもっとも良く使わ -れると思われるのはrb_define_variable()です． - - void rb_define_variable(char *name, VALUE *var) - -この関数はRubyとCとで共有する大域変数を定義します．変数名が -`$'で始まらない時には自動的に追加されます．この変数の値を変 -更すると自動的にRubyの対応する変数の値も変わります． - -またRuby側からは更新できない変数もあります．このread onlyの -変数は以下の関数で定義します． - - void rb_define_readonly_variable(char *name, VALUE *var) - -これら変数の他にhookをつけた大域変数を定義できます．hook付き -の大域変数は以下の関数を用いて定義します．hook付き大域変数の -値の参照や設定はhookで行う必要があります． - - void rb_define_hooked_variable(char *name, VALUE *var, - VALUE (*getter)(), VALUE (*setter)()) - -この関数はCの関数によってhookのつけられた大域変数を定義しま -す．変数が参照された時には関数getterが，変数に値がセットされ -た時には関数setterが呼ばれる．hookを指定しない場合はgetterや -setterに0を指定します． - -# getterもsetterも0ならばrb_define_variable()と同じになる． - -それから，Cの関数によって実現されるRubyの大域変数を定義する -関数があります． - - void rb_define_virtual_variable(char *name, - VALUE (*getter)(), VALUE (*setter)()) - -この関数によって定義されたRubyの大域変数が参照された時には -getterが，変数に値がセットされた時にはsetterが呼ばれます． - -The prototypes of the getter and setter functions are as following: - - (*getter)(ID id, void *data, struct global_entry* entry); - (*setter)(VALUE val, ID id, void *data, struct global_entry* entry); - -3.3 Encapsulate C data into Ruby object - -Cの世界で定義されたデータ(構造体)をRubyのオブジェクトとして -取り扱いたい場合がありえます．このような場合には，Dataという -RubyオブジェクトにCの構造体(へのポインタ)をくるむことでRuby -オブジェクトとして取り扱えるようになります． - -Dataオブジェクトを生成して構造体をRubyオブジェクトにカプセル -化するためには，以下のマクロを使います． - - Data_Wrap_Struct(class,mark,free,ptr) - -このマクロの戻り値は生成されたDataオブジェクトです． - -classはこのDataオブジェクトのクラスです．ptrはカプセル化する -Cの構造体へのポインタです．markはこの構造体がRubyのオブジェ -クトへの参照がある時に使う関数です．そのような参照を含まない -時には0を指定します． - -# そのような参照は勧められません． - -freeはこの構造体がもう不要になった時に呼ばれる関数です．この -関数がガーベージコレクタから呼ばれます． - -Cの構造体の割当とDataオブジェクトの生成を同時に行うマクロと -して以下のものが提供されています． - - Data_Make_Struct(class, type, mark, free, sval) - -このマクロの戻り値は生成されたDataオブジェクトです． - -class, mark, freeはData_Wrap_Structと同じ働きをします．type -は割り当てるC構造体の型です．割り当てられた構造体は変数sval -に代入されます．この変数の型は (type*) である必要があります． - -Dataオブジェクトからポインタを取り出すのは以下のマクロを用い -ます． - - Data_Get_Struct(obj, type, sval) - -Cの構造体へのポインタは変数svalに代入されます． - -これらのDataの使い方はちょっと分かりにくいので，後で説明する -例題を参照してください． - -4．Example - Create dbm module - -ここまでの説明でとりあえず拡張モジュールは作れるはずです． -Rubyのextディレクトリにすでに含まれているdbmモジュールを例に -して段階的に説明します． - -(1) make the directory - - % mkdir ext/dbm - -Rubyを展開したディレクトリの下，extディレクトリの中に拡張モ -ジュール用のディレクトリを作ります．名前は適当に選んで構いま -せん． - -(2) create MANIFEST file - - % cd ext/dbm - % touch MANIFEST - -拡張モジュールのディレクトリの下にはMANIFESTというファイルが -必要なので，とりあえず空のファイルを作っておきます．後でこの -ファイルには必要なファイル一覧が入ることになります． - -MANIFESTというファイルは，makeの時にディレクトリが拡張モジュー -ルを含んでいるかどうか判定するために使われれています． - -(3) design the library - -まあ，当然なんですけど，どういう機能を実現するかどうかまず設 -計する必要があります．どんなクラスをつくるか，そのクラスには -どんなメソッドがあるか，クラスが提供する定数などについて設計 -します．dbmクラスについてはext/dbm.docを参照してください． - -(4) write C code. - -拡張モジュール本体となるC言語のソースを書きます．C言語のソー -スがひとつの時には「モジュール名.c」を選ぶと良いでしょう．C -言語のソースが複数の場合には逆に「モジュール名.c」というファ -イル名は避ける必要があります．オブジェクトファイルとモジュー -ル生成時に中間的に生成される「モジュール名.o」というファイル -とが衝突するからです． - -Rubyは拡張モジュールをロードする時に「Init_モジュール名」と -いう関数を自動的に実行します．dbmモジュールの場合「Init_dbm」 -です．この関数の中でクラス，モジュール，メソッド，定数などの -定義を行います．dbm.cから一部引用します． - --- -Init_dbm() -{ - /* DBMクラスを定義する */ - cDBM = rb_define_class("DBM", cObject); - /* DBMはEnumerateモジュールをインクルードする */ - rb_include_module(cDBM, mEnumerable); - - /* DBMクラスのクラスメソッドopen(): 引数はCの配列で受ける */ - rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1); - - /* DBMクラスのメソッドclose(): 引数はなし */ - rb_define_method(cDBM, "close", fdbm_close, 0); - /* DBMクラスのメソッド[]: 引数は1個 */ - rb_define_method(cDBM, "[]", fdbm_fetch, 1); - : - - /* DBMデータを格納するインスタンス変数名のためのID */ - id_dbm = rb_intern("dbm"); -} --- - -DBMモジュールはdbmのデータと対応するオブジェクトになるはずで -すから，Cの世界のdbmをRubyの世界に取り込む必要があります． - - -dbm.cではData_Make_Structを以下のように使っています． - --- -struct dbmdata { - int di_size; - DBM *di_dbm; -}; - - -obj = Data_Make_Struct(class,struct dbmdata,0,free_dbm,dbmp); --- - -ここではdbmstruct構造体へのポインタをDataにカプセル化してい -ます．DBM*を直接カプセル化しないのはclose()した時の処理を考 -えてのことです． - -Dataオブジェクトからdbmstruct構造体のポインタを取り出すため -に以下のマクロを使っています． - --- -#define GetDBM(obj, dbmp) {\ - Data_Get_Struct(obj, struct dbmdata, dbmp);\ - if (dbmp->di_dbm == 0) closed_dbm();\ -} --- - -ちょっと複雑なマクロですが，要するにdbmdata構造体のポインタ -の取り出しと，closeされているかどうかのチェックをまとめてい -るだけです． - -DBMクラスにはたくさんメソッドがありますが，分類すると3種類の -引数の受け方があります．ひとつは引数の数が固定のもので，例と -してはdeleteメソッドがあります．deleteメソッドを実装している -fdbm_delete()はこのようになっています． - --- -static VALUE -fdbm_delete(obj, keystr) - VALUE obj, keystr; -{ - : -} --- - -引数の数が固定のタイプは第1引数がself，第2引数以降がメソッド -の引数となります． - -引数の数が不定のものはCの配列で受けるものとRubyの配列で受け -るものとがあります．dbmモジュールの中で，Cの配列で受けるもの -はDBMのクラスメソッドであるopen()です．これを実装している関 -数fdbm_s_open()はこうなっています． - --- -static VALUE -fdbm_s_open(argc, argv, class) - int argc; - VALUE *argv; - VALUE class; -{ - : - if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) { - mode = 0666; /* default value */ - } - : -} --- - -このタイプの関数は第1引数が与えられた引数の数，第2引数が与え -られた引数の入っている配列になります．selfは第3引数として与 -えられます． - -この配列で与えられた引数を解析するための関数がopen()でも使わ -れているrb_scan_args()です．第3引数に指定したフォーマットに -従い，第4変数以降に指定した変数に値を代入してくれます．この -フォーマットは，第1文字目が省略できない引数の数，第2文字目が -省略できる引数の数，第3文字目が対応する相手が無いあまりの引 -数があるかどうかを示す"*"です．2文字目と3文字目は省略できま -す．dbm.cの例では，フォーマットは"11"ですから，引数は最低1つ -で，2つまで許されるという意味になります．省略されている時の -変数の値はnil(C言語のレベルではQnil)になります． - -Rubyの配列で引数を受け取るものはindexesがあります．実装はこ -うです． - --- -static VALUE -fdbm_indexes(obj, args) - VALUE obj; - struct RArray *args; -{ - : -} --- - -第1引数はself，第2引数はRubyの配列です．ここではキャストを減 -らすため struct RArray* で受けていますが，VALUEでも同じこと -です． - -** 注意事項 - -Rubyと共有はしないがRubyのオブジェクトを格納する可能性のある -Cの大域変数は以下の関数を使ってRubyインタプリタに変数の存在 -を教えてあげてください．でないとGCでトラブルを起こします． - - void rb_global_variable(VALUE *var) - -(5) prepare extconf.rb - -もしディレクトリに「extconf.rb」というファイルが存在すれば， -make時に実行されます．なければ適当にMakefileが生成されます． - -extconf.rbはモジュールのコンパイルに必要な条件のチェックなど -を行うことが目的です．extconf.rbの中では以下のRuby関数を使う -ことが出来ます． - - have_library(lib, func): ライブラリの存在チェック - have_func(func): 関数の存在チェック - have_header(header): ヘッダファイルの存在チェック - create_makefile(target): Makefileの生成 - -以下の変数を使うことができます． - - $CFLAGS: コンパイル時に追加的に指定するフラグ(-Iなど) - $LDFLAGS: リンク時に追加的に指定するフラグ(-Lなど) - -モジュールをコンパイルする条件が揃わなず，そのモジュールはコ -ンパイルしない時にはcreate_makefileを呼ばなければMakefileは -生成されず，コンパイルも行われません． - -(6) prepare depend (optional) - -もし，ディレクトリにdependというファイルが存在すれば， -Makefileが依存関係をチェックしてくれます． - - % gcc -MM *.c > depend - -などで作ることが出来ます．あって損は無いでしょう． - -(7) MANIFESTファイルにファイル名を入れる - - % ls > MANIFEST - % vi MANIFEST - -*.o, *~など不必要なファイル以外はMANIFESTに追加しておきます． -make時にはMANIFESTの内容は参照しませんので，空のままでも問題 -は起きませんが，パッケージングの時に参照することがあるのと， -必要なファイルを区別できるので，用意しておいた方が良いでしょ -う． - -(8) make - -Rubyのディレクトリでmakeを実行するとMakefileを生成からmake， -必要によってはそのモジュールのRubyへのリンクまで自動的に実行 -してくれます．extconf.rbを書き換えるなどしてMakefileの再生成 -が必要な時はまたRubyディレクトリでmakeしてください． - -(9) debug - -You may need to debug the module. The modules can be linked -statically by adding directory name in the ext/Setup file, -so that you can inspect the module by the debugger. - -(10) done, now you have the extension module - -後はこっそり使うなり，広く公開するなり，売るなり，ご自由にお -使いください．Rubyの作者は拡張モジュールに関して一切の権利を -主張しません． - -Appendix A. Rubyのソースコードの分類 - -Rubyのソースはいくつかに分類することが出来ます．このうちクラ -スライブラリの部分は基本的に拡張モジュールと同じ作り方になっ -ています．これらのソースは今までの説明でほとんど理解できると -思います． - -ruby language core - - class.c - error.c - eval.c - gc.c - object.c - parse.y - variable.c - -utility functions - - dln.c - fnmatch.c - glob.c - regex.c - st.c - util.c - -ruby interpreter implementation - - dmyext.c - inits.c - main.c - ruby.c - version.c - -class library - - array.c - bignum.c - compar.c - dir.c - enum.c - file.c - hash.c - io.c - math.c - numeric.c - pack.c - process.c - random.c - range.c - re.c - signal.c - sprintf.c - string.c - struct.c - time.c - -Appendix B. 拡張用関数リファレンス - -C言語からRubyの機能を利用するAPIは以下の通りである． - -** 型 - - VALUE - -Rubyオブジェクトを表現する型．必要に応じてキャストして用いる． -組み込み型を表現するCの型はruby.hに記述してあるRで始まる構造 -体である．VALUE型をこれらにキャストするためにRで始まる構造体 -名を全て大文字にした名前のマクロが用意されている． - -** Variables and constants - - Qnil - -const: nil object - - TRUE - -const: TRUE object(default true value) - - FALSE - -const: FALSE object - -** Cデータのカプセル化 - - Data_Wrap_Struct(VALUE class, void (*mark)(), void (*free)(), void *sval) - -Cの任意のポインタをカプセル化したRubyオブジェクトを返す．こ -のポインタがRubyからアクセスされなくなった時，freeで指定した -関数が呼ばれる．また，このポインタの指すデータが他のRubyオブ -ジェクトを指している場合，markに指定する関数でマークする必要 -がある． - - Data_Make_Struct(class, type, mark, free, sval) - -type型のメモリをmallocし，変数svalに代入した後，それをカプセ -ル化したデータを返すマクロ． - - Data_Get_Struct(data, type, sval) - -dataからtype型のポインタを取り出し変数svalに代入するマクロ． - -** クラス/モジュール定義 - - VALUE rb_define_class(char *name, VALUE super) - -superのサブクラスとして新しいRubyクラスを定義する． - - VALUE rb_define_class_under(VALUE module, char *name, VALUE super) - -superのサブクラスとして新しいRubyクラスを定義し，moduleの定 -数として定義する． - - VALUE rb_define_module(char *name) - -新しいRubyモジュールを定義する． - - VALUE rb_define_module_under(VALUE module, char *name, VALUE super) - -新しいRubyモジュールを定義し，moduleの定数として定義する． - - void rb_include_module(VALUE class, VALUE module) - -モジュールをインクルードする．classがすでにmoduleをインクルー -ドしている時には何もしない(多重インクルードの禁止)． - - void rb_extend_object(VALUE object, VALUE module) - -オブジェクトをモジュール(で定義されているメソッド)で拡張する． - -** 大域変数定義 - - void rb_define_variable(char *name, VALUE *var) - -RubyとCとで共有するグローバル変数を定義する．変数名が`$'で始 -まらない時には自動的に追加される．nameとしてRubyの識別子とし -て許されない文字(例えば` ')を含む場合にはRubyプログラムから -は見えなくなる． - - void rb_define_readonly_variable(char *name, VALUE *var) - -RubyとCとで共有するread onlyのグローバル変数を定義する．read -onlyであること以外はrb_define_variable()と同じ． - - void rb_define_virtual_variable(char *name, - VALUE (*getter)(), VALUE (*setter)()) - -関数によって実現されるRuby変数を定義する．変数が参照された時 -にはgetterが，変数に値がセットされた時にはsetterが呼ばれる． - - void rb_define_hooked_variable(char *name, VALUE *var, - VALUE (*getter)(), VALUE (*setter)()) - -関数によってhookのつけられたグローバル変数を定義する．変数が -参照された時にはgetterが，関数に値がセットされた時にはsetter -が呼ばれる．getterやsetterに0を指定した時にはhookを指定しな -いのと同じ事になる． - - void rb_global_variable(VALUE *var) - -GCのため，Rubyプログラムからはアクセスされないが, Rubyオブジェ -クトを含む大域変数をマークする． - -** クラス定数 - - void rb_define_const(VALUE class, char *name, VALUE val) - -クラス定数を定義する． - - void rb_define_global_const(char *name, VALUE val) - -大域定数を定義する． - - rb_define_const(cKernal, name, val) - -と同じ意味． - -** メソッド定義 - - rb_define_method(VALUE class, char *name, VALUE (*func)(), int argc) - -メソッドを定義する．argcはselfを除く引数の数．argcが-1の時, -関数には引数の数(selfを含まない)を第1引数, 引数の配列を第2引 -数とする形式で与えられる(第3引数はself)．argcが-2の時, 第1引 -数がself, 第2引数がargs(argsは引数を含むRubyの配列)という形 -式で与えられる． - - rb_define_private_method(VALUE class, char *name, VALUE (*func)(), int argc) - -privateメソッドを定義する．引数はrb_define_method()と同じ． - - rb_define_singleton_method(VALUE class, char *name, VALUE (*func)(), int argc) - -特異メソッドを定義する．引数はrb_define_method()と同じ． - - rb_scan_args(int atgc, VALUE *argv, char *fmt, ...) - -argc,argv形式で与えられた引数を分解する．fmtは必須引数の数, -付加引数の数, 残りの引数があるかを指定する文字列で, "数字数 -字*"という形式である． 2 番目の数字と"*"はそれぞれ省略可能で -ある．必須引数が一つもない場合は0を指定する．第3引数以降は変 -数へのポインタで, 該当する要素がその変数に格納される．付加引 -数に対応する引数が与えられていない場合は変数にQnilが代入され -る． - -** Rubyメソッド呼び出し - - VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) - -メソッド呼び出し．文字列からmidを得るためにはrb_intern()を使う． - - VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv) - -メソッド呼び出し．引数をargc,argv形式で渡す． - - VALUE rb_eval_string(char *str) - -文字列をRubyとスクリプトしてコンパイル・実行する． - - ID rb_intern(char *name) - -文字列に対応するIDを返す． - - char *rb_id2name(ID id) - -IDに対応する文字列を返す(デバッグ用)． - - char *rb_class2name(VALUE class) - -classの名前を返す(デバッグ用)．classが名前を持たない時には, -祖先を遡って名前を持つクラスの名前を返す． - -** インスタンス変数 - - VALUE rb_iv_get(VALUE obj, char *name) - -objのインスタンス変数の値を得る．`@'で始まらないインスタンス -変数は Rubyプログラムからアクセスできない「隠れた」インスタ -ンス変数になる． - - VALUE rb_iv_set(VALUE obj, char *name, VALUE val) - -objのインスタンス変数をvalにセットする． - -** 制御構造 - - VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) - -func2をブロックとして設定し, func1をイテレータとして呼ぶ． -func1には arg1が引数として渡され, func2には第1引数にイテレー -タから与えられた値, 第2引数にarg2が渡される． - - VALUE rb_yield(VALUE val) - -valを値としてイテレータブロックを呼び出す． - - VALUE rb_rescue(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2) - -関数func1をarg1を引数に呼び出す．func1の実行中に例外が発生し -た時には func2をarg2を引数として呼ぶ．戻り値は例外が発生しな -かった時はfunc1の戻り値, 例外が発生した時にはfunc2の戻り値で -ある． - - VALUE rb_ensure(VALUE (*func1)(), void *arg1, void (*func2)(), void *arg2) - -関数func1をarg1を引数として実行し, 実行終了後(たとえ例外が発 -生しても) func2をarg2を引数として実行する．戻り値はfunc1の戻 -り値である(例外が発生した時は戻らない)． - -** 例外・エラー - - void Warning(char *fmt, ...) - -verbose時に標準エラー出力に警告情報を表示する．引数はprintf()と同じ． - - void Fail(char *fmt, ...) - -例外を発生させる．引数はprintf()と同じ． - - void Fatal(char *fmt, ...) - -致命的例外を発生させる．通常の例外処理は行なわれず, インター -プリタが終了する(ただしensureで指定されたコードは終了前に実 -行される)． - - void Bug(char *fmt, ...) - -インタープリタなどプログラムのバグでしか発生するはずのない状 -況の時呼ぶ．インタープリタはコアダンプし直ちに終了する．例外 -処理は一切行なわれない． - -** Rubyの初期化・実行 - -Rubyをアプリケーションに埋め込む場合には以下のインタフェース -を使う．通常の拡張モジュールには必要ない． - - void ruby_init(int argc, char **argv, char **envp) - -Rubyインタプリタの初期化を行なう． - - void ruby_run() - -Rubyインタプリタを実行する． - - void ruby_script(char *name) - -Rubyのスクリプト名($0)を設定する． - - -Appendix B. extconf.rbで使える関数たち - -extconf.rbの中では利用可能なコンパイル条件チェックの関数は以 -下の通りである． - - have_library(lib, func) - -関数funcを定義しているライブラリlibの存在をチェックする．ラ -イブラリが存在する時，TRUEを返す． - - have_func(func) - -関数funcの存在をチェックする．funcが標準ではリンクされないラ -イブラリ内のものである時には先にhave_libraryでそのライブラリ -をチェックしておく事．関数が存在する時TRUEを返す． - - have_header(header) - -ヘッダファイルの存在をチェックする．ヘッダファイルが存在する -時TRUEを返す． - - create_makefile(target) - -拡張モジュール用のMakefileを生成する．この関数を呼ばなければ -そのモジュールはコンパイルされない．targetはモジュール名を表 -す． - -/* - * Local variables: - * fill-column: 60 - * end: - */ |