rbs-relaxed 3.9.0.1

data/core/object.rbs

@@ -0,0 +1,110 @@
+# <!-- rdoc-file=object.c -->
+# Object is the default root of all Ruby objects.  Object inherits from
+# BasicObject which allows creating alternate object hierarchies.  Methods on
+# Object are available to all classes unless explicitly overridden.
+#
+# Object mixes in the Kernel module, making the built-in kernel functions
+# globally accessible.  Although the instance methods of Object are defined by
+# the Kernel module, we have chosen to document them here for clarity.
+#
+# When referencing constants in classes inheriting from Object you do not need
+# to use the full namespace.  For example, referencing `File` inside `YourClass`
+# will find the top-level File class.
+#
+# In the descriptions of Object's methods, the parameter *symbol* refers to a
+# symbol, which is either a quoted string or a Symbol (such as `:name`).
+#
+# ## What's Here
+#
+# First, what's elsewhere. Class Object:
+#
+# *   Inherits from [class BasicObject](rdoc-ref:BasicObject@What-27s+Here).
+# *   Includes [module Kernel](rdoc-ref:Kernel@What-27s+Here).
+#
+# Here, class Object provides methods for:
+#
+# *   [Querying](rdoc-ref:Object@Querying)
+# *   [Instance Variables](rdoc-ref:Object@Instance+Variables)
+# *   [Other](rdoc-ref:Object@Other)
+#
+# ### Querying
+#
+# *   #!~: Returns `true` if `self` does not match the given object, otherwise
+#     `false`.
+# *   #<=>: Returns 0 if `self` and the given object `object` are the same
+#     object, or if `self == object`; otherwise returns `nil`.
+# *   #===: Implements case equality, effectively the same as calling #==.
+# *   #eql?: Implements hash equality, effectively the same as calling #==.
+# *   #kind_of? (aliased as #is_a?): Returns whether given argument is an
+#     ancestor of the singleton class of `self`.
+# *   #instance_of?: Returns whether `self` is an instance of the given class.
+# *   #instance_variable_defined?: Returns whether the given instance variable
+#     is defined in `self`.
+# *   #method: Returns the Method object for the given method in `self`.
+# *   #methods: Returns an array of symbol names of public and protected methods
+#     in `self`.
+# *   #nil?: Returns `false`. (Only `nil` responds `true` to method `nil?`.)
+# *   #object_id: Returns an integer corresponding to `self` that is unique for
+#     the current process
+# *   #private_methods: Returns an array of the symbol names of the private
+#     methods in `self`.
+# *   #protected_methods: Returns an array of the symbol names of the protected
+#     methods in `self`.
+# *   #public_method: Returns the Method object for the given public method in
+#     `self`.
+# *   #public_methods: Returns an array of the symbol names of the public
+#     methods in `self`.
+# *   #respond_to?: Returns whether `self` responds to the given method.
+# *   #singleton_class: Returns the singleton class of `self`.
+# *   #singleton_method: Returns the Method object for the given singleton
+#     method in `self`.
+# *   #singleton_methods: Returns an array of the symbol names of the singleton
+#     methods in `self`.
+#
+# *   #define_singleton_method: Defines a singleton method in `self` for the
+#     given symbol method-name and block or proc.
+# *   #extend: Includes the given modules in the singleton class of `self`.
+# *   #public_send: Calls the given public method in `self` with the given
+#     argument.
+# *   #send: Calls the given method in `self` with the given argument.
+#
+# ### Instance Variables
+#
+# *   #instance_variable_get: Returns the value of the given instance variable
+#     in `self`, or `nil` if the instance variable is not set.
+# *   #instance_variable_set: Sets the value of the given instance variable in
+#     `self` to the given object.
+# *   #instance_variables: Returns an array of the symbol names of the instance
+#     variables in `self`.
+# *   #remove_instance_variable: Removes the named instance variable from
+#     `self`.
+#
+# ### Other
+#
+# *   #clone:  Returns a shallow copy of `self`, including singleton class and
+#     frozen state.
+# *   #define_singleton_method: Defines a singleton method in `self` for the
+#     given symbol method-name and block or proc.
+# *   #display: Prints `self` to the given IO stream or `$stdout`.
+# *   #dup: Returns a shallow unfrozen copy of `self`.
+# *   #enum_for (aliased as #to_enum): Returns an Enumerator for `self` using
+#     the using the given method, arguments, and block.
+# *   #extend: Includes the given modules in the singleton class of `self`.
+# *   #freeze: Prevents further modifications to `self`.
+# *   #hash: Returns the integer hash value for `self`.
+# *   #inspect: Returns a human-readable  string representation of `self`.
+# *   #itself: Returns `self`.
+# *   #method_missing: Method called when an undefined method is called on
+#     `self`.
+# *   #public_send: Calls the given public method in `self` with the given
+#     argument.
+# *   #send: Calls the given method in `self` with the given argument.
+# *   #to_s: Returns a string representation of `self`.
+#
+class Object < BasicObject
+  include Kernel
+end
+
+# A previous incarnation of `interned` for backward-compatibility (see #1499)
+%a{steep:deprecated}
+type Object::name = interned

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

