* 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

ChangeLog

@@ -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

README.EXT

@@ -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
+There are some more functions to define methods. One takes an ID
-private methods:
+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
+At last, rb_define_module_funcion defines a module functions, 
-methods of the module.  For example, sqrt is the module function
+which are private AND singleton methods of the module.
-defined in Math module.  It can be called in the following way:
+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);
+  VALUE (*getter)(ID id);
-  (*setter)(VALUE val, ID id, void *data, struct global_entry* entry);
+  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
+  class.c         : classes and modules
-  error.c
+  error.c         : exception classes and exception mechanism
-  eval.c
+  gc.c            : memory management
-  gc.c
+  load.c          : library loading
-  object.c
+  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
+  debug.c       : debug symbols for C debuggger
-  regex.c
+  dln.c         : dynamic loading
-  st.c
+  st.c          : general purpose hash table
-  util.c
+  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
+  array.c       : Array
-  bignum.c
+  bignum.c      : Bignum
-  compar.c
+  compar.c      : Comparable
-  dir.c
+  complex.c     : Complex
-  enum.c
+  cont.c        : Fiber, Continuation
-  file.c
+  dir.c         : Dir
-  hash.c
+  enum.c        : Enumerable
-  io.c
+  enumerator.c  : Enumerable::Enumerator
-  marshal.c
+  file.c        : File
-  math.c
+  hash.c        : Hash
-  numeric.c
+  io.c          : IO
-  pack.c
+  marshal.c     : Marshal
-  prec.c
+  math.c        : Math
-  process.c
+  numeric.c     : Numeric, Integer, Fixnum, Float
-  random.c
+  pack.c        : Array#pack, String#unpack
-  range.c
+  prec.c        : Precision
-  re.c
+  proc.c        : Binding, Proc
-  signal.c
+  process.c     : Process
-  sprintf.c
+  random.c      : random number
-  string.c
+  range.c       : Range
-  struct.c
+  rational.c    : Rational
-  time.c
+  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
 

README.EXT.ja

@@ -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引数は必ず
-    配列でなければならない．
-
 2．Rubyの機能を使う
 
 原理的に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メソッドとは関数形式でしか呼び出すことの出来ないメソッ
 ドです．
 
-もうひとつはモジュール関数を定義するものです．モジュール関数
+最後に、 rb_define_module関数はモジュール関数を定義します。
-とはモジュールの特異メソッドであり，同時にprivateメソッドで
+モジュール関数とはモジュールの特異メソッドであり，同時に
-もあるものです．例をあげるとMathモジュールのsqrt()などがあげ
+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);
+  (*getter)(ID id);
-  (*setter)(VALUE val, ID id, void *data, struct global_entry* entry);
+  (*setter)(VALUE val, ID id);
 
 3.3 CのデータをRubyオブジェクトにする
 
@@ -840,53 +899,117 @@ Ruby
 
 Ruby言語のコア
 
-  class.c
+  class.c         : クラスとモジュール
-  error.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
+  eval_error.c
-  object.c
+  eval_jump.c
-  parse.y
+  eval_safe.c
-  variable.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
+  debug.c       : Cデバッガ用のデバッグシンボル
-  regex.c
+  dln.c         : 動的ローディング
-  st.c
+  st.c          : 汎用ハッシュ表
-  util.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
+  array.c       : Array
-  bignum.c
+  bignum.c      : Bignum
-  compar.c
+  compar.c      : Comparable
-  dir.c
+  complex.c     : Complex
-  enum.c
+  cont.c        : Fiber, Continuation
-  file.c
+  dir.c         : Dir
-  hash.c
+  enum.c        : Enumerable
-  io.c
+  enumerator.c  : Enumerable::Enumerator
-  marshal.c
+  file.c        : File
-  math.c
+  hash.c        : Hash
-  numeric.c
+  io.c          : IO
-  pack.c
+  marshal.c     : Marshal
-  prec.c
+  math.c        : Math
-  process.c
+  numeric.c     : Numeric, Integer, Fixnum, Float
-  random.c
+  pack.c        : Array#pack, String#unpack
-  range.c
+  prec.c        : Precision
-  re.c
+  proc.c        : Binding, Proc
-  signal.c
+  process.c     : Process
-  sprintf.c
+  random.c      : random number
-  string.c
+  range.c       : Range
-  struct.c
+  rational.c    : Rational
-  time.c
+  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. 拡張用関数リファレンス