rbs 4.1.0.pre.2-java

data/core/builtin.rbs

@@ -0,0 +1,278 @@
+# 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 `Rational`.
+  #
+  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
+
+interface _Each[out T, out R = void]
+  def each: () { (T) -> void } -> R
+end
+
+interface _EachEntry[out T]
+  def each_entry: () { (T) -> void } -> self
+end
+
+interface _Reader
+  def read: (?int? length, ?string? outbuf) -> String?
+end
+
+interface _ReaderPartial
+  def readpartial: (int maxlen, ?string? outbuf) -> String
+end
+
+interface _Writer
+  # Writes the +data+ string. Returns the number of bytes written
+  #
+  def write: (*_ToS data) -> Integer
+end
+
+interface _Rewindable
+  # Positions the stream to the beginning of input, resetting `lineno` to zero.
+  #
+  def rewind: () -> Integer
+end
+
+# 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
+  def exception: () -> Exception
+               | (String arg0) -> Exception
+end
+
+# Represents an `Integer`, or a type convertible to it (via `.to_int`).
+#
+type int = Integer | _ToInt
+
+# Represents a `Float`, or a type convertible to it (via `.to_f`).
+#
+%a{deprecated: Use `_ToF` directly}
+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
+
+# 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`.
+# Any Ruby object can have `boolish` type.
+#
+type boolish = top

data/core/class.rbs

@@ -0,0 +1,223 @@
+# <!-- rdoc-file=object.c -->
+# Classes in Ruby are first-class objects---each is an instance of class Class.
+#
+# Typically, you create a new class by using:
+#
+#     class Name
+#      # some code describing the class behavior
+#     end
+#
+# When a new class is created, an object of type Class is initialized and
+# assigned to a global constant (Name in this case).
+#
+# When <code>Name.new</code> is called to create a new object, the #new method
+# in Class is run by default. This can be demonstrated by overriding #new in
+# Class:
+#
+#     class Class
+#       alias old_new new
+#       def new(*args)
+#         print "Creating a new ", self.name, "\n"
+#         old_new(*args)
+#       end
+#     end
+#
+#     class Name
+#     end
+#
+#     n = Name.new
+#
+# <em>produces:</em>
+#
+#     Creating a new Name
+#
+# Classes, modules, and objects are interrelated. In the diagram that follows,
+# the vertical arrows represent inheritance, and the parentheses metaclasses.
+# All metaclasses are instances of the class `Class'.
+#                              +---------+             +-...
+#                              |         |             |
+#              BasicObject-----|-->(BasicObject)-------|-...
+#                  ^           |         ^             |
+#                  |           |         |             |
+#               Object---------|----->(Object)---------|-...
+#                  ^           |         ^             |
+#                  |           |         |             |
+#                  +-------+   |         +--------+    |
+#                  |       |   |         |        |    |
+#                  |    Module-|---------|--->(Module)-|-...
+#                  |       ^   |         |        ^    |
+#                  |       |   |         |        |    |
+#                  |     Class-|---------|---->(Class)-|-...
+#                  |       ^   |         |        ^    |
+#                  |       +---+         |        +----+
+#                  |                     |
+#     obj--->OtherClass---------->(OtherClass)-----------...
+#
+%a{annotate:rdoc:source:from=object.c}
+class Class < Module
+  # <!--
+  #   rdoc-file=object.c
+  #   - Class.new(super_class=Object)               -> a_class
+  #   - Class.new(super_class=Object) { |mod| ... } -> a_class
+  # -->
+  # Creates a new anonymous (unnamed) class with the given superclass (or Object
+  # if no parameter is given). You can give a class a name by assigning the class
+  # object to a constant.
+  #
+  # If a block is given, it is passed the class object, and the block is evaluated
+  # in the context of this class like #class_eval.
+  #
+  #     fred = Class.new do
+  #       def meth1
+  #         "hello"
+  #       end
+  #       def meth2
+  #         "bye"
+  #       end
+  #     end
+  #
+  #     a = fred.new     #=> #<#<Class:0x100381890>:0x100376b98>
+  #     a.meth1          #=> "hello"
+  #     a.meth2          #=> "bye"
+  #
+  # Assign the class to a constant (name starting uppercase) if you want to treat
+  # it like a regular class.
+  #
+  def initialize: (?Class superclass) ?{ (Class newclass) [self: Class] -> void } -> void
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - class.allocate()   ->   obj
+  # -->
+  # Allocates space for a new object of *class*'s class and does not call
+  # initialize on the new instance. The returned object must be an instance of
+  # *class*.
+  #
+  #     klass = Class.new do
+  #       def initialize(*args)
+  #         @initialized = true
+  #       end
+  #
+  #       def initialized?
+  #         @initialized || false
+  #       end
+  #     end
+  #
+  #     klass.allocate.initialized? #=> false
+  #
+  def allocate: () -> untyped
+
+  def self.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)
+  # -->
+  # Callback invoked whenever a subclass of the current class is created.
+  #
+  # Example:
+  #
+  #     class Foo
+  #       def self.inherited(subclass)
+  #         puts "New subclass: #{subclass}"
+  #       end
+  #     end
+  #
+  #     class Bar < Foo
+  #     end
+  #
+  #     class Baz < Bar
+  #     end
+  #
+  # <em>produces:</em>
+  #
+  #     New subclass: Bar
+  #     New subclass: Baz
+  #
+  private def inherited: (Class subclass) -> void
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - class.new(args, ...)    ->  obj
+  # -->
+  # Calls #allocate to create a new object of *class*'s class, then invokes that
+  # object's #initialize method, passing it *args*.  This is the method that ends
+  # up getting called whenever an object is constructed using <code>.new</code>.
+  #
+  def new: (*untyped, **untyped) ?{ (?) -> untyped } -> untyped
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - subclasses -> array
+  # -->
+  # Returns an array of classes where the receiver is the direct superclass of the
+  # class, excluding singleton classes. The order of the returned array is not
+  # defined.
+  #
+  #     class A; end
+  #     class B < A; end
+  #     class C < B; end
+  #     class D < A; end
+  #
+  #     A.subclasses        #=> [D, B]
+  #     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]
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - class.superclass -> a_super_class or nil
+  # -->
+  # Returns the superclass of *class*, or `nil`.
+  #
+  #     File.superclass          #=> IO
+  #     IO.superclass            #=> Object
+  #     Object.superclass        #=> BasicObject
+  #     class Foo; end
+  #     class Bar < Foo; end
+  #     Bar.superclass           #=> Foo
+  #
+  # Returns nil when the given class does not have a parent class:
+  #
+  #     BasicObject.superclass   #=> nil
+  #
+  def superclass: () -> Class?
+end

