rbs 2.8.4 → 3.8.1

data/core/object_space/weak_key_map.rbs

@@ -0,0 +1,166 @@
+%a{annotate:rdoc:skip}
+module ObjectSpace
+  # <!-- rdoc-file=weakmap.c -->
+  # An ObjectSpace::WeakKeyMap is a key-value map that holds weak references to
+  # its keys, so they can be garbage collected when there is no more references.
+  #
+  # Unlike ObjectSpace::WeakMap:
+  #
+  # *   references to values are *strong*, so they aren't garbage collected while
+  #     they are in the map;
+  # *   keys are compared by value (using Object#eql?), not by identity;
+  # *   only garbage-collectable objects can be used as keys.
+  #
+  #         map = ObjectSpace::WeakKeyMap.new
+  #         val = Time.new(2023, 12, 7)
+  #         key = "name"
+  #         map[key] = val
+  #
+  #         # Value is fetched by equality: the instance of string "name" is
+  #         # different here, but it is equal to the key
+  #         map["name"] #=> 2023-12-07 00:00:00 +0200
+  #
+  #         val = nil
+  #         GC.start
+  #         # There are no more references to `val`, yet the pair isn't
+  #         # garbage-collected.
+  #         map["name"] #=> 2023-12-07 00:00:00 +0200
+  #
+  #         key = nil
+  #         GC.start
+  #         # There are no more references to `key`, key and value are
+  #         # garbage-collected.
+  #         map["name"] #=> nil
+  #
+  # (Note that GC.start is used here only for demonstrational purposes and might
+  # not always lead to demonstrated results.)
+  #
+  # The collection is especially useful for implementing caches of lightweight
+  # value objects, so that only one copy of each value representation would be
+  # stored in memory, but the copies that aren't used would be garbage-collected.
+  #
+  #     CACHE = ObjectSpace::WeakKeyMap
+  #
+  #     def make_value(**)
+  #        val = ValueObject.new(**)
+  #        if (existing = @cache.getkey(val))
+  #           # if the object with this value exists, we return it
+  #           existing
+  #        else
+  #           # otherwise, put it in the cache
+  #           @cache[val] = true
+  #           val
+  #        end
+  #     end
+  #
+  # This will result in `make_value` returning the same object for same set of
+  # attributes always, but the values that aren't needed anymore wouldn't be
+  # sitting in the cache forever.
+  #
+  class WeakKeyMap[Key, Value]
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map[key] -> value
+    # -->
+    # Returns the value associated with the given `key` if found.
+    #
+    # If `key` is not found, returns `nil`.
+    #
+    def []: (Key) -> Value?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map[key] = value -> value
+    # -->
+    # Associates the given `value` with the given `key`
+    #
+    # The reference to `key` is weak, so when there is no other reference to `key`
+    # it may be garbage collected.
+    #
+    # If the given `key` exists, replaces its value with the given `value`; the
+    # ordering is not affected
+    #
+    def []=: (Key, Value?) -> Value?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.clear -> self
+    # -->
+    # Removes all map entries; returns `self`.
+    #
+    def clear: () -> self
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.delete(key) -> value or nil
+    #   - map.delete(key) {|key| ... } -> object
+    # -->
+    # Deletes the entry for the given `key` and returns its associated value.
+    #
+    # If no block is given and `key` is found, deletes the entry and returns the
+    # associated value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     key = "foo" # to hold reference to the key
+    #     m[key] = 1
+    #     m.delete("foo") # => 1
+    #     m["foo"] # => nil
+    #
+    # If no block given and `key` is not found, returns `nil`.
+    #
+    # If a block is given and `key` is found, ignores the block, deletes the entry,
+    # and returns the associated value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     key = "foo" # to hold reference to the key
+    #     m[key] = 2
+    #     m.delete("foo") { |key| raise 'Will never happen'} # => 2
+    #
+    # If a block is given and `key` is not found, yields the `key` to the block and
+    # returns the block's return value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m.delete("nosuch") { |key| "Key #{key} not found" } # => "Key nosuch not found"
+    #
+    def delete: (Key) -> Value?
+              | [T] (Key) { (Key) -> T } -> (Value | T)
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.getkey(key) -> existing_key or nil
+    # -->
+    # Returns the existing equal key if it exists, otherwise returns `nil`.
+    #
+    # This might be useful for implementing caches, so that only one copy of some
+    # object would be used everywhere in the program:
+    #
+    #     value = {amount: 1, currency: 'USD'}
+    #
+    #     # Now if we put this object in a cache:
+    #     cache = ObjectSpace::WeakKeyMap.new
+    #     cache[value] = true
+    #
+    #     # ...we can always extract from there and use the same object:
+    #     copy = cache.getkey({amount: 1, currency: 'USD'})
+    #     copy.object_id == value.object_id #=> true
+    #
+    def getkey: (untyped) -> Key?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.inspect -> new_string
+    # -->
+    # Returns a new String containing informations about the map:
+    #
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m[key] = value
+    #     m.inspect # => "#<ObjectSpace::WeakKeyMap:0x00000001028dcba8 size=1>"
+    #
+    def inspect: () -> String
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.key?(key) -> true or false
+    # -->
+    # Returns `true` if `key` is a key in `self`, otherwise `false`.
+    #
+    def key?: (Key) -> bool
+  end
+end

