Document *_kw functions added to include/ruby/ruby.h [ci skip]

Also documents the non-*_kw functions if they were not already
documented.

1 files changed, 107 insertions, 6 deletions

diff --git a/doc/extension.rdoc b/doc/extension.rdoc
index 1355cdae64..8162c5ea1f 100644
--- a/doc/extension.rdoc
+++ b/doc/extension.rdoc
@@ -458,6 +458,19 @@ you may rely on:
 
   VALUE rb_call_super(int argc, const VALUE *argv)
 
+To specify whether keyword arguments are passed when calling super:
+
+  VALUE rb_call_super(int argc, const VALUE *argv, int kw_splat)
+
++kw_splat+ can have these possible values (used by all methods that accept
++kw_splat+ argument):
+
+RB_NO_KEYWORDS :: Do not pass keywords
+RB_PASS_KEYWORDS :: Pass keywords, final argument should be a hash of keywords
+RB_PASS_EMPTY_KEYWORDS :: Pass empty keywords (not included in arguments)
+RB_PASS_CALLED_KEYWORDS :: Pass keywords if current method was called with
+                           keywords, useful for argument delegation
+
 To achieve the receiver of the current scope (if no other way is
 available), you can use:
 
@@ -1398,7 +1411,7 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
   according to the format string.  The format can be described in ABNF
   as follows:
 
-    scan-arg-spec  := param-arg-spec [option-hash-arg-spec] [block-arg-spec]
+    scan-arg-spec  := param-arg-spec [keyword-arg-spec] [block-arg-spec]
 
     param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec /
                       pre-opt-post-arg-spec
@@ -1407,7 +1420,7 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
                       [num-of-trailing-mandatory-args]
     pre-opt-post-arg-spec := num-of-leading-mandatory-args num-of-optional-args
                              num-of-trailing-mandatory-args
-    option-hash-arg-spec := sym-for-option-hash-arg
+    keyword-arg-spec := sym-for-keyword-arg
     block-arg-spec := sym-for-block-arg
 
     num-of-leading-mandatory-args  := DIGIT ; The number of leading
@@ -1419,9 +1432,14 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
                                             ; captured as a ruby array
     num-of-trailing-mandatory-args := DIGIT ; The number of trailing
                                             ; mandatory arguments
-    sym-for-option-hash-arg        := ":"   ; Indicates that an option
-                                            ; hash is captured if the last
-                                            ; argument is a hash or can be
+    sym-for-keyword-arg            := ":"   ; Indicates that keyword
+                                            ; argument captured as a hash.
+                                            ; If keyword arguments are not
+                                            ; provided, returns nil.
+                                            ;
+                                            ; Currently, will also consider
+                                            ; final argument as keywords if
+                                            ; it is a hash or can be
                                             ; converted to a hash with
                                             ; #to_hash.  When the last
                                             ; argument is nil, it is
@@ -1431,6 +1449,15 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
                                             ; is not specified and
                                             ; arguments are given more
                                             ; than sufficient.
+                                            ;
+                                            ; However, handling final
+                                            ; argument as keywords if
+                                            ; method was not called with
+                                            ; keywords (whether final
+                                            ; argument is hash or nil) is
+                                            ; deprecated. In that case, a
+                                            ; warning will be emitted, and
+                                            ; in Ruby 3.0 it will be an error.
     sym-for-block-arg              := "&"   ; Indicates that an iterator
                                             ; block should be captured if
                                             ; given
@@ -1445,6 +1472,20 @@ rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ::
   The number of given arguments, excluding an option hash or iterator
   block, is returned.
 
+rb_scan_args_kw(int kw_splat, int argc, VALUE *argv, const char *fmt, ...) ::
+
+  The same as +rb_scan_args+, except the +kw_splat+ argument specifies whether
+  keyword arguments are provided (instead of being determined by the call
+  from Ruby to the C function). +kw_splat+ should be one of the following
+  values:
+
+  RB_SCAN_ARGS_PASS_CALLED_KEYWORDS :: Same behavior as +rb_scan_args+.
+  RB_SCAN_ARGS_KEYWORDS :: The final argument should be a hash treated as
+                           keywords.
+  RB_SCAN_ARGS_EMPTY_KEYWORDS :: Don't treat a final hash as keywords.
+  RB_SCAN_ARGS_LAST_HASH_KEYWORDS :: Treat a final argument as keywords if it
+                                     is a hash, and not as keywords otherwise.
+
 int rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values) ::
 
   Retrieves argument VALUEs bound to keywords, which directed by +table+
