rbs 2.8.4 → 3.8.1

data/core/true_class.rbs

@@ -1,72 +1,98 @@
 # <!-- rdoc-file=object.c -->
-# The global value `true` is the only instance of class TrueClass and represents
-# a logically true value in boolean expressions. The class provides operators
-# allowing `true` to be used in logical expressions.
+# The class of the singleton object `true`.
+#
+# Several of its methods act as operators:
+#
+# *   #&
+# *   #|
+# *   #===
+# *   #^
+#
+# One other method:
+#
+# *   #to_s and its alias #inspect.
 #
 class TrueClass
-  public
-
   def !: () -> false
 
   # <!--
   #   rdoc-file=object.c
-  #   - true & obj    -> true or false
+  #   - true & object -> true or false
   # -->
-  # And---Returns `false` if *obj* is `nil` or `false`, `true` otherwise.
+  # Returns `false` if `object` is `false` or `nil`, `true` otherwise:
+  #
+  # true & Object.new # => true true & false      # => false true & nil        #
+  # => false
   #
-  def &: (nil) -> false
-       | (false) -> false
-       | (untyped obj) -> true
+  def &: (false | nil) -> false
+       | (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=object.c
-  #   - obj === other   -> true or false
+  #   - true === other -> true or false
+  #   - false === other -> true or false
+  #   - nil === other -> true or false
   # -->
-  # Case Equality -- For class Object, effectively the same as calling `#==`, but
-  # typically overridden by descendants to provide meaningful semantics in `case`
-  # statements.
+  # Returns `true` or `false`.
+  #
+  # Like Object#==, if `object` is an instance of Object (and not an instance of
+  # one of its many subclasses).
+  #
+  # This method is commonly overridden by those subclasses, to provide meaningful
+  # semantics in `case` statements.
   #
   def ===: (true) -> true
-         | (untyped obj) -> false
+         | (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=object.c
-  #   - true ^ obj   -> !obj
+  #   - true ^ object -> !object
   # -->
-  # Exclusive Or---Returns `true` if *obj* is `nil` or `false`, `false` otherwise.
+  # Returns `true` if `object` is `false` or `nil`, `false` otherwise:
+  #
+  #     true ^ Object.new # => false
+  #     true ^ false      # => true
+  #     true ^ nil        # => true
   #
-  def ^: (nil) -> true
-       | (false) -> true
-       | (untyped obj) -> false
+  def ^: (false | nil) -> true
+       | (untyped obj) -> bool
 
   # <!-- rdoc-file=object.c -->
-  # The string representation of `true` is "true".
+  # Returns string `'true'`:
+  #
+  #     true.to_s # => "true"
+  #
+  # TrueClass#inspect is an alias for TrueClass#to_s.
   #
   alias inspect to_s
 
   # <!--
   #   rdoc-file=object.c
-  #   - true.to_s   ->  "true"
+  #   - true.to_s -> 'true'
   # -->
-  # The string representation of `true` is "true".
+  # Returns string `'true'`:
+  #
+  #     true.to_s # => "true"
+  #
+  # TrueClass#inspect is an alias for TrueClass#to_s.
   #
   def to_s: () -> "true"
 
   # <!--
   #   rdoc-file=object.c
-  #   - true | obj   -> true
+  #   - true | object -> true
   # -->
-  # Or---Returns `true`. As *obj* is an argument to a method call, it is always
-  # evaluated; there is no short-circuit evaluation in this case.
+  # Returns `true`:
   #
-  #     true |  puts("or")
-  #     true || puts("logical or")
+  #     true | Object.new # => true
+  #     true | false      # => true
+  #     true | nil        # => true
   #
-  # *produces:*
+  # Argument `object` is evaluated. This is different from `true` with the
+  # short-circuit operator, whose operand is evaluated only if necessary:
   #
-  #     or
+  #     true | raise # => Raises RuntimeError.
+  #     true || raise # => true
   #
   def |: (untyped obj) -> true
-
-  def clone: (?freeze: true?) -> self
 end

data/core/unbound_method.rbs

@@ -46,6 +46,44 @@
 #     um.bind(t).call   #=> :original
 #
 class UnboundMethod
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.eql?(other_meth)  -> true or false
+  #   - meth == other_meth  -> true or false
+  # -->
+  # Two unbound method objects are equal if they refer to the same method
+  # definition.
+  #
+  #     Array.instance_method(:each_slice) == Enumerable.instance_method(:each_slice)
+  #     #=> true
+  #
+  #     Array.instance_method(:sum) == Enumerable.instance_method(:sum)
+  #     #=> false, Array redefines the method for efficiency
+  #
+  def ==: (untyped other) -> bool
+
+  # <!-- rdoc-file=proc.c -->
+  # Two unbound method objects are equal if they refer to the same method
+  # definition.
+  #
+  #     Array.instance_method(:each_slice) == Enumerable.instance_method(:each_slice)
+  #     #=> true
+  #
+  #     Array.instance_method(:sum) == Enumerable.instance_method(:sum)
+  #     #=> false, Array redefines the method for efficiency
+  #
+  alias eql? ==
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.hash   -> integer
+  # -->
+  # Returns a hash value corresponding to the method object.
+  #
+  # See also Object#hash.
+  #
+  def hash: () -> Integer
+
   # <!--
   #   rdoc-file=proc.c
   #   - method.clone -> new_method
@@ -62,7 +100,7 @@ class UnboundMethod
   #     m.call # => "bar"
   #     n = m.clone.call # => "bar"
   #
-  def clone: () -> self
+  def clone: () -> instance
 
   # <!--
   #   rdoc-file=proc.c
@@ -141,6 +179,66 @@ class UnboundMethod
   #
   def bind: (untyped obj) -> Method
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.to_s      ->  string
+  #   - meth.inspect   ->  string
+  # -->
+  # Returns a human-readable description of the underlying method.
+  #
+  #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
+  #     (1..3).method(:map).inspect    #=> "#<Method: Range(Enumerable)#map()>"
+  #
+  # In the latter case, the method description includes the "owner" of the
+  # original method (`Enumerable` module, which is included into `Range`).
+  #
+  # `inspect` also provides, when possible, method argument names (call sequence)
+  # and source location.
+  #
+  #     require 'net/http'
+  #     Net::HTTP.method(:get).inspect
+  #     #=> "#<Method: Net::HTTP.get(uri_or_host, path=..., port=...) <skip>/lib/ruby/2.7.0/net/http.rb:457>"
+  #
+  # `...` in argument definition means argument is optional (has some default
+  # value).
+  #
+  # For methods defined in C (language core and extensions), location and argument
+  # names can't be extracted, and only generic information is provided in form of
+  # `*` (any number of arguments) or `_` (some positional argument).
+  #
+  #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
+  #     "cat".method(:+).inspect       #=> "#<Method: String#+(_)>""
+  #
+  def inspect: () -> String
+
+  # <!-- rdoc-file=proc.c -->
+  # Returns a human-readable description of the underlying method.
+  #
+  #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
+  #     (1..3).method(:map).inspect    #=> "#<Method: Range(Enumerable)#map()>"
+  #
+  # In the latter case, the method description includes the "owner" of the
+  # original method (`Enumerable` module, which is included into `Range`).
+  #
+  # `inspect` also provides, when possible, method argument names (call sequence)
+  # and source location.
+  #
+  #     require 'net/http'
+  #     Net::HTTP.method(:get).inspect
+  #     #=> "#<Method: Net::HTTP.get(uri_or_host, path=..., port=...) <skip>/lib/ruby/2.7.0/net/http.rb:457>"
+  #
+  # `...` in argument definition means argument is optional (has some default
+  # value).
+  #
+  # For methods defined in C (language core and extensions), location and argument
+  # names can't be extracted, and only generic information is provided in form of
+  # `*` (any number of arguments) or `_` (some positional argument).
+  #
+  #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
+  #     "cat".method(:+).inspect       #=> "#<Method: String#+(_)>""
+  #
+  alias to_s inspect
+
   # <!--
   #   rdoc-file=proc.c
   #   - meth.name    -> symbol
@@ -165,7 +263,7 @@ class UnboundMethod
   #
   #     (1..3).method(:map).owner #=> Enumerable
   #
-  def owner: () -> Module
+  def owner: () -> (Class | Module)
 
   # <!--
   #   rdoc-file=proc.c
@@ -185,32 +283,7 @@ class UnboundMethod
   #     def foo(bar, baz, *args, &blk); end
   #     method(:foo).parameters #=> [[:req, :bar], [:req, :baz], [:rest, :args], [:block, :blk]]
   #
-  def parameters: () -> ::Array[[ Symbol, Symbol ]]
-                | () -> ::Array[[ Symbol ]]
-
-  # <!--
-  #   rdoc-file=proc.c
-  #   - meth.private? -> true or false
-  # -->
-  # Returns whether the method is private.
-  #
-  def private?: () -> bool
-
-  # <!--
-  #   rdoc-file=proc.c
-  #   - meth.protected? -> true or false
-  # -->
-  # Returns whether the method is protected.
-  #
-  def protected?: () -> bool
-
-  # <!--
-  #   rdoc-file=proc.c
-  #   - meth.public? -> true or false
-  # -->
-  # Returns whether the method is public.
-  #
-  def public?: () -> bool
+  def parameters: () -> Method::param_types
 
   # <!--
   #   rdoc-file=proc.c
@@ -219,7 +292,7 @@ class UnboundMethod
   # Returns the Ruby source filename and line number containing this method or nil
   # if this method was not defined in Ruby (i.e. native).
   #
-  def source_location: () -> [ String, Integer ]?
+  def source_location: () -> [String, Integer]?
 
   # <!--
   #   rdoc-file=proc.c
@@ -252,5 +325,5 @@ class UnboundMethod
   # arguments. This is semantically equivalent to `umeth.bind(recv).call(args,
   # ...)`.
   #
-  def bind_call: (untyped recv, *untyped args) ?{ (*untyped) -> untyped } -> untyped
+  def bind_call: (untyped recv, *untyped, **untyped) ?{ (?) -> untyped } -> untyped
 end

data/core/warning.rbs

@@ -5,11 +5,11 @@
 #
 # Changing the behavior of Warning.warn is useful to customize how warnings are
 # handled by Ruby, for instance by filtering some warnings, and/or outputting
-# warnings somewhere other than $stderr.
+# warnings somewhere other than `$stderr`.
 #
 # If you want to change the behavior of Warning.warn you should use
-# +Warning.extend(MyNewModuleWithWarnMethod)+ and you can use `super` to get the
-# default behavior of printing the warning to $stderr.
+# `Warning.extend(MyNewModuleWithWarnMethod)` and you can use `super` to get the
+# default behavior of printing the warning to `$stderr`.
 #
 # Example:
 #     module MyWarningFilter
@@ -26,9 +26,54 @@
 # You should never redefine Warning#warn (the instance method), as that will
 # then no longer provide a way to use the default behavior.
 #
-# The `warning` gem provides convenient ways to customize Warning.warn.
+# The [warning](https://rubygems.org/gems/warning) gem provides convenient ways
+# to customize Warning.warn.
 #
 module Warning
+  # The types of categories the `Warning` module understands.
+  #
+  type category = :deprecated | :experimental | :performance
+
+  # <!--
+  #   rdoc-file=error.c
+  #   - Warning[category]  -> true or false
+  # -->
+  # Returns the flag to show the warning messages for `category`. Supported
+  # categories are:
+  #
+  # `:deprecated`
+  # :   deprecation warnings
+  #     *   assignment of non-nil value to `$,` and `$;`
+  #     *   keyword arguments
+  #     etc.
+  #
+  #
+  # `:experimental`
+  # :   experimental features
+  #
+  #
+  # `:performance`
+  # :   performance hints
+  #     *   Shape variation limit
+  #
+  def self.[]: (category) -> bool
+
+  # <!--
+  #   rdoc-file=error.c
+  #   - Warning[category] = flag -> flag
+  # -->
+  # Sets the warning flags for `category`. See Warning.[] for the categories.
+  #
+  def self.[]=: [T] (category, T flag) -> T
+
+  # <!--
+  #   rdoc-file=error.c
+  #   - categories  -> array
+  # -->
+  # Returns a list of the supported category symbols.
+  #
+  def self.categories: () -> Array[Symbol]
+
   # <!--
   #   rdoc-file=error.c
   #   - warn(msg, category: nil)  -> nil
@@ -38,5 +83,5 @@ module Warning
   #
   # See the documentation of the Warning module for how to customize this.
   #
-  def self?.warn: (String message, ?category: :deprecated | :experimental | nil) -> nil
+  def self?.warn: (String message, ?category: category?) -> nil
 end

data/docs/CONTRIBUTING.md

@@ -69,7 +69,7 @@ We define the standard members order so that ordering doesn't bother reading dif
 5. `public` & public instance methods
 6. `private` & private instance methods
 
-```
+```rbs
 class HelloWorld[X]
   def self.new: [A] () { (void) -> A } -> HelloWorld[A]         # new or initialize comes first
   def initialize: () -> void

data/docs/architecture.md

@@ -0,0 +1,110 @@
+# Architecture
+
+This guide describes the outline of the architecture of RBS library. It helps you to understand the structure and key features of the library to start contributing to the library.
+
+## Bird's Eye View
+
+The goal of the library is simple: Read RBS files and generate the structure of Ruby programs.
+
+```
+RBS files
+  ↓         -- RBS::Parser
+Syntax tree
+  ↓
+Environment
+  ↓        -- Definition builder
+Definition
+```
+
+The input is RBS files. The gem ships with RBS type definitions of Ruby core library and some of the standard libraries. You write RBS files for your applications or gems.
+
+Syntax tree is the next representation. `RBS::Parser` transforms the sequence of characters in RBS files into syntax trees.
+
+Syntax tree objects are loaded to `RBS::Environment`. It collects loaded RBS objects, organizes the definitions, and provides some utilities, like resolving type names and finding the declarations.
+
+`RBS::Definition` is the goal of the transformation steps. It is associated with a class singleton, a class object, or an interface. You can find the list of available methods and their types, instance variables, and class hierarchies.
+
+## Core classes
+
+### Types
+
+Types are defined under `RBS::Types`, like `RBS::Types::ClassInstance` or `RBS::Types::Union`. You will find the definition of each type supported in RBS.
+
+### Parsing RBS files
+
+The RBS source code is loaded into `RBS::Buffer`, and `RBS::Parser` is the parser. The parser is implemented in C extension.
+
+`RBS::Parser` provides three entrypoints.
+
+- `RBS::Parser.parse_method_type` parsers a *method type*. (`[T] (String) { (IO) -> T } -> Array[T]`)
+- `RBS::Parser.parse_type` parses a *type*. (`Hash[Symbol, untyped]`)
+- `RBS::Parser.parse_signature` parses the whole RBS file.
+
+### Environment
+
+RBS AST is loaded to `RBS::Environment` by `RBS::EnvironmentLoader`. `Environment` gives *absolute names* to the declarations, and provides an index from the *absolute name* to their declarations.
+
+Assume we have the following nested RBS declarations:
+
+```rbs
+module Hello
+  class World
+  end
+end
+
+class Hello::World
+end
+```
+
+And the environment organizes the definitions as follows:
+
+- There are two classes `::Hello` and `::Hello::World`
+- It provides a mapping from `::Hello` to it's `module` declaration and `::Hello::World` to it's two `class` declarations
+
+### Definition and DefinitionBuilder
+
+`RBS::Definition` tells you:
+
+- The set of available methods in a class/module/interface
+- The set of instance variables in a class/module
+- The ancestors in a class/module
+
+Definition is constructed for:
+
+- A singleton class of a class/module -- `singleton(String)`, `singleton(Array)`,
+- An instance of a class -- `String`, `Array[T]`, or
+- An interface -- `_ToS`
+
+Note that generic class instances/interfaces are kept generic. We don't have a definition of `Array[String]` but of `Array[T]`.
+
+`DefinitionBuilder` constructs `Definition` of given type names.
+
+- `DefinitionBuilder#build_singleton` returns a definition of singleton classes of given class/module.
+- `DefinitionBuilder#build_instance` returns a definition of instances of given class/module.
+- `DefinitionBuilder#build_interface` returns a definition of interfaces.
+
+It uses `AncestorBuilder` to construct ancestor chains of the type. `MethodBuilder` constructs sets of available methods based on the ancestor chains.
+
+The `#build_singleton` calculates the type of `.new` methods based on the definition of `#initialize` method. This is different from Ruby's implementation -- it reused `Class#new` method but we need the custom implementation to give precise `.new` method type of each class.
+
+#### Working with type aliases
+
+`DefinitionBuilder#expand_alias` and its variants provide one step *unfold* operation of type aliases.
+
+```ruby
+builder.expand_alias2(RBS::TypeName.parse("::int"), []) # => returns `::Integer | ::_ToInt`
+```
+
+We don't have *normalize* operation for type aliases, because RBS allows recursive type alias definition, which cannot be *fully* unfolded.
+
+### Other utilities
+
+`RBS::Validator` provides validation of RBS type declaration. It validates that all of the type name references can be resolved, all type applications have correct arity, and so on.
+
+`RBS::Test` provides runtime type checking, which confirms if a Ruby object can have an RBS type. It also provides an integration to existing Ruby code so that we run Ruby code, assuming unit tests, with runtime type checking.
+
+`RBS::UnitTest` provides utilities to help write unit tests for RBS type definitions. Use the tool to make sure your RBS type definition is consistent with implementation.
+
+`RBS::Prototype` is the core of `rbs prototype` feature. It scans Ruby source code or uses reflection features, and it generates the prototype of RBS files.
+
+`RBS::Collection` includes `rbs collection` features.

data/docs/collection.md

@@ -28,11 +28,10 @@ sources:
 # A directory to install the downloaded RBSs
 path: .gem_rbs_collection
 
-gems:
-  # Skip loading rbs gem's RBS.
-  # It's unnecessary if you don't use rbs as a library.
-  - name: rbs
-    ignore: true
+# gems:
+#   # If you want to avoid installing rbs files for gems, you can specify them here.
+#   - name: GEM_NAME
+#     ignore: true
 ```
 
 I also recommend updating `.gitignore`.
@@ -79,6 +78,10 @@ sources:
     revision: main
     repo_dir: gems
 
+  # You can also add a local path as a collection source optionally.
+  - type: local
+    path: path/to/local/dir
+
 # A directory to install the downloaded RBSs
 path: .gem_rbs_collection
 
@@ -95,6 +98,57 @@ gems:
     ignore: true
 ```
 
+### Avoid installing RBS
+
+There are two ways to avoid RBS installation.
+
+#### `require: false` in `Gemfile`
+
+First, you can specify `require: false` in `Gemfile`. It is the recommended way to avoid installing RBS.
+For example:
+
+```ruby
+# Gemfile
+
+gem 'GEM_NAME', require: false
+```
+
+In this case, `rbs collection` doesn't install the RBS of `GEM_NAME`.
+We recommend to specify `require: false` for `rbs` gem itself because `rbs` gem's RBS file is not necessary in most cases.
+
+#### `ignore: true` in `rbs_collection.yaml`
+
+Second, you can write `ignore: true` in `rbs_collection.yaml`. It is useful if you want to avoid installing RBS but you need to require the gem.
+
+```yaml
+# rbs_collection.yaml
+
+gems:
+  - name: GEM_NAME
+    ignore: true
+```
+
+#### Load RBS specified `require: false`
+
+You can also use `ignore: false` if you want to install RBS for a gem which you specify `require: false` in `Gemfile`.
+For example:
+
+```ruby
+# Gemfile
+
+gem 'GEM_NAME', require: false
+```
+
+```yaml
+# rbs_collection.yaml
+
+gems:
+  - name: GEM_NAME
+    ignore: false
+```
+
+In this case, `rbs collection` installs the RBS of `GEM_NAME`.
+
 ### `manifest.yaml`
 
 If you are a gem maintainer, you can write `manifest.yaml`.

data/docs/data_and_struct.md

@@ -0,0 +1,86 @@
+# Using `Data` and `Struct`
+
+`Data` and `Struct` are commonly used utilities to define simple *value* objects. The objects have attributes, and the equality between the two objects are defined by equality of the attributes. (Note that we can define additional methods and overwrite the equality definitions when we want.)
+
+```ruby
+# Defines `Measure` class with `#amount` and `#unit` attributes
+Measure = Data.define(:amount, :unit)
+```
+
+Unfortunately, supporting `Data` and `Struct` in RBS is not straightforward. You have to write down the attribute definitions and initializers in RBS.
+
+```rbs
+class Measure
+  # `attr_accessor amount: Integer` in the case of Struct
+  attr_reader amount: Integer
+  
+  # `attr_accessor unit: String` in the case of Struct
+  attr_reader unit: String
+  
+  def initialize: (Integer amount, String unit) -> void
+                | (amount: Integer, unit: String) -> void             
+end
+```
+
+This is simplified definition of the `Measure` class, for the case you only use the attributes and initializers. You can add more method definitions or inherit from `Data` class to make the definition more complete.
+
+However, it's common that you don't need all of the `Data` and `Struct` methods, like `.members` and `.[]`. When you are using those utility classes just for the attributes methods, you can simply ignore other methods or skip specifying a super class.
+
+> You may want to implement a generator that understands `Data.define` and `Struct.new`. But even with the generator, you need to edit the generated RBS files so that the attribute definitions have correct types.
+
+## Type checking class definitions using `Data` and `Struct`
+
+If you use Steep, you may need additional annotation in Ruby implementation.
+
+```ruby
+# Type error because return type of `Data.define(...)` is not `singleton(Measure)`
+Measure = Data.define(:amount, :unit)
+```
+
+You can please the type checker by adding a cast (`_`) or define the class inheriting from `Data.define(...)`.
+
+```ruby
+# Skip type checking by assigning to `_`
+Measure = _ = Data.define(:amount, :unit)
+
+# Super class is not type checked by Steep
+class Measure < Data.define(:amount, :unit)
+end
+```
+
+@soutaro has prefered inheriting from `Data.define`, but you may find an extra annonymous class in `.ancestors` [^1].
+
+```ruby
+Measure.ancestors #=> [Measure, #<Class:0xOOF>, Data, ...]
+```
+
+[^1]: [Shannon Skipper](https://github.com/havenwood) told me it in Discord
+
+## Generate prototype for `Data` and `Struct`
+
+RBS prototypes for classes using `Data` and `Struct` can be generated by `rbs prototype runtime`.
+
+```rb
+# t.rb
+class Measure < Data.define(:amount, :unit)
+end
+```
+
+```
+$ bundle exec rbs prototype runtime -R t.rb Measure
+class Measure < ::Data
+  def self.new: (untyped amount, untyped unit) -> instance
+              | (amount: untyped, unit: untyped) -> instance
+
+  def self.[]: (untyped amount, untyped unit) -> instance
+             | (amount: untyped, unit: untyped) -> instance
+
+  def self.members: () -> [ :amount, :unit ]
+
+  def members: () -> [ :amount, :unit ]
+
+  attr_reader amount: untyped
+
+  attr_reader unit: untyped
+end
+```