From 678adc8714bd325967464eaf4b37c8a863f04919 Mon Sep 17 00:00:00 2001 From: knu Date: Wed, 18 Feb 2009 18:34:38 +0000 Subject: * 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 | 5 ++++ README.EXT | 76 +++++++++++++++++++++++++++++------------------------------ README.EXT.ja | 71 +++++++++++++++++++++++++++---------------------------- 3 files changed, 78 insertions(+), 74 deletions(-) diff --git a/ChangeLog b/ChangeLog index 306aea511f..d0c77137cf 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Thu Feb 19 03:28:59 2009 Akinori MUSHA + + * README.EXT, README.EXT.ja: Improve the document about + rb_scan_args() even more. + Thu Feb 19 03:12:51 2009 Yusuke Endoh * test/ruby/test_file_exhaustive.rb: skip some tests if euid == 0. diff --git a/README.EXT b/README.EXT index f1504021ba..1ea29bdc47 100644 --- a/README.EXT +++ b/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 -references. The format can be described in ABNF as follows: +capture method arguments and assign them to the following VALUE +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 -by Ruby's array, like this: +The following is an example of a method that takes arguments by Ruby's +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 -the arguments, such as "12" for 1 non-optional argument, 2 optional -arguments. If `*' appears at the end of fmt, it means the rest of -the arguments are assigned to the corresponding variable, packed in -an array. +Retrieve argument from argc and argv to given VALUE references +according to the format string. The format can be described in ABNF +as follows: + +-- +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 diff --git a/README.EXT.ja b/README.EXT.ja index de2fe60f2b..e8dc8bc4a9 100644 --- a/README.EXT.ja +++ b/README.EXT.ja @@ -766,37 +766,12 @@ fdbm_s_open(int argc, VALUE *argv, VALUE klass) えられます． この配列で与えられた引数を解析するための関数がopen()でも使わ -れているrb_scan_args()です．第3引数に指定したフォーマットに -従い，第4変数以降に指定した変数(の参照)に値を代入してくれます． -このフォーマットは，ABNFで記述すると以下の通りです． +れているrb_scan_args()です．第3引数に指定したフォーマットに従 +い，第4変数以降に指定したVALUEへの参照に値を代入してくれま +す． --- -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は必須引数の数, - 付加引数の数, 残りの引数があるかを指定する文字列で, "数字 - 数字*"という形式である． 2 番目の数字と"*"はそれぞれ省略可 - 能である．必須引数が一つもない場合は0を指定する．第3引数以 - 降は変数へのポインタで, 該当する要素がその変数に格納される． - 付加引数に対応する引数が与えられていない場合は変数にQnilが - 代入される． + argc, argv形式で与えられた指定されたフォーマットに従って引 + 数を分解し，続く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 := "&" ; イテレータブロックを取得するための + ; 指定 +-- + + フォーマットが"12"の場合，引数は最低1つで，3つ(1+2)まで許さ + れるという意味になります．従って，フォーマット文字列に続い + て3つのVALUEへの参照を置く必要があります．それらには取得した + 変数がセットされます．変数への参照の代わりにNULLを指定する + こともでき，その場合は取得した引数の値は捨てられます．なお、 + 省略可能引数が省略された時の変数の値はnil(C言語のレベルでは + Qnil)になります． + + 返り値は与えられた引数の数です．イテレータブロックは数えま + せん． ** Rubyメソッド呼び出し -- cgit v1.2.3