data/core/object_space.rbs

@@ -4,9 +4,9 @@
 # an iterator.
 #
 # ObjectSpace also provides support for object finalizers, procs that will be
-# called when a specific object is about to be destroyed by garbage collection.
-# See the documentation for `ObjectSpace.define_finalizer` for important
-# information on how to use this method correctly.
+# called after a specific object was destroyed by garbage collection.  See the
+# documentation for `ObjectSpace.define_finalizer` for important information on
+# how to use this method correctly.
 #
 #     a = "A"
 #     b = "B"
@@ -166,6 +166,7 @@ module ObjectSpace
   #   rdoc-file=gc.rb
   #   - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
   # -->
+  # Alias of GC.start
   #
   def self.garbage_collect: (?full_mark: bool, ?immediate_mark: bool, ?immediate_sweep: bool) -> void
 
@@ -183,6 +184,7 @@ module ObjectSpace
   #   rdoc-file=gc.rb
   #   - garbage_collect(full_mark: true, immediate_mark: true, immediate_sweep: true)
   # -->
+  # Alias of GC.start
   #
   def garbage_collect: (?full_mark: bool, ?immediate_mark: bool, ?immediate_sweep: bool) -> void
 end

data/core/proc.rbs

@@ -51,12 +51,11 @@
 #         lambda1 = lambda {|x| x**2 }
 #
 # *   Use the [Lambda proc
-#     literal](doc/syntax/literals_rdoc.html#label-Lambda+Proc+Literals) syntax
-#     (also constructs a proc with lambda semantics):
+#     literal](rdoc-ref:syntax/literals.rdoc@Lambda+Proc+Literals) syntax (also
+#     constructs a proc with lambda semantics):
 #
 #         lambda2 = ->(x) { x**2 }
 #
-#
 # ## Lambda and non-lambda semantics
 #
 # Procs are coming in two flavors: lambda and non-lambda (regular procs).
@@ -75,7 +74,6 @@
 #     filled with `nil`, single Array arguments are deconstructed if the proc
 #     has multiple arguments, and there is no error raised on extra arguments.
 #
-#
 # Examples:
 #
 #     # +return+ in non-lambda proc, +b+, exits +m2+.
@@ -238,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 }
@@ -264,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:
 #
@@ -282,14 +352,188 @@
 # 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 < Object