data/core/comparable.rbs

@@ -0,0 +1,192 @@
+# <!-- rdoc-file=compar.c -->
+# The Comparable mixin is used by classes whose objects may be ordered. The
+# class must define the <code><=></code> operator, which compares the receiver
+# against another object, returning a value less than 0, returning 0, or
+# returning a value greater than 0, depending on whether the receiver is less
+# than, equal to, or greater than the other object. If the other object is not
+# comparable then the <code><=></code> operator should return `nil`. Comparable
+# uses <code><=></code> to implement the conventional comparison operators
+# (<code><</code>, <code><=</code>, <code>==</code>, <code>>=</code>, and
+# <code>></code>) and the method <code>between?</code>.
+#
+#     class StringSorter
+#       include Comparable
+#
+#       attr :str
+#       def <=>(other)
+#         str.size <=> other.str.size
+#       end
+#
+#       def initialize(str)
+#         @str = str
+#       end
+#
+#       def inspect
+#         @str
+#       end
+#     end
+#
+#     s1 = StringSorter.new("Z")
+#     s2 = StringSorter.new("YY")
+#     s3 = StringSorter.new("XXX")
+#     s4 = StringSorter.new("WWWW")
+#     s5 = StringSorter.new("VVVVV")
+#
+#     s1 < s2                       #=> true
+#     s4.between?(s1, s3)           #=> false
+#     s4.between?(s3, s5)           #=> true
+#     [ s3, s2, s5, s4, s1 ].sort   #=> [Z, YY, XXX, WWWW, VVVVV]
+#
+# ## What's Here
+#
+# Module Comparable provides these methods, all of which use method
+# <code>#<=></code>:
+#
+# *   #<: Returns whether `self` is less than the given object.
+# *   #<=: Returns whether `self` is less than or equal to the given object.
+# *   #==: Returns whether `self` is equal to the given object.
+# *   #>: Returns whether `self` is greater than the given object.
+# *   #>=: Returns whether `self` is greater than or equal to the given object.
+# *   #between?: Returns `true` if `self` is between two given objects.
+# *   #clamp: For given objects `min` and `max`, or range
+#     <code>(min..max)</code>, returns:
+#
+#     *   `min` if <code>(self <=> min) < 0</code>.
+#     *   `max` if <code>(self <=> max) > 0</code>.
+#     *   `self` otherwise.
+#
+module Comparable : _WithSpaceshipOperator
+  # <!--
+  #   rdoc-file=compar.c
+  #   - self < other -> true or false
+  # -->
+  # Returns whether `self` is "less than" `other`; equivalent to <code>(self <=>
+  # other) < 0</code>:
+  #
+  #     'foo' < 'foo'  # => false
+  #     'foo' < 'food' # => true
+  #
+  def <: (untyped other) -> bool
+
+  # <!--
+  #   rdoc-file=compar.c
+  #   - self <= other -> true or false
+  # -->
+  # Returns whether `self` is "less than or equal to" `other`; equivalent to
+  # <code>(self <=> other) <= 0</code>:
+  #
+  #     'foo' <= 'foo'  # => true
+  #     'foo' <= 'food' # => true
+  #     'food' <= 'foo' # => false
+  #
+  def <=: (untyped other) -> bool
+
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj == other    -> true or false
+  # -->
+  # Compares two objects based on the receiver's <code><=></code> method,
+  # returning true if it returns 0. Also returns true if *obj* and *other* are the
+  # same object.
+  #
+  def ==: (untyped other) -> bool
+
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj > other    -> true or false
+  # -->
+  # Compares two objects based on the receiver's <code><=></code> method,
+  # returning true if it returns a value greater than 0.
+  #
+  def >: (untyped other) -> bool
+
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj >= other    -> true or false
+  # -->
+  # Compares two objects based on the receiver's <code><=></code> method,
+  # returning true if it returns a value greater than or equal to 0.
+  #
+  def >=: (untyped other) -> bool
+
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj.between?(min, max)    -> true or false
+  # -->
+  # Returns `false` if *obj* <code><=></code> *min* is less than zero or if *obj*
+  # <code><=></code> *max* is greater than zero, `true` otherwise.
+  #
+  #     3.between?(1, 5)               #=> true
+  #     6.between?(1, 5)               #=> false
+  #     'cat'.between?('ant', 'dog')   #=> true
+  #     'gnu'.between?('ant', 'dog')   #=> false
+  #
+  def between?: (untyped min, untyped max) -> bool
+
+  # <!--
+  #   rdoc-file=compar.c
+  #   - obj.clamp(min, max) ->  obj
+  #   - obj.clamp(range)    ->  obj
+  # -->
+  # In <code>(min, max)</code> form, returns *min* if *obj* <code><=></code> *min*
+  # is less than zero, *max* if *obj* <code><=></code> *max* is greater than zero,
+  # and *obj* otherwise.
+  #
+  #     12.clamp(0, 100)         #=> 12
+  #     523.clamp(0, 100)        #=> 100
+  #     -3.123.clamp(0, 100)     #=> 0
+  #
+  #     'd'.clamp('a', 'f')      #=> 'd'
+  #     'z'.clamp('a', 'f')      #=> 'f'
+  #
+  # If *min* is `nil`, it is considered smaller than *obj*, and if *max* is `nil`,
+  # it is considered greater than *obj*.
+  #
+  #     -20.clamp(0, nil)           #=> 0
+  #     523.clamp(nil, 100)         #=> 100
+  #
+  # In <code>(range)</code> form, returns <em>range.begin</em> if *obj*
+  # <code><=></code> <em>range.begin</em> is less than zero, <em>range.end</em> if
+  # *obj* <code><=></code> <em>range.end</em> is greater than zero, and *obj*
+  # otherwise.
+  #
+  #     12.clamp(0..100)         #=> 12
+  #     523.clamp(0..100)        #=> 100
+  #     -3.123.clamp(0..100)     #=> 0
+  #
+  #     'd'.clamp('a'..'f')      #=> 'd'
+  #     'z'.clamp('a'..'f')      #=> 'f'
+  #
+  # If <em>range.begin</em> is `nil`, it is considered smaller than *obj*, and if
+  # <em>range.end</em> is `nil`, it is considered greater than *obj*.
+  #
+  #     -20.clamp(0..)           #=> 0
+  #     523.clamp(..100)         #=> 100
+  #
+  # When <em>range.end</em> is excluded and not `nil`, an exception is raised.
+  #
+  #     100.clamp(0...100)       # ArgumentError
+  #
+  def clamp: [A, B] (A min, B max) -> (self | A | B)
+           | [A] (Range[A]) -> (self | A)
+end
+
+# This interface defines the condition for Comparable mixin.
+#
+interface Comparable::_WithSpaceshipOperator
+  # `<=>` operator must return Integer or `nil`.
+  # If `other` is greater than `self`, it returns a positive Integer.
+  # If `other` equals to `self`, it returns zero.
+  # If `other` is less than `self`, it returns a positive Integer.
+  # If no comparison is defined with `other` and `self`, it returns `nil`.
+  #
+  def <=>: (untyped other) -> Comparable::_CompareToZero?
+end
+
+# This interface indicates a type is comparable against zero.
+#
+interface Comparable::_CompareToZero
+  def <: (0) -> boolish
+
+  def >: (0) -> boolish
+end