rbs 3.9.4 → 3.10.2

data/core/enumerable.rbs

@@ -114,8 +114,8 @@
 #     by the block.
 # *   #grep: Returns elements selected by a given object or objects returned by
 #     a given block.
-# *   #grep_v: Returns elements selected by a given object or objects returned
-#     by a given block.
+# *   #grep_v: Returns elements not selected by a given object or objects
+#     returned by a given block.
 # *   #inject (aliased as #reduce): Returns the object formed by combining all
 #     elements.
 # *   #sum: Returns the sum of the elements, using method `+`.
@@ -191,6 +191,82 @@
 #     usage would not make sense, and so it is not shown.  Example: #tally would
 #     find exactly one of each Hash entry.
 #
+# ## Extended Methods
+#
+# A Enumerable class may define extended methods. This section describes the
+# standard behavior of extension methods for reference purposes.
+#
+# ### #size
+#
+# Enumerator has a #size method. It uses the size function argument passed to
+# `Enumerator.new`.
+#
+#     e = Enumerator.new(-> { 3 }) {|y| p y; y.yield :a; y.yield :b; y.yield :c; :z }
+#     p e.size #=> 3
+#     p e.next #=> :a
+#     p e.next #=> :b
+#     p e.next #=> :c
+#     begin
+#       e.next
+#     rescue StopIteration
+#       p $!.result #=> :z
+#     end
+#
+# The result of the size function should represent the number of iterations
+# (i.e., the number of times Enumerator::Yielder#yield is called). In the above
+# example, the block calls #yield three times, and the size function, +-> { 3
+# }+, returns 3 accordingly. The result of the size function can be an integer,
+# `Float::INFINITY`, or `nil`. An integer means the exact number of times #yield
+# will be called, as shown above. `Float::INFINITY` indicates an infinite number
+# of #yield calls. `nil` means the number of #yield calls is difficult or
+# impossible to determine.
+#
+# Many iteration methods return an Enumerator object with an appropriate size
+# function if no block is given.
+#
+# Examples:
+#
+#     ["a", "b", "c"].each.size #=> 3
+#     {a: "x", b: "y", c: "z"}.each.size #=> 3
+#     (0..20).to_a.permutation.size #=> 51090942171709440000
+#     loop.size #=> Float::INFINITY
+#     (1..100).drop_while.size #=> nil  # size depends on the block's behavior
+#     STDIN.each.size #=> nil # cannot be computed without consuming input
+#     File.open("/etc/resolv.conf").each.size #=> nil # cannot be computed without reading the file
+#
+# The behavior of #size for Range-based enumerators depends on the #begin
+# element:
+#
+# *   If the #begin element is an Integer, the #size method returns an Integer
+#     or `Float::INFINITY`.
+# *   If the #begin element is an object with a #succ method (other than
+#     Integer), #size returns `nil`. (Computing the size would require
+#     repeatedly calling #succ, which may be too slow.)
+# *   If the #begin element does not have a #succ method, #size raises a
+#     TypeError.
+#
+# Examples:
+#
+#     (10..42).each.size #=> 33
+#     (10..42.9).each.size #=> 33 (the #end element may be a non-integer numeric)
+#     (10..).each.size #=> Float::INFINITY
+#     ("a".."z").each.size #=> nil
+#     ("a"..).each.size #=> nil
+#     (1.0..9.0).each.size # raises TypeError (Float does not have #succ)
+#     (..10).each.size # raises TypeError (beginless range has nil as its #begin)
+#
+# The Enumerable module itself does not define a #size method. A class that
+# includes Enumerable may define its own #size method. It is recommended that
+# such a #size method be consistent with Enumerator#size.
+#
+# Array and Hash implement #size and return values consistent with
+# Enumerator#size. IO and Dir do not define #size, which is also consistent
+# because the corresponding enumerator's size function returns `nil`.
+#
+# However, it is not strictly required for a class's #size method to match
+# Enumerator#size. For example, File#size returns the number of bytes in the
+# file, not the number of lines.
+#
 module Enumerable[unchecked out Elem] : _Each[Elem]
   # <!--
   #   rdoc-file=enum.c
@@ -438,6 +514,17 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   #
   # With no block given, returns an Enumerator.
   #
