rbs-relaxed 3.9.0.1

data/core/exception.rbs

@@ -0,0 +1,485 @@
+# <!-- rdoc-file=error.c -->
+# 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 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.
+#
+# ## Built-In Exception Class Hierarchy
+#
+# The hierarchy of built-in subclasses of class `Exception`:
+#
+# *   NoMemoryError
+# *   ScriptError
+#     *   LoadError
+#     *   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 (and its subclasses, representing system errors)
+#     *   ThreadError
+#     *   TypeError
+#     *   ZeroDivisionError
+# *   SystemExit
+# *   SystemStackError
+# *   [fatal](rdoc-ref:fatal)
+#
+class Exception
+  # <!--
+  #   rdoc-file=error.c
+  #   - Exception.to_tty? -> true or false
+  # -->
+  # Returns `true` if exception messages will be sent to a terminal device.
+  #
+  def self.to_tty?: () -> bool
+
+  # <!--
+  #   rdoc-file=error.c
+  #   - exception(message = nil) -> self or new_exception
+  # -->
+  # 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
+  #   - self == object -> true or false
+  # -->
+  # 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
+  #   - backtrace -> array or nil
+  # -->
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of strings.
+  #
+  # Example (assuming the code is stored in the file named `t.rb`):
+  #
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
+  #
+  #     begin
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace.first
+  #       p loc.class
+  #       # String
+  #     end
+  #
+  # The value returned by this method migth 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
+  # objects. (Note though that two values might not be consistent with each other
+  # when backtraces are manually adjusted.)
+  #
+  # see [Backtraces](rdoc-ref:exceptions.md@Backtraces).
+  #
+  def backtrace: () -> Array[String]?
+
+  # <!--
+  #   rdoc-file=error.c
+  #   - backtrace_locations -> array or nil
+  # -->
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of Thread::Backtrace::Location instances.
+  #
+  # Example (assuming the code is stored in the file named `t.rb`):
+  #
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
+  #
+  #     begin
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace_locations
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace_locations.first
+  #       p loc.class
+  #       # Thread::Backtrace::Location
+  #       p loc.path
+  #       # "t.rb"
+  #       p loc.lineno
+  #       # 2
+  #       p loc.label
+  #       # "Integer#/"
+  #     end
+  #
+  # The value returned by this method might be adjusted when raising (see
+  # Kernel#raise), or during intermediate handling by #set_backtrace.
+  #
+  # See also #backtrace that provide the same value as an array of strings. (Note
+  # though that two values might not be consistent with each other when backtraces
+  # are manually adjusted.)
+  #
+  # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
+  #
+  def backtrace_locations: () -> Array[Thread::Backtrace::Location]?
+
+  # <!--
+  #   rdoc-file=error.c
+  #   - cause -> exception or nil
+  # -->
+  # 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
+  #   - detailed_message(highlight: false, **kwargs) -> string
+  # -->
+  # 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.
+  #
+  # Examples:
+  #
+  #     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
+  #
+  # Output:
+  #
+  #     "divided by 0"
+  #     "divided by 0 (ZeroDivisionError)"
+  #     "\e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m"
+  #
+  # 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):
+  #
+  # *   `: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
+  #   - exception(message = nil) -> self or new_exception
+  # -->
+  # 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(message = nil) -> exception
+  # -->
+  # 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
+  #   - inspect -> string
+  # -->
+  # 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
+  #   - message -> string
+  # -->
+  # Returns #to_s.
+  #
+  # See [Messages](rdoc-ref:exceptions.md@Messages).
+  #
+  def message: () -> String
+
+  # <!--
+  #   rdoc-file=error.c
+  #   - set_backtrace(value) -> value
+  # -->
+  # Sets the backtrace value for `self`; returns the given `value`.
+  #
+  # The `value` might be:
+  #
+  # *   an array of Thread::Backtrace::Location;
+  # *   an array of String instances;
+  # *   a single String instance; or
+  # *   `nil`.
+  #
+  # Using array of Thread::Backtrace::Location is the most consistent option: it
+  # sets both #backtrace and #backtrace_locations. It should be preferred when
+  # possible. The suitable array of locations can be obtained from
+  # Kernel#caller_locations, copied from another error, or just set to the
+  # adjusted result of the current error's #backtrace_locations:
+  #
+  #     require 'json'
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)  # test.rb, line 4
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(ex.backtrace_locations[2...])
+  #       raise
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #     # test.rb:4:in 'Object#parse_payload': unexpected token at '{"wrong: "json"' (JSON::ParserError)
+  #     #
+  #     # An error points to the body of parse_payload method,
+  #     # hiding the parts of the backtrace related to the internals
+  #     # of the "json" library
+  #
+  #     # The error has both #backtace and #backtrace_locations set
+  #     # consistently:
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #     end
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only #backtrace is affected:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(["dsl.rb:34", "framework.rb:1"])
+  #       # The error have the new value in #backtrace:
+  #       p ex.backtrace
+  #       # ["dsl.rb:34", "framework.rb:1"]
+  #
+  #       # but the original one in #backtrace_locations
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # Calling #set_backtrace with `nil` clears up #backtrace but doesn't affect
+  # #backtrace_locations:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       p ex.backtrace
+  #       # nil
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # On reraising of such an exception, both #backtrace and #backtrace_locations is
+  # set to the place of reraising:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       raise # test.rb, line 7
+  #     end
+  #
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #     end
+  #
+  # 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
+  #   - to_s -> string
+  # -->
+  # 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
+  #   - full_message(highlight: true, order: :top) -> string
+  # -->
+  # 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 'Integer#/': divided by 0 (ZeroDivisionError)",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#foo'",
+  #      "\tfrom t.rb:12:in '<main>'"]
+  #     ["t.rb:3:in 'Integer#/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#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/false_class.rbs

