rbs 4.0.0.dev.4 → 4.0.0.dev.5

data/core/dir.rbs

@@ -171,7 +171,7 @@ class Dir
   # system's encoding is used:
   #
   #     Dir.new('.').read.encoding                       # => #<Encoding:UTF-8>
-  #     Dir.new('.', encoding: 'US-ASCII').read.encoding # => #<Encoding:US-ASCII>
+  #     Dir.new('.', encoding: Encoding::US_ASCI).read.encoding # => #<Encoding:US-ASCII>
   #
   def initialize: (path dir, ?encoding: encoding?) -> void
 
@@ -477,8 +477,8 @@ class Dir
 
   # <!--
   #   rdoc-file=dir.rb
-  #   - Dir.glob(*patterns, flags: 0, base: nil, sort: true) -> array
-  #   - Dir.glob(*patterns, flags: 0, base: nil, sort: true) {|entry_name| ... } -> nil
+  #   - Dir.glob(patterns, flags: 0, base: nil, sort: true) -> array
+  #   - Dir.glob(patterns, flags: 0, base: nil, sort: true) {|entry_name| ... } -> nil
   # -->
   # Forms an array *entry_names* of the entry names selected by the arguments.
   #
@@ -704,7 +704,7 @@ class Dir
   # system's encoding is used:
   #
   #     Dir.open('.').read.encoding                       # => #<Encoding:UTF-8>
-  #     Dir.open('.', encoding: 'US-ASCII').read.encoding # => #<Encoding:US-ASCII>
+  #     Dir.open('.', encoding: Encoding::US_ASCII).read.encoding # => #<Encoding:US-ASCII>
   #
   def self.open: (path dirname, ?encoding: encoding?) -> instance
                | [U] (path dirname, ?encoding: encoding?) { (instance) -> U } -> U

data/core/encoding.rbs

@@ -281,7 +281,7 @@ class Encoding
   def inspect: () -> String
 
   # <!-- rdoc-file=encoding.c -->
-  # Returns the name of the encoding.
+  # The name of the encoding.
   #
   #     Encoding::UTF_8.name      #=> "UTF-8"
   #
@@ -297,12 +297,8 @@ class Encoding
   #
   def names: () -> Array[String]
 
-  # <!--
-  #   rdoc-file=encoding.c
-  #   - enc.name -> string
-  #   - enc.to_s -> string
-  # -->
-  # Returns the name of the encoding.
+  # <!-- rdoc-file=encoding.c -->
+  # The name of the encoding.
   #
   #     Encoding::UTF_8.name      #=> "UTF-8"
   #
@@ -785,7 +781,7 @@ class Encoding::Converter < Object
   #   - ec == other        -> true or false
   # -->
   #
-  def ==: (self) -> bool
+  def ==: (untyped) -> bool
 
   # <!--
   #   rdoc-file=transcode.c
@@ -923,8 +919,9 @@ class Encoding::Converter < Object
   #     p ec.primitive_convert(src, dst, nil, 1)             #=> :destination_buffer_full
   #     p ec.last_error      #=> nil
   #
-  def last_error: () -> Encoding::InvalidByteSequenceError?
-                | () -> Encoding::UndefinedConversionError?
+  def last_error: () -> ( Encoding::InvalidByteSequenceError
+                        | Encoding::UndefinedConversionError
+                        | nil )
 
   # <!--
   #   rdoc-file=transcode.c

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]
   %a{private}
   interface _Pattern
@@ -445,6 +521,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]]
 
@@ -2049,7 +2136,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/arithmetic_sequence.rbs

@@ -0,0 +1,70 @@
+# <!-- rdoc-file=enumerator.c -->
+# Enumerator::ArithmeticSequence is a subclass of Enumerator, that is a
+# representation of sequences of numbers with common difference. Instances of
+# this class can be generated by the Range#step and Numeric#step methods.
+#
+# The class can be used for slicing Array (see Array#slice) or custom
+# collections.
+#
+class Enumerator::ArithmeticSequence < Enumerator[Numeric]
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - aseq.begin -> num or nil
+  # -->
+  # Returns the number that defines the first element of this arithmetic sequence.
+  #
+  def begin: () -> Numeric?
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - aseq.end -> num or nil
+  # -->
+  # Returns the number that defines the end of this arithmetic sequence.
+  #
+  def end: () -> Numeric?
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - aseq.each {|i| block } -> aseq
+  #   - aseq.each              -> aseq
+  # -->
+  #
+  def each: () ?{ (Numeric) -> void } -> self
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - aseq.exclude_end? -> true or false
+  # -->
+  # Returns `true` if this arithmetic sequence excludes its end value.
+  #
+  def exclude_end?: () -> bool
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - aseq.last    -> num or nil
+  #   - aseq.last(n) -> an_array
+  # -->
+  # Returns the last number in this arithmetic sequence, or an array of the last
+  # `n` elements.
+  #
+  def last: () -> Numeric?
+          | (Integer n) -> Array[Numeric]
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - aseq.size -> num or nil
+  # -->
+  # Returns the number of elements in this arithmetic sequence if it is a finite
+  # sequence.  Otherwise, returns `nil`.
+  #
+  def size: () -> (Integer | Float)
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - aseq.step -> num
+  # -->
+  # Returns the number that defines the common difference between two adjacent
+  # elements in this arithmetic sequence.
+  #
+  def step: () -> Numeric
+end

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,8 +469,39 @@ 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)?
 
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - e + enum -> enumerator
+  # -->
+  # Returns an enumerator object generated from this enumerator and a given
+  # enumerable.
+  #
+  #     e = (1..3).each + [4, 5]
+  #     e.to_a #=> [1, 2, 3, 4, 5]
+  #
+  def +: [Elem2] (::_Each[Elem2]) -> ::Enumerator::Chain[Elem | Elem2]
+
   # <!--
   #   rdoc-file=enumerator.c
   #   - e.with_index(offset = 0) {|(*args), idx| ... }
@@ -578,6 +632,14 @@ class Enumerator::Lazy[out Elem, out Return = void] < Enumerator[Elem, Return]
   # Like Enumerable#compact, but chains operation to be lazy-evaluated.
   #
   def compact: () -> Enumerator::Lazy[Elem, Return]
+
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - lzy.eager -> enum
+  # -->
+  # Returns a non-lazy Enumerator converted from the lazy enumerator.
+  #
+  def eager: () -> ::Enumerator[Elem, Return]
 end
 
 # <!-- rdoc-file=enumerator.c -->

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::[]=.
   #
@@ -101,6 +102,17 @@ class Fiber < Object
   #
   def self.[]=: [A] (Symbol, A) -> A
 
+  # <!--
+  #   rdoc-file=cont.c
+  #   - Fiber.blocking{|fiber| ...} -> result
+  # -->
+  # Forces the fiber to be blocking for the duration of the block. Returns the
+  # result of the block.
+  #
+  # See the "Non-blocking fibers" section in class docs for details.
+  #
+  def self.blocking: [T] () { (Fiber) -> T } -> T
+
   # <!--
   #   rdoc-file=cont.c
   #   - Fiber.blocking? -> false or 1
@@ -392,30 +404,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