rbs 3.0.0.dev.2 → 3.0.0.dev.3

data/core/basic_object.rbs

@@ -49,45 +49,17 @@
 #
 # 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.
 #
 class BasicObject
   # <!--

data/core/binding.rbs

@@ -52,7 +52,7 @@ class Binding
 
   # <!--
   #   rdoc-file=lib/irb.rb
-  #   - irb()
+  #   - irb(show_code: true)
   # -->
   # Opens an IRB session where `binding.irb` is called which allows for
   # interactive debugging. You can call any methods or variables available in the

data/core/builtin.rbs

@@ -14,6 +14,10 @@ interface _ToS
   def to_s: () -> String
 end
 
+interface _ToF
+  def to_f: () -> Float
+end
+
 interface _ToStr
   def to_str: () -> String
 end
@@ -34,6 +38,10 @@ interface _Each[out A]
   def each: () { (A) -> void } -> void
 end
 
+interface _EachEntry[out A]
+  def each_entry: () { (A) -> void } -> self
+end
+
 interface _Reader
   def read: (?int? length, ?string outbuf) -> String?
 end

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]
 
   # <!--

data/core/comparable.rbs

@@ -37,24 +37,13 @@
 #
 # Module Comparable provides these methods, all of which use method `<=>`:
 #
-#     [<](#method-i-3C)
-# :       Returns whether `self` is less than the given object.
-#
-#     [<=](#method-i-3C-3D)
-# :       Returns whether `self` is less than or equal to the given object.
-#
-#     [==](#method-i-3D-3D)
-# :       Returns whether `self` is equal to the given object.
-#
-#     [>](#method-i-3E)
-# :       Returns whether `self` is greater than or equal to the given object.
-#
-#     [>=](#method-i-3E-3D)
-# :       Returns whether `self` is greater than the given object.
-#
-# *   #between? Returns `true` if `self` is between two given objects.
-#     #clamp
-# :       For given objects `min` and `max`, or range `(min..max)`, returns:
+# *   #<: 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 or equal to the given object.
+# *   #>=: Returns whether `self` is greater than the given object.
+# *   #between?: Returns `true` if `self` is between two given objects.
+# *   #clamp: For given objects `min` and `max`, or range `(min..max)`, returns:
 #
 #     *   `min` if `(self <=> min) < 0`.
 #     *   `max` if `(self <=> max) > 0`.

data/core/complex.rbs

@@ -5,12 +5,12 @@
 #
 # You can create a Complex object explicitly with:
 #
-# *   A [complex literal](doc/syntax/literals_rdoc.html#label-Complex+Literals).
+# *   A [complex literal](rdoc-ref:syntax/literals.rdoc@Complex+Literals).
 #
 #
 # You can convert certain objects to Complex objects with:
 #
-# *   Method [Complex](Kernel.html#method-i-Complex).
+# *   Method #Complex.
 #
 #
 # Complex object can be created as literal, and also by using Kernel#Complex,

data/core/data.rbs

