rbs 3.0.0.dev.2 → 3.0.0.dev.3

data/core/object.rbs

@@ -18,162 +18,92 @@
 #
 # First, what's elsewhere. Class Object:
 #
-# *   Inherits from [class
-#     BasicObject](BasicObject.html#class-BasicObject-label-What-27s+Here).
-# *   Includes [module Kernel](Kernel.html#module-Kernel-label-What-27s+Here).
+# *   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](#class-Object-label-Querying)
-# *   [Instance Variables](#class-Object-label-Instance+Variables)
-# *   [Other](#class-Object-label-Other)
+# *   [Querying](rdoc-ref:Object@Querying)
+# *   [Instance Variables](rdoc-ref:Object@Instance+Variables)
+# *   [Other](rdoc-ref:Object@Other)
 #
 #
 # ### Querying
 #
-#     [!~](#method-i-21~)
-# :       Returns `true` if `self` does not match the given object, otherwise
-#         `false`.
-#
-#     [<=>](#method-i-3C-3D-3E)
-# :       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.
+# *   #!~: 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`.
-#
+# *   #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`.
-#
-#     #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`.
+# *   #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
@@ -217,17 +147,6 @@ class Object < BasicObject
   #
   def ===: (untyped) -> bool
 
-  # <!--
-  #   rdoc-file=object.c
-  #   - obj =~ other  -> nil
-  # -->
-  # This method is deprecated.
-  #
-  # This is not only useless but also troublesome because it may hide a type
-  # error.
-  #
-  def =~: (untyped) -> bool
-
   # Returns the class of *obj*. This method must always be called with an explicit
   # receiver, as `class` is also a reserved word in Ruby.
   #
@@ -261,9 +180,9 @@ class Object < BasicObject
   #   - define_singleton_method(symbol, method) -> symbol
   #   - define_singleton_method(symbol) { block } -> symbol
   # -->
-  # Defines a singleton method in the receiver. The *method* parameter can be a
-  # `Proc`, a `Method` or an `UnboundMethod` object. If a block is specified, it
-  # is used as the method body. If a block or a method has parameters, they're
+  # Defines a public singleton method in the receiver. The *method* parameter can
+  # be a `Proc`, a `Method` or an `UnboundMethod` object. If a block is specified,
+  # it is used as the method body. If a block or a method has parameters, they're
   # used as method parameters.
   #
   #     class A
@@ -291,23 +210,16 @@ class Object < BasicObject
 
   # <!--
   #   rdoc-file=io.c
-  #   - obj.display(port=$>)    -> nil
+  #   - display(port = $>) -> nil
   # -->
-  # Prints *obj* on the given port (default `$>`). Equivalent to:
-  #
-  #     def display(port=$>)
-  #       port.write self
-  #       nil
-  #     end
-  #
-  # For example:
+  # Writes `self` on the given port:
   #
   #     1.display
   #     "cat".display
   #     [ 4, 5, 6 ].display
   #     puts
   #
-  # *produces:*
+  # Output:
   #
   #     1cat[4, 5, 6]
   #
@@ -586,6 +498,18 @@ class Object < BasicObject
   # Certain core classes such as Integer use built-in hash calculations and do not
   # call the #hash method when used as a hash key.
   #
+  # When implementing your own #hash based on multiple values, the best practice
+  # is to combine the class and any values using the hash code of an array:
+  #
+  # For example:
+  #
+  #     def hash
+  #       [self.class, a, b, c].hash
+  #     end
+  #
+  # The reason for this is that the Array#hash method already has logic for safely
+  # and efficiently combining multiple hash values.
+  #
   def hash: () -> Integer
 
   # <!--
@@ -1078,38 +1002,6 @@ class Object < BasicObject
   #
   def singleton_methods: () -> Array[Symbol]
 
-  # <!--
-  #   rdoc-file=object.c
-  #   - obj.taint -> obj
-  # -->
-  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
-  #
-  def taint: () -> self
-
-  # <!--
-  #   rdoc-file=object.c
-  #   - obj.untrust -> obj
-  # -->
-  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
-  #
-  alias untrust taint
-
-  # <!--
-  #   rdoc-file=object.c
-  #   - obj.tainted?    -> false
-  # -->
-  # Returns false.  This method is deprecated and will be removed in Ruby 3.2.
-  #
-  def tainted?: () -> bool
-
-  # <!--
-  #   rdoc-file=object.c
-  #   - obj.untrusted?    -> false
-  # -->
-  # Returns false.  This method is deprecated and will be removed in Ruby 3.2.
-  #
-  alias untrusted? tainted?
-
   # Yields self to the block, and then returns self. The primary purpose of this
   # method is to "tap into" a method chain, in order to perform operations on
   # intermediate results within the chain.
