rbs 3.7.0 → 3.8.0.pre.1

data/core/enumerator.rbs

@@ -6,7 +6,6 @@
 # *   Object#enum_for
 # *   Enumerator.new
 #
-#
 # Most methods have two forms: a block form where the contents are evaluated for
 # each item in the enumeration, and a non-block form which returns a new
 # Enumerator wrapping the iteration.
@@ -75,7 +74,6 @@
 #     Enumerator Fiber, you need to use an extra indirection (e.g., use some
 #     object in the Fiber storage variable and mutate some ivar of it).
 #
-#
 # Concretely:
 #
 #     Thread.current[:fiber_local] = 1

data/core/env.rbs

@@ -1,5 +1,5 @@
 # <!-- rdoc-file=hash.c -->
-# ENV is a Hash-like accessor for environment variables.
+# `ENV` is a Hash-like accessor for environment variables.
 #
 # See ENV (the class) for more details.
 #

data/core/errno.rbs

@@ -1,25 +1,42 @@
 # <!-- rdoc-file=error.c -->
-# Ruby exception objects are subclasses of Exception.  However, operating
-# systems typically report errors using plain integers. Module Errno is created
-# dynamically to map these operating system errors to Ruby classes, with each
-# error number generating its own subclass of SystemCallError.  As the subclass
-# is created in module Errno, its name will start `Errno::`.
+# When an operating system encounters an error, it typically reports the error
+# as an integer error code:
 #
-# The names of the `Errno::` classes depend on the environment in which Ruby
-# runs. On a typical Unix or Windows platform, there are Errno classes such as
-# Errno::EACCES, Errno::EAGAIN, Errno::EINTR, and so on.
+#     $ ls nosuch.txt
+#     ls: cannot access 'nosuch.txt': No such file or directory
+#     $ echo $? # Code for last error.
+#     2
 #
-# The integer operating system error number corresponding to a particular error
-# is available as the class constant `Errno::`*error*`::Errno`.
+# When the Ruby interpreter interacts with the operating system and receives
+# such an error code (e.g., `2`), it maps the code to a particular Ruby
+# exception class (e.g., `Errno::ENOENT`):
 #
-#     Errno::EACCES::Errno   #=> 13
-#     Errno::EAGAIN::Errno   #=> 11
-#     Errno::EINTR::Errno    #=> 4
+#     File.open('nosuch.txt')
+#     # => No such file or directory @ rb_sysopen - nosuch.txt (Errno::ENOENT)
 #
-# The full list of operating system errors on your particular platform are
-# available as the constants of Errno.
+# Each such class is:
 #
-#     Errno.constants   #=> :E2BIG, :EACCES, :EADDRINUSE, :EADDRNOTAVAIL, ...
+# *   A nested class in this module, `Errno`.
+# *   A subclass of class SystemCallError.
+# *   Associated with an error code.
+#
+# Thus:
+#
+#     Errno::ENOENT.superclass # => SystemCallError
+#     Errno::ENOENT::Errno     # => 2
+#
+# The names of nested classes are returned by method `Errno.constants`:
+#
+#     Errno.constants.size         # => 158
+#     Errno.constants.sort.take(5) # => [:E2BIG, :EACCES, :EADDRINUSE, :EADDRNOTAVAIL, :EADV]
+#
+# As seen above, the error code associated with each class is available as the
+# value of a constant; the value for a particular class may vary among operating
+# systems. If the class is not needed for the particular operating system, the
+# value is zero:
+#
+#     Errno::ENOENT::Errno      # => 2
+#     Errno::ENOTCAPABLE::Errno # => 0
 #
 module Errno
   class NOERROR < SystemCallError

data/core/errors.rbs

@@ -190,7 +190,7 @@ end
 #
 class LoadError < ScriptError
   # <!-- rdoc-file=error.c -->
-  # the path failed to load
+  # the path that failed to load
   #
   def path: () -> String?
 end
@@ -564,7 +564,7 @@ class SyntaxError < ScriptError
   def initialize: (?string msg) -> void
 
   # <!-- rdoc-file=error.c -->
