* README.EXT, README.EXT.ja: Improve the document about

rb_scan_args() even more.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@22424 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Thu Feb 19 03:28:59 2009  Akinori MUSHA  <knu@iDaemons.org>
+
+	* README.EXT, README.EXT.ja: Improve the document about
+	  rb_scan_args() even more.
+
 Thu Feb 19 03:12:51 2009  Yusuke Endoh  <mame@tsg.ne.jp>
 
 	* test/ruby/test_file_exhaustive.rb: skip some tests if euid == 0. 

README.EXT

@@ -679,41 +679,12 @@ argument is the receiver of the method.
 
 You can use the function rb_scan_args() to check and retrieve the
 arguments.  The third argument is a string that specifies how to
-capture method arguments and assign them to the following variable
+capture method arguments and assign them to the following VALUE
-references.  The format can be described in ABNF as follows:
+references.
-
---
-scan-arg-spec  := param-arg-spec [block-arg-spec]
-
-param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec
-pre-arg-spec   := num-of-leading-mandatory-args [num-of-optional-args]
-post-arg-spec  := sym-for-variable-length-args [num-of-trailing-mandatory-args]
-block-arg-spec := sym-for-block-arg
-
-num-of-leading-mandatory-args  := DIGIT ; The number of leading
-                                        ; mandatory arguments
-num-of-optional-args           := DIGIT ; The number of optional
-                                        ; arguments
-sym-for-variable-length-args   := "*"   ; Indicates that variable
-                                        ; length arguments are
-                                        ; captured as a ruby array
-num-of-trailing-mandatory-args := DIGIT ; The number of trailing
-                                        ; mandatory arguments
-sym-for-block-arg              := "&"   ; Indicates that an iterator
-                                        ; block should be captured if
-                                        ; given
---
-
-For example, "11" means that the method requires at least one
-argument, and at most receives two (1+1) arguments.  So, the format
-string must be followed by two variable references, which are to be
-set to captured arguments.  For omitted arguments, variables are set
-to Qnil.  NULL can be put in place of a variable reference, which
-means the corresponding captured argument(s) does not need to be set.
 
 
-Methods with an arbitrary number of arguments can receive arguments
+The following is an example of a method that takes arguments by Ruby's
-by Ruby's array, like this:
+array:
 
 --
 static VALUE
@@ -1103,11 +1074,40 @@ Defines a singleton method.  Arguments are same as rb_define_method().
 
  rb_scan_args(int argc, VALUE *argv, const char *fmt, ...)
 
