kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

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

Browse source 
Also documents the non-*_kw functions if they were not already
documented.
This commit is contained in:
Jeremy Evans 2019-10-03 14:07:32 -07:00
parent c7715a4936
commit 9f24e8fdbb
1 changed files with 107 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

113
doc/extension.rdoc
View file

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