-  # the path failed to parse
+  # the path that failed to parse
   #
   def path: () -> String?
 end

data/core/exception.rbs

@@ -1,310 +1,376 @@
 # <!-- rdoc-file=error.c -->
-# Class Exception and its subclasses are used to communicate between
-# Kernel#raise and `rescue` statements in `begin ... end` blocks.
+# Class `Exception` and its subclasses are used to indicate that an error or
+# other problem has occurred, and may need to be handled. See
+# [Exceptions](rdoc-ref:exceptions.md).
 #
-# An Exception object carries information about an exception:
-# *   Its type (the exception's class).
-# *   An optional descriptive message.
-# *   Optional backtrace information.
+# An `Exception` object carries certain information:
 #
+# *   The type (the exception's class), commonly StandardError, RuntimeError, or
+#     a subclass of one or the other; see [Built-In Exception Class
+#     Hierarchy](rdoc-ref:Exception@Built-In+Exception+Class+Hierarchy).
+# *   An optional descriptive message; see methods ::new, #message.
+# *   Optional backtrace information; see methods #backtrace,
+#     #backtrace_locations, #set_backtrace.
+# *   An optional cause; see method #cause.
 #
-# Some built-in subclasses of Exception have additional methods: e.g.,
-# NameError#name.
+# ## Built-In Exception Class Hierarchy
 #
-# ## Defaults
-#
-# Two Ruby statements have default exception classes:
-# *   `raise`: defaults to RuntimeError.
-# *   `rescue`: defaults to StandardError.
-#
-#
-# ## Global Variables
-#
-# When an exception has been raised but not yet handled (in `rescue`, `ensure`,
-# `at_exit` and `END` blocks), two global variables are set:
-# *   `$!` contains the current exception.
-# *   `$@` contains its backtrace.
-#
-#
-# ## Custom Exceptions
-#
-# To provide additional or alternate information, a program may create custom
-# exception classes that derive from the built-in exception classes.
-#
-# A good practice is for a library to create a single "generic" exception class
-# (typically a subclass of StandardError or RuntimeError) and have its other
-# exception classes derive from that class. This allows the user to rescue the
-# generic exception, thus catching all exceptions the library may raise even if
-# future versions of the library add new exception subclasses.
-#
-# For example:
-#
-#     class MyLibrary
-#       class Error < ::StandardError
-#       end
-#
-#       class WidgetError < Error
-#       end
-#
-#       class FrobError < Error
-#       end
-#
-#     end
-#
-# To handle both MyLibrary::WidgetError and MyLibrary::FrobError the library
-# user can rescue MyLibrary::Error.
-#
-# ## Built-In Exception Classes
-#
-# The built-in subclasses of Exception are:
+# The hierarchy of built-in subclasses of class `Exception`:
 #
 # *   NoMemoryError
 # *   ScriptError
-#     *   LoadError
+#     *   [LoadError](https://docs.ruby-lang.org/en/master/LoadError.html)
 #     *   NotImplementedError
 #     *   SyntaxError
-#
 # *   SecurityError
 # *   SignalException
 #     *   Interrupt
-#
 # *   StandardError
 #     *   ArgumentError
 #         *   UncaughtThrowError
-#
 #     *   EncodingError
 #     *   FiberError
 #     *   IOError
 #         *   EOFError
-#
 #     *   IndexError
 #         *   KeyError
 #         *   StopIteration
 #             *   ClosedQueueError
-#
-#
 #     *   LocalJumpError
 #     *   NameError
 #         *   NoMethodError
-#
 #     *   RangeError
 #         *   FloatDomainError
-#
 #     *   RegexpError
 #     *   RuntimeError
 #         *   FrozenError
-#
 #     *   SystemCallError
-#         *   Errno::*
-#
+#         *   Errno (and its subclasses, representing system errors)
 #     *   ThreadError
 #     *   TypeError
 #     *   ZeroDivisionError
-#
 # *   SystemExit
 # *   SystemStackError
-# *   fatal
+# *   [fatal](https://docs.ruby-lang.org/en/master/fatal.html)
 #
 class Exception
   # <!--
   #   rdoc-file=error.c