@@ -0,0 +1,419 @@
+# <!-- rdoc-file=struct.c -->
+# Class Data provides a convenient way to define simple classes for value-alike
+# objects.
+#
+# The simplest example of usage:
+#
+#     Measure = Data.define(:amount, :unit)
+#
+#     # Positional arguments constructor is provided
+#     distance = Measure.new(100, 'km')
+#     #=> #<data Measure amount=100, unit="km">
+#
+#     # Keyword arguments constructor is provided
+#     weight = Measure.new(amount: 50, unit: 'kg')
+#     #=> #<data Measure amount=50, unit="kg">
+#
+#     # Alternative form to construct an object:
+#     speed = Measure[10, 'mPh']
+#     #=> #<data Measure amount=10, unit="mPh">
+#
+#     # Works with keyword arguments, too:
+#     area = Measure[amount: 1.5, unit: 'm^2']
+#     #=> #<data Measure amount=1.5, unit="m^2">
+#
+#     # Argument accessors are provided:
+#     distance.amount #=> 100
+#     distance.unit #=> "km"
+#
+# Constructed object also has a reasonable definitions of #== operator, #to_h
+# hash conversion, and #deconstruct/#deconstruct_keys to be used in pattern
+# matching.
+#
+# ::define method accepts an optional block and evaluates it in the context of
+# the newly defined class. That allows to define additional methods:
+#
+#     Measure = Data.define(:amount, :unit) do
+#       def <=>(other)
+#         return unless other.is_a?(self.class) && other.unit == unit
+#         amount <=> other.amount
+#       end
+#
+#       include Comparable
+#     end
+#
+#     Measure[3, 'm'] < Measure[5, 'm'] #=> true
+#     Measure[3, 'm'] < Measure[5, 'kg']
+#     # comparison of Measure with Measure failed (ArgumentError)
+#
+# Data provides no member writers, or enumerators: it is meant to be a storage
+# for immutable atomic values. But note that if some of data members is of a
+# mutable class, Data does no additional immutability enforcement:
+#
+#     Event = Data.define(:time, :weekdays)
+#     event = Event.new('18:00', %w[Tue Wed Fri])
+#     #=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri"]>
+#
+#     # There is no #time= or #weekdays= accessors, but changes are
+#     # still possible:
+#     event.weekdays << 'Sat'
+#     event
+#     #=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri", "Sat"]>
+#
+# See also Struct, which is a similar concept, but has more container-alike API,
+# allowing to change contents of the object and enumerate it.
+#
+class Data
+  # <!--
+  #   rdoc-file=struct.c
+  #   - define(name, *symbols) -> class
+  #   - define(*symbols) -> class
+  # -->
+  # Defines a new Data class. If the first argument is a string, the class is
+  # stored in `Data::<name>` constant.
+  #
+  #     measure = Data.define(:amount, :unit)
+  #     #=> #<Class:0x00007f70c6868498>
+  #     measure.new(1, 'km')
+  #     #=> #<data amount=1, unit="km">
+  #
+  #     # It you store the new class in the constant, it will
+  #     # affect #inspect and will be more natural to use:
+  #     Measure = Data.define(:amount, :unit)
+  #     #=> Measure
+  #     Measure.new(1, 'km')
+  #     #=> #<data Measure amount=1, unit="km">
+  #
+  # Note that member-less Data is acceptable and might be a useful technique for
+  # defining several homogenous data classes, like
+  #
+  #     class HTTPFetcher
+  #       Response = Data.define(:body)
+  #       NotFound = Data.define
+  #       # ... implementation
+  #     end
+  #
+  # Now, different kinds of responses from `HTTPFetcher` would have consistent
+  # representation:
+  #
+  #     #<data HTTPFetcher::Response body="<html...">
+  #     #<data HTTPFetcher::NotFound>
+  #
+  # And are convenient to use in pattern matching:
+  #
+  #     case fetcher.get(url)
+  #     in HTTPFetcher::Response(body)
+  #       # process body variable
+  #     in HTTPFetcher::NotFound
+  #       # handle not found case
+  #     end
+  #
+  def self.define: [KLASS < _DataClass] (*Symbol) ?{ (KLASS) [self: KLASS] -> void } -> KLASS
+
+  interface _DataClass
+    # <!--
+    #   rdoc-file=struct.c
+    #   - new(*args) -> instance
+    #   - new(**kwargs) -> instance
+    #   - ::[](*args) -> instance
+    #   - ::[](**kwargs) -> instance
+    # -->
+    # Constructors for classes defined with ::define accept both positional and
+    # keyword arguments.
+    #
+    #     Measure = Data.define(:amount, :unit)
+    #
+    #     Measure.new(1, 'km')
+    #     #=> #<data Measure amount=1, unit="km">
+    #     Measure.new(amount: 1, unit: 'km')
+    #     #=> #<data Measure amount=1, unit="km">
+    #
+    #     # Alternative shorter intialization with []
+    #     Measure[1, 'km']
+    #     #=> #<data Measure amount=1, unit="km">
+    #     Measure[amount: 1, unit: 'km']
+    #     #=> #<data Measure amount=1, unit="km">
+    #
+    # All arguments are mandatory (unlike Struct), and converted to keyword
+    # arguments:
+    #
+    #     Measure.new(amount: 1)
+    #     # in `initialize': missing keyword: :unit (ArgumentError)
+    #
+    #     Measure.new(1)
+    #     # in `initialize': missing keyword: :unit (ArgumentError)
+    #
+    # Note that `Measure#initialize` always receives keyword arguments, and that
+    # mandatory arguments are checked in `initialize`, not in `new`. This can be
+    # important for redefining initialize in order to convert arguments or provide
+    # defaults:
+    #
+    #     Measure = Data.define(:amount, :unit) do
+    #       NONE = Data.define
+    #
+    #       def initialize(amount:, unit: NONE.new)
+    #         super(amount: Float(amount), unit:)
+    #       end
+    #     end
+    #
+    #     Measure.new('10', 'km') # => #<data Measure amount=10.0, unit="km">
+    #     Measure.new(10_000)     # => #<data Measure amount=10000.0, unit=#<data NONE>>
+    #
+    %a{annotate:rdoc:copy:Data.new}
+    def new: (*untyped) -> Data
+           | (**untyped) -> Data
+
+    %a{annotate:rdoc:copy:Data.[]}
+    def []: (*untyped) -> Data
+          | (**untyped) -> Data
+
+    # <!--
+    #   rdoc-file=struct.c
+    #   - DataClass::members -> array_of_symbols
+    # -->
+    # Returns an array of member names of the data class:
+    #
+    #     Measure = Data.define(:amount, :unit)
+    #     Measure.members # => [:amount, :unit]
+    #
+    %a{annotate:rdoc:copy:Data.members}
+    def members: () -> Array[Symbol]
+  end
+
+  %a{annotate:rdoc:skip}
+  def self.new: () -> bot
+
+  def self.allocate: () -> bot
+
+  public
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - self == other -> true or false
+  # -->
+  # Returns  `true` if `other` is the same class as `self`, and all members are
+  # equal.
+  #
+  # Examples:
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #
+  #     Measure[1, 'km'] == Measure[1, 'km'] #=> true
+  #     Measure[1, 'km'] == Measure[2, 'km'] #=> false
+  #     Measure[1, 'km'] == Measure[1, 'm']  #=> false
+  #
+  #     Measurement = Data.define(:amount, :unit)
+  #     # Even though Measurement and Measure have the same "shape"
+  #     # their instances are never equal
+  #     Measure[1, 'km'] == Measurement[1, 'km'] #=> false
+  #
+  def ==: (untyped) -> bool
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - deconstruct     -> array
+  # -->
+  # Returns the values in `self` as an array, to use in pattern matching:
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #
+  #     distance = Measure[10, 'km']
+  #     distance.deconstruct #=> [10, "km"]
+  #
+  #     # usage
+  #     case distance
+  #     in n, 'km' # calls #deconstruct underneath
+  #       puts "It is #{n} kilometers away"
+  #     else
+  #       puts "Don't know how to handle it"
+  #     end
+  #     # prints "It is 10 kilometers away"
+  #
+  # Or, with checking the class, too:
+  #
+  #     case distance
+  #     in Measure(n, 'km')
+  #       puts "It is #{n} kilometers away"
+  #     # ...
+  #     end
+  #
+  def deconstruct: () -> Array[untyped]
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - deconstruct_keys(array_of_names_or_nil) -> hash
+  # -->
+  # Returns a hash of the name/value pairs, to use in pattern matching.
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #
+  #     distance = Measure[10, 'km']
+  #     distance.deconstruct_keys(nil) #=> {:amount=>10, :unit=>"km"}
+  #     distance.deconstruct_keys([:amount]) #=> {:amount=>10}
+  #
+  #     # usage
+  #     case distance
+  #     in amount:, unit: 'km' # calls #deconstruct_keys underneath
+  #       puts "It is #{amount} kilometers away"
+  #     else
+  #       puts "Don't know how to handle it"
+  #     end
+  #     # prints "It is 10 kilometers away"
+  #
+  # Or, with checking the class, too:
+  #
+  #     case distance
+  #     in Measure(amount:, unit: 'km')
+  #       puts "It is #{amount} kilometers away"
+  #     # ...
+  #     end
+  #
+  def deconstruct_keys: (?Array[Symbol]?) -> Hash[Symbol, untyped]
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - self.eql?(other) -> true or false
+  # -->
+  # Equality check that is used when two items of data are keys of a Hash.
+  #
+  # The subtle difference with #== is that members are also compared with their
+  # #eql? method, which might be important in some cases:
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #
+  #     Measure[1, 'km'] == Measure[1.0, 'km'] #=> true, they are equal as values
+  #     # ...but...
+  #     Measure[1, 'km'].eql? Measure[1.0, 'km'] #=> false, they represent different hash keys
+  #
+  # See also Object#eql? for further explanations of the method usage.
+  #
+  def eql?: (untyped) -> bool
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - hash -> integer
+  # -->
+  # Redefines Object#hash (used to distinguish objects as Hash keys) so that data
+  # objects of the same class with same content would have the same `hash` value,
+  # and represented the same Hash key.
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #
+  #     Measure[1, 'km'].hash == Measure[1, 'km'].hash #=> true
+  #     Measure[1, 'km'].hash == Measure[10, 'km'].hash #=> false
+  #     Measure[1, 'km'].hash == Measure[1, 'm'].hash #=> false
+  #     Measure[1, 'km'].hash == Measure[1.0, 'km'].hash #=> false
+  #
+  #     # Structurally similar data class, but shouldn't be considered
+  #     # the same hash key
+  #     Measurement = Data.define(:amount, :unit)
+  #
+  #     Measure[1, 'km'].hash == Measurement[1, 'km'].hash #=> false
+  #
+  def hash: () -> Integer
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - inspect -> string
+  #   - to_s -> string
+  # -->
+  # Returns a string representation of `self`:
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #
+  #     distance = Measure[10, 'km']
+  #
+  #     p distance  # uses #inspect underneath
+  #     #<data Measure amount=10, unit="km">
+  #
+  #     puts distance  # uses #to_s underneath, same representation
+  #     #<data Measure amount=10, unit="km">
+  #
+  def inspect: () -> String
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - members -> array_of_symbols
+  # -->
+  # Returns the member names from `self` as an array:
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #     distance = Measure[10, 'km']
+  #
+  #     distance.members #=> [:amount, :unit]
+  #
+  def members: () -> Array[Symbol]
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - to_h -> hash
+  #   - to_h {|name, value| ... } -> hash
+  # -->
+  # Returns Hash representation of the data object.
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #     distance = Measure[10, 'km']
+  #
+  #     distance.to_h
+  #     #=> {:amount=>10, :unit=>"km"}
+  #
+  # Like Enumerable#to_h, if the block is provided, it is expected to produce
+  # key-value pairs to construct a hash:
+  #
+  #     distance.to_h { |name, val| [name.to_s, val.to_s] }
+  #     #=> {"amount"=>"10", "unit"=>"km"}
+  #
+  # Note that there is a useful symmetry between #to_h and #initialize:
+  #
+  #     distance2 = Measure.new(**distance.to_h)
+  #     #=> #<data Measure amount=10, unit="km">
+  #     distance2 == distance
+  #     #=> true
+  #
+  def to_h: () -> Hash[Symbol, untyped]
+
+  # <!-- rdoc-file=struct.c -->
+  # Returns a string representation of `self`:
+  #
+  #     Measure = Data.define(:amount, :unit)
+  #
+  #     distance = Measure[10, 'km']
+  #
+  #     p distance  # uses #inspect underneath
+  #     #<data Measure amount=10, unit="km">
+  #
+  #     puts distance  # uses #to_s underneath, same representation
+  #     #<data Measure amount=10, unit="km">
+  #
+  alias to_s inspect
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - with(**kwargs) -> instance
+  # -->
+  # Returns a shallow copy of `self` --- the instance variables of `self` are
+  # copied, but not the objects they reference.
+  #
+  # If the method is supplied any keyword arguments, the copy will be created with
+  # the respective field values updated to use the supplied keyword argument
+  # values. Note that it is an error to supply a keyword that the Data class does
+  # not have as a member.
+  #
+  #     Point = Data.define(:x, :y)
+  #
+  #     origin = Point.new(x: 0, y: 0)
+  #
+  #     up = origin.with(x: 1)
+  #     right = origin.with(y: 1)
+  #     up_and_right = up.with(y: 1)
+  #
+  #     p origin       # #<data Point x=0, y=0>
+  #     p up           # #<data Point x=1, y=0>
+  #     p right        # #<data Point x=0, y=1>
+  #     p up_and_right # #<data Point x=1, y=1>
+  #
+  #     out = origin.with(z: 1) # ArgumentError: unknown keyword: :z
+  #     some_point = origin.with(1, 2) # ArgumentError: expected keyword arguments, got positional arguments
+  #
+  def with: (**untyped) -> instance
+end