rbs 4.0.0.dev.4 → 4.0.0

data/core/proc.rbs

@@ -37,7 +37,7 @@
 #
 #         proc2 = proc {|x| x**2 }
 #
-# *   Receiving a block of code into proc argument (note the `&`):
+# *   Receiving a block of code into proc argument (note the <code>&</code>):
 #
 #         def make_proc(&block)
 #           block
@@ -149,7 +149,7 @@
 # method.
 #
 # Lambda semantics is typically preserved during the proc lifetime, including
-# `&`-deconstruction to a block of code:
+# <code>&</code>-deconstruction to a block of code:
 #
 #     p = proc {|x, y| x }
 #     l = lambda {|x, y| x }
@@ -184,7 +184,7 @@
 # ## Conversion of other objects to procs
 #
 # Any object that implements the `to_proc` method can be converted into a proc
-# by the `&` operator, and therefore can be consumed by iterators.
+# by the <code>&</code> operator, and therefore can be consumed by iterators.
 #
 #     class Greeter
 #       def initialize(greeting)
@@ -201,8 +201,8 @@
 #     ["Bob", "Jane"].map(&hi)    #=> ["Hi, Bob!", "Hi, Jane!"]
 #     ["Bob", "Jane"].map(&hey)   #=> ["Hey, Bob!", "Hey, Jane!"]
 #
-# Of the Ruby core classes, this method is implemented by Symbol, Method, and
-# Hash.
+# Of the Ruby core classes, this method is implemented by `Symbol`, `Method`,
+# and `Hash`.
 #
 #     :to_s.to_proc.call(1)           #=> "1"
 #     [1, 2].map(&:to_s)              #=> ["1", "2"]
@@ -285,7 +285,7 @@
 #     [1, 2, 3].each { |x| p it }
 #     # syntax error found (SyntaxError)
 #     # [1, 2, 3].each { |x| p it }
-#     #                        ^~ `it` is not allowed when an ordinary parameter is defined
+#     #                        ^~ 'it' is not allowed when an ordinary parameter is defined
 #
 # But if a local name (variable or method) is available, it would be used:
 #
@@ -302,7 +302,7 @@
 #
 #     p = proc { it**2 }
 #     l = lambda { it**2 }
-#     p.parameters     # => [[:opt, nil]]
+#     p.parameters     # => [[:opt]]
 #     p.arity          # => 1
 #     l.parameters     # => [[:req]]
 #     l.arity          # => 1
@@ -332,7 +332,7 @@
 # Numbered parameters can't be mixed with `it` either:
 #
 #     [10, 20, 30].map { _1 + it }
-#     # SyntaxError: `it` is not allowed when a numbered parameter is already used
+#     # SyntaxError: 'it' is not allowed when a numbered parameter is already used
 #
 # To avoid conflicts, naming local variables or method arguments `_1`, `_2` and
 # so on, causes an error.
@@ -377,12 +377,11 @@ class Proc
   def self.new: () { (?) -> untyped } -> instance
 
   def clone: () -> self
-  def dup: () -> self
 
   # <!-- rdoc-file=proc.c -->
-  # Invokes the block, setting the block's parameters to the values in *params*
-  # using something close to method calling semantics. Returns the value of the
-  # last expression evaluated in the block.
+  # Invokes the block, setting the block's parameters to the arguments using
+  # something close to method calling semantics. Returns the value of the last
+  # expression evaluated in the block.
   #
   #     a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } }
   #     a_proc.call(9, 1, 2, 3)    #=> [9, 18, 27]
@@ -390,13 +389,13 @@ class Proc
   #     a_proc.(9, 1, 2, 3)        #=> [9, 18, 27]
   #     a_proc.yield(9, 1, 2, 3)   #=> [9, 18, 27]
   #
-  # Note that `prc.()` invokes `prc.call()` with the parameters given.  It's
-  # syntactic sugar to hide "call".
+  # Note that <code>prc.()</code> invokes <code>prc.call()</code> with the
+  # parameters given.  It's syntactic sugar to hide "call".
   #
-  # For procs created using #lambda or `->()` an error is generated if the wrong
-  # number of parameters are passed to the proc.  For procs created using Proc.new
-  # or Kernel.proc, extra parameters are silently discarded and missing parameters
-  # are set to `nil`.
+  # For procs created using #lambda or <code>->()</code> an error is generated if
+  # the wrong number of parameters are passed to the proc.  For procs created
+  # using Proc.new or Kernel.proc, extra parameters are silently discarded and
+  # missing parameters are set to `nil`.
   #
   #     a_proc = proc {|a,b| [a,b] }
   #     a_proc.call(1)   #=> [1, nil]