-  #   - Exception.to_tty?   ->  true or false
+  #   - Exception.to_tty? -> true or false
   # -->
-  # Returns `true` if exception messages will be sent to a tty.
+  # Returns `true` if exception messages will be sent to a terminal device.
   #
   def self.to_tty?: () -> bool
 
   # <!--
   #   rdoc-file=error.c
-  #   - exc.exception([string])  ->  an_exception or exc
+  #   - exception(message = nil) -> self or new_exception
   # -->
-  # With no argument, or if the argument is the same as the receiver, return the
-  # receiver. Otherwise, create a new exception object of the same class as the
-  # receiver, but with a message equal to `string.to_str`.
+  # Returns an exception object of the same class as `self`; useful for creating a
+  # similar exception, but with a different message.
+  #
+  # With `message` `nil`, returns `self`:
+  #
+  #     x0 = StandardError.new('Boom') # => #<StandardError: Boom>
+  #     x1 = x0.exception              # => #<StandardError: Boom>
+  #     x0.__id__ == x1.__id__         # => true
+  #
+  # With [string-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@String-Convertible+Objects)
+  # `message` (even the same as the original message), returns a new exception
+  # object whose class is the same as `self`, and whose message is the given
+  # `message`:
+  #
+  #     x1 = x0.exception('Boom') # => #<StandardError: Boom>
+  #     x0..equal?(x1)            # => false
   #
   def self.exception: (?string | _ToS msg) -> instance
 
   # <!--
   #   rdoc-file=error.c
-  #   - exc == obj   -> true or false
+  #   - self == object -> true or false
   # -->
