rbs 3.2.2 → 3.3.0.pre.1

data/core/builtin.rbs

@@ -1,60 +1,172 @@
+# 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
 
+# 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
+  # 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
 
+# 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
 
@@ -76,6 +188,7 @@ end
 
 interface _Writer
   # Writes the +data+ string. Returns the number of bytes written
+  #
   def write: (*_ToS data) -> Integer
 end
 
@@ -85,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
@@ -94,15 +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
-type path = string | _ToPath
 
+# 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/constants.rbs

@@ -4,16 +4,16 @@
 #
 # See ARGF (the class) for more details.
 #
-::ARGF: RBS::Unnamed::ARGFClass
+ARGF: RBS::Unnamed::ARGFClass
 
 # <!-- rdoc-file=ruby.c -->
 # ARGV contains the command line arguments used to run ruby.
 #
 # A library like OptionParser can be used to process command-line arguments.
 #
-::ARGV: Array[String]
+ARGV: Array[String]
 
-::CROSS_COMPILING: NilClass
+CROSS_COMPILING: true?
 
 # <!-- rdoc-file=ruby.c -->
 # DATA is a File that contains the data section of the executed file. To create
@@ -27,70 +27,70 @@
 #     $ ruby t.rb
 #     hello world!
 #
-::DATA: File
+DATA: File
 
 # <!-- rdoc-file=version.c -->
 # The copyright string for ruby
 #
-::RUBY_COPYRIGHT: String
+RUBY_COPYRIGHT: String
 
 # <!-- rdoc-file=version.c -->
 # The full ruby version string, like `ruby -v` prints
 #
-::RUBY_DESCRIPTION: String
+RUBY_DESCRIPTION: String
 
 # <!-- rdoc-file=version.c -->
 # The engine or interpreter this ruby uses.
 #
-::RUBY_ENGINE: String
+RUBY_ENGINE: String
 
 # <!-- rdoc-file=version.c -->
 # The version of the engine or interpreter this ruby uses.
 #
-::RUBY_ENGINE_VERSION: String
+RUBY_ENGINE_VERSION: String
 
 # <!-- rdoc-file=version.c -->
 # The patchlevel for this ruby.  If this is a development build of ruby the
 # patchlevel will be -1
 #
-::RUBY_PATCHLEVEL: Integer
+RUBY_PATCHLEVEL: Integer
 
 # <!-- rdoc-file=version.c -->
 # The platform for this ruby
 #
-::RUBY_PLATFORM: String
+RUBY_PLATFORM: String
 
 # <!-- rdoc-file=version.c -->
 # The date this ruby was released
 #
-::RUBY_RELEASE_DATE: String
+RUBY_RELEASE_DATE: String
 
 # <!-- rdoc-file=version.c -->
 # The GIT commit hash for this ruby.
 #
-::RUBY_REVISION: Integer
+RUBY_REVISION: String
 
 # <!-- rdoc-file=version.c -->
 # The running version of ruby
 #
-::RUBY_VERSION: String
+RUBY_VERSION: String
 
 # <!-- rdoc-file=io.c -->
 # Holds the original stderr
 #
-::STDERR: IO
+STDERR: IO
 
 # <!-- rdoc-file=io.c -->
 # Holds the original stdin
 #
-::STDIN: IO
+STDIN: IO
 
 # <!-- rdoc-file=io.c -->
 # Holds the original stdout
 #
-::STDOUT: IO
+STDOUT: IO
 
 # <!-- rdoc-file=vm.c -->
 # The Binding of the top level scope
 #
-::TOPLEVEL_BINDING: Binding
+TOPLEVEL_BINDING: Binding

data/core/dir.rbs

@@ -241,7 +241,7 @@ class Dir
   # -->
   # Returns `true` if the named file is a directory, `false` otherwise.
   #
-  def self.exist?: (path | _ToIO file_name) -> bool
+  def self.exist?: (path | io file_name) -> bool
 
   # <!--
   #   rdoc-file=dir.c
@@ -371,8 +371,8 @@ class Dir
   #
   #     Dir.glob("**/lib/*.rb")             #=> ["lib/song.rb"]
   #
-  def self.glob: (_ToAry[path] | path pattern, ?int flags, ?base: path?, ?sort: bool) -> Array[String]
-               | (_ToAry[path] | path pattern, ?int flags, ?base: path?, ?sort: bool) { (String pathname) -> void } -> nil
+  def self.glob: (array[path] | path pattern, ?int flags, ?base: path?, ?sort: bool) -> Array[String]
+               | (array[path] | path pattern, ?int flags, ?base: path?, ?sort: bool) { (String pathname) -> void } -> nil
 
   # <!--
   #   rdoc-file=dir.c