-Retrieve argument from argc, argv.  The fmt is the format string for
+Retrieve argument from argc and argv to given VALUE references
-the arguments, such as "12" for 1 non-optional argument, 2 optional
+according to the format string.  The format can be described in ABNF
-arguments.  If `*' appears at the end of fmt, it means the rest of
+as follows:
-the arguments are assigned to the corresponding variable, packed in
+
-an array.
+--
+scan-arg-spec  := param-arg-spec [block-arg-spec]
+
+param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec
+pre-arg-spec   := num-of-leading-mandatory-args [num-of-optional-args]
+post-arg-spec  := sym-for-variable-length-args [num-of-trailing-mandatory-args]
+block-arg-spec := sym-for-block-arg
+
+num-of-leading-mandatory-args  := DIGIT ; The number of leading
+                                        ; mandatory arguments
+num-of-optional-args           := DIGIT ; The number of optional
+                                        ; arguments
+sym-for-variable-length-args   := "*"   ; Indicates that variable
+                                        ; length arguments are
+                                        ; captured as a ruby array
+num-of-trailing-mandatory-args := DIGIT ; The number of trailing
+                                        ; mandatory arguments
+sym-for-block-arg              := "&"   ; Indicates that an iterator
+                                        ; block should be captured if
+                                        ; given
+--
+
+For example, "12" means that the method requires at least one
+argument, and at most receives three (1+2) arguments.  So, the format
+string must be followed by three variable references, which are to be
+assigned to captured arguments.  For omitted arguments, variables are
+set to Qnil.  NULL can be put in place of a variable reference, which
+means the corresponding captured argument(s) should be just dropped.
+
+The number of given arguments is returned.
 
 ** Invoking Ruby method
 

README.EXT.ja

@@ -766,37 +766,12 @@ fdbm_s_open(int argc, VALUE *argv, VALUE klass)
 えられます．
 
 この配列で与えられた引数を解析するための関数がopen()でも使わ
-れているrb_scan_args()です．第3引数に指定したフォーマットに
+れているrb_scan_args()です．第3引数に指定したフォーマットに従
-従い，第4変数以降に指定した変数(の参照)に値を代入してくれます．
+い，第4変数以降に指定したVALUEへの参照に値を代入してくれま
-このフォーマットは，ABNFで記述すると以下の通りです．
+す．
-
---
-scan-arg-spec  := param-arg-spec [block-arg-spec]
-
-param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec
-pre-arg-spec   := num-of-leading-mandatory-args [num-of-optional-args]
-post-arg-spec  := sym-for-variable-length-args [num-of-trailing-mandatory-args]
-block-arg-spec := sym-for-block-arg
-
-num-of-leading-mandatory-args  := DIGIT ; 先頭に置かれる省略不可能な引数の数
-num-of-optional-args           := DIGIT ; 続いて置かれる省略可能な引数の数
-sym-for-variable-length-args   := "*"   ; 続いて置かれる可変長引数を
-                                        ; Rubyの配列で取得するための指定
-num-of-trailing-mandatory-args := DIGIT ; 終端に置かれる省略不可能な引数の数
-sym-for-block-arg              := "&"   ; イテレータブロックを取得するための
-                                        ; 指定
---
-
-dbm.cの例では，フォーマットは"11"ですから，引数は最低1つで，2つ
-(1+1)まで許されるという意味になります．従って，フォーマット文
-字列に続いて2つの変数への参照を置く必要があります．それらには
-取得した変数がセットされます．変数への参照の代わりにNULLを指
-定することもでき，その場合は取得した引数の値は捨てられます．
-なお、省略可能引数が省略された時の変数の値はnil(C言語のレベル
-ではQnil)になります．
 
 
-最後に，引数をRubyの配列として受け取るものには
+引数をRubyの配列として受け取るメソッドの例には
 Thread#initializeがあります．実装はこうです．
 
 --
@@ -1198,13 +1173,37 @@ rb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int a
 
 rb_scan_args(int argc, VALUE *argv, const char *fmt, ...)
 
-  argc, argv形式で与えられた引数を分解する．fmtは必須引数の数, 
+  argc, argv形式で与えられた指定されたフォーマットに従って引
-  付加引数の数, 残りの引数があるかを指定する文字列で, "数字
+  数を分解し，続くVALUEへの参照にセットします．このフォーマッ
-  数字*"という形式である． 2 番目の数字と"*"はそれぞれ省略可
+  トは，ABNFで記述すると以下の通りです．
-  能である．必須引数が一つもない場合は0を指定する．第3引数以
+
-  降は変数へのポインタで, 該当する要素がその変数に格納される．
+--
-  付加引数に対応する引数が与えられていない場合は変数にQnilが
+scan-arg-spec  := param-arg-spec [block-arg-spec]
-  代入される．
+
+param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec
+pre-arg-spec   := num-of-leading-mandatory-args [num-of-optional-args]
+post-arg-spec  := sym-for-variable-length-args [num-of-trailing-mandatory-args]
+block-arg-spec := sym-for-block-arg
+
+num-of-leading-mandatory-args  := DIGIT ; 先頭に置かれる省略不可能な引数の数
+num-of-optional-args           := DIGIT ; 続いて置かれる省略可能な引数の数
+sym-for-variable-length-args   := "*"   ; 続いて置かれる可変長引数を
+                                        ; Rubyの配列で取得するための指定
+num-of-trailing-mandatory-args := DIGIT ; 終端に置かれる省略不可能な引数の数
+sym-for-block-arg              := "&"   ; イテレータブロックを取得するための
+                                        ; 指定
+--
+
+  フォーマットが"12"の場合，引数は最低1つで，3つ(1+2)まで許さ
+  れるという意味になります．従って，フォーマット文字列に続い
+  て3つのVALUEへの参照を置く必要があります．それらには取得した
+  変数がセットされます．変数への参照の代わりにNULLを指定する
+  こともでき，その場合は取得した引数の値は捨てられます．なお、
+  省略可能引数が省略された時の変数の値はnil(C言語のレベルでは
+  Qnil)になります．
+
+  返り値は与えられた引数の数です．イテレータブロックは数えま
+  せん．
 
 ** Rubyメソッド呼び出し