-  # Equality---If *obj* is not an Exception, returns `false`. Otherwise, returns
-  # `true` if *exc* and *obj* share same class, messages, and backtrace.
+  # Returns whether `object` is the same class as `self` and its #message and
+  # #backtrace are equal to those of `self`.
   #
   def ==: (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.backtrace    -> array or nil
+  #   - backtrace -> array or nil
   # -->
-  # Returns any backtrace associated with the exception. The backtrace is an array
-  # of strings, each containing either ``filename:lineNo: in `method''' or
-  # ``filename:lineNo.''
+  # Returns a backtrace value for `self`; the returned value depends on the form
+  # of the stored backtrace value:
   #
-  #     def a
-  #       raise "boom"
-  #     end
+  # *   Array of Thread::Backtrace::Location objects: returns the array of strings
+  #     given by `Exception#backtrace_locations.map {|loc| loc.to_s }`. This is
+  #     the normal case, where the backtrace value was stored by Kernel#raise.
+  # *   Array of strings: returns that array. This is the unusual case, where the
+  #     backtrace value was explicitly stored as an array of strings.
+  # *   `nil`: returns `nil`.
   #
-  #     def b
-  #       a()
-  #     end
+  # Example:
   #
   #     begin
-  #       b()
-  #     rescue => detail
-  #       print detail.backtrace.join("\n")
+  #       1 / 0
+  #     rescue => x
+  #       x.backtrace.take(2)
   #     end
+  #     # => ["(irb):132:in `/'", "(irb):132:in `<top (required)>'"]
   #
-  # *produces:*
-  #
-  #     prog.rb:2:in `a'
-  #     prog.rb:6:in `b'
-  #     prog.rb:10
-  #
-  # In the case no backtrace has been set, `nil` is returned
-  #
-  #     ex = StandardError.new
-  #     ex.backtrace
-  #     #=> nil
+  # see [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
   def backtrace: () -> Array[String]?
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.backtrace_locations    -> array or nil
+  #   - backtrace_locations -> array or nil
   # -->
-  # Returns any backtrace associated with the exception. This method is similar to
-  # Exception#backtrace, but the backtrace is an array of
-  # Thread::Backtrace::Location.
+  # Returns a backtrace value for `self`; the returned value depends on the form
+  # of the stored backtrace value:
+  #
+  # *   Array of Thread::Backtrace::Location objects: returns that array.
+  # *   Array of strings or `nil`: returns `nil`.
   #
-  # This method is not affected by Exception#set_backtrace().
+  # Example:
+  #
+  #     begin
+  #       1 / 0
+  #     rescue => x
+  #       x.backtrace_locations.take(2)
+  #     end
+  #     # => ["(irb):150:in `/'", "(irb):150:in `<top (required)>'"]
+  #
+  # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
   def backtrace_locations: () -> Array[Thread::Backtrace::Location]?
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.cause   -> an_exception or nil
+  #   - cause -> exception or nil
   # -->
-  # Returns the previous exception ($!) at the time this exception was raised.
-  # This is useful for wrapping exceptions and retaining the original exception
-  # information.
+  # Returns the previous value of global variable `$!`, which may be `nil` (see
+  # [Global Variables](rdoc-ref:exceptions.md@Global+Variables)):
+  #
+  #     begin
+  #       raise('Boom 0')
+  #     rescue => x0
+  #       puts "Exception: #{x0};  $!: #{$!};  cause: #{x0.cause.inspect}."
+  #       begin
+  #         raise('Boom 1')
+  #       rescue => x1
+  #         puts "Exception: #{x1};  $!: #{$!};  cause: #{x1.cause}."
+  #         begin
+  #           raise('Boom 2')
+  #         rescue => x2
+  #           puts "Exception: #{x2};  $!: #{$!};  cause: #{x2.cause}."
+  #         end
+  #       end
+  #     end
+  #
+  # Output:
+  #
+  #     Exception: Boom 0;  $!: Boom 0;  cause: nil.
+  #     Exception: Boom 1;  $!: Boom 1;  cause: Boom 0.
+  #     Exception: Boom 2;  $!: Boom 2;  cause: Boom 1.
   #
   def cause: () -> Exception?
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.detailed_message(highlight: bool, **opt)   ->  string
+  #   - detailed_message(highlight: false, **kwargs) -> string
   # -->
-  # Processes a string returned by #message.
+  # Returns the message string with enhancements:
+  #
+  # *   Includes the exception class name in the first line.
+  # *   If the value of keyword `highlight` is `true`, includes bolding and
+  #     underlining ANSI codes (see below) to enhance the appearance of the
+  #     message.
   #
-  # It may add the class name of the exception to the end of the first line. Also,
-  # when `highlight` keyword is true, it adds ANSI escape sequences to make the
-  # message bold.
+  # Examples:
   #
-  # If you override this method, it must be tolerant for unknown keyword
-  # arguments. All keyword arguments passed to #full_message are delegated to this
-  # method.
+  #     begin
+  #       1 / 0
+  #     rescue => x
+  #       p x.message
+  #       p x.detailed_message                  # Class name added.
+  #       p x.detailed_message(highlight: true) # Class name, bolding, and underlining added.
+  #     end
   #
-  # This method is overridden by did_you_mean and error_highlight to add their
-  # information.
+  # Output:
   #
-  # A user-defined exception class can also define their own `detailed_message`
-  # method to add supplemental information. When `highlight` is true, it can
-  # return a string containing escape sequences, but use widely-supported ones. It
-  # is recommended to limit the following codes:
+  #     "divided by 0"
+  #     "divided by 0 (ZeroDivisionError)"
+  #     "\e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m"
   #
-  # *   Reset (`\e[0m`)
-  # *   Bold (`\e[1m`)
-  # *   Underline (`\e[4m`)
-  # *   Foreground color except white and black
-  #     *   Red (`\e[31m`)
-  #     *   Green (`\e[32m`)
-  #     *   Yellow (`\e[33m`)
-  #     *   Blue (`\e[34m`)
-  #     *   Magenta (`\e[35m`)
-  #     *   Cyan (`\e[36m`)
+  # This method is overridden by some gems in the Ruby standard library to add
+  # information:
   #
+  # *   DidYouMean::Correctable#detailed_message.
+  # *   ErrorHighlight::CoreExt#detailed_message.
+  # *   SyntaxSuggest#detailed_message.
   #
+  # An overriding method must be tolerant of passed keyword arguments, which may
+  # include (but may not be limited to):
   #
-  # Use escape sequences carefully even if `highlight` is true. Do not use escape
-  # sequences to express essential information; the message should be readable
-  # even if all escape sequences are ignored.
+  # *   `:highlight`.
+  # *   `:did_you_mean`.
+  # *   `:error_highlight`.
+  # *   `:syntax_suggest`.
+  #
+  # An overriding method should also be careful with ANSI code enhancements; see
+  # [Messages](rdoc-ref:exceptions.md@Messages).
   #
   def detailed_message: (?highlight: bool?, **untyped ignored) -> String
 
   # <!--
   #   rdoc-file=error.c
-  #   - exc.exception([string])  ->  an_exception or exc
+  #   - exception(message = nil) -> self or new_exception
   # -->
-  # With no argument, or if the argument is the same as the receiver, return the
-  # receiver. Otherwise, create a new exception object of the same class as the
-  # receiver, but with a message equal to `string.to_str`.
+  # Returns an exception object of the same class as `self`; useful for creating a
+  # similar exception, but with a different message.
+  #
+  # With `message` `nil`, returns `self`:
+  #
+  #     x0 = StandardError.new('Boom') # => #<StandardError: Boom>
+  #     x1 = x0.exception              # => #<StandardError: Boom>
+  #     x0.__id__ == x1.__id__         # => true
+  #
+  # With [string-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@String-Convertible+Objects)
+  # `message` (even the same as the original message), returns a new exception
+  # object whose class is the same as `self`, and whose message is the given
+  # `message`:
+  #
+  #     x1 = x0.exception('Boom') # => #<StandardError: Boom>
+  #     x0..equal?(x1)            # => false
   #
   def exception: (?self) -> self
                | (string | _ToS message) -> instance
 
   # <!--
   #   rdoc-file=error.c
-  #   - Exception.new(msg = nil)        ->  exception
-  #   - Exception.exception(msg = nil)  ->  exception
+  #   - Exception.new(message = nil) -> exception
   # -->
-  # Construct a new Exception object, optionally passing in a message.
+  # Returns a new exception object.
+  #
+  # The given `message` should be a [string-convertible
+  # object](rdoc-ref:implicit_conversion.rdoc@String-Convertible+Objects); see
+  # method #message; if not given, the message is the class name of the new
+  # instance (which may be the name of a subclass):
+  #
+  # Examples:
+  #
+  #     Exception.new         # => #<Exception: Exception>
+  #     LoadError.new         # => #<LoadError: LoadError> # Subclass of Exception.
+  #     Exception.new('Boom') # => #<Exception: Boom>
   #
   def initialize: (?string | _ToS message) -> void
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.inspect   -> string
+  #   - inspect -> string
   # -->
-  # Return this exception's class name and message.
+  # Returns a string representation of `self`:
+  #
+  #     x = RuntimeError.new('Boom')
+  #     x.inspect # => "#<RuntimeError: Boom>"
+  #     x = RuntimeError.new
+  #     x.inspect # => "#<RuntimeError: RuntimeError>"
   #
   def inspect: () -> String
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.message   ->  string
+  #   - message -> string
   # -->
-  # Returns the result of invoking `exception.to_s`. Normally this returns the
-  # exception's message or name.
+  # Returns #to_s.
+  #
+  # See [Messages](rdoc-ref:exceptions.md@Messages).
   #
   def message: () -> String
 
   # <!--
   #   rdoc-file=error.c
-  #   - exc.set_backtrace(backtrace)   ->  array
+  #   - set_backtrace(value) -> value
   # -->
-  # Sets the backtrace information associated with `exc`. The `backtrace` must be
-  # an array of String objects or a single String in the format described in
-  # Exception#backtrace.
+  # Sets the backtrace value for `self`; returns the given +value:
+  #
+  #     x = RuntimeError.new('Boom')
+  #     x.set_backtrace(%w[foo bar baz]) # => ["foo", "bar", "baz"]
+  #     x.backtrace                      # => ["foo", "bar", "baz"]
   #
-  def set_backtrace: (String | Array[String] backtrace) -> Array[String]
+  # The given `value` must be an array of strings, a single string, or `nil`.
+  #
+  # Does not affect the value returned by #backtrace_locations.
+  #
+  # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
+  #
+  def set_backtrace: (String | Array[String]) -> Array[String]
+                   | (Array[Thread::Backtrace::Location]) -> Array[Thread::Backtrace::Location]
                    | (nil) -> nil
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.to_s   ->  string
+  #   - to_s -> string
   # -->
-  # Returns exception's message (or the name of the exception if no message is
-  # set).
+  # Returns a string representation of `self`:
+  #
+  #     x = RuntimeError.new('Boom')
+  #     x.to_s # => "Boom"
+  #     x = RuntimeError.new
+  #     x.to_s # => "RuntimeError"
   #
   def to_s: () -> String
 
   # <!--
   #   rdoc-file=error.c
-  #   - exception.full_message(highlight: bool, order: [:top or :bottom]) ->  string
+  #   - full_message(highlight: true, order: :top) -> string
   # -->
-  # Returns formatted string of *exception*. The returned string is formatted
-  # using the same format that Ruby uses when printing an uncaught exceptions to
-  # stderr.
-  #
-  # If *highlight* is `true` the default error handler will send the messages to a
-  # tty.
-  #
-  # *order* must be either of `:top` or `:bottom`, and places the error message
-  # and the innermost backtrace come at the top or the bottom.
-  #
-  # The default values of these options depend on `$stderr` and its `tty?` at the
-  # timing of a call.
+  # Returns an enhanced message string:
+  #
+  # *   Includes the exception class name.
+  # *   If the value of keyword `highlight` is true (not `nil` or `false`),
+  #     includes bolding ANSI codes (see below) to enhance the appearance of the
+  #     message.
+  # *   Includes the [backtrace](rdoc-ref:exceptions.md@Backtraces):
+  #
+  #     *   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.
+  #
+  # Example:
+  #
+  #     def baz
+  #       begin
+  #         1 / 0
+  #       rescue => x
+  #         pp x.message
+  #         pp x.full_message(highlight: false).split("\n")
+  #         pp x.full_message.split("\n")
+  #       end
+  #     end
+  #     def bar; baz; end
+  #     def foo; bar; end
+  #     foo
+  #
+  # Output:
+  #
+  #     "divided by 0"
+  #     ["t.rb:3:in `/': divided by 0 (ZeroDivisionError)",
+  #      "\tfrom t.rb:3:in `baz'",
+  #      "\tfrom t.rb:10:in `bar'",
+  #      "\tfrom t.rb:11:in `foo'",
+  #      "\tfrom t.rb:12:in `<main>'"]
+  #     ["t.rb:3:in `/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
+  #      "\tfrom t.rb:3:in `baz'",
+  #      "\tfrom t.rb:10:in `bar'",
+  #      "\tfrom t.rb:11:in `foo'",
+  #      "\tfrom t.rb:12:in `<main>'"]
+  #
+  # An overriding method should be careful with ANSI code enhancements; see
+  # [Messages](rdoc-ref:exceptions.md@Messages).
   #
   def full_message: (?highlight: bool?, ?order: (:top | :bottom | string)?) -> String
 end

data/core/fiber.rbs

@@ -412,8 +412,10 @@ class Fiber < Object
   #
   # Raises `FiberError` if called on a Fiber belonging to another `Thread`.
   #
+  # See Kernel#raise for more information.
+  #
   def raise: (?string msg) -> untyped
-           | (_Exception, ?string msg, ?Array[string] backtrace) -> untyped
+           | (_Exception, ?string msg, ?Array[string] | Array[Thread::Backtrace::Location] | nil backtrace) -> untyped
 
   # <!--
   #   rdoc-file=cont.c
@@ -493,7 +495,6 @@ class Fiber < Object
   #     transferred back, and if it had yielded, it only can be resumed back.
   #     After that, it again can transfer or yield.
   #
-  #
   # If those rules are broken FiberError is raised.
   #
   # For an individual Fiber design, yield/resume is easier to use (the Fiber just