@@ -409,9 +408,9 @@ class Proc
   alias === call
 
   # <!-- rdoc-file=proc.c -->
-  # Invokes the block, setting the block's parameters to the values in *params*
-  # using something close to method calling semantics. Returns the value of the
-  # last expression evaluated in the block.
+  # Invokes the block, setting the block's parameters to the arguments using
+  # something close to method calling semantics. Returns the value of the last
+  # expression evaluated in the block.
   #
   #     a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } }
   #     a_proc.call(9, 1, 2, 3)    #=> [9, 18, 27]
@@ -419,13 +418,13 @@ class Proc
   #     a_proc.(9, 1, 2, 3)        #=> [9, 18, 27]
   #     a_proc.yield(9, 1, 2, 3)   #=> [9, 18, 27]
   #
-  # Note that `prc.()` invokes `prc.call()` with the parameters given.  It's
-  # syntactic sugar to hide "call".
+  # Note that <code>prc.()</code> invokes <code>prc.call()</code> with the
+  # parameters given.  It's syntactic sugar to hide "call".
   #
-  # For procs created using #lambda or `->()` an error is generated if the wrong
-  # number of parameters are passed to the proc.  For procs created using Proc.new
-  # or Kernel.proc, extra parameters are silently discarded and missing parameters
-  # are set to `nil`.
+  # For procs created using #lambda or <code>->()</code> an error is generated if
+  # the wrong number of parameters are passed to the proc.  For procs created
+  # using Proc.new or Kernel.proc, extra parameters are silently discarded and
+  # missing parameters are set to `nil`.
   #
   #     a_proc = proc {|a,b| [a,b] }
   #     a_proc.call(1)   #=> [1, nil]
@@ -546,8 +545,8 @@ class Proc
   # lambdas and have only a finite number of optional arguments; in this latter
   # case, returns n. Keyword arguments will be considered as a single additional
   # argument, that argument being mandatory if any keyword argument is mandatory.
-  # A #proc with no argument declarations is the same as a block declaring `||` as
-  # its arguments.
+  # A #proc with no argument declarations is the same as a block declaring
+  # <code>||</code> as its arguments.
   #
   #     proc {}.arity                  #=>  0
   #     proc { || }.arity              #=>  0
@@ -592,14 +591,13 @@ class Proc
 
   # <!--
   #   rdoc-file=proc.c
-  #   - prc.call(params,...)   -> obj
-  #   - prc[params,...]        -> obj
-  #   - prc.(params,...)       -> obj
-  #   - prc.yield(params,...)  -> obj
+  #   - call(...) -> obj
+  #   - self[...] -> obj
+  #   - yield(...) -> obj
   # -->
-  # Invokes the block, setting the block's parameters to the values in *params*
-  # using something close to method calling semantics. Returns the value of the
-  # last expression evaluated in the block.
+  # Invokes the block, setting the block's parameters to the arguments using
+  # something close to method calling semantics. Returns the value of the last
+  # expression evaluated in the block.
   #
   #     a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } }
   #     a_proc.call(9, 1, 2, 3)    #=> [9, 18, 27]
@@ -607,13 +605,13 @@ class Proc
   #     a_proc.(9, 1, 2, 3)        #=> [9, 18, 27]
   #     a_proc.yield(9, 1, 2, 3)   #=> [9, 18, 27]
   #
-  # Note that `prc.()` invokes `prc.call()` with the parameters given.  It's
-  # syntactic sugar to hide "call".
+  # Note that <code>prc.()</code> invokes <code>prc.call()</code> with the
+  # parameters given.  It's syntactic sugar to hide "call".
   #
-  # For procs created using #lambda or `->()` an error is generated if the wrong
-  # number of parameters are passed to the proc.  For procs created using Proc.new
-  # or Kernel.proc, extra parameters are silently discarded and missing parameters
-  # are set to `nil`.
+  # For procs created using #lambda or <code>->()</code> an error is generated if
+  # the wrong number of parameters are passed to the proc.  For procs created
+  # using Proc.new or Kernel.proc, extra parameters are silently discarded and
+  # missing parameters are set to `nil`.
   #
   #     a_proc = proc {|a,b| [a,b] }
   #     a_proc.call(1)   #=> [1, nil]
@@ -626,9 +624,9 @@ class Proc
   def call: (?) -> untyped
 
   # <!-- rdoc-file=proc.c -->