@@ -1483,11 +1524,41 @@ VALUE rb_funcallv(VALUE recv, ID mid, int argc, VALUE *argv) ::
   Invokes a method, passing arguments as an array of values.
   Able to call even private/protected methods.
 
+VALUE rb_funcallv_kw(VALUE recv, ID mid, int argc, VALUE *argv, int kw_splat) ::
+
+  Same as rb_funcallv, using +kw_splat+ to determine whether keyword
+  arguments are passed.
+
 VALUE rb_funcallv_public(VALUE recv, ID mid, int argc, VALUE *argv) ::
 
   Invokes a method, passing arguments as an array of values.
   Able to call only public methods.
 
+VALUE rb_funcallv_public_kw(VALUE recv, ID mid, int argc, VALUE *argv, int kw_splat) ::
+
+  Same as rb_funcallv_public, using +kw_splat+ to determine whether keyword
+  arguments are passed.
+
+VALUE rb_funcall_passing_block(VALUE recv, ID mid, int argc, const VALUE* argv) ::
+
+  Same as rb_funcallv_public, except is passes the currently active block as
+  the block when calling the method.
+
+VALUE rb_funcall_passing_block_kw(VALUE recv, ID mid, int argc, const VALUE* argv, int kw_splat) ::
+
+  Same as rb_funcall_passing_block, using +kw_splat+ to determine whether
+  keyword arguments are passed.
+
+VALUE rb_funcall_with_block(VALUE recv, ID mid, int argc, const VALUE *argv, VALUE passed_procval) ::
+
+  Same as rb_funcallv_public, except +passed_procval+ specifies the block to
+  pass to the method.
+
+VALUE rb_funcall_with_block_kw(VALUE recv, ID mid, int argc, const VALUE *argv, VALUE passed_procval, int kw_splat) ::
+
+  Same as rb_funcall_with_block, using +kw_splat+ to determine whether
+  keyword arguments are passed.
+
 VALUE rb_eval_string(const char *str) ::
 
   Compiles and executes the string as a Ruby program.
@@ -1532,6 +1603,11 @@ VALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (A
   whereas yielded values can be gotten via argc/argv of the third/fourth
   arguments.
 
+VALUE rb_block_call_kw(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2, int kw_splat) ::
+
+  Same as rb_funcall_with_block, using +kw_splat+ to determine whether
+  keyword arguments are passed.
+
 \[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ::
 
   Calls the function func1, supplying func2 as the block.  func1 will be
@@ -1543,7 +1619,32 @@ VALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (A
 
 VALUE rb_yield(VALUE val) ::
 
-  Evaluates the block with value val.
+  Yields val as a single argument to the block.
+
+VALUE rb_yield_values(int n, ...) ::
+
+  Yields +n+ number of arguments to the block, using one C argument per Ruby
+  argument.
+
+VALUE rb_yield_values2(int n, VALUE *argv) ::
+
+  Yields +n+ number of arguments to the block, with all Ruby arguments in the
+  C argv array.
+
+VALUE rb_yield_values_kw(int n, VALUE *argv, int kw_splat) ::
+
+  Same as rb_yield_values2, using +kw_splat+ to determine whether
+  keyword arguments are passed.
+
+VALUE rb_yield_splat(VALUE args) ::
+
+  Same as rb_yield_values2, except arguments are specified by the Ruby
+  array +args+.
+
+VALUE rb_yield_splat_kw(VALUE args, int kw_splat) ::
+
+  Same as rb_yield_splat, using +kw_splat+ to determine whether
+  keyword arguments are passed.
 
 VALUE rb_rescue(VALUE (*func1)(ANYARGS), VALUE arg1, VALUE (*func2)(ANYARGS), VALUE arg2) ::