+  #     e = (1..4).drop_while
+  #     p e #=> #<Enumerator: 1..4:drop_while>
+  #     i = e.next; p i; e.feed(i < 3) #=> 1
+  #     i = e.next; p i; e.feed(i < 3) #=> 2
+  #     i = e.next; p i; e.feed(i < 3) #=> 3
+  #     begin
+  #       e.next
+  #     rescue StopIteration
+  #       p $!.result #=> [3, 4]
+  #     end
+  #
   def drop_while: () { (Elem) -> boolish } -> ::Array[Elem]
                 | () -> ::Enumerator[Elem, ::Array[Elem]]
 
@@ -2040,7 +2127,7 @@ module Enumerable[unchecked out Elem] : _Each[Elem]
   #     ["F", 6860]
   #
   # You can use the special symbol `:_alone` to force an element into its own
-  # separate chuck:
+  # separate chunk:
   #
   #     a = [0, 0, 1, 1]
   #     e = a.chunk{|i| i.even? ? :_alone : true }

data/core/enumerator.rbs

@@ -137,7 +137,7 @@ class Enumerator[unchecked out Elem, out Return = void] < Object
 
   # <!--
   #   rdoc-file=enumerator.c
-  #   - Enumerator.produce(initial = nil) { |prev| block } -> enumerator
+  #   - Enumerator.produce(initial = nil, size: nil) { |prev| block } -> enumerator
   # -->
   # Creates an infinite enumerator from any block, just called over and over.  The
   # result of the previous iteration is passed to the next one. If `initial` is
@@ -169,6 +169,29 @@ class Enumerator[unchecked out Elem, out Return = void] < Object
   #     Enumerator.produce { scanner.scan(PATTERN) }.slice_after { scanner.eos? }.first
   #     # => ["7", "+", "38", "/", "6"]
   #
+  # The optional `size` keyword argument specifies the size of the enumerator,
+  # which can be retrieved by Enumerator#size.  It can be an integer,
+  # `Float::INFINITY`, a callable object (such as a lambda), or `nil` to indicate
+  # unknown size.  When not specified, the size defaults to `Float::INFINITY`.
+  #
+  #     # Infinite enumerator
+  #     enum = Enumerator.produce(1, size: Float::INFINITY, &:succ)
+  #     enum.size  # => Float::INFINITY
+  #
+  #     # Finite enumerator with known/computable size
+  #     abs_dir = File.expand_path("./baz") # => "/foo/bar/baz"
+  #     traverser = Enumerator.produce(abs_dir, size: -> { abs_dir.count("/") + 1 }) {
+  #       raise StopIteration if it == "/"
+  #       File.dirname(it)
+  #     }
+  #     traverser.size  # => 4
+  #
+  #     # Finite enumerator with unknown size
+  #     calendar = Enumerator.produce(Date.today, size: nil) {
+  #       it.monday? ? raise(StopIteration) : it + 1
+  #     }
+  #     calendar.size  # => nil
+  #
   def self.produce: [T] () { (T? prev) -> T } -> Enumerator[T, bot]
                   | [T] (T initial) { (T prev) -> T } -> Enumerator[T, bot]
 
@@ -446,6 +469,25 @@ class Enumerator[unchecked out Elem, out Return = void] < Object
   #     loop.size # => Float::INFINITY
   #     (1..100).drop_while.size # => nil
   #
+  # Note that enumerator size might be inaccurate, and should be rather treated as
+  # a hint. For example, there is no check that the size provided to ::new is
+  # accurate:
+  #
+  #     e = Enumerator.new(5) { |y| 2.times { y << it} }
+  #     e.size # => 5
+  #     e.to_a.size # => 2
+  #
+  # Another example is an enumerator created by ::produce without a `size`
+  # argument. Such enumerators return `Infinity` for size, but this is inaccurate
+  # if the passed block raises StopIteration:
+  #
+  #     e = Enumerator.produce(1) { it + 1 }
+  #     e.size # => Infinity
+  #
+  #     e = Enumerator.produce(1) { it > 3 ? raise(StopIteration) : it + 1 }
+  #     e.size # => Infinity
+  #     e.to_a.size # => 4
+  #
   def size: () -> (Integer | Float)?
 
   # <!--

