rbs 3.8.0.pre.1 → 3.8.0

data/core/nil_class.rbs

@@ -18,6 +18,9 @@
 # *   #to_r
 # *   #to_s
 #
+# While `nil` doesn't have an explicitly defined #to_hash method, it can be used
+# in `**` unpacking, not adding any keyword arguments.
+#
 # Another method provides inspection:
 #
 # *   #inspect

data/core/numeric.rbs

@@ -776,7 +776,7 @@ class Numeric
   #     Rational(1, 2).to_int # => 0
   #     Rational(2, 1).to_int # => 2
   #     Complex(2, 0).to_int  # => 2
-  #     Complex(2, 1)         # Raises RangeError (non-zero imaginary part)
+  #     Complex(2, 1).to_int  # Raises RangeError (non-zero imaginary part)
   #
   def to_int: () -> Integer
 

data/core/proc.rbs

@@ -236,19 +236,86 @@
 # Since `return` and `break` exits the block itself in lambdas, lambdas cannot
 # be orphaned.
 #
-# ## Numbered parameters
+# ## Anonymous block parameters
 #
-# Numbered parameters are implicitly defined block parameters intended to
-# simplify writing short blocks:
+# To simplify writing short blocks, Ruby provides two different types of
+# anonymous parameters: `it` (single parameter) and numbered ones: `_1`, `_2`
+# and so on.
 #
 #     # Explicit parameter:
 #     %w[test me please].each { |str| puts str.upcase } # prints TEST, ME, PLEASE
 #     (1..5).map { |i| i**2 } # => [1, 4, 9, 16, 25]
 #
-#     # Implicit parameter:
+#     # it:
+#     %w[test me please].each { puts it.upcase } # prints TEST, ME, PLEASE
+#     (1..5).map { it**2 } # => [1, 4, 9, 16, 25]
+#
+#     # Numbered parameter:
 #     %w[test me please].each { puts _1.upcase } # prints TEST, ME, PLEASE
 #     (1..5).map { _1**2 } # => [1, 4, 9, 16, 25]
 #
+# ### `it`
+#
+# `it` is a name that is available inside a block when no explicit parameters
+# defined, as shown above.
+#
+#     %w[test me please].each { puts it.upcase } # prints TEST, ME, PLEASE
+#     (1..5).map { it**2 } # => [1, 4, 9, 16, 25]
+#
+# `it` is a "soft keyword": it is not a reserved name, and can be used as a name
+# for methods and local variables:
+#
+#     it = 5 # no warnings
+#     def it(&block) # RSpec-like API, no warnings
+#        # ...
+#     end
+#
+# `it` can be used as a local variable even in blocks that use it as an implicit
+# parameter (though this style is obviously confusing):
+#
+#     [1, 2, 3].each {
+#       # takes a value of implicit parameter "it" and uses it to
+#       # define a local variable with the same name
+#       it = it**2
+#       p it
+#     }
+#
+# In a block with explicit parameters defined `it` usage raises an exception:
+#
+#     [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
+#
+# But if a local name (variable or method) is available, it would be used:
+#
+#     it = 5
+#     [1, 2, 3].each { |x| p it }
+#     # Prints 5, 5, 5
+#
+# Blocks using `it` can be nested:
+#
+#     %w[test me].each { it.each_char { p it } }
+#     # Prints "t", "e", "s", "t", "m", "e"
+#
+# Blocks using `it` are considered to have one parameter:
+#
+#     p = proc { it**2 }
+#     l = lambda { it**2 }
+#     p.parameters     # => [[:opt, nil]]
+#     p.arity          # => 1
+#     l.parameters     # => [[:req]]
+#     l.arity          # => 1
+#
+# ### Numbered parameters
+#
+# Numbered parameters are another way to name block parameters implicitly.
+# Unlike `it`, numbered parameters allow to refer to several parameters in one
+# block.
+#
+#     %w[test me please].each { puts _1.upcase } # prints TEST, ME, PLEASE
+#     {a: 100, b: 200}.map { "#{_1} = #{_2}" } # => "a = 100", "b = 200"
+#
 # Parameter names from `_1` to `_9` are supported:
 #
 #     [10, 20, 30].zip([40, 50, 60], [70, 80, 90]).map { _1 + _2 + _3 }
