rbs 2.8.4 → 3.8.1

data/core/basic_object.rbs

@@ -1,93 +1,68 @@
 # <!-- rdoc-file=object.c -->
-# BasicObject is the parent class of all classes in Ruby.  It's an explicit
-# blank class.
+# `BasicObject` is the parent class of all classes in Ruby. In particular,
+# `BasicObject` is the parent class of class Object, which is itself the default
+# parent class of every Ruby class:
 #
-# BasicObject can be used for creating object hierarchies independent of Ruby's
-# object hierarchy, proxy objects like the Delegator class, or other uses where
-# namespace pollution from Ruby's methods and classes must be avoided.
+#     class Foo; end
+#     Foo.superclass    # => Object
+#     Object.superclass # => BasicObject
 #
-# To avoid polluting BasicObject for other users an appropriately named subclass
-# of BasicObject should be created instead of directly modifying BasicObject:
+# `BasicObject` is the only class that has no parent:
 #
-#     class MyObjectSystem < BasicObject
-#     end
+#     BasicObject.superclass # => nil
 #
-# BasicObject does not include Kernel (for methods like `puts`) and BasicObject
-# is outside of the namespace of the standard library so common classes will not
-# be found without using a full class path.
+# Class `BasicObject` can be used to create an object hierarchy (e.g., class
+# Delegator) that is independent of Ruby's object hierarchy. Such objects:
 #
-# A variety of strategies can be used to provide useful portions of the standard
-# library to subclasses of BasicObject.  A subclass could `include Kernel` to
-# obtain `puts`, `exit`, etc.  A custom Kernel-like module could be created and
-# included or delegation can be used via #method_missing:
+# *   Do not have namespace "pollution" from the many methods provided in class
+#     Object and its included module Kernel.
+# *   Do not have definitions of common classes, and so references to such
+#     common classes must be fully qualified (`::String`, not `String`).
 #
-#     class MyObjectSystem < BasicObject
-#       DELEGATE = [:puts, :p]
+# A variety of strategies can be used to provide useful portions of the Standard
+# Library in subclasses of `BasicObject`:
 #
-#       def method_missing(name, *args, &block)
-#         return super unless DELEGATE.include? name
-#         ::Kernel.send(name, *args, &block)
-#       end
+# *   The immediate subclass could `include Kernel`, which would define methods
+#     such as `puts`, `exit`, etc.
+# *   A custom Kernel-like module could be created and included.
+# *   Delegation can be used via #method_missing:
 #
-#       def respond_to_missing?(name, include_private = false)
-#         DELEGATE.include?(name) or super
-#       end
-#     end
+#         class MyObjectSystem < BasicObject
+#           DELEGATE = [:puts, :p]
 #
-# Access to classes and modules from the Ruby standard library can be obtained
-# in a BasicObject subclass by referencing the desired constant from the root
-# like `::File` or `::Enumerator`. Like #method_missing, #const_missing can be
-# used to delegate constant lookup to `Object`:
+#           def method_missing(name, *args, &block)
+#             return super unless DELEGATE.include? name
+#             ::Kernel.send(name, *args, &block)
+#           end
 #
-#     class MyObjectSystem < BasicObject
-#       def self.const_missing(name)
-#         ::Object.const_get(name)
-#       end
-#     end
+#           def respond_to_missing?(name, include_private = false)
+#             DELEGATE.include?(name)
+#           end
+#         end
 #
 # ### What's Here
 #
 # These are the methods defined for BasicObject:
 #
