path: root/README.EXT

.\" README.EXT -  -*- Text -*- created at: Mon Aug  7 16:45:54 JST 1995

Rubyを拡張するための方法を解説する．

RubyはCコードを書くことによって，簡単に機能を追加できる．おおまかな手
順は以下の通りである．

  1. ファイルを用意する

     extディレクトリの下に拡張モジュール用のディレクトリを用意して，そ
     の配下に以下のファイルを用意する必要がある．

     + MANIFEST．必要なファイルの一覧．

       必ず必要．一時的なファイル以外の全てのファイル名を1行1ファイル
       の形式で記述すること．

     + Cのソースファイル．

       モジュールが1ファイルだけからなる時はモジュール名と同じ名前のファ
       イル名(モジュール.c)をつける．逆にモジュールが複数からなる時は
       モジュール名のついたソースファイルは避けること．

     + extconf.rb(optional)．設定用ファイル．

       関数やライブラリ，ヘッダの存在チェックをしたり，モジュール名な
       どを設定する．このファイルが無ければ全てデフォルトでコンパイル
       される．

     + depend(optional)．Makefileにインクルードするためのファ
       イルの依存関係を記述したファイル．

       `gcc -MM *.c > depend'とすれば自動的に生成できる．

  2. Cのソースファイルを用意する

     必ず「Init_モジュール名」という関数を用意し，その中で，変数やクラ
     スの定義や，クラスへのメソッドの登録などの初期化を行うこと．この
     関数の呼び出しはインタプリタの初期化時(静的リンクの場合)かモジュー
     ルのロード時(動的リンクの場合)に自動的に行われる．

* Ruby API

C言語からRubyの機能を利用するAPIは以下の通りである．

** 型

 VALUE

   Rubyオブジェクトを表現する型．必要に応じてキャストして用いる．組み
   込み型を表現するCの型はruby.hに記述してあるRで始まる構造体である．
   VALUE型をこれらにキャストするためにRで始まる構造体名を全て大文字に
   した名前のマクロが用意されている．

** 変数・定数

 Qnil

   定数: nilオブジェクト

 Qself

   変数: 現在のselfオブジェクトの値．一般にメソッドにはselfを指す引数
   が与えられるので, この変数にアクセスする必要はない．この変数の値を
   変更する時は以後のselfの値そのものが変わってしまうので, 特別な事情
   がない限り代入してはならない．

 TRUE

   定数: tオブジェクト(真のデフォルト値)

 FALSE

   定数: nilオブジェクト

** Cデータのカプセル化

 VALUE data_new(void *sval, void (*mark)(), void (*free)())

   Cの任意のポインタをカプセル化したrubyオブジェクトを返す．このポイン
   タがrubyからアクセスされなくなった時，freeで指定した関数が呼ばれる．
   また，このポインタの指すデータが他のrubyオブジェクトを指している場
   合，markに指定する関数でマークする必要がある．

 Make_Data_Struct(obj, iv, type, mark, free, sval)

   type型のメモリをmallocし，変数svalに代入した後，それをカプセル化し
   たデータをobjのインスタンス変数ivに代入するマクロ．

 Get_Data_Struct(obj, iv, type, sval)

   objのインスタンス変数ivが指すデータからtype型のポインタを取り出し
   変数svalに代入するマクロ．

** クラス/モジュール定義

 VALUE rb_define_class(char *name, VALUE super)

   superのサブクラスとして新しいRubyクラスを定義する．

 VALUE rb_define_module(char *name)

   新しいRubyモジュールを定義する．

 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)

   クラス定数を定義する．

** メソッド定義

 rb_define_method(VALUE class, char *name, VALUE (*func)(), int argc)

   メソッドを定義する．argcはselfを除く引数の数．argcが-1の時, 関数に
   は引数の数(selfを含まない)を第1引数, 引数の配列を第2引数とする形式
   で与えられる(第3引数はself)．argcが-2の時, 引数はself, 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)を設定する．

* extconf.rbの記述

拡張モジュールのディレクトリに`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を生成する．この関数を呼ばなければそのモ
   ジュールはコンパイルされない．

/*
 * Local variables:
 * fill-column: 70
 * end:
 */