@@ -262,11 +329,16 @@
 #     [10, 20, 30].map { |x| _1**2 }
 #     # SyntaxError (ordinary parameter is defined)
 #
+# 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
+#
 # To avoid conflicts, naming local variables or method arguments `_1`, `_2` and
-# so on, causes a warning.
+# so on, causes an error.
 #
-#     _1 = 'test'
-#     # warning: `_1' is reserved as numbered parameter
+#       _1 = 'test'
+#     # ^~ _1 is reserved for numbered parameters (SyntaxError)
 #
 # Using implicit numbered parameters affects block's arity:
 #
@@ -280,12 +352,10 @@
 # Blocks with numbered parameters can't be nested:
 #
 #     %w[test me].each { _1.each_char { p _1 } }
-#     # SyntaxError (numbered parameter is already used in outer block here)
+#     # numbered parameter is already used in outer block (SyntaxError)
 #     # %w[test me].each { _1.each_char { p _1 } }
 #     #                    ^~
 #
-# Numbered parameters were introduced in Ruby 2.7.
-#
 class Proc
   interface _Callable
     def call: (?) -> untyped

data/core/ractor.rbs

@@ -588,6 +588,23 @@ class Ractor
   #
   def self.shareable?: (untyped obj) -> bool
 
+  # <!--
+  #   rdoc-file=ractor.rb
+  #   - Ractor.store_if_absent(key){ init_block }
+  # -->
+  # If the correponding value is not set, yield a value with init_block and store
+  # the value in thread-safe manner. This method returns corresponding stored
+  # value.
+  #
+  #     (1..10).map{
+  #       Thread.new(it){|i|
+  #         Ractor.store_if_absent(:s){ f(); i }
+  #         #=> return stored value of key :s
+  #       }
+  #     }.map(&:value).uniq.size #=> 1 and f() is called only once
+  #
+  def self.store_if_absent: (Symbol) { () -> untyped } -> untyped
+
   # <!--
   #   rdoc-file=ractor.rb
   #   - Ractor.yield(msg, move: false) -> nil

data/core/regexp.rbs

@@ -897,7 +897,7 @@
 # *   [Nl, Letter_Number](https://www.compart.com/en/unicode/category/Nl).
 # *   [No, Other_Number](https://www.compart.com/en/unicode/category/No).
 #
-# Punctation:
+# Punctuation:
 #
 # *   `P`, `Punctuation`: `Pc`, `Pd`, `Pe`, `Pf`, `Pi`, `Po`, or `Ps`.
 # *   [Pc,
@@ -1603,7 +1603,7 @@ class Regexp
   # `self`:
   #
   # *   Is a regexp literal; see [Regexp
-  #     Literals](rdoc-ref:literals.rdoc@Regexp+Literals).
+  #     Literals](rdoc-ref:syntax/literals.rdoc@Regexp+Literals).
   # *   Does not contain interpolations; see [Regexp
   #     interpolation](rdoc-ref:Regexp@Interpolation+Mode).
   # *   Is at the left of the expression.

data/core/ruby_vm.rbs

@@ -591,7 +591,7 @@ module RubyVM::AbstractSyntaxTree
 
   # <!-- rdoc-file=ast.rb -->
   # RubyVM::AbstractSyntaxTree::Location instances are created by
-  # RubyVM::AbstractSyntaxTree#locations.
+  # RubyVM::AbstractSyntaxTree::Node#locations.
   #
   # This class is MRI specific.
   #

data/core/rubygems/errors.rbs

@@ -83,7 +83,9 @@
 #
 # ## License
 #
-# See [LICENSE.txt](rdoc-ref:lib/rubygems/LICENSE.txt) for permissions.
+# See
+# [LICENSE.txt](https://github.com/rubygems/rubygems/blob/master/LICENSE.txt)
+# for permissions.
 #
 # Thanks!
 #

data/core/rubygems/rubygems.rbs

@@ -83,7 +83,9 @@
 #
 # ## License
 #
-# See [LICENSE.txt](rdoc-ref:lib/rubygems/LICENSE.txt) for permissions.
+# See
+# [LICENSE.txt](https://github.com/rubygems/rubygems/blob/master/LICENSE.txt)
+# for permissions.
 #
 # Thanks!
 #