From 6fd4db3848dccf0fe44d1f09e24bec93db3c44dc Mon Sep 17 00:00:00 2001 From: kazu Date: Mon, 20 Feb 2017 12:20:22 +0000 Subject: extension.rdoc: add document title * doc/extension.rdoc, doc/extension.ja.rdoc: [DOC] add title and adapt subheading levels. * doc/extension.rdoc: [DOC] fix subheading level of section about "Ruby Constants That Can Be Accessed From C". * doc/extension.ja.rdoc: [DOC] add missing subheading. [ruby-core:79590] [Bug #13229] Author: Marcus Stollsteimer git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@57665 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- doc/extension.ja.rdoc | 130 ++++++++++++++++++++++++++------------------------ 1 file changed, 67 insertions(+), 63 deletions(-) (limited to 'doc/extension.ja.rdoc') diff --git a/doc/extension.ja.rdoc b/doc/extension.ja.rdoc index 5323bce36b..5ae96a96ae 100644 --- a/doc/extension.ja.rdoc +++ b/doc/extension.ja.rdoc @@ -1,8 +1,10 @@ # extension.ja.rdoc - -*- RDoc -*- created at: Mon Aug 7 16:45:54 JST 1995 += Rubyの拡張ライブラリの作り方 + Rubyの拡張ライブラリの作り方を説明します． -= 基礎知識 +== 基礎知識 Cの変数には型があり，データには型がありません．ですから，た とえばポインタをintの変数に代入すると，その値は整数として取 @@ -23,7 +25,7 @@ VALUEからCにとって意味のあるデータを取り出すためには の両方が必要です．(1)を忘れると間違ったデータの変換が行われ て，最悪プログラムがcore dumpします． -== データタイプ +=== データタイプ Rubyにはユーザが使う可能性のある以下のタイプがあります． @@ -57,7 +59,7 @@ T_SYMBOL :: シンボル ほとんどのタイプはCの構造体で実装されています． -== VALUEのデータタイプをチェックする +=== VALUEのデータタイプをチェックする ruby.hではTYPE()というマクロが定義されていて，VALUEのデータ タイプを知ることが出来ます．TYPE()マクロは上で紹介したT_XXXX @@ -94,7 +96,7 @@ FIXNUMとNILに関してはより高速な判別マクロが用意されてい FIXNUM_P(obj) NIL_P(obj) -== VALUEをCのデータに変換する +=== VALUEをCのデータに変換する データタイプがT_NIL，T_FALSE，T_TRUEである時，データはそれぞ れnil，false，trueです．このデータタイプのオブジェクトはひと @@ -155,7 +157,7 @@ Rubyの構造体を直接アクセスする時に気をつけなければなら ないことです．直接変更した場合，オブジェクトの内容の整合性が とれなくなって，思わぬバグの原因になります． -== CのデータをVALUEに変換する +=== CのデータをVALUEに変換する VALUEの実際の構造は @@ -188,7 +190,7 @@ INT2NUM() :: 任意の整数からVALUEへ INT2NUM()は整数がFIXNUMの範囲に収まらない場合，Bignumに変換 してくれます(が，少し遅い)． -== Rubyのデータを操作する +=== Rubyのデータを操作する 先程も述べた通り，Rubyの構造体をアクセスする時に内容の更新を 行うことは勧められません．で，Rubyのデータを操作する時には @@ -197,7 +199,7 @@ Rubyが用意している関数を用いてください． ここではもっとも使われるであろう文字列と配列の生成/操作を行 う関数をあげます(全部ではないです)． -=== 文字列に対する関数 +==== 文字列に対する関数 rb_str_new(const char *ptr, long len) :: @@ -295,7 +297,7 @@ rb_str_set_len(VALUE str, long len) :: lenバイトまでの内容は保存される．lenはstrの容量を越えてい てはならない． -=== 配列に対する関数 +==== 配列に対する関数 rb_ary_new() :: @@ -353,14 +355,14 @@ rb_ary_cat(VALUE ary, const VALUE *ptr, long len) :: 配列aryにptrからlen個のオブジェクトを追加する． -= Rubyの機能を使う +== Rubyの機能を使う 原理的にRubyで書けることはCでも書けます．RubyそのものがCで記 述されているんですから，当然といえば当然なんですけど．ここで はRubyの拡張に使うことが多いだろうと予測される機能を中心に紹 介します． -== Rubyに機能を追加する +=== Rubyに機能を追加する Rubyで提供されている関数を使えばRubyインタプリタに新しい機能 を追加することができます．Rubyでは以下の機能を追加する関数が @@ -372,7 +374,7 @@ Rubyで提供されている関数を使えばRubyインタプリタに新しい では順に紹介します． -=== クラス/モジュール定義 +==== クラス/モジュール定義 クラスやモジュールを定義するためには，以下の関数を使います． @@ -389,7 +391,7 @@ Rubyで提供されている関数を使えばRubyインタプリタに新しい VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super) VALUE rb_define_module_under(VALUE outer, const char *name) -=== メソッド/特異メソッド定義 +==== メソッド/特異メソッド定義 メソッドや特異メソッドを定義するには以下の関数を使います． @@ -483,7 +485,7 @@ funcはクラスを引数として受け取って，新しく割り当てられ VALUE rb_current_receiver(void) -=== 定数定義 +==== 定数定義 拡張ライブラリが必要な定数はあらかじめ定義しておいた方が良い でしょう．定数を定義する関数は二つあります． @@ -494,7 +496,7 @@ funcはクラスを引数として受け取って，新しく割り当てられ 前者は特定のクラス/モジュールに属する定数を定義するもの，後 者はグローバルな定数を定義するものです． -== Rubyの機能をCから呼び出す +=== Rubyの機能をCから呼び出す 既に『1.5 Rubyのデータを操作する』で一部紹介したような関数を 使えば，Rubyの機能を実現している関数を直接呼び出すことが出来 @@ -505,7 +507,7 @@ funcはクラスを引数として受け取って，新しく割り当てられ それ以外にもRubyの機能を呼び出す方法はいくつかあります． -=== Rubyのプログラムをevalする +==== Rubyのプログラムをevalする CからRubyの機能を呼び出すもっとも簡単な方法として，文字列で 与えられたRubyのプログラムを評価する以下の関数があります． @@ -523,7 +525,7 @@ CからRubyの機能を呼び出すもっとも簡単な方法として，文字 この関数はエラーが発生するとnilを返します．そして，成功時には *stateはゼロに，さもなくば非ゼロになります． -=== IDまたはシンボル +==== IDまたはシンボル Cから文字列を経由せずにRubyのメソッドを呼び出すこともできま す．その前に，Rubyインタプリタ内でメソッドや変数名を指定する @@ -566,7 +568,7 @@ Rubyから引数として与えられたシンボル(または文字列)をシ これらの関数は，IDの代わりにシンボルを返すことを除けば上記の 関数と同じです． -=== CからRubyのメソッドを呼び出す +==== CからRubyのメソッドを呼び出す Cから文字列を経由せずにRubyのメソッドを呼び出すためには以下 の関数を使います． @@ -582,7 +584,7 @@ Cから文字列を経由せずにRubyのメソッドを呼び出すためには applyには引数としてRubyの配列を与えます． -=== 変数/定数を参照/更新する +==== 変数/定数を参照/更新する Cから関数を使って参照・更新できるのは，定数，インスタンス変 数です．大域変数は一部のものはCの大域変数としてアクセスでき @@ -603,11 +605,11 @@ idはrb_intern()で得られるものを使ってください． 定数を新しく定義するためには『2.1.3 定数定義』で紹介さ れている関数を使ってください． -= RubyとCとの情報共有 +== RubyとCとの情報共有 C言語とRubyの間で情報を共有する方法について解説します． -== Cから参照できるRubyの定数 +=== Cから参照できるRubyの定数 以下のRubyの定数はCのレベルから参照できます． @@ -620,7 +622,7 @@ Qnil :: C言語から見た「nil」． -== CとRubyで共有される大域変数 +=== CとRubyで共有される大域変数 CとRubyで大域変数を使って情報を共有できます．共有できる大域 変数にはいくつかの種類があります．そのなかでもっとも良く使わ @@ -672,7 +674,7 @@ getterとsetterの仕様は以下の通りです． (*getter)(ID id); (*setter)(VALUE val, ID id); -== CのデータをRubyオブジェクトにする +=== CのデータをRubyオブジェクトにする Cの世界で定義されたデータ(構造体)をRubyのオブジェクトとして 取り扱いたい場合がありえます．このような場合はTypedData_XXX @@ -685,7 +687,7 @@ Cの世界で定義されたデータ(構造体)をRubyのオブジェクトと があります． ++ -=== 構造体からオブジェクトへ +==== 構造体からオブジェクトへ 構造体へのポインタsvalをRubyオブジェクトに変換するには次のマ クロを使います。 @@ -793,7 +795,7 @@ klass, data_typeはData_Wrap_Structと同じ働きをします．type は割り当てるC構造体の型です．割り当てられた構造体は変数sval に代入されます．この変数の型は (type*) である必要があります． -=== オブジェクトから構造体へ +==== オブジェクトから構造体へ TypedData_Wrap_StructやTypedData_Make_Structで生成したオブジェ クトから構造体へのポインタを復元するには以下のマクロを用いま @@ -806,7 +808,9 @@ Cの構造体へのポインタは変数svalに代入されます． これらのマクロの使い方はちょっと分かりにくいので，後で説明す る例題を参照してください． -== ディレクトリを作る +== 例: dbmの拡張ライブラリの作成 + +=== ディレクトリを作る % mkdir ext/dbm @@ -816,14 +820,14 @@ Ruby 1.1からは任意のディレクトリでダイナミックライブラリ ライブラリ用のディレクトリを作る必要があります．名前は適当に 選んで構いません． -== 設計する +=== 設計する まあ，当然なんですけど，どういう機能を実現するかどうかまず設 計する必要があります．どんなクラスをつくるか，そのクラスには どんなメソッドがあるか，クラスが提供する定数などについて設計 します． -== Cコードを書く +=== Cコードを書く 拡張ライブラリ本体となるC言語のソースを書きます．C言語のソー スがひとつの時には「ライブラリ名.c」を選ぶと良いでしょう．C @@ -960,7 +964,7 @@ Cの大域変数は以下の関数を使ってRubyインタプリタに変数の void rb_global_variable(VALUE *var) -== extconf.rbを用意する +=== extconf.rbを用意する Makefileを作る場合の雛型になるextconf.rbというファイルを作り ます．extconf.rbはライブラリのコンパイルに必要な条件のチェッ @@ -991,7 +995,7 @@ Makefileを作る場合の雛型になるextconf.rbというファイルを作 パイルしない時にはcreate_makefileを呼ばなければMakefileは生 成されず，コンパイルも行われません． -== dependを用意する +=== dependを用意する もし，ディレクトリにdependというファイルが存在すれば， Makefileが依存関係をチェックしてくれます． @@ -1000,7 +1004,7 @@ Makefileが依存関係をチェックしてくれます． などで作ることが出来ます．あって損は無いでしょう． -== Makefileを生成する +=== Makefileを生成する Makefileを実際に生成するためには @@ -1022,7 +1026,7 @@ vendor_ruby ディレクトリにインストールする場合には ディレクトリをext以下に用意した場合にはRuby全体のmakeの時に 自動的にMakefileが生成されますので，このステップは不要です． -== makeする +=== makeする 動的リンクライブラリを生成する場合にはその場でmakeしてくださ い．必要であれば make install でインストールされます． @@ -1040,26 +1044,26 @@ extconf.rbを書き換えるなどしてMakefileの再生成が必要な時は を作り，そこに 拡張子 .rb のファイルを置いておけば同時にイン ストールされます． -== デバッグ +=== デバッグ まあ，デバッグしないと動かないでしょうね．ext/Setupにディレ クトリ名を書くと静的にリンクするのでデバッガが使えるようにな ります．その分コンパイルが遅くなりますけど． -== できあがり +=== できあがり 後はこっそり使うなり，広く公開するなり，売るなり，ご自由にお 使いください．Rubyの作者は拡張ライブラリに関して一切の権利を 主張しません． -= Appendix A. Rubyのソースコードの分類 +== Appendix A. Rubyのソースコードの分類 Rubyのソースはいくつかに分類することが出来ます．このうちクラ スライブラリの部分は基本的に拡張ライブラリと同じ作り方になっ ています．これらのソースは今までの説明でほとんど理解できると 思います． -== Ruby言語のコア +=== Ruby言語のコア class.c :: クラスとモジュール error.c :: 例外クラスと例外機構 @@ -1068,14 +1072,14 @@ load.c :: ライブラリのロード object.c :: オブジェクト variable.c :: 変数と定数 -== Rubyの構文解析器 +=== Rubyの構文解析器 parse.y :: 字句解析器と構文定義 parse.c :: 自動生成 defs/keywords :: 予約語 lex.c :: 自動生成 -== Rubyの評価器 (通称YARV) +=== Rubyの評価器 (通称YARV) compile.c eval.c @@ -1101,7 +1105,7 @@ lex.c :: 自動生成 -> opt*.inc : 自動生成 -> vm.inc : 自動生成 -== 正規表現エンジン (鬼車) +=== 正規表現エンジン (鬼車) regex.c regcomp.c @@ -1111,7 +1115,7 @@ lex.c :: 自動生成 regparse.c regsyntax.c -== ユーティリティ関数 +=== ユーティリティ関数 debug.c :: Cデバッガ用のデバッグシンボル dln.c :: 動的ローディング @@ -1119,7 +1123,7 @@ st.c :: 汎用ハッシュ表 strftime.c :: 時刻整形 util.c :: その他のユーティリティ -== Rubyコマンドの実装 +=== Rubyコマンドの実装 dmyext.c dmydln.c @@ -1133,7 +1137,7 @@ util.c :: その他のユーティリティ gem_prelude.rb prelude.rb -== クラスライブラリ +=== クラスライブラリ array.c :: Array bignum.c :: Bignum @@ -1165,24 +1169,24 @@ time.c :: Time defs/known_errors.def :: 例外クラス Errno::* -> known_errors.inc :: 自動生成 -== 多言語化 +=== 多言語化 encoding.c :: Encoding transcode.c :: Encoding::Converter enc/*.c :: エンコーディングクラス群 enc/trans/* :: コードポイント対応表 -== gorubyコマンドの実装 +=== gorubyコマンドの実装 goruby.c golf_prelude.rb : goruby固有のライブラリ -> golf_prelude.c : 自動生成 -= Appendix B. 拡張用関数リファレンス +== Appendix B. 拡張用関数リファレンス C言語からRubyの機能を利用するAPIは以下の通りである． -== 型 +=== 型 VALUE :: @@ -1191,7 +1195,7 @@ VALUE :: 体である．VALUE型をこれらにキャストするためにRで始まる構造体 名を全て大文字にした名前のマクロが用意されている． -== 変数・定数 +=== 変数・定数 Qnil :: @@ -1205,7 +1209,7 @@ Qfalse :: 定数: falseオブジェクト -== Cデータのカプセル化 +=== Cデータのカプセル化 Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) :: @@ -1224,7 +1228,7 @@ Data_Get_Struct(data, type, sval) :: dataからtype型のポインタを取り出し変数svalに代入するマクロ． -== 型チェック +=== 型チェック RB_TYPE_P(value, type) TYPE(value) @@ -1235,7 +1239,7 @@ Data_Get_Struct(data, type, sval) :: void Check_Type(VALUE value, int type) SafeStringValue(value) -== 型変換 +=== 型変換 FIX2INT(value), INT2FIX(i) FIX2LONG(value), LONG2FIX(l) @@ -1258,7 +1262,7 @@ Data_Get_Struct(data, type, sval) :: StringValueCStr(value) rb_str_new2(s) -== クラス/モジュール定義 +=== クラス/モジュール定義 VALUE rb_define_class(const char *name, VALUE super) :: @@ -1286,7 +1290,7 @@ void rb_extend_object(VALUE object, VALUE module) :: オブジェクトをモジュール(で定義されているメソッド)で拡張する． -== 大域変数定義 +=== 大域変数定義 void rb_define_variable(const char *name, VALUE *var) :: @@ -1318,7 +1322,7 @@ void rb_global_variable(VALUE *var) :: GCのため，Rubyプログラムからはアクセスされないが, Rubyオブ ジェクトを含む大域変数をマークする． -== 定数 +=== 定数 void rb_define_const(VALUE klass, const char *name, VALUE val) :: @@ -1332,7 +1336,7 @@ void rb_define_global_const(const char *name, VALUE val) :: と同じ意味． -== メソッド定義 +=== メソッド定義 rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) :: @@ -1421,7 +1425,7 @@ VALUE rb_extract_keywords(VALUE *original_hash) :: 先には，元のHashがSymbol以外のキーを含んでいた場合はそれらが コピーされた別の新しいHash，そうでなければ0が保存されます． -== Rubyメソッド呼び出し +=== Rubyメソッド呼び出し VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) :: @@ -1461,7 +1465,7 @@ int rb_respond_to(VALUE obj, ID id) :: objがidで示されるメソッドを持つかどうかを返す． -== インスタンス変数 +=== インスタンス変数 VALUE rb_iv_get(VALUE obj, const char *name) :: @@ -1474,7 +1478,7 @@ VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) :: objのインスタンス変数をvalにセットする． -== 制御構造 +=== 制御構造 VALUE rb_block_call(VALUE obj, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) :: @@ -1536,7 +1540,7 @@ void rb_iter_break_value(VALUE value) :: 現在の最も内側のブロックをvalueで終了する．ブロックは引数で 与えられたvalueを返す．この関数は直接の呼び出し元に戻らない． -== 例外・エラー +=== 例外・エラー void rb_warning(const char *fmt, ...) :: @@ -1568,7 +1572,7 @@ void rb_bug(const char *fmt, ...) :: きはObject#inspect)を使ったVALUEの出力に利用できる．これは "%i"と衝突するため，整数には"%d"を使用すること． -== Rubyの初期化・実行 +=== Rubyの初期化・実行 Rubyをアプリケーションに埋め込む場合には以下のインタフェース を使う．通常の拡張ライブラリには必要ない． @@ -1592,7 +1596,7 @@ void ruby_script(char *name) :: Rubyのスクリプト名($0)を設定する． -== インタプリタのイベントのフック +=== インタプリタのイベントのフック void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) :: @@ -1622,7 +1626,7 @@ int rb_remove_event_hook(rb_event_hook_func_t func) :: 指定されたフック関数を削除します． -== メモリ使用量 +=== メモリ使用量 void rb_gc_adjust_memory_usage(ssize_t diff) :: @@ -1634,7 +1638,7 @@ void rb_gc_adjust_memory_usage(ssize_t diff) :: す．メモリブロックが解放されたり，メモリブロックがより小さいサイズで再 確保されたりした場合などです．この関数はGCを引き起こすかもしれません． -== 互換性のためのマクロ +=== 互換性のためのマクロ APIの互換性をチェックするために以下のマクロがデフォルトで定義されています． @@ -1676,7 +1680,7 @@ RB_EVENT_HOOKS_HAVE_CALLBACK_DATA :: rb_add_event_hook() がフック関数に渡す data を第3引数として 受け取ることを意味する． -= Appendix C. extconf.rbで使える関数たち +== Appendix C. extconf.rbで使える関数たち extconf.rbの中では利用可能なコンパイル条件チェックの関数は以 下の通りである． @@ -1802,7 +1806,7 @@ pkg_config(pkg, option=nil) :: optionが指定された場合は，上記の配列の代わりにそのオプションを 指定して得られた出力をstripしたものを返す． -= Appendix D. 世代別GC +== Appendix D. 世代別GC Ruby 2.1から世代別GCに対応しました．我々はこれをRGenGCと呼んでいます． RGenGCは，過去の拡張ライブラリに（ほぼ）互換性を保つように開発されている -- cgit v1.2.3