rbs-relaxed 3.9.0.1

data/core/unbound_method.rbs

@@ -0,0 +1,329 @@
+# <!-- rdoc-file=proc.c -->
+# Ruby supports two forms of objectified methods. Class Method is used to
+# represent methods that are associated with a particular object: these method
+# objects are bound to that object. Bound method objects for an object can be
+# created using Object#method.
+#
+# Ruby also supports unbound methods; methods objects that are not associated
+# with a particular object. These can be created either by calling
+# Module#instance_method or by calling #unbind on a bound method object. The
+# result of both of these is an UnboundMethod object.
+#
+# Unbound methods can only be called after they are bound to an object. That
+# object must be a kind_of? the method's original class.
+#
+#     class Square
+#       def area
+#         @side * @side
+#       end
+#       def initialize(side)
+#         @side = side
+#       end
+#     end
+#
+#     area_un = Square.instance_method(:area)
+#
+#     s = Square.new(12)
+#     area = area_un.bind(s)
+#     area.call   #=> 144
+#
+# Unbound methods are a reference to the method at the time it was objectified:
+# subsequent changes to the underlying class will not affect the unbound method.
+#
+#     class Test
+#       def test
+#         :original
+#       end
+#     end
+#     um = Test.instance_method(:test)
+#     class Test
+#       def test
+#         :modified
+#       end
+#     end
+#     t = Test.new
+#     t.test            #=> :modified
+#     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
+  # -->
+  # Returns a clone of this method.
+  #
+  #     class A
+  #       def foo
+  #         return "bar"
+  #       end
+  #     end
+  #
+  #     m = A.new.method(:foo)
+  #     m.call # => "bar"
+  #     n = m.clone.call # => "bar"
+  #
+  def clone: () -> instance
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.arity    -> integer
+  # -->
+  # Returns an indication of the number of arguments accepted by a method. Returns
+  # a nonnegative integer for methods that take a fixed number of arguments. For
+  # Ruby methods that take a variable number of arguments, returns -n-1, where n
+  # is the number of required arguments. Keyword arguments will be considered as a
+  # single additional argument, that argument being mandatory if any keyword
+  # argument is mandatory. For methods written in C, returns -1 if the call takes
+  # a variable number of arguments.
+  #
+  #     class C
+  #       def one;    end
+  #       def two(a); end
+  #       def three(*a);  end
+  #       def four(a, b); end
+  #       def five(a, b, *c);    end
+  #       def six(a, b, *c, &d); end
+  #       def seven(a, b, x:0); end
+  #       def eight(x:, y:); end
+  #       def nine(x:, y:, **z); end
+  #       def ten(*a, x:, y:); end
+  #     end
+  #     c = C.new
+  #     c.method(:one).arity     #=> 0
+  #     c.method(:two).arity     #=> 1
+  #     c.method(:three).arity   #=> -1
+  #     c.method(:four).arity    #=> 2
+  #     c.method(:five).arity    #=> -3
+  #     c.method(:six).arity     #=> -3
+  #     c.method(:seven).arity   #=> -3
+  #     c.method(:eight).arity   #=> 1
+  #     c.method(:nine).arity    #=> 1
+  #     c.method(:ten).arity     #=> -2
+  #
+  #     "cat".method(:size).arity      #=> 0
+  #     "cat".method(:replace).arity   #=> 1
+  #     "cat".method(:squeeze).arity   #=> -1
+  #     "cat".method(:count).arity     #=> -1
+  #
+  def arity: () -> Integer
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - umeth.bind(obj) -> method
+  # -->
+  # Bind *umeth* to *obj*. If Klass was the class from which *umeth* was obtained,
+  # `obj.kind_of?(Klass)` must be true.
+  #
+  #     class A
+  #       def test
+  #         puts "In test, class = #{self.class}"
+  #       end
+  #     end
+  #     class B < A
+  #     end
+  #     class C < B
+  #     end
+  #
+  #     um = B.instance_method(:test)
+  #     bm = um.bind(C.new)
+  #     bm.call
+  #     bm = um.bind(B.new)
+  #     bm.call
+  #     bm = um.bind(A.new)
+  #     bm.call
+  #
+  # *produces:*
+  #
+  #     In test, class = C
+  #     In test, class = B
+  #     prog.rb:16:in `bind': bind argument must be an instance of B (TypeError)
+  #      from prog.rb:16
+  #
+  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
+  # -->
+  # Returns the name of the method.
+  #
+  def name: () -> Symbol
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.owner    -> class_or_module
+  # -->
+  # Returns the class or module on which this method is defined. In other words,
+  #
+  #     meth.owner.instance_methods(false).include?(meth.name) # => true
+  #
+  # holds as long as the method is not removed/undefined/replaced, (with
+  # private_instance_methods instead of instance_methods if the method is
+  # private).
+  #
+  # See also Method#receiver.
+  #
+  #     (1..3).method(:map).owner #=> Enumerable
+  #
+  def owner: () -> (Class | Module)
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.parameters  -> array
+  # -->
+  # Returns the parameter information of this method.
+  #
+  #     def foo(bar); end
+  #     method(:foo).parameters #=> [[:req, :bar]]
+  #
+  #     def foo(bar, baz, bat, &blk); end
+  #     method(:foo).parameters #=> [[:req, :bar], [:req, :baz], [:req, :bat], [:block, :blk]]
+  #
+  #     def foo(bar, *args); end
+  #     method(:foo).parameters #=> [[:req, :bar], [:rest, :args]]
+  #
+  #     def foo(bar, baz, *args, &blk); end
+  #     method(:foo).parameters #=> [[:req, :bar], [:req, :baz], [:rest, :args], [:block, :blk]]
+  #
+  def parameters: () -> Method::param_types
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.source_location  -> [String, Integer]
+  # -->
+  # 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]?
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.super_method  -> method
+  # -->
+  # Returns a Method of superclass which would be called when super is used or nil
+  # if there is no method on superclass.
+  #
+  def super_method: () -> UnboundMethod?
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.original_name    -> symbol
+  # -->
+  # Returns the original name of the method.
+  #
+  #     class C
+  #       def foo; end
+  #       alias bar foo
+  #     end
+  #     C.instance_method(:bar).original_name # => :foo
+  #
+  def original_name: () -> Symbol
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - umeth.bind_call(recv, args, ...) -> obj
+  # -->
+  # Bind *umeth* to *recv* and then invokes the method with the specified
+  # arguments. This is semantically equivalent to `umeth.bind(recv).call(args,
+  # ...)`.
+  #
+  def bind_call: (untyped recv, *untyped, **untyped) ?{ (?) -> untyped } -> untyped
+end