-  # Invokes the block, setting the block's parameters to the values in *params*
-  # using something close to method calling semantics. Returns the value of the
-  # last expression evaluated in the block.
+  # Invokes the block, setting the block's parameters to the arguments using
+  # something close to method calling semantics. Returns the value of the last
+  # expression evaluated in the block.
   #
   #     a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } }
   #     a_proc.call(9, 1, 2, 3)    #=> [9, 18, 27]
@@ -636,13 +634,13 @@ class Proc
   #     a_proc.(9, 1, 2, 3)        #=> [9, 18, 27]
   #     a_proc.yield(9, 1, 2, 3)   #=> [9, 18, 27]
   #
-  # Note that `prc.()` invokes `prc.call()` with the parameters given.  It's
-  # syntactic sugar to hide "call".
+  # Note that <code>prc.()</code> invokes <code>prc.call()</code> with the
+  # parameters given.  It's syntactic sugar to hide "call".
   #
-  # For procs created using #lambda or `->()` an error is generated if the wrong
-  # number of parameters are passed to the proc.  For procs created using Proc.new
-  # or Kernel.proc, extra parameters are silently discarded and missing parameters
-  # are set to `nil`.
+  # For procs created using #lambda or <code>->()</code> an error is generated if
+  # the wrong number of parameters are passed to the proc.  For procs created
+  # using Proc.new or Kernel.proc, extra parameters are silently discarded and
+  # missing parameters are set to `nil`.
   #
   #     a_proc = proc {|a,b| [a,b] }
   #     a_proc.call(1)   #=> [1, nil]
@@ -749,7 +747,7 @@ class Proc
   #     Proc.new {}.lambda?          #=> false
   #
   # `lambda`, `proc` and Proc.new preserve the tricks of a Proc object given by
-  # `&` argument.
+  # <code>&</code> argument.
   #
   #     lambda(&lambda {}).lambda?   #=> true
   #     proc(&lambda {}).lambda?     #=> true
@@ -759,13 +757,13 @@ class Proc
   #     proc(&proc {}).lambda?       #=> false
   #     Proc.new(&proc {}).lambda?   #=> false
   #
-  # A Proc object generated by `&` argument has the tricks
+  # A Proc object generated by <code>&</code> argument has the tricks
   #
   #     def n(&b) b.lambda? end
   #     n {}                         #=> false
   #
-  # The `&` argument preserves the tricks if a Proc object is given by `&`
-  # argument.
+  # The <code>&</code> argument preserves the tricks if a Proc object is given by
+  # <code>&</code> argument.
   #
   #     n(&lambda {})                #=> true
   #     n(&proc {})                  #=> false
@@ -835,10 +833,49 @@ class Proc
 
   # <!--
   #   rdoc-file=proc.c
-  #   - prc.source_location  -> [String, Integer]
+  #   - proc.ruby2_keywords -> proc
   # -->
-  # Returns the Ruby source filename and line number containing this proc or `nil`
-  # if this proc was not defined in Ruby (i.e. native).
+  # Marks the proc as passing keywords through a normal argument splat. This
+  # should only be called on procs that accept an argument splat
+  # (<code>*args</code>) but not explicit keywords or a keyword splat.  It marks
+  # the proc such that if the proc is called with keyword arguments, the final
+  # hash argument is marked with a special flag such that if it is the final
+  # element of a normal argument splat to another method call, and that method
+  # call does not include explicit keywords or a keyword splat, the final element
+  # is interpreted as keywords.  In other words, keywords will be passed through
+  # the proc to other methods.
+  #
+  # This should only be used for procs that delegate keywords to another method,
+  # and only for backwards compatibility with Ruby versions before 2.7.
+  #
+  # This method will probably be removed at some point, as it exists only for
+  # backwards compatibility. As it does not exist in Ruby versions before 2.7,
+  # check that the proc responds to this method before calling it. Also, be aware
+  # that if this method is removed, the behavior of the proc will change so that
+  # it does not pass through keywords.
+  #
+  #     module Mod
+  #       foo = ->(meth, *args, &block) do
+  #         send(:"do_#{meth}", *args, &block)
+  #       end
+  #       foo.ruby2_keywords if foo.respond_to?(:ruby2_keywords)
+  #     end
+  #
+  def ruby2_keywords: () -> self
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - prc.source_location  -> [String, Integer, Integer, Integer, Integer]
+  # -->
+  # Returns the location where the Proc was defined. The returned Array contains:
+  #     (1) the Ruby source filename
+  #     (2) the line number where the definition starts
+  #     (3) the column number where the definition starts
+  #     (4) the line number where the definition ends
+  #     (5) the column number where the definitions ends
+  #
+  # This method will return `nil` if the Proc was not defined in Ruby (i.e.
+  # native).
   #
   def source_location: () -> [String, Integer]?