summaryrefslogtreecommitdiff
path: root/README.EXT
diff options
context:
space:
mode:
Diffstat (limited to 'README.EXT')
-rw-r--r--README.EXT308
1 files changed, 308 insertions, 0 deletions
diff --git a/README.EXT b/README.EXT
new file mode 100644
index 0000000000..efa627a24a
--- /dev/null
+++ b/README.EXT
@@ -0,0 +1,308 @@
+.\" 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:
+ */