@@ -1157,22 +1049,6 @@ class Object < BasicObject
   #
   def to_s: () -> String
 
-  # <!--
-  #   rdoc-file=object.c
-  #   - obj.untaint    -> obj
-  # -->
-  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
-  #
-  def untaint: () -> self
-
-  # <!--
-  #   rdoc-file=object.c
-  #   - obj.trust    -> obj
-  # -->
-  # Returns object. This method is deprecated and will be removed in Ruby 3.2.
-  #
-  alias trust untaint
-
   # Yields self to the block and returns the result of the block.
   #
   #     3.next.then {|x| x**x }.to_s             #=> "256"
@@ -1202,4 +1078,4 @@ interface _Writeable
   def write: (untyped) -> void
 end
 
-type Object::name = Symbol | String
+type Object::name = Symbol | string

data/core/proc.rbs

@@ -51,8 +51,8 @@
 #         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 }
 #
@@ -421,6 +421,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
@@ -583,14 +587,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) -> ::Array[[ Symbol, Symbol ]]
 
   # <!--
   #   rdoc-file=proc.c

data/core/process.rbs

@@ -26,6 +26,12 @@ module Process
   # You can add custom code before and after fork events by overriding this
   # method.
   #
+  # Note: Process.daemon may be implemented using fork(2) BUT does not go through
+  # this method. Thus, depending on your reason to hook into this method, you may
+  # also want to hook into that one. See [this
+  # issue](https://bugs.ruby-lang.org/issues/18911) for a more detailed discussion
+  # of this.
+  #
   def self._fork: () -> Integer
 
   # <!--
@@ -229,7 +235,7 @@ module Process
   #
   # The underlying function, clock_gettime(), returns a number of nanoseconds.
   # Float object (IEEE 754 double) is not enough to represent the return value for
-  # CLOCK_REALTIME. If the exact nanoseconds value is required, use `:nanoseconds`
+  # CLOCK_REALTIME. If the exact nanoseconds value is required, use `:nanosecond`
   # as the `unit`.
   #
   # The origin (zero) of the returned value varies. For example, system start up
@@ -446,6 +452,7 @@ module Process
   # *   the result is sorted
   # *   the result includes effective GIDs
   # *   the result does not include duplicated GIDs
+  # *   the result size does not exceed the value of Process.maxgroups
   #
   #
   # You can make sure to get a sorted unique GID list of the current process by
@@ -474,7 +481,7 @@ module Process
   # Initializes the supplemental group access list by reading the system group
   # database and using all groups of which the given user is a member. The group
   # with the specified *gid* is also added to the list. Returns the resulting
-  # Array of the gids of all the groups in the supplementary group access list.
+  # Array of the GIDs of all the groups in the supplementary group access list.
   # Not available on all platforms.
   #
   #     Process.groups   #=> [0, 1, 2, 3, 4, 6, 10, 11, 20, 26, 27]
@@ -485,7 +492,7 @@ module Process
 
   # <!--
   #   rdoc-file=process.c
-  #   - Process.kill(signal, pid, ...)    -> integer
+  #   - Process.kill(signal, pid, *pids)    -> integer
   # -->
   # Sends the given signal to the specified process id(s) if *pid* is positive. If
   # *pid* is zero, *signal* is sent to all processes whose group ID is equal to
@@ -522,7 +529,7 @@ module Process
   #   rdoc-file=process.c
   #   - Process.maxgroups   -> integer
   # -->
-  # Returns the maximum number of gids allowed in the supplemental group access
+  # Returns the maximum number of GIDs allowed in the supplemental group access
   # list.
   #
   #     Process.maxgroups   #=> 32
@@ -533,7 +540,7 @@ module Process
   #   rdoc-file=process.c
   #   - Process.maxgroups= integer   -> integer
   # -->
-  # Sets the maximum number of gids allowed in the supplemental group access list.
+  # Sets the maximum number of GIDs allowed in the supplemental group access list.
   #
   def self.maxgroups=: (Integer arg0) -> Integer
 