@@ -0,0 +1,82 @@
+# <!-- rdoc-file=object.c -->
+# The global value `false` is the only instance of class FalseClass and
+# represents a logically false value in boolean expressions. The class provides
+# operators allowing `false` to participate correctly in logical expressions.
+#
+class FalseClass
+  def !: () -> true
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - false & object -> false
+  #   - nil & object   -> false
+  # -->
+  # Returns `false`:
+  #
+  #     false & true       # => false
+  #     false & Object.new # => false
+  #
+  # Argument `object` is evaluated:
+  #
+  #     false & raise # Raises RuntimeError.
+  #
+  def &: (untyped obj) -> false
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - true === other -> true or false
+  #   - false === other -> true or false
+  #   - nil === other -> true or false
+  # -->
+  # Returns `true` or `false`.
+  #
+  # Like Object#==, if `object` is an instance of Object (and not an instance of
+  # one of its many subclasses).
+  #
+  # This method is commonly overridden by those subclasses, to provide meaningful
+  # semantics in `case` statements.
+  #
+  def ===: (false) -> true
+         | (untyped obj) -> bool
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - false ^ object -> true or false
+  #   - nil ^ object   -> true or false
+  # -->
+  # Returns `false` if `object` is `nil` or `false`, `true` otherwise:
+  #
+  #     nil ^ nil        # => false
+  #     nil ^ false      # => false
+  #     nil ^ Object.new # => true
+  #
+  def ^: (false | nil) -> false
+       | (untyped obj) -> bool
+
+  # <!-- rdoc-file=object.c -->
+  # The string representation of `false` is "false".
+  #
+  alias inspect to_s
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - false.to_s   ->  "false"
+  # -->
+  # The string representation of `false` is "false".
+  #
+  def to_s: () -> "false"
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - false | object -> true or false
+  #   - nil   | object -> true or false
+  # -->
+  # Returns `false` if `object` is `nil` or `false`, `true` otherwise:
+  #
+  #     nil | nil        # => false
+  #     nil | false      # => false
+  #     nil | Object.new # => true
+  #
+  def |: (nil | false) -> false
+       | (untyped obj) -> bool
+end