data/core/errno.rbs

@@ -38,6 +38,14 @@
 #     Errno::ENOENT::Errno      # => 2
 #     Errno::ENOTCAPABLE::Errno # => 0
 #
+# Each class in Errno can be created with optional messages:
+#
+#     Errno::EPIPE.new                  # => #<Errno::EPIPE: Broken pipe>
+#     Errno::EPIPE.new("foo")           # => #<Errno::EPIPE: Broken pipe - foo>
+#     Errno::EPIPE.new("foo", "here")   # => #<Errno::EPIPE: Broken pipe @ here - foo>
+#
+# See SystemCallError.new.
+#
 module Errno
   class NOERROR < SystemCallError
     Errno: 0

data/core/errors.rbs

@@ -302,9 +302,15 @@ class NameError[T] < StandardError
   def receiver: () -> T?
 end
 
+# <!-- rdoc-file=error.c -->
+# Raised when matching pattern not found.
+#
 class NoMatchingPatternError < StandardError
 end
 
+# <!-- rdoc-file=error.c -->
+# Raised when matching key not found.
+#
 class NoMatchingPatternKeyError[M, K] < NoMatchingPatternError
   # <!--
   #   rdoc-file=error.c
@@ -588,13 +594,34 @@ end
 class SystemCallError < StandardError
   # <!--
   #   rdoc-file=error.c
-  #   - SystemCallError.new(msg, errno)  -> system_call_error_subclass
+  #   - SystemCallError.new(msg, errno = nil, func = nil)  -> system_call_error_subclass
   # -->
   # If *errno* corresponds to a known system error code, constructs the
   # appropriate Errno class for that error, otherwise constructs a generic
   # SystemCallError object. The error number is subsequently available via the
   # #errno method.
   #
+  # If only numeric object is given, it is treated as an Integer *errno*, and
+  # *msg* is omitted, otherwise the first argument *msg* is used as the additional
+  # error message.
+  #
+  #     SystemCallError.new(Errno::EPIPE::Errno)
+  #     #=> #<Errno::EPIPE: Broken pipe>
+  #
+  #     SystemCallError.new("foo")
+  #     #=> #<SystemCallError: unknown error - foo>
+  #
+  #     SystemCallError.new("foo", Errno::EPIPE::Errno)
+  #     #=> #<Errno::EPIPE: Broken pipe - foo>
+  #
+  # If *func* is not `nil`, it is appended to the message with "` @ `".
+  #
+  #     SystemCallError.new("foo", Errno::EPIPE::Errno, "here")
+  #     #=> #<Errno::EPIPE: Broken pipe @ here - foo>
+  #
+  # A subclass of SystemCallError can also be instantiated via the `new` method of
+  # the subclass.  See Errno.
+  #
   def initialize: (string msg, Integer errno) -> void
 
   # <!--

data/core/exception.rbs

@@ -118,7 +118,7 @@ class Exception
   #       # String
   #     end
   #
-  # The value returned by this method migth be adjusted when raising (see
+  # The value returned by this method might be adjusted when raising (see
   # Kernel#raise), or during intermediate handling by #set_backtrace.
   #
   # See also #backtrace_locations that provide the same value, as structured
@@ -447,7 +447,7 @@ class Exception
   #     *   If the value of keyword `order` is `:top` (the default), lists the
   #         error message and the innermost backtrace entry first.
   #     *   If the value of keyword `order` is `:bottom`, lists the error message
-  #         the the innermost entry last.
+  #         the innermost entry last.
   #
   # Example:
   #

data/core/fiber.rbs

@@ -58,7 +58,7 @@
 # ## Non-blocking Fibers
 #
 # The concept of *non-blocking fiber* was introduced in Ruby 3.0. A non-blocking
-# fiber, when reaching a operation that would normally block the fiber (like
+# fiber, when reaching an operation that would normally block the fiber (like
 # `sleep`, or wait for another process or I/O) will yield control to other
 # fibers and allow the *scheduler* to handle blocking and waking up (resuming)
 # this fiber when it can proceed.
