* README.EXT (Data-types): fixed for current status.

(Manipulating Ruby data): mentioned some more functions.
  (Class/module definition): ditto.
  (Global variables shared between C and Ruby):
    fixed prototypes for the getter/setter's of global variables.
  (Appendix A): mentioned some more files.

* README.EXT.ja: ditto.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@19012 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
yugui 2008-09-01 05:08:44 +00:00
Родитель a107e1e998
Коммит a4ee7c2c3b
3 изменённых файлов: 356 добавлений и 97 удалений

Просмотреть файл

@ -1,3 +1,14 @@
Mon Sep 1 14:00:04 2008 Yuki Sonoda (Yugui) <yugui@yugui.jp>
* README.EXT (Data-types): fixed for current status.
(Manipulating Ruby data): mentioned some more functions.
(Class/module definition): ditto.
(Global variables shared between C and Ruby):
fixed prototypes for the getter/setter's of global variables.
(Appendix A): mentioned some more files.
* README.EXT.ja: ditto.
Mon Sep 1 11:31:49 2008 Nobuyoshi Nakada <nobu@ruby-lang.org>
* lib/fileutils.rb (copy_stream, fu_copy_stream0, copy_file): use

Просмотреть файл

@ -31,10 +31,12 @@ The Ruby interpreter has the following data types:
T_STRING string
T_REGEXP regular expression
T_ARRAY array
T_FIXNUM Fixnum(31bit or 63bit integer)
T_HASH associative array
T_STRUCT (Ruby) structure
T_BIGNUM multi precision integer
T_FIXNUM Fixnum(31bit or 63bit integer)
T_COMPLEX complex number
T_RATIONAL rational number
T_FILE IO
T_TRUE true
T_FALSE false
@ -46,9 +48,8 @@ In addition, there are several other types used internally:
T_ICLASS
T_MATCH
T_UNDEF
T_VARMAP
T_SCOPE
T_NODE
T_ZOMBIE
Most of the types are represented by C structures.
@ -176,6 +177,7 @@ listed below:
Creates a new Ruby string.
rb_str_new2(const char *ptr)
rb_str_new_cstr(const char *ptr)
Creates a new Ruby string from a C string. This is equivalent to
rb_str_new(ptr, strlen(ptr)).
@ -186,6 +188,7 @@ listed below:
sources should be tainted.
rb_tainted_str_new2(const char *ptr)
rb_tainted_str_new_cstr(const char *ptr)
Creates a new tainted Ruby string from a C string.
@ -211,6 +214,15 @@ listed below:
equivalent to rb_str_cat2(str, rb_sprintf(format, ...)) and
rb_str_cat2(str, rb_vsprintf(format, ap)), respectively.
rb_enc_str_new(const char *ptr, long len, rb_encoding *enc)
Creates a new Ruby string with the specified encoding.
rb_usascii_str_new(const char *ptr, long len)
rb_usascii_str_new_cstr(const char *ptr)
Creates a new Ruby string with encoding US-ASCII.
Array functions
rb_ary_new()
@ -230,13 +242,31 @@ listed below:
Creates an n-element array from a C array.
rb_ary_to_ary(VALUE obj)
Converts the object into an array.
Equivalent to Object#to_ary.
There are many functions to operate an array.
They may dump core if other types are given.
rb_ary_aref(argc, VALUE *argv, VALUE ary)
Equivaelent to Array#[].
rb_ary_entry(VALUE ary, long offset)
ary[offset]
rb_ary_subseq(VALUE ary, long beg, long len)
ary[beg, len]
rb_ary_push(VALUE ary, VALUE val)
rb_ary_pop(VALUE ary)
rb_ary_shift(VALUE ary)
rb_ary_unshift(VALUE ary, VALUE val)
Array operations. The first argument to each functions must be an
array. They may dump core if other types are given.
2. Extending Ruby with C
@ -295,15 +325,23 @@ will be called like:
where obj is the receiver, and args is the Ruby array containing
actual arguments.
There are two more functions to define methods. One is to define
private methods:
There are some more functions to define methods. One takes an ID
as the name of method to be defined. See 2.2.2 for IDs.
void rb_define_method_id(VALUE klass, ID name,
VALUE (*func)(ANYARGS), int argc)
There are two functions to define private/protected methods:
void rb_define_private_method(VALUE klass, const char *name,
VALUE (*func)(), int argc)
void rb_define_protected_method(VALUE klass, const char *name,
VALUE (*func)(), int argc)
The other is to define module functions, which are private AND singleton
methods of the module. For example, sqrt is the module function
defined in Math module. It can be called in the following way:
At last, rb_define_module_funcion defines a module functions,
which are private AND singleton methods of the module.
For example, sqrt is the module function defined in Math module.
It can be called in the following way:
Math.sqrt(4)
@ -326,6 +364,10 @@ To define an alias for the method,
void rb_define_alias(VALUE module, const char* new, const char* old);
To define an reader/writer to an attribute,
void rb_define_attr(VALUE klass, const char *name, int read, int write)
To define and undefine the `allocate' class method,
void rb_define_alloc_func(VALUE klass, VALUE (*func)(VALUE klass));
@ -359,6 +401,15 @@ evaluate the string as Ruby program. This function will do the job:
Evaluation is done under the current context, thus current local variables
of the innermost method (which is defined by Ruby) can be accessed.
Note that the evaluation can raise an exception. There is a safer
function:
VALUE rb_eval_string_protect(const char *str, int *state)
It returns nil when an error occur. And *state is zero if str was
successfully evaluated, or nonzero otherwise.
2.2.2 ID or Symbol
You can invoke methods directly, without parsing the string. First I
@ -368,6 +419,8 @@ corresponding to ID is Symbol. It can be accessed from Ruby in the
form:
:Identifier
or
:"any kind of string"
You can get the ID value from a string within C code by using
@ -448,23 +501,30 @@ function below.
You can defined hooked variables. The accessor functions (getter and
setter) are called on access to the hooked variables.
void rb_define_hooked_variable(constchar *name, VALUE *var,
void rb_define_hooked_variable(const char *name, VALUE *var,
VALUE (*getter)(), void (*setter)())
If you need to supply either setter or getter, just supply 0 for the
hook you don't need. If both hooks are 0, rb_define_hooked_variable()
works just like rb_define_variable().
The prototypes of the getter and setter functions are as follows:
VALUE (*getter)(ID id, VALUE *var);
void (*setter)(VALUE val, ID id, VALUE *var);
Also you can define a Ruby global variable without a corresponding C
variable. The value of the variable will be set/get only by hooks.
void rb_define_virtual_variable(const char *name,
VALUE (*getter)(), void (*setter)())
This function defines a Ruby global variable without a corresponding C
variable. The value of the variable will be set/get only by hooks.
The prototypes of the getter and setter functions are as follows:
(*getter)(ID id, void *data, struct global_entry* entry);
(*setter)(VALUE val, ID id, void *data, struct global_entry* entry);
VALUE (*getter)(ID id);
void (*setter)(VALUE val, ID id);
3.3 Encapsulate C data into a Ruby object
@ -728,53 +788,118 @@ Appendix A. Ruby source files overview
ruby language core
class.c
error.c
eval.c
gc.c
object.c
class.c : classes and modules
error.c : exception classes and exception mechanism
gc.c : memory management
load.c : library loading
object.c : objects
variable.c : variables and constants
ruby syntax parser
parse.y
variable.c
-> parse.c : automatically generated
keywords : reserved keywords
-> lex.c : automatically generated
ruby evaluator (a.k.a. YARV)
blockinlining.c
compile.c
eval.c
eval_error.c
eval_jump.c
eval_safe.c
insns.def : definition of VM instructions
iseq.c : implementation of VM::ISeq
thread.c : thread management and context swiching
thread_win32.c : thread implementation
thread_pthread.c : ditto
vm.c
vm_dump.c
vm_eval.c
vm_evalbody.c
vm_insnhelper.c
vm_method.c
opt_insns_unif.def : instruction unification
opt_operand.def : definitions for optimization
-> insn*.inc : automatically generated
-> opt*.inc : automatically generated
-> vm.inc : automatically generated
regular expression engine (oniguruma)
regex.c
regcomp.c
regenc.c
regerror.c
regexec.c
regparse.c
regsyntax.c
utility functions
dln.c
regex.c
st.c
util.c
debug.c : debug symbols for C debuggger
dln.c : dynamic loading
st.c : general purpose hash table
strftime.c : formatting times
util.c : misc utilities
ruby interpreter implementation
dmyext.c
dmydln.c
dmyencoding.c
id.c
inits.c
main.c
ruby.c
version.c
gem_prelude.rb
prelude.rb
class library
array.c
bignum.c
compar.c
dir.c
enum.c
file.c
hash.c
io.c
marshal.c
math.c
numeric.c
pack.c
prec.c
process.c
random.c
range.c
re.c
signal.c
sprintf.c
string.c
struct.c
time.c
array.c : Array
bignum.c : Bignum
compar.c : Comparable
complex.c : Complex
cont.c : Fiber, Continuation
dir.c : Dir
enum.c : Enumerable
enumerator.c : Enumerable::Enumerator
file.c : File
hash.c : Hash
io.c : IO
marshal.c : Marshal
math.c : Math
numeric.c : Numeric, Integer, Fixnum, Float
pack.c : Array#pack, String#unpack
prec.c : Precision
proc.c : Binding, Proc
process.c : Process
random.c : random number
range.c : Range
rational.c : Rational
re.c : Regexp, MatchData
signal.c : Signal
sprintf.c :
string.c : String
struct.c : Struct
time.c : Time
multilingualization
encoding.c : Encoding
transcode.c : Encoding::Converter
enc/*.c : encoding classes
enc/trans/* : codepoint mapping tables
goruby interpreter implementation
goruby.c
golf_prelude.rb
Appendix B. Ruby extension API reference

Просмотреть файл

@ -35,10 +35,12 @@ Ruby
T_STRING 文字列
T_REGEXP 正規表現
T_ARRAY 配列
T_FIXNUM Fixnum(31bitまたは63bit長整数)
T_HASH 連想配列
T_STRUCT (Rubyの)構造体
T_BIGNUM 多倍長整数
T_FIXNUM Fixnum(31bitまたは63bit長整数)
T_COMPLEX 複素数
T_RATIONAL 有理数
T_FILE 入出力
T_TRUE 真
T_FALSE 偽
@ -50,9 +52,8 @@ Ruby
T_ICLASS
T_MATCH
T_UNDEF
T_VARMAP
T_SCOPE
T_NODE
T_ZOMBIE
ほとんどのタイプはCの構造体で実装されています
@ -203,11 +204,13 @@ Ruby
新しいRubyの文字列を生成する
rb_str_new2(const char *ptr)
rb_str_new_cstr(const char *ptr)
Cの文字列からRubyの文字列を生成するこの関数の機能は
rb_str_new(ptr, strlen(ptr))と同等である.
rb_tainted_str_new(const char *ptr, long len)
rb_tainted_str_new_cstr(const char *ptr)
汚染マークが付加された新しいRubyの文字列を生成する外部
からのデータに基づく文字列には汚染マークが付加されるべき
@ -240,6 +243,16 @@ Ruby
rb_str_cat2(str, rb_sprintf(format, ...)) や
rb_str_cat2(str, rb_vsprintf(format, ap)) と同等である.
rb_enc_str_new(const char *ptr, long len, rb_encoding *enc)
指定されたエンコーディングでRubyの文字列を生成する.
rb_usascii_str_new(const char *ptr, long len)
rb_usascii_str_new_cstr(const char *ptr)
エンコーディングがUS-ASCIIのRubyの文字列を生成する.
配列に対する関数
rb_ary_new()
@ -259,14 +272,32 @@ Ruby
配列で与えたn要素の配列を生成する
rb_ary_to_ary(VALUE obj)
オブジェクトを配列に変換する.
Object#to_aryと同等である.
他にも配列を操作する関数が多数ある. これらは
引数aryに配列を渡さなければならない. さもないと
コアを吐く.
rb_ary_aref(argc, VALUE *argv, VALUE ary)
Array#[]と同等.
rb_ary_entry(VALUE ary, long offset)
ary[offset]
rb_ary_subseq(VALUE ary, long beg, long len)
ary[beg, len]
rb_ary_push(VALUE ary, VALUE val)
rb_ary_pop(VALUE ary)
rb_ary_shift(VALUE ary)
rb_ary_unshift(VALUE ary, VALUE val)
Arrayの同名のメソッドと同じ働きをする関数第1引数は必ず
配列でなければならない.
2Rubyの機能を使う
原理的にRubyで書けることはCでも書けますRubyそのものがCで記
@ -329,19 +360,26 @@ argc
argcが-1の時は引数を配列に入れて渡されますargcが-2の時は引
数はRubyの配列として渡されます
メソッドを定義する関数はもう二つありますひとつはprivateメ
ソッドを定義する関数で引数はrb_define_method()と同じです.
メソッドを定義する関数はまだいくつかあります. ひとつはメソッド
名としてIDを取ります. IDについては2.2.2を参照.
void rb_define_method_id(VALUE klass, ID name,
VALUE (*func)(ANYARGS), int argc)
private/protectedなメソッドを定義するふたつの関数があります.
void rb_define_private_method(VALUE klass, const char *name,
VALUE (*func)(), int argc)
void rb_define_protected_method(VALUE klass, const char *name,
VALUE (*func)(), int argc)
privateメソッドとは関数形式でしか呼び出すことの出来ないメソッ
ドです.
もうひとつはモジュール関数を定義するものです.モジュール関数
とはモジュールの特異メソッドであり,同時にprivateメソッドで
もあるものです例をあげるとMathモジュールのsqrt()などがあげ
られます.このメソッドは
最後に、 rb_define_module関数はモジュール関数を定義します。
モジュール関数とはモジュールの特異メソッドであり,同時に
privateメソッドでもあるものです例をあげるとMathモジュール
のsqrt()などがあげられます.このメソッドは
Math.sqrt(4)
@ -366,6 +404,10 @@ private
void rb_define_alias(VALUE module, const char* new, const char* old);
属性の取得・設定メソッドを定義するには
void rb_define_attr(VALUE klass, const char *name, int read, int write)
クラスメソッドallocateを定義したり削除したりするための関数は
以下の通りです.
@ -409,6 +451,15 @@ C
この評価は現在の環境で行われます.つまり,現在のローカル変数
などを受け継ぎます.
評価は例外を発生するかもしれないことに注意しましょう. より安全
な関数もあります.
VALUE rb_eval_string_protect(const char *str, int *state)
この関数はエラーが発生するとnilを返します。そして、成功時には
*stateはゼロに、さもなくば非ゼロになります。
2.2.2 IDまたはシンボル
Cから文字列を経由せずにRubyのメソッドを呼び出すこともできま
@ -418,6 +469,8 @@ C
IDとは変数名メソッド名を表す整数ですRubyの中では
:識別子
または
:"任意の文字列"
でアクセスできますCからこの整数を得るためには関数
@ -509,11 +562,17 @@ C
変数が参照された時には関数getterが変数に値がセットされ
た時には関数setterが呼ばれるhookを指定しない場合はgetterや
setterに0を指定します
# getterもsetterも0ならばrb_define_variable()と同じになる.
それからCの関数によって実現されるRubyの大域変数を定義する
関数があります.
getterとsetterの仕様は次の通りです。
VALUE (*getter)(ID id, VALUE *var);
void (*setter)(VALUE val, ID id, VALUE *var);
それから対応するCの変数を持たないRubyの大域変数を定義する
こともできます. その変数の値はフック関数のみによって取得・設定
されます.
void rb_define_virtual_variable(const char *name,
VALUE (*getter)(), void (*setter)())
@ -523,8 +582,8 @@ getter
getterとsetterの仕様は以下の通りです
(*getter)(ID id, void *data, struct global_entry* entry);
(*setter)(VALUE val, ID id, void *data, struct global_entry* entry);
(*getter)(ID id);
(*setter)(VALUE val, ID id);
3.3 CのデータをRubyオブジェクトにする
@ -840,53 +899,117 @@ Ruby
Ruby言語のコア
class.c
error.c
class.c : クラスとモジュール
error.c : 例外クラスと例外機構
gc.c : 記憶領域管理
load.c : ライブラリのロード
object.c : オブジェクト
variable.c : 変数と定数
Rubyの構文解析器
parse.y : 字句解析器と構文定義
-> parse.c : 自動生成
keywords : 予約語
-> lex.c : 自動生成
Rubyの評価器(通称YARV)
blockinlining.c
compile.c
eval.c
gc.c
object.c
parse.y
variable.c
eval_error.c
eval_jump.c
eval_safe.c
insns.def : 仮想機械語の定義
iseq.c : VM::ISeqの実装
thread.c : スレッド管理とコンテキスト切り替え
thread_win32.c : スレッド実装
thread_pthread.c : 同上
vm.c
vm_dump.c
vm_eval.c
vm_evalbody.c
vm_insnhelper.c
vm_method.c
opt_insns_unif.def : 命令融合
opt_operand.def : 最適化のための定義
-> insn*.inc : 自動生成
-> opt*.inc : 自動生成
-> vm.inc : 自動生成
正規表現エンジン (鬼車)
regex.c
regcomp.c
regenc.c
regerror.c
regexec.c
regparse.c
regsyntax.c
ユーティリティ関数
dln.c
regex.c
st.c
util.c
debug.c : Cデバッガ用のデバッグシンボル
dln.c : 動的ローディング
st.c : 汎用ハッシュ表
strftime.c : 時刻整形
util.c : その他のユーティリティ
Rubyコマンドの実装
dmyext.c
dmydln.c
dmyencoding.c
id.c
inits.c
main.c
ruby.c
version.c
gem_prelude.rb
prelude.rb
クラスライブラリ
array.c
bignum.c
compar.c
dir.c
enum.c
file.c
hash.c
io.c
marshal.c
math.c
numeric.c
pack.c
prec.c
process.c
random.c
range.c
re.c
signal.c
sprintf.c
string.c
struct.c
time.c
array.c : Array
bignum.c : Bignum
compar.c : Comparable
complex.c : Complex
cont.c : Fiber, Continuation
dir.c : Dir
enum.c : Enumerable
enumerator.c : Enumerable::Enumerator
file.c : File
hash.c : Hash
io.c : IO
marshal.c : Marshal
math.c : Math
numeric.c : Numeric, Integer, Fixnum, Float
pack.c : Array#pack, String#unpack
prec.c : Precision
proc.c : Binding, Proc
process.c : Process
random.c : random number
range.c : Range
rational.c : Rational
re.c : Regexp, MatchData
signal.c : Signal
sprintf.c :
string.c : String
struct.c : Struct
time.c : Time
多言語化
encoding.c : Encoding
transcode.c : Encoding::Converter
enc/*.c : エンコーディングクラス群
enc/trans/* : コードポイント対応表
gorubyコマンドの実装
goruby.c
golf_prelude.rb
Appendix B. 拡張用関数リファレンス