@@ -640,6 +647,8 @@ module Process
   # :   file descriptors (number) (SUSv3)
   # NPROC
   # :   number of processes for the user (number) (4.4BSD, GNU/Linux)
+  # NPTS
+  # :   number of pseudo terminals (number) (FreeBSD)
   # RSS
   # :   resident memory size (bytes) (4.2BSD, GNU/Linux)
   # RTPRIO
@@ -996,6 +1005,14 @@ Process::RLIMIT_NOFILE: Integer
 #
 Process::RLIMIT_NPROC: Integer
 
+# <!-- rdoc-file=process.c -->
+# The maximum number of pseudo-terminals that can be created for the real user
+# ID of the calling process.
+#
+# see the system getrlimit(2) manual for details.
+#
+Process::RLIMIT_NPTS: Integer
+
 # <!-- rdoc-file=process.c -->
 # Specifies the limit (in pages) of the process's resident set.
 #

data/core/ractor.rbs

@@ -1,5 +1,5 @@
 # <!-- rdoc-file=ractor.rb -->
-# Ractor is a Actor-model abstraction for Ruby that provides thread-safe
+# Ractor is an Actor-model abstraction for Ruby that provides thread-safe
 # parallel execution.
 #
 # Ractor.new can make a new Ractor, and it will run in parallel.

data/core/random.rbs

@@ -20,6 +20,9 @@
 # of 2**19937-1.  As this algorithm is *not* for cryptographical use, you must
 # use SecureRandom for security purpose, instead of this PRNG.
 #
+# See also Random::Formatter module that adds convenience methods to generate
+# various forms of random data.
+#
 class Random < RBS::Unnamed::Random_Base
   # <!--
   #   rdoc-file=random.c
@@ -164,15 +167,18 @@ class Random < RBS::Unnamed::Random_Base
   def state: () -> untyped
 end
 
-Random::DEFAULT: Random
-
 class Random::Base < RBS::Unnamed::Random_Base
 end
 
 # <!-- rdoc-file=lib/random/formatter.rb -->
 # ## Random number formatter.
 #
-# Formats generated random numbers in many manners.
+# Formats generated random numbers in many manners. When `'random/formatter'` is
+# required, several methods are added to empty core module `Random::Formatter`,
+# making them available as Random's instance and module methods.
+#
+# Standard library SecureRandom is also extended with the module, and the
+# methods described below are available as a module methods in it.
 #
 # ### Examples
 #
@@ -180,30 +186,41 @@ end
 #
 #     require 'random/formatter'
 #
+#     prng = Random.new
 #     prng.hex(10) #=> "52750b30ffbc7de3b362"
 #     prng.hex(10) #=> "92b15d6c8dc4beb5f559"
 #     prng.hex(13) #=> "39b290146bea6ce975c37cfc23"
+#     # or just
+#     Random.hex #=> "1aed0c631e41be7f77365415541052ee"
 #
 # Generate random base64 strings:
 #
 #     prng.base64(10) #=> "EcmTPZwWRAozdA=="
 #     prng.base64(10) #=> "KO1nIU+p9DKxGg=="
 #     prng.base64(12) #=> "7kJSM/MzBJI+75j8"
+#     Random.base64(4) #=> "bsQ3fQ=="
 #
 # Generate random binary strings:
 #
 #     prng.random_bytes(10) #=> "\016\t{\370g\310pbr\301"
 #     prng.random_bytes(10) #=> "\323U\030TO\234\357\020\a\337"
+#     Random.random_bytes(6) #=> "\xA1\xE6Lr\xC43"
 #
 # Generate alphanumeric strings:
 #
 #     prng.alphanumeric(10) #=> "S8baxMJnPl"
 #     prng.alphanumeric(10) #=> "aOxAg8BAJe"
+#     Random.alphanumeric #=> "TmP9OsJHJLtaZYhP"
 #
 # Generate UUIDs:
 #
 #     prng.uuid #=> "2d931510-d99f-494a-8c67-87feb05e1594"
 #     prng.uuid #=> "bad85eb9-0713-4da7-8d36-07a8e4b00eab"
+#     Random.uuid #=> "f14e0271-de96-45cc-8911-8910292a42cd"
+#
+# All methods are available in the standard library SecureRandom, too:
+#
+#     SecureRandom.hex #=> "05b45376a30c67238eb93b16499e50cf"
 #
 # <!-- rdoc-file=random.c -->
 # Generate a random number in the given range as Random does