@@ -82,7 +82,8 @@ class Fiber < Object
   # -->
   # Returns the value of the fiber storage variable identified by `key`.
   #
-  # The `key` must be a symbol, and the value is set by Fiber#[]= or Fiber#store.
+  # The `key` must be a symbol, and the value is set by Fiber#[]= or
+  # Fiber#storage.
   #
   # See also Fiber::[]=.
   #
@@ -392,30 +393,38 @@ class Fiber < Object
 
   # <!--
   #   rdoc-file=cont.c
-  #   - fiber.raise                                 -> obj
-  #   - fiber.raise(string)                         -> obj
-  #   - fiber.raise(exception [, string [, array]]) -> obj
+  #   - raise(exception, message = exception.to_s, backtrace = nil, cause: $!)
+  #   - raise(message = nil, cause: $!)
   # -->
   # Raises an exception in the fiber at the point at which the last `Fiber.yield`
-  # was called. If the fiber has not been started or has already run to
-  # completion, raises `FiberError`. If the fiber is yielding, it is resumed. If
-  # it is transferring, it is transferred into. But if it is resuming, raises
-  # `FiberError`.
-  #
-  # With no arguments, raises a `RuntimeError`. With a single `String` argument,
-  # raises a `RuntimeError` with the string as a message.  Otherwise, the first
-  # parameter should be the name of an `Exception` class (or an object that
-  # returns an `Exception` object when sent an `exception` message). The optional
-  # second parameter sets the message associated with the exception, and the third
-  # parameter is an array of callback information. Exceptions are caught by the
-  # `rescue` clause of `begin...end` blocks.
+  # was called.
+  #
+  #     f = Fiber.new {
+  #       puts "Before the yield"
+  #       Fiber.yield 1 # -- exception will be raised here
+  #       puts "After the yield"
+  #     }
+  #
+  #     p f.resume
+  #     f.raise "Gotcha"
+  #
+  # Output
+  #
+  #     Before the first yield
+  #     1
+  #     t.rb:8:in 'Fiber.yield': Gotcha (RuntimeError)
+  #       from t.rb:8:in 'block in <main>'
+  #
+  # If the fiber has not been started or has already run to completion, raises
+  # `FiberError`. If the fiber is yielding, it is resumed. If it is transferring,
+  # it is transferred into. But if it is resuming, raises `FiberError`.
   #
   # Raises `FiberError` if called on a Fiber belonging to another `Thread`.
   #
-  # See Kernel#raise for more information.
+  # See Kernel#raise for more information on arguments.
   #
-  def raise: (?string msg) -> untyped
-           | (_Exception, ?string msg, ?Array[string] | Array[Thread::Backtrace::Location] | nil backtrace) -> untyped
+  def raise: (?string msg, ?cause: Exception?) -> untyped
+           | (_Exception, ?string msg, ?Array[string] | Array[Thread::Backtrace::Location] | nil backtrace, ?cause: Exception?) -> untyped
 
   # <!--
   #   rdoc-file=cont.c

data/core/file.rbs

@@ -1414,7 +1414,7 @@ class File < IO
   #   rdoc-file=file.c
   #   - File.owned?(file_name)   -> true or false
   # -->
-  # Returns `true` if the named file exists and the effective used id of the
+  # Returns `true` if the named file exists and the effective user id of the
   # calling process is the owner of the file.
   #
   # *file_name* can be an IO object.
@@ -1427,8 +1427,25 @@ class File < IO
   # -->
   # Returns the string representation of the path
   #
-  #     File.path(File::NULL)           #=> "/dev/null"
-  #     File.path(Pathname.new("/tmp")) #=> "/tmp"
+  #        File.path(File::NULL)           #=> "/dev/null"
+  #        File.path(Pathname.new("/tmp")) #=> "/tmp"
+  #
+  # If `path` is not a String:
+  #
+  # 1.  If it has the `to_path` method, that method will be called to coerce to a
+  #     String.
+  #
+  # 2.  Otherwise, or if the coerced result is not a String too, the standard
+  #     coersion using `to_str` method will take place on that object. (See also
+  #     String.try_convert)
+  #
+  # The coerced string must satisfy the following conditions:
+  #
+  # 1.  It must be in an ASCII-compatible encoding; otherwise, an
+  #     Encoding::CompatibilityError is raised.
+  #
+  # 2.  It must not contain the NUL character (`\0`); otherwise, an ArgumentError
+  #     is raised.
   #
   def self.path: (string | _ToPath path) -> String
 