-#     ::new
-# :       Returns a new BasicObject instance.
-#
-#     [!](#method-i-21)
-# :       Returns the boolean negation of `self`: `true` or `false`.
-#
-#     [!=](#method-i-21-3D)
-# :       Returns whether `self` and the given object are *not* equal.
-#
-#     [==](#method-i-3D-3D)
-# :       Returns whether `self` and the given object are equivalent.
-#
-#     [__id__](#method-i-__id__)
-# :       Returns the integer object identifier for `self`.
-#
-#     [__send__](#method-i-__send__)
-# :       Calls the method identified by the given symbol.
-#
-#     #equal?
-# :       Returns whether `self` and the given object are the same object.
-#
-#     #instance_eval
-# :       Evaluates the given string or block in the context of `self`.
-#
-#     #instance_exec
-# :       Executes the given block in the context of `self`, passing the given
-#         arguments.
-#
-#     #method_missing
-# :       Method called when an undefined method is called on `self`.
-#
-#     #singleton_method_added
-# :       Method called when a singleton method is added to `self`.
-#
-#     #singleton_method_removed
-# :       Method called when a singleton method is added removed from `self`.
-#
-#     #singleton_method_undefined
-# :       Method called when a singleton method is undefined in `self`.
+# *   ::new: Returns a new BasicObject instance.
+# *   #!: Returns the boolean negation of `self`: `true` or `false`.
+# *   #!=: Returns whether `self` and the given object are *not* equal.
+# *   #==: Returns whether `self` and the given object are equivalent.
+# *   #__id__: Returns the integer object identifier for `self`.
+# *   #__send__: Calls the method identified by the given symbol.
+# *   #equal?: Returns whether `self` and the given object are the same object.
+# *   #instance_eval: Evaluates the given string or block in the context of
+#     `self`.
+# *   #instance_exec: Executes the given block in the context of `self`, passing
+#     the given arguments.
+# *   #method_missing: Called when `self` is called with a method it does not
+#     define.
+# *   #singleton_method_added: Called when a singleton method is added to
+#     `self`.
+# *   #singleton_method_removed: Called when a singleton method is removed from
+#     `self`.
+# *   #singleton_method_undefined: Called when a singleton method is undefined
+#     in `self`.
 #
 class BasicObject
   # <!--
@@ -156,7 +131,7 @@ class BasicObject
   # Note: that some objects of builtin classes are reused for optimization. This
   # is the case for immediate values and frozen string literals.
   #
-  # BasicObject implements +__id__+, Kernel implements `object_id`.
+  # BasicObject implements `__id__`, Kernel implements `object_id`.
   #
   # Immediate values are not passed by reference but are passed by value: `nil`,
   # `true`, `false`, Fixnums, Symbols, and some Floats.
@@ -179,7 +154,7 @@ class BasicObject
   # When the method is identified by a string, the string is converted to a
   # symbol.
   #
-  # BasicObject implements +__send__+, Kernel implements `send`. `__send__` is
+  # BasicObject implements `__send__`, Kernel implements `send`. `__send__` is
   # safer than `send` when *obj* has the same method name like `Socket`. See also
   # `public_send`.
   #
@@ -191,7 +166,7 @@ class BasicObject
   #     k = Klass.new
   #     k.send :hello, "gentle", "readers"   #=> "Hello gentle readers"
   #
-  def __send__: (String | Symbol arg0, *untyped args) -> untyped
+  def __send__: (interned name, *untyped, **untyped) ?{ (?) -> untyped } -> untyped
 
   # <!-- rdoc-file=object.c -->
   # Equality --- At the Object level, #== returns `true` only if `obj` and `other`
@@ -223,7 +198,7 @@ class BasicObject
   #     1 == 1.0     #=> true
   #     1.eql? 1.0   #=> false
   #
-  def equal?: (untyped other) -> bool
+  alias equal? ==
 
   # <!--
   #   rdoc-file=vm_eval.c
@@ -256,7 +231,7 @@ class BasicObject
   #     k.instance_eval { the_secret }       #=> "Ssssh! The secret is 99."
   #     k.instance_eval {|obj| obj == self } #=> true
   #
-  def instance_eval: (String, ?String filename, ?Integer lineno) -> untyped
+  def instance_eval: (string code, ?string filename, ?int lineno) -> untyped
                    | [U] () { (self) [self: self] -> U } -> U
 
   # <!--
@@ -276,7 +251,7 @@ class BasicObject
   #     k = KlassWithSecret.new
   #     k.instance_exec(5) {|x| @secret+x }   #=> 104
   #
