Skip to content

Commit

Permalink
Document *_kw functions added to include/ruby/ruby.h [ci skip]
Browse files Browse the repository at this point in the history 
Also documents the non-*_kw functions if they were not already
documented.
  • Loading branch information
@jeremyevans
jeremyevans committed Oct 3, 2019
1 parent c7715a4 commit 9f24e8f
Showing 1 changed file with 107 additions and 6 deletions.
113 changes: 107 additions & 6 deletions doc/extension.rdoc
View file
Expand Up @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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+
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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) ::

Expand Down

0 comments on commit 9f24e8f

Please sign in to comment.