rbs 0.2.0

data/stdlib/builtin/errors.rbs

@@ -0,0 +1,582 @@
+# Raised when the arguments are wrong and there isn't a more specific Exception
+# class.
+#
+# Ex: passing the wrong number of arguments
+#
+#     [1, 2, 3].first(4, 5)
+#
+# *raises the exception:*
+#
+#     ArgumentError: wrong number of arguments (given 2, expected 1)
+#
+# Ex: passing an argument that is not acceptable:
+#
+#     [1, 2, 3].first(-4)
+#
+# *raises the exception:*
+#
+#     ArgumentError: negative array size
+#
+class ArgumentError < StandardError
+end
+
+# The exception class which will be raised when pushing into a closed Queue. 
+# See Queue#close and SizedQueue#close.
+#
+class ClosedQueueError < StopIteration
+end
+
+# EncodingError is the base class for encoding errors.
+#
+class EncodingError < StandardError
+end
+
+# Raised by some IO operations when reaching the end of file. Many IO methods
+# exist in two forms,
+#
+# one that returns `nil` when the end of file is reached, the other raises
+# `EOFError`.
+#
+# `EOFError` is a subclass of `IOError`.
+#
+#     file = File.open("/etc/hosts")
+#     file.read
+#     file.gets     #=> nil
+#     file.readline #=> EOFError: end of file reached
+#
+class EOFError < IOError
+end
+
+# Raised when attempting to convert special float values (in particular
+# `Infinity` or `NaN`) to numerical classes which don't support them.
+#
+#     Float::INFINITY.to_r   #=> FloatDomainError: Infinity
+#
+class FloatDomainError < RangeError
+end
+
+# Raised when there is an attempt to modify a frozen object.
+#
+#     [1, 2, 3].freeze << 4
+#
+# *raises the exception:*
+#
+#     FrozenError: can't modify frozen Array
+#
+class FrozenError[T] < RuntimeError
+  # Construct a new FrozenError exception. If given the *receiver* parameter may
+  # subsequently be examined using the FrozenError#receiver method.
+  #
+  #     a = [].freeze
+  #     raise FrozenError.new("can't modify frozen array", receiver: a)
+  #
+  def initialize: (?string? msg, ?receiver: T?) -> void
+
+  # Return the receiver associated with this FrozenError exception.
+  #
+  def receiver: () -> T?
+end
+
+# Raised when the given index is invalid.
+#
+#     a = [:foo, :bar]
+#     a.fetch(0)   #=> :foo
+#     a[4]         #=> nil
+#     a.fetch(4)   #=> IndexError: index 4 outside of array bounds: -2...2
+#
+class IndexError < StandardError
+end
+
+# Raised when the interrupt signal is received, typically because the user has
+# pressed Control-C (on most posix platforms). As such, it is a subclass of
+# `SignalException`.
+#
+#     begin
+#       puts "Press ctrl-C when you get bored"
+#       loop {}
+#     rescue Interrupt => e
+#       puts "Note: You will typically use Signal.trap instead."
+#     end
+#
+# *produces:*
+#
+#     Press ctrl-C when you get bored
+#
+# *then waits until it is interrupted with Control-C and then prints:*
+#
+#     Note: You will typically use Signal.trap instead.
+#
+class Interrupt < SignalException
+  def initialize: (?string) -> void
+end
+
+# Raised when an IO operation fails.
+#
+#     File.open("/etc/hosts") {|f| f << "example"}
+#       #=> IOError: not opened for writing
+#
+#     File.open("/etc/hosts") {|f| f.close; f.read }
+#       #=> IOError: closed stream
+#
+# Note that some IO failures raise `SystemCallError`s and these are not
+# subclasses of IOError:
+#
+#     File.open("does/not/exist")
+#       #=> Errno::ENOENT: No such file or directory - does/not/exist
+#
+class IOError < StandardError
+end
+
+# Raised when the specified key is not found. It is a subclass of IndexError.
+#
+#     h = {"foo" => :bar}
+#     h.fetch("foo") #=> :bar
+#     h.fetch("baz") #=> KeyError: key not found: "baz"
+#
+class KeyError[K, R] < IndexError
+  # Construct a new `KeyError` exception with the given message, receiver and key.
+  #
+  def initialize: (?string msg, ?receiver: R?, ?key: K?) -> void
+
+  # Return the key caused this KeyError exception.
+  #
+  def key: () -> K?
+
+  # Return the receiver associated with this KeyError exception.
+  #
+  def receiver: () -> R?
+end
+
+# Raised when a file required (a Ruby script, extension library, ...) fails to
+# load.
+#
+#     require 'this/file/does/not/exist'
+#
+# *raises the exception:*
+#
+#     LoadError: no such file to load -- this/file/does/not/exist
+#
+class LoadError < ScriptError
+  # the path failed to load
+  #
+  #
+  def path: () -> String?
+end
+
+# Raised when Ruby can't yield as requested.
+#
+# A typical scenario is attempting to yield when no block is given:
+#
+#     def call_block
+#       yield 42
+#     end
+#     call_block
+#
+# *raises the exception:*
+#
+#     LocalJumpError: no block given (yield)
+#
+# A more subtle example:
+#
+#     def get_me_a_return
+#       Proc.new { return 42 }
+#     end
+#     get_me_a_return.call
+#
+# *raises the exception:*
+#
+#     LocalJumpError: unexpected return
+#
+class LocalJumpError < StandardError
+  # Returns the exit value associated with this `LocalJumpError`.
+  #
+  def exit_value: () -> untyped
+
+  # The reason this block was terminated: :break, :redo, :retry, :next, :return,
+  # or :noreason.
+  #
+  def reason: () -> Symbol
+end
+
+# Raised when a given name is invalid or undefined.
+#
+#     puts foo
+#
+# *raises the exception:*
+#
+#     NameError: undefined local variable or method `foo' for main:Object
+#
+# Since constant names must start with a capital:
+#
+#     Integer.const_set :answer, 42
+#
+# *raises the exception:*
+#
+#     NameError: wrong constant name answer
+#
+class NameError[T] < StandardError
+  # Construct a new NameError exception. If given the *name* parameter may
+  # subsequently be examined using the NameError#name method. *receiver* parameter
+  # allows to pass object in context of which the error happened. Example:
+  #
+  #     [1, 2, 3].method(:rject) # NameError with name "rject" and receiver: Array
+  #     [1, 2, 3].singleton_method(:rject) # NameError with name "rject" and receiver: [1, 2, 3]
+  #
+  def initialize: (?string msg, ?String? name, ?receiver: T?) -> void
+
+  public
+
+  # Return a list of the local variable names defined where this NameError
+  # exception was raised.
+  #
+  # Internal use only.
+  #
+  def local_variables: () -> ::Array[Symbol]
+
+  # Return the name associated with this NameError exception.
+  #
+  def name: () -> String?
+
+  # Return the receiver associated with this NameError exception.
+  #
+  def receiver: () -> T?
+end
+
+# Raised when memory allocation fails.
+#
+class NoMemoryError < Exception
+end
+
+# Raised when a method is called on a receiver which doesn't have it defined and
+# also fails to respond with `method_missing`.
+#
+#     "hello".to_ary
+#
+# *raises the exception:*
+#
+#     NoMethodError: undefined method `to_ary' for "hello":String
+#
+class NoMethodError[T] < NameError[T]
+  # Construct a NoMethodError exception for a method of the given name called with
+  # the given arguments. The name may be accessed using the `#name` method on the
+  # resulting object, and the arguments using the `#args` method.
+  #
+  # If *private* argument were passed, it designates method was attempted to call
+  # in private context, and can be accessed with `#private_call?` method.
+  #
+  # *receiver* argument stores an object whose method was called.
+  #
+  def initialize: (?string? msg, ?String? name, ?Array[untyped] args, ?bool `private`, ?receiver: T?) -> void
+
+  public
+
+  # Return the arguments passed in as the third parameter to the constructor.
+  #
+  def args: () -> Array[untyped]
+
+  # Return true if the caused method was called as private.
+  #
+  def private_call?: () -> bool
+end
+
+# Raised when a feature is not implemented on the current platform. For example,
+# methods depending on the `fsync` or `fork` system calls may raise this
+# exception if the underlying operating system or Ruby runtime does not support
+# them.
+#
+# Note that if `fork` raises a `NotImplementedError`, then `respond_to?(:fork)`
+# returns `false`.
+#
+class NotImplementedError < ScriptError
+end
+
+# Raised when a given numerical value is out of range.
+#
+#     [1, 2, 3].drop(1 << 100)
+#
+# *raises the exception:*
+#
+#     RangeError: bignum too big to convert into `long'
+#
+class RangeError < StandardError
+end
+
+# Raised when given an invalid regexp expression.
+#
+#     Regexp.new("?")
+#
+# *raises the exception:*
+#
+#     RegexpError: target of repeat operator is not specified: /?/
+#
+class RegexpError < StandardError
+end
+
+# A generic error class raised when an invalid operation is attempted.
+# Kernel#raise will raise a RuntimeError if no Exception class is specified.
+#
+#     raise "ouch"
+#
+# *raises the exception:*
+#
+#     RuntimeError: ouch
+#
+class RuntimeError < StandardError
+end
+
+# ScriptError is the superclass for errors raised when a script can not be
+# executed because of a `LoadError`, `NotImplementedError` or a `SyntaxError`.
+# Note these type of `ScriptErrors` are not `StandardError` and will not be
+# rescued unless it is specified explicitly (or its ancestor `Exception`).
+#
+class ScriptError < Exception
+end
+
+# No longer used by internal code.
+#
+class SecurityError < Exception
+end
+
+# Raised when a signal is received.
+#
+#     begin
+#       Process.kill('HUP',Process.pid)
+#       sleep # wait for receiver to handle signal sent by Process.kill
+#     rescue SignalException => e
+#       puts "received Exception #{e}"
+#     end
+#
+# *produces:*
+#
+#     received Exception SIGHUP
+#
+class SignalException < Exception
+  # Construct a new SignalException object.  `sig_name` should be a known signal
+  # name.
+  #
+  def initialize: (?string sig_name) -> void
+                | (int sig_number, ?string sig_name) -> void
+
+  public
+
+  def signm: () -> String
+
+  # Returns a signal number.
+  #
+  def signo: () -> Integer
+end
+
+# The most standard error types are subclasses of StandardError. A rescue clause
+# without an explicit Exception class will rescue all StandardErrors (and only
+# those).
+#
+#     def foo
+#       raise "Oups"
+#     end
+#     foo rescue "Hello"   #=> "Hello"
+#
+# On the other hand:
+#
+#     require 'does/not/exist' rescue "Hi"
+#
+# *raises the exception:*
+#
+#     LoadError: no such file to load -- does/not/exist
+#
+class StandardError < Exception
+end
+
+# Raised to stop the iteration, in particular by Enumerator#next. It is rescued
+# by Kernel#loop.
+#
+#     loop do
+#       puts "Hello"
+#       raise StopIteration
+#       puts "World"
+#     end
+#     puts "Done!"
+#
+# *produces:*
+#
+#     Hello
+#     Done!
+#
+class StopIteration < IndexError
+  # Returns the return value of the iterator.
+  #
+  #     o = Object.new
+  #     def o.each
+  #       yield 1
+  #       yield 2
+  #       yield 3
+  #       100
+  #     end
+  #
+  #     e = o.to_enum
+  #
+  #     puts e.next                   #=> 1
+  #     puts e.next                   #=> 2
+  #     puts e.next                   #=> 3
+  #
+  #     begin
+  #       e.next
+  #     rescue StopIteration => ex
+  #       puts ex.result              #=> 100
+  #     end
+  #
+  def result: () -> untyped
+end
+
+# Raised when encountering Ruby code with an invalid syntax.
+#
+#     eval("1+1=2")
+#
+# *raises the exception:*
+#
+#     SyntaxError: (eval):1: syntax error, unexpected '=', expecting $end
+#
+class SyntaxError < ScriptError
+  # Construct a SyntaxError exception.
+  #
+  def initialize: (?string msg) -> void
+end
+
+# SystemCallError is the base class for all low-level platform-dependent errors.
+#
+# The errors available on the current platform are subclasses of SystemCallError
+# and are defined in the Errno module.
+#
+#     File.open("does/not/exist")
+#
+# *raises the exception:*
+#
+#     Errno::ENOENT: No such file or directory - does/not/exist
+#
+class SystemCallError < StandardError
+  # 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.
+  #
+  def initialize: (string msg, Integer errno) -> SystemCallError
+
+  # Return `true` if the receiver is a generic `SystemCallError`, or if the error
+  # numbers `self` and *other* are the same.
+  #
+  def self.===: (untyped other) -> bool
+
+  public
+
+  # Return this SystemCallError's error number.
+  #
+  def errno: () -> Integer
+end
+
+# Raised by `exit` to initiate the termination of the script.
+#
+class SystemExit < Exception
+  # Create a new `SystemExit` exception with the given status and message. Status
+  # is true, false, or an integer. If status is not given, true is used.
+  #
+  def initialize: () -> void
+                | (string msg) -> void
+                | (true | false | int status, ?string msg) -> void
+
+  public
+
+  # Return the status value associated with this system exit.
+  #
+  def status: () -> Integer
+
+  # Returns `true` if exiting successful, `false` if not.
+  #
+  def success?: () -> bool
+end
+
+# Raised in case of a stack overflow.
+#
+#     def me_myself_and_i
+#       me_myself_and_i
+#     end
+#     me_myself_and_i
+#
+# *raises the exception:*
+#
+#     SystemStackError: stack level too deep
+#
+class SystemStackError < Exception
+end
+
+# Raised when an invalid operation is attempted on a thread.
+#
+# For example, when no other thread has been started:
+#
+#     Thread.stop
+#
+# This will raises the following exception:
+#
+#     ThreadError: stopping only thread
+#     note: use sleep to stop forever
+#
+class ThreadError < StandardError
+end
+
+# Raised when encountering an object that is not of the expected type.
+#
+#     [1, 2, 3].first("two")
+#
+# *raises the exception:*
+#
+#     TypeError: no implicit conversion of String into Integer
+#
+class TypeError < StandardError
+end
+
+# Raised when `throw` is called with a *tag* which does not have corresponding
+# `catch` block.
+#
+#     throw "foo", "bar"
+#
+# *raises the exception:*
+#
+#     UncaughtThrowError: uncaught throw "foo"
+#
+class UncaughtThrowError < ArgumentError
+  # Raised when `throw` is called with a *tag* which does not have corresponding
+  # `catch` block.
+  #
+  #     throw "foo", "bar"
+  #
+  # *raises the exception:*
+  #
+  #     UncaughtThrowError: uncaught throw "foo"
+  #
+  def initialize: (untyped tag, untyped value) -> void
+
+  public
+
+  # Return the tag object which was called for.
+  #
+  def tag: () -> untyped
+
+  # Returns formatted message with the inspected tag.
+  #
+  def to_s: () -> String
+
+  # Return the return value which was called for.
+  #
+  def value: () -> untyped
+end
+
+# Raised when attempting to divide an integer by 0.
+#
+#     42 / 0   #=> ZeroDivisionError: divided by 0
+#
+# Note that only division by an exact 0 will raise the exception:
+#
+#     42 /  0.0   #=> Float::INFINITY
+#     42 / -0.0   #=> -Float::INFINITY
+#     0  /  0.0   #=> NaN
+#
+class ZeroDivisionError < StandardError
+end