-  def clone: () -> self
+class Proc
+  interface _Callable
+    def call: (?) -> untyped
+  end
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - Proc.new {|...| block } -> a_proc
+  # -->
+  # Creates a new Proc object, bound to the current context.
+  #
+  #     proc = Proc.new { "hello" }
+  #     proc.call   #=> "hello"
+  #
+  # Raises ArgumentError if called without a block.
+  #
+  #     Proc.new    #=> ArgumentError
+  #
+  def self.new: () { (?) -> untyped } -> instance
+
+  def clone: () -> instance
+  def dup: () -> instance
+
+  # <!-- 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.
+  #
+  #     a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } }
+  #     a_proc.call(9, 1, 2, 3)    #=> [9, 18, 27]
+  #     a_proc[9, 1, 2, 3]         #=> [9, 18, 27]
+  #     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".
+  #
+  # 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`.
+  #
+  #     a_proc = proc {|a,b| [a,b] }
+  #     a_proc.call(1)   #=> [1, nil]
+  #
+  #     a_proc = lambda {|a,b| [a,b] }
+  #     a_proc.call(1)   # ArgumentError: wrong number of arguments (given 1, expected 2)
+  #
+  # See also Proc#lambda?.
+  #
+  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.
+  #
+  #     a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } }
+  #     a_proc.call(9, 1, 2, 3)    #=> [9, 18, 27]
+  #     a_proc[9, 1, 2, 3]         #=> [9, 18, 27]
+  #     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".
+  #
+  # 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`.
+  #
+  #     a_proc = proc {|a,b| [a,b] }
+  #     a_proc.call(1)   #=> [1, nil]
+  #
+  #     a_proc = lambda {|a,b| [a,b] }
+  #     a_proc.call(1)   # ArgumentError: wrong number of arguments (given 1, expected 2)
+  #
+  # See also Proc#lambda?.
+  #
+  alias yield call
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - prc << g -> a_proc
+  # -->
+  # Returns a proc that is the composition of this proc and the given *g*. The
+  # returned proc takes a variable number of arguments, calls *g* with them then
+  # calls this proc with the result.
+  #
+  #     f = proc {|x| x * x }
+  #     g = proc {|x| x + x }
+  #     p (f << g).call(2) #=> 16
+  #
+  # See Proc#>> for detailed explanations.
+  #
+  def <<: (_Callable callable) -> Proc
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - prc >> g -> a_proc
+  # -->
+  # Returns a proc that is the composition of this proc and the given *g*. The
+  # returned proc takes a variable number of arguments, calls this proc with them
+  # then calls *g* with the result.
+  #
+  #     f = proc {|x| x * x }
+  #     g = proc {|x| x + x }
+  #     p (f >> g).call(2) #=> 8
+  #
+  # *g* could be other Proc, or Method, or any other object responding to `call`
+  # method:
+  #
+  #     class Parser
+  #       def self.call(text)
+  #          # ...some complicated parsing logic...
+  #       end
+  #     end
+  #
+  #     pipeline = File.method(:read) >> Parser >> proc { |data| puts "data size: #{data.count}" }
+  #     pipeline.call('data.json')
+  #
+  # See also Method#>> and Method#<<.
+  #
+  def >>: (_Callable callable) -> Proc
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - prc == other -> true or false
+  #   - prc.eql?(other) -> true or false
+  # -->
+  # Two procs are the same if, and only if, they were created from the same code
+  # block.
+  #
+  #     def return_block(&block)
+  #       block
+  #     end
+  #
+  #     def pass_block_twice(&block)
+  #       [return_block(&block), return_block(&block)]
+  #     end
+  #
+  #     block1, block2 = pass_block_twice { puts 'test' }
+  #     # Blocks might be instantiated into Proc's lazily, so they may, or may not,
+  #     # be the same object.
+  #     # But they are produced from the same code block, so they are equal
+  #     block1 == block2
+  #     #=> true
+  #
+  #     # Another Proc will never be equal, even if the code is the "same"
+  #     block1 == proc { puts 'test' }
+  #     #=> false
+  #
+  def ==: (untyped other) -> bool
+
+  # <!-- rdoc-file=proc.c -->
+  # Two procs are the same if, and only if, they were created from the same code
+  # block.
+  #
+  #     def return_block(&block)
+  #       block
+  #     end
+  #
+  #     def pass_block_twice(&block)
+  #       [return_block(&block), return_block(&block)]
+  #     end
+  #
+  #     block1, block2 = pass_block_twice { puts 'test' }
+  #     # Blocks might be instantiated into Proc's lazily, so they may, or may not,
+  #     # be the same object.
+  #     # But they are produced from the same code block, so they are equal
+  #     block1 == block2
+  #     #=> true
+  #
+  #     # Another Proc will never be equal, even if the code is the "same"
+  #     block1 == proc { puts 'test' }
+  #     #=> false
+  #
+  alias eql? ==
 
   # <!--
   #   rdoc-file=proc.c