@@ -1822,12 +1839,12 @@ class File < IO
   # Returns `false` if `File::LOCK_NB` is specified and the operation would have
   # blocked;
   # otherwise returns `0`.
-  #    Constant    |    Lock    |                                                    Effect
-  # ---------------|------------|--------------------------------------------------------------------------------------------------------------
-  # +File::LOCK_EX+| Exclusive  |                      Only one process may hold an exclusive lock for +self+ at a time.
-  # +File::LOCK_NB+|Non-blocking|No blocking; may be combined with +File::LOCK_SH+ or +File::LOCK_EX+ using the bitwise OR operator <tt>|</tt>.
-  # +File::LOCK_SH+|   Shared   |                 Multiple processes may each hold a shared lock for +self+ at the same time.
-  # +File::LOCK_UN+|   Unlock   |                                Remove an existing lock held by this process.
+  #    Constant    |    Lock    |                                                Effect
+  # ---------------|------------|-------------------------------------------------------------------------------------------------------
+  # `File::LOCK_EX`| Exclusive  |                   Only one process may hold an exclusive lock for `self` at a time.
+  # `File::LOCK_NB`|Non-blocking|No blocking; may be combined with `File::LOCK_SH` or `File::LOCK_EX` using the bitwise OR operator `|`.
+  # `File::LOCK_SH`|   Shared   |              Multiple processes may each hold a shared lock for `self` at the same time.
+  # `File::LOCK_UN`|   Unlock   |                             Remove an existing lock held by this process.
   # Example:
   #     # Update a counter using an exclusive lock.
   # # Don't use File::WRONLY because it truncates the file.
@@ -2429,10 +2446,8 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - new(p1)
+  #   - File::Stat.new(file_name)  -> stat
   # -->
-  # File::Stat.new(file_name)  -> stat
-  #
   # Create a File::Stat object for the given file name (raising an exception if
   # the file doesn't exist).
   #
@@ -2440,16 +2455,31 @@ class File::Stat < Object
 
   # <!--
   #   rdoc-file=file.c
-  #   - stat <=> other_stat    -> -1, 0, 1, nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
-  # Compares File::Stat objects by comparing their respective modification times.
+  # Compares `self` and `other`, by comparing their modification times; that is,
+  # by comparing `self.mtime` and `other.mtime`.
+  #
+  # Returns:
   #
-  # `nil` is returned if `other_stat` is not a File::Stat object
+  # *   `-1`, if `self.mtime` is earlier.
+  # *   `0`, if the two values are equal.
+  # *   `1`, if `self.mtime` is later.
+  # *   `nil`, if `other` is not a File::Stat object.
+  #
+  # Examples:
   #
-  #     f1 = File.new("f1", "w")
-  #     sleep 1
-  #     f2 = File.new("f2", "w")
-  #     f1.stat <=> f2.stat   #=> -1
+  #     stat0 = File.stat('README.md')
+  #     stat1 = File.stat('NEWS.md')
+  #     stat0.mtime         # => 2025-12-20 15:33:05.6972341 -0600
+  #     stat1.mtime         # => 2025-12-20 16:02:08.2672945 -0600
+  #     stat0 <=> stat1     # => -1
+  #     stat0 <=> stat0.dup # => 0
+  #     stat1 <=> stat0     # => 1
+  #     stat0 <=> :foo      # => nil
+  #
+  # Class File::Stat includes module Comparable, each of whose methods uses
+  # File::Stat#<=> for comparison.
   #
   def <=>: (File::Stat other) -> Integer
          | (untyped) -> nil

data/core/file_test.rbs

@@ -145,7 +145,7 @@ module FileTest
   #   rdoc-file=file.c
   #   - File.owned?(file_name)   -> true or false
   # -->
-  # Returns `true` if the named file exists and the effective used id of the
+  # Returns `true` if the named file exists and the effective user id of the
   # calling process is the owner of the file.
   #
   # *file_name* can be an IO object.