data/core/warning.rbs

@@ -0,0 +1,87 @@
+# <!-- rdoc-file=error.c -->
+# The Warning module contains a single method named #warn, and the module
+# extends itself, making Warning.warn available. Warning.warn is called for all
+# warnings issued by Ruby. By default, warnings are printed to $stderr.
+#
+# 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`.
+#
+# 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`.
+#
+# Example:
+#     module MyWarningFilter
+#       def warn(message, category: nil, **kwargs)
+#         if /some warning I want to ignore/.match?(message)
+#           # ignore
+#         else
+#           super
+#         end
+#       end
+#     end
+#     Warning.extend MyWarningFilter
+#
+# 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](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
+  # -->
+  # Writes warning message `msg` to $stderr. This method is called by Ruby for all
+  # emitted warnings. A `category` may be included with the warning.
+  #
+  # See the documentation of the Warning module for how to customize this.
+  #
+  def self?.warn: (String message, ?category: category?) -> nil
+end

data/docs/CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Core and Standard Library Signatures Contribution Guide
+
+## Guides
+
+* [RBS by Example](rbs_by_example.md)
+* [Writing Signature Guide](sigs.md)
+* [Testing Core API and Standard Library Types](stdlib.md)
+* [Syntax](syntax.md)
+
+## Introduction
+
+The RBS repository contains the type definitions of Core API and Standard Libraries.
+There are some discussions whether if it is the best to have them in this repository, but we have them and continue updating the files meanwhile.
+
+The target version of the bundled type definitions is the latest _release_ of Ruby -- `3.1` as of January 2022.
+
+**The core API** type definitions are in `core` directory.
+You will find the familiar class names in the directory, like `string.rbs` or `array.rbs`.
+
+**The standard libraries** type definitions are in `stdlib` directory.
+They have the [third party repository](repo.md) structure.
+There is a `set` directory for the `set` library, and it contains `0` directory.
+Because RBS supports the latest release of Ruby, we have one set of RBS files which corresponds to the bundled versions of the libraries.
+
+## Steps for Contribution
+
+1. Pick the class/library you will work for.
+2. Make a directory `stdlib/foo/0` if you work for one of the standard libraries.
+3. Write RBS type definitions and tests.
+
+You will typically follow the steps as follows:
+
+1. Run `rbs prototype runtime` to generate list of methods.
+2. Run `rbs annotate` to import RDoc comments.
+3. Run `rake generate:stdlib_test[LIB]` to generate a test case.
+4. Write the type definitions and tests.
+
+See the next *Useful Tools* section and the guides above for writing and testing RBS files.
+
+## Useful Tools
+
+* `rbs prototype runtime --merge String`
+  * Generate a prototype using runtime API.
+  * `--merge` tells to use the method types in RBS if exists.
+* `rbs prototype runtime --merge --method-owner=Numeric Integer`
+  * You can use --method-owner if you want to print method of other classes too, for documentation purpose.
+* `rbs annotate core/string.rbs`
+  * Import RDoc comments.
+  * The imported docs contain the description, *arglists*, and filenames to help writing types.
+* `bin/query-rdoc String#initialize`
+  * Print RDoc documents in the format you can copy-and-paste to RBS.
+* `bin/sort core/string.rbs`
+  * Sort declarations members in RBS files.
+* `rbs -r LIB validate`
+  Validate the syntax and some of the semantics.
+* `rake generate:stdlib_test[String]`
+  Scaffold the stdlib test.
+* `rake test/stdlib/Array_test.rb`
+  Run specific stdlib test with the path.
+
+### Standard STDLIB Members Order
+
+We define the standard members order so that ordering doesn't bother reading diffs or git-annotate outputs.
+
+1. `def self.new` or `def initialize`
+2. Mixins
+3. Attributes
+4. Singleton methods
+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
+
+  include Enumerable[X, void]                                   # Mixin comes next
+
+  attr_reader language: (:ja | :en)                             # Attributes
+
+  def self.all_languages: () -> Array[Symbol]                   # Singleton methods
+
+  public                                                        # Public instance methods
+
+  def each: () { (A) -> void } -> void                          # Members are sorted dictionary order
+
+  def to_s: (?Locale) -> String
+
+  private                                                       # Private instance methods
+
+  alias validate validate_locale
+
+  def validate_locale: () -> void
+end
+```
+
+## Q&A
+
+### Some of the standard libraries are gems. Why we put the files in this repo?
+
+You are correct. We want to move to their repos. We haven't started the migration yet.
+
+### How can we handle incompatibilities of core APIs and standard libraries between Rubies
+
+We ignore the incompatibilities for now.
+We focus on the latest version of core APIs and standard libraries.

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.