@@ -379,7 +623,7 @@ class Proc < Object
   #
   # See also Proc#lambda?.
   #
-  def call: (*untyped arg0) -> untyped
+  def call: (?) -> untyped
 
   # <!-- rdoc-file=proc.c -->
   # Invokes the block, setting the block's parameters to the values in *params*
@@ -408,7 +652,7 @@ class Proc < Object
   #
   # See also Proc#lambda?.
   #
-  def []: (*untyped arg0) -> untyped
+  alias [] call
 
   # <!--
   #   rdoc-file=proc.c
@@ -421,6 +665,10 @@ class Proc < Object
   # arguments to the original proc and returns the result. Otherwise, returns
   # another curried proc that takes the rest of arguments.
   #
+  # The optional *arity* argument should be supplied when currying procs with
+  # variable arguments to determine how many arguments are needed before the proc
+  # is called.
+  #
   #     b = proc {|x, y, z| (x||0) + (y||0) + (z||0) }
   #     p b.curry[1][2][3]           #=> 6
   #     p b.curry[1, 2][3, 4]        #=> 6
@@ -451,7 +699,7 @@ class Proc < Object
   #     b = proc { :foo }
   #     p b.curry[]                  #=> :foo
   #
-  def curry: (?_ToInt arity) -> Proc
+  def curry: (?int? arity) -> Proc
 
   # <!--
   #   rdoc-file=proc.c
@@ -463,21 +711,6 @@ class Proc < Object
   #
   def hash: () -> Integer
 
-  # <!--
-  #   rdoc-file=proc.c
-  #   - Proc.new {|...| block } -> a_proc
-  # -->
-  # Creates a new Proc object, bound to the current context.
-  #
-  #     proc = Proc.new { "hello" }
-  #     proc.call   #=> "hello"
-  #
-  # Raises ArgumentError if called without a block.
-  #
-  #     Proc.new    #=> ArgumentError
-  #
-  def initialize: () { (*untyped) -> untyped } -> void
-
   # <!--
   #   rdoc-file=proc.c
   #   - prc.lambda? -> true or false
@@ -583,14 +816,22 @@ class Proc < Object
 
   # <!--
   #   rdoc-file=proc.c
-  #   - prc.parameters  -> array
+  #   - prc.parameters(lambda: nil)  -> array
   # -->
-  # Returns the parameter information of this proc.
+  # Returns the parameter information of this proc.  If the lambda keyword is
+  # provided and not nil, treats the proc as a lambda if true and as a non-lambda
+  # if false.
   #
+  #     prc = proc{|x, y=42, *other|}
+  #     prc.parameters  #=> [[:opt, :x], [:opt, :y], [:rest, :other]]
   #     prc = lambda{|x, y=42, *other|}
   #     prc.parameters  #=> [[:req, :x], [:opt, :y], [:rest, :other]]
+  #     prc = proc{|x, y=42, *other|}
+  #     prc.parameters(lambda: true)  #=> [[:req, :x], [:opt, :y], [:rest, :other]]
+  #     prc = lambda{|x, y=42, *other|}
+  #     prc.parameters(lambda: false) #=> [[:opt, :x], [:opt, :y], [:rest, :other]]
   #
-  def parameters: () -> ::Array[[ Symbol, Symbol ]]
+  def parameters: (?lambda: boolish) -> Method::param_types
 
   # <!--
   #   rdoc-file=proc.c
@@ -599,7 +840,7 @@ class Proc < Object
   # Returns the Ruby source filename and line number containing this proc or `nil`
   # if this proc was not defined in Ruby (i.e. native).
   #
-  def source_location: () -> [ String, Integer ]
+  def source_location: () -> [String, Integer]?
 
   # <!--
   #   rdoc-file=proc.c
@@ -623,5 +864,5 @@ class Proc < Object
   # Returns the unique identifier for this proc, along with an indication of where
   # the proc was defined.
   #
-  def inspect: () -> String
+  alias inspect to_s
 end