-  def instance_exec: [U, V] (*V args) { (*V args) [self: self] -> U } -> U
+  def instance_exec: [U] (*untyped, **untyped) { (?) [self: self] -> U } -> U
 
   # <!--
   #   rdoc-file=object.c
@@ -323,7 +298,7 @@ class BasicObject
   #     r.mm      #=> 2000
   #     r.foo     #=> NoMethodError
   #
-  def method_missing: (Symbol, *untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
+  def method_missing: (Symbol, *untyped, **untyped) ?{ (?) -> untyped } -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -346,7 +321,7 @@ class BasicObject
   #     Adding one
   #     Adding three
   #
-  def singleton_method_added: (Symbol) -> void
+  def singleton_method_added: (Symbol name) -> nil
 
   # <!--
   #   rdoc-file=object.c
@@ -373,7 +348,7 @@ class BasicObject
   #     Removing three
   #     Removing one
   #
-  def singleton_method_removed: (Symbol) -> void
+  def singleton_method_removed: (Symbol name) -> nil
 
   # <!--
   #   rdoc-file=object.c
@@ -396,5 +371,5 @@ class BasicObject
   #
   #     Undefining one
   #
-  def singleton_method_undefined: (Symbol) -> void
+  def singleton_method_undefined: (Symbol name) -> nil
 end

data/core/binding.rbs

@@ -30,10 +30,10 @@
 # Binding objects have no class-specific methods.
 #
 class Binding
-  public
-
   def clone: () -> self
 
+  def dup: () -> self
+
   # <!--
   #   rdoc-file=proc.c
   #   - binding.eval(string [, filename [,lineno]])  -> obj
@@ -48,69 +48,7 @@ class Binding
   #     b = get_binding("hello")
   #     b.eval("param")   #=> "hello"
   #
-  def eval: (String arg0, ?String filename, ?Integer lineno) -> untyped
-
-  # <!--
-  #   rdoc-file=lib/irb.rb
-  #   - irb()
-  # -->
-  # Opens an IRB session where `binding.irb` is called which allows for
-  # interactive debugging. You can call any methods or variables available in the
-  # current scope, and mutate state if you need to.
-  #
-  # Given a Ruby file called `potato.rb` containing the following code:
-  #
-  #     class Potato
-  #       def initialize
-  #         @cooked = false
-  #         binding.irb
-  #         puts "Cooked potato: #{@cooked}"
-  #       end
-  #     end
-  #
-  #     Potato.new
-  #
-  # Running `ruby potato.rb` will open an IRB session where `binding.irb` is
-  # called, and you will see the following:
-  #
-  #     $ ruby potato.rb
-  #
-  #     From: potato.rb @ line 4 :
-  #
-  #         1: class Potato
-  #         2:   def initialize
-  #         3:     @cooked = false
-  #      => 4:     binding.irb
-  #         5:     puts "Cooked potato: #{@cooked}"
-  #         6:   end
-  #         7: end
-  #         8:
-  #         9: Potato.new
-  #
-  #     irb(#<Potato:0x00007feea1916670>):001:0>
-  #
-  # You can type any valid Ruby code and it will be evaluated in the current
-  # context. This allows you to debug without having to run your code repeatedly:
-  #
-  #     irb(#<Potato:0x00007feea1916670>):001:0> @cooked
-  #     => false
-  #     irb(#<Potato:0x00007feea1916670>):002:0> self.class
-  #     => Potato
-  #     irb(#<Potato:0x00007feea1916670>):003:0> caller.first
-  #     => ".../2.5.1/lib/ruby/2.5.0/irb/workspace.rb:85:in `eval'"
-  #     irb(#<Potato:0x00007feea1916670>):004:0> @cooked = true
-  #     => true
-  #
-  # You can exit the IRB session with the `exit` command. Note that exiting will
-  # resume execution where `binding.irb` had paused it, as you can see from the
-  # output printed to standard output in this example:
-  #
-  #     irb(#<Potato:0x00007feea1916670>):005:0> exit
-  #     Cooked potato: true
-  #
-  # See IRB@IRB+Usage for more information.
-  #
-  def irb: () -> void
+  def eval: (string src, ?string filename, ?int lineno) -> untyped
 
   # <!--
   #   rdoc-file=proc.c
@@ -128,7 +66,7 @@ class Binding
   #
   #     binding.eval("defined?(#{symbol}) == 'local-variable'")
   #
-  def local_variable_defined?: (String | Symbol symbol) -> bool
+  def local_variable_defined?: (interned varname) -> bool
 
   # <!--
   #   rdoc-file=proc.c
@@ -146,7 +84,7 @@ class Binding
   #
   #     binding.eval("#{symbol}")
   #
-  def local_variable_get: (String | Symbol symbol) -> untyped
+  def local_variable_get: (interned varname) -> untyped
 
   # <!--
   #   rdoc-file=proc.c
@@ -173,7 +111,7 @@ class Binding
   #
   # if `obj` can be dumped in Ruby code.
   #
-  def local_variable_set: [U] (String | Symbol symbol, U obj) -> U
+  def local_variable_set: [U] (interned varname, U obj) -> U
 
   # <!--
   #   rdoc-file=proc.c
@@ -208,5 +146,5 @@ class Binding
   # -->
   # Returns the Ruby source filename and line number of the binding object.
   #
-  def source_location: () -> [ String, Integer ]
+  def source_location: () -> [String, Integer]
 end

data/core/builtin.rbs

@@ -1,37 +1,181 @@
+# A type that's convertible to a `Complex`.
+#
+interface _ToC
+  # Convert `self` to a `Complex`.
+  #
+  def to_c: () -> Complex
+end
+
+# A type that's convertible to a `Rational`.
+#
+interface _ToR
+  # Convert `self` to a `Complex`.
+  #
+  def to_r: () -> Rational
+end
+
+# A type that's convertible to a `Float`.
+#
+interface _ToF
+  # Convert `self` to a `Float`.
+  #
+  def to_f: () -> Float
+end
+
+# A type that's convertible to an `Integer`.
+#
 interface _ToI
+  # Convert `self` to an `Integer`.
+  #
   def to_i: () -> Integer
 end
 
+# A type that's implicitly convertible to an `Integer`.
+#
+# Implicit `.to_int` conversions are usable all over Ruby's stdlib, such as `Kernel#exit`,
+# `File#chmod`, and `Array#take`. Virtually anywhere that accepts an `Integer` will also accept
+# something that defines `.to_int`.
+#
+# Interestingly, types that define `.to_int` aren't immediately converted in math operations on
+# `Integers` (eg `1 + defines_to_int`): Instead, `.coerce` must be defined on the right-hand-side
+# value.
+#
 interface _ToInt
+  # Converts `self` to an `Integer`.
+  #
   def to_int: () -> Integer
 end
 
-interface _ToR
-  def to_r: () -> Rational
-end
-
+# A type that's convertible to a `String`.
+#
 interface _ToS
+  # Converts `self` to a `String`.
+  #
   def to_s: () -> String
 end
 
+# A type that's implicitly convertible to a `String`.
+#
+# Implicit `.to_str` conversions are usable all over Ruby's stdlib, such as `Kernel#abort`,
+# `String#+`, and `Object#send`. Virtually anywhere that accepts a `String` will also accept
+# something that defines `.to_Str`.
+#
+# Types that define `.to_str` are also usable wherever paths are expected (See the `path` type
+# alias).
+#
 interface _ToStr
+  # Converts `self` to a `String`.
+  #
   def to_str: () -> String
 end
 
+# A type that's explicitly convertible to a `String`.
+#
+# Interestingly enough, most methods that accept `Symbol` in the standard library _do not_ accept
+# an object that defines `.to_sym` (unlike `String` and `.to_str`).
+#
+# There are only two places that `Symbol | _ToSym`, and they're quite obscure:
+# - `Kernel#warn`'s `category:` optional parameter. (Oddly enough, not for  `Warning.warn`, though.)
+# - `TracePoint#trace`'s `event`s parameter.
+# Additionally, the `rb_iseq_load` C function, only accessible through `Fiddle`, uses `.to_sym`
+# internally.
+#
+interface _ToSym
+  # Converts `self` to a `Symbol`.
+  #
+  def to_sym: () -> Symbol
+end
+
+# A type that's convertible to a `Hash`.
+#
+interface _ToH[K, V]
+  # Converts `self` to a `Hash`.
+  #
+  def to_h: () -> Hash[K, V]
+end
+
+# A type that's implicitly convertible to a `Hash`.
+#
+# Implicit `.to_hash` conversions are usable infrequently in Ruby's stdlib, such as `Io#popen`,
+# `Kernel#sprintf`, and `Enumerable#tally`. It's also used with the `**` "splatsplat" operator.
+#
 interface _ToHash[K, V]
+  # Converts `self` to a `Hash`.
+  #
   def to_hash: () -> Hash[K, V]
 end
 
+# A type that's convertible to an `Array`.
+#
+interface _ToA[T]
+  # Converts `self` to an `Array`.
+  #
+  def to_a: () -> Array[T]
+end
+
+# A type that's implicitly convertible to an `Array`.
+#
+# Implicit `.to_ary` conversions are usable semi-frequently in Ruby's stdlib, such as `Dir#glob`,
+# `Regex#union`, and `Class#private`. It's also used with the `*` "splat" operator.
+#
+interface _ToAry[T]
+  # Converts `self` to an `Array`.
+  #
+  def to_ary: () -> Array[T]
+end
+
+# A type that's convertible to a `Proc`.
+#
+# This is implicitly called when the `&` "block-passing" operator is used, in addition to a handful
+# of other places, such as `Hash#default_proc=`.
+#
 interface _ToProc
-  def to_proc: () -> untyped
+  # Converts `self` to a `Proc.`
+  #
+  def to_proc: () -> Proc
 end
 
+# A type that's convertible to a `String` that contains a filepath.
+#
+# Implicit `.to_path` conversions are usable throughout Ruby's stdlib, whenever a file path is
+# expected, such as `Dir#mkdir`, `File#open`, and `UNIXSocket#read`. These functions, however, also
+# accept types that define `.to_str`. See the `path` type alias.
+#
 interface _ToPath
+  # Converts `self` to a `String` containing a filepath.
+  #
   def to_path: () -> String
 end
 
-interface _Each[out A]
-  def each: () { (A) -> void } -> void
+# A type that's convertible to an `IO`.
+#
+# Implicit `.to_io` conversions are usuable infrequently in Ruby's stdlib, such as `IO#reopen`,
+# `File.exist?`, and `Kernel#select`.
+#
+interface _ToIO
+  # Converts `self` to an `IO` object.
+  #
+  def to_io: () -> IO
+end
+
+# A type that defines the `.inspect` method.
+#
+# Since `Object` defines `.inspect`, nearly every object in Ruby has it defined: Only those that
+# derive from `BasicObject`, or `undef inspect` won't have it. It's used in a few locations,
+# such as `Kernel#p` and `Array#join`.
+#
+interface _Inspect
+  # Returns a debugging representation of `self`.
+  #
+  def inspect: () -> String
+end
+
+interface _Each[out E, out R = void]
+  def each: () { (E) -> void } -> R
+end
+
+interface _EachEntry[out E]
+  def each_entry: () { (E) -> void } -> self
 end
 
 interface _Reader
@@ -44,6 +188,7 @@ end
 
 interface _Writer
   # Writes the +data+ string. Returns the number of bytes written
+  #
   def write: (*_ToS data) -> Integer
 end
 
@@ -53,8 +198,20 @@ interface _Rewindable
   def rewind: () -> Integer
 end
 
-interface _ToIO
-  def to_io: () -> IO
+# A type that's usable like a `Range[T]`.
+#
+# Implicit `_Range` usage is usable frequently in ruby's stdlib, such as `Comparable#clamp`,
+# `String#[]`, and `Kernel#rand`.
+#
+interface _Range[T]
+  # The beginning value, `nil` if there is no beginning.
+  def begin: () -> T?
+
+  # The ending value, `nil` if there is no ending.
+  def end: () -> T?
+
+  # Whether or not to include the end in the range.
+  def exclude_end?: () -> bool
 end
 
 interface _Exception
@@ -62,14 +219,56 @@ interface _Exception
                | (String arg0) -> Exception
 end
 
+# Represents an `Integer`, or a type convertible to it (via `.to_int`).
+#
 type int = Integer | _ToInt
-type real = Integer | Float | Rational
 
+# Represents a `Float`, or a type convertible to it (via `.to_f`).
+#
+type float = Float | _ToF
+
+# Represents a `Range[T]`, or a type that acts like it (via `.begin`, `.end`, and `.exclude_end?`).
+#
+type range[T] = Range[T] | _Range[T]
+
+# Represents a `String`, or a type convertible to it (via `.to_str`).
+#
 type string = String | _ToStr
-type encoding = Encoding | string
 
+# Represents an `Array[T]`, or a type convertible to it (via `.to_ary`).
+#
+type array[T] = Array[T] | _ToAry[T]
+
+# Represents a `Hash[K, V]`, or a type convertible to it (via `.to_hash`).
+#
+type hash[K, V] = Hash[K, V] | _ToHash[K, V]
+
+# Represents an `IO`, or a type convertible to it (via `.to_io`).
+#
 type io = IO | _ToIO
 
+# A filesystem path: Either something that defines `.to_path`, or a `String` (or a type that is
+# convertible to a string via `.to_str`).
+#
+# If a type defines both `.to_path` and `.to_str`, the `.to_path` function is called.
+#
+type path = string | _ToPath
+
+# An `Encoding`, or a `String` (or type that defines `.to_str`) that represents it.
+#
+type encoding = Encoding | string
+
+# A real number, ie not a `Complex`.
+#
+type real = Integer | Float | Rational
+
+# Represents a `Symbol` or a `string`.
+#
+# A lot of builtin functions accept either a Symbol, a String, or something which has `.to_str`
+# defined.
+#
+type interned = Symbol | string
+
 # `boolish` is a type for documentation.
 # It means the value of this type is only for testing a condition.
 # Unlike `bool` type, it doesn't require the value is one of `true` or `false`.

data/core/class.rbs

@@ -106,6 +106,24 @@ class Class < Module
   #
   def allocate: () -> untyped
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - attached_object -> object
+  # -->
+  # Returns the object for which the receiver is the singleton class.
+  #
+  # Raises an TypeError if the class is not a singleton class.
+  #
+  #     class Foo; end
+  #
+  #     Foo.singleton_class.attached_object        #=> Foo
+  #     Foo.attached_object                        #=> TypeError: `Foo' is not a singleton class
+  #     Foo.new.singleton_class.attached_object    #=> #<Foo:0x000000010491a370>
+  #     TrueClass.attached_object                  #=> TypeError: `TrueClass' is not a singleton class
+  #     NilClass.attached_object                   #=> TypeError: `NilClass' is not a singleton class
+  #
+  def attached_object: () -> untyped
+
   # <!--
   #   rdoc-file=object.c
   #   - inherited(subclass)
@@ -160,6 +178,25 @@ class Class < Module
   #     B.subclasses        #=> [C]
   #     C.subclasses        #=> []
   #
+  # Anonymous subclasses (not associated with a constant) are returned, too:
+  #
+  #     c = Class.new(A)
+  #     A.subclasses        # => [#<Class:0x00007f003c77bd78>, D, B]
+  #
+  # Note that the parent does not hold references to subclasses and doesn't
+  # prevent them from being garbage collected. This means that the subclass might
+  # disappear when all references to it are dropped:
+  #
+  #     # drop the reference to subclass, it can be garbage-collected now
+  #     c = nil
+  #
+  #     A.subclasses
+  #     # It can be
+  #     #  => [#<Class:0x00007f003c77bd78>, D, B]
+  #     # ...or just
+  #     #  => [D, B]
+  #     # ...depending on whether garbage collector was run
+  #
   def subclasses: () -> Array[Class]
 
   # <!--