# <!-- 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 a backtrace value for `self`; the returned value depends on the form
  # of the stored backtrace value:
  #
  # *   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`.
  #
  # Example:
  #
  #     begin
  #       1 / 0
  #     rescue => x
  #       x.backtrace.take(2)
  #     end
  #     # => ["(irb):132:in `/'", "(irb):132:in `<top (required)>'"]
  #
  # see [Backtraces](rdoc-ref:exceptions.md@Backtraces).
  #
  def backtrace: () -> Array[String]?

  # <!--
  #   rdoc-file=error.c
  #   - backtrace_locations -> array or nil
  # -->
  # 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`.
  #
  # 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
  #   - 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:
  #
  #     x = RuntimeError.new('Boom')
  #     x.set_backtrace(%w[foo bar baz]) # => ["foo", "bar", "baz"]
  #     x.backtrace                      # => ["foo", "bar", "baz"]
  #
  # 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
  #   - 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 `/': 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