@@ -0,0 +1,190 @@
+# <!-- rdoc-file=gc.c -->
+# The ObjectSpace module contains a number of routines that interact with the
+# garbage collection facility and allow you to traverse all living objects with
+# an iterator.
+#
+# ObjectSpace also provides support for object finalizers, procs that will be
+# 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"
+#
+#     ObjectSpace.define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
+#     ObjectSpace.define_finalizer(b, proc {|id| puts "Finalizer two on #{id}" })
+#
+#     a = nil
+#     b = nil
+#
+# *produces:*
+#
+#     Finalizer two on 537763470
+#     Finalizer one on 537763480
+#
+%a{annotate:rdoc:source:from=gc.c}
+module ObjectSpace
+  # <!--
+  #   rdoc-file=gc.c
+  #   - _id2ref(p1)
+  # -->
+  #
+  def self._id2ref: (Integer id) -> untyped
+
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.count_objects([result_hash]) -> hash
+  # -->
+  # Counts all objects grouped by type.
+  #
+  # It returns a hash, such as:
+  #     {
+  #       :TOTAL=>10000,
+  #       :FREE=>3011,
+  #       :T_OBJECT=>6,
+  #       :T_CLASS=>404,
+  #       # ...
+  #     }
+  #
+  # The contents of the returned hash are implementation specific. It may be
+  # changed in future.
+  #
+  # The keys starting with `:T_` means live objects. For example, `:T_ARRAY` is
+  # the number of arrays. `:FREE` means object slots which is not used now.
+  # `:TOTAL` means sum of above.
+  #
+  # If the optional argument `result_hash` is given, it is overwritten and
+  # returned. This is intended to avoid probe effect.
+  #
+  #     h = {}
+  #     ObjectSpace.count_objects(h)
+  #     puts h
+  #     # => { :TOTAL=>10000, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249 }
+  #
+  # This method is only expected to work on C Ruby.
+  #
+  def self.count_objects: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
+
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.define_finalizer(obj, aProc=proc())
+  # -->
+  # Adds *aProc* as a finalizer, to be called after *obj* was destroyed. The
+  # object ID of the *obj* will be passed as an argument to *aProc*. If *aProc* is
+  # a lambda or method, make sure it can be called with a single argument.
+  #
+  # The return value is an array `[0, aProc]`.
+  #
+  # The two recommended patterns are to either create the finaliser proc in a
+  # non-instance method where it can safely capture the needed state, or to use a
+  # custom callable object that stores the needed state explicitly as instance
+  # variables.
+  #
+  #     class Foo
+  #       def initialize(data_needed_for_finalization)
+  #         ObjectSpace.define_finalizer(self, self.class.create_finalizer(data_needed_for_finalization))
+  #       end
+  #
+  #       def self.create_finalizer(data_needed_for_finalization)
+  #         proc {
+  #           puts "finalizing #{data_needed_for_finalization}"
+  #         }
+  #       end
+  #     end
+  #
+  #     class Bar
+  #      class Remover
+  #         def initialize(data_needed_for_finalization)
+  #           @data_needed_for_finalization = data_needed_for_finalization
+  #         end
+  #
+  #         def call(id)
+  #           puts "finalizing #{@data_needed_for_finalization}"
+  #         end
+  #       end
+  #
+  #       def initialize(data_needed_for_finalization)
+  #         ObjectSpace.define_finalizer(self, Remover.new(data_needed_for_finalization))
+  #       end
+  #     end
+  #
+  # Note that if your finalizer references the object to be finalized it will
+  # never be run on GC, although it will still be run at exit. You will get a
+  # warning if you capture the object to be finalized as the receiver of the
+  # finalizer.
+  #
+  #     class CapturesSelf
+  #       def initialize(name)
+  #         ObjectSpace.define_finalizer(self, proc {
+  #           # this finalizer will only be run on exit
+  #           puts "finalizing #{name}"
+  #         })
+  #       end
+  #     end
+  #
+  # Also note that finalization can be unpredictable and is never guaranteed to be
+  # run except on exit.
+  #
+  def self.define_finalizer: (untyped obj, ^(Integer id) -> void aProc) -> [ Integer, Proc ]
+                           | (untyped obj) { (Integer id) -> void } -> [ Integer, Proc ]
+
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.each_object([module]) {|obj| ... } -> integer
+  #   - ObjectSpace.each_object([module])              -> an_enumerator
+  # -->
+  # Calls the block once for each living, nonimmediate object in this Ruby
+  # process. If *module* is specified, calls the block for only those classes or
+  # modules that match (or are a subclass of) *module*. Returns the number of
+  # objects found. Immediate objects (`Fixnum`s, `Symbol`s `true`, `false`, and
+  # `nil`) are never returned. In the example below, #each_object returns both the
+  # numbers we defined and several constants defined in the Math module.
+  #
+  # If no block is given, an enumerator is returned instead.
+  #
+  #     a = 102.7
+  #     b = 95       # Won't be returned
+  #     c = 12345678987654321
+  #     count = ObjectSpace.each_object(Numeric) {|x| p x }
+  #     puts "Total count: #{count}"
+  #
+  # *produces:*
+  #
+  #     12345678987654321
+  #     102.7
+  #     2.71828182845905
+  #     3.14159265358979
+  #     2.22044604925031e-16
+  #     1.7976931348623157e+308
+  #     2.2250738585072e-308
+  #     Total count: 7
+  #
+  def self.each_object: (?Module `module`) -> Enumerator[untyped, Integer]
+                      | (?Module `module`) { (untyped obj) -> void } -> Integer
+
+  # <!--
+  #   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
+
+  # <!--
+  #   rdoc-file=gc.c
+  #   - ObjectSpace.undefine_finalizer(obj)
+  # -->
+  # Removes all finalizers for *obj*.
+  #
+  def self.undefine_finalizer: [X] (X obj) -> X
+
+  private
+
+  # <!--
+  #   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