rbs 4.1.0.pre.2-java

data/core/unbound_method.rbs

@@ -0,0 +1,337 @@
+# <!-- 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: () -> self
+
+  # <!--
+  #   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,
+  # <code>obj.kind_of?(Klass)</code> 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
+  #
+  # <em>produces:</em>
+  #
+  #     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>"
+  #
+  # <code>...</code> 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
+  # <code>*</code> (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>"
+  #
+  # <code>...</code> 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
+  # <code>*</code> (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, Integer, Integer, Integer]
+  # -->
+  # Returns the location where the method was defined. The returned Array
+  # contains:
+  #     (1) the Ruby source filename
+  #     (2) the line number where the definition starts
+  #     (3) the column number where the definition starts
+  #     (4) the line number where the definition ends
+  #     (5) the column number where the definitions ends
+  #
+  # This method will return `nil` if the 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
+  # <code>umeth.bind(recv).call(args, ...)</code>.
+  #
+  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 <code>$stderr</code>.
+#
+# If you want to change the behavior of Warning.warn you should use
+# <code>Warning.extend(MyNewModuleWithWarnMethod)</code> and you can use `super`
+# to get the default behavior of printing the warning to <code>$stderr</code>.
+#
+# 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:
+  #
+  # <code>:deprecated</code>
+  # :   deprecation warnings
+  #     *   assignment of non-nil value to <code>$,</code> and <code>$;</code>
+  #     *   keyword arguments
+  #     etc.
+  #
+  #
+  # <code>:experimental</code>
+  # :   experimental features
+  #
+  #
+  # <code>:performance</code>
+  # :   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,107 @@
+# 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](https://www.ruby-lang.org/en/downloads/branches/) -- `4.0` as of 2026.
+Note, however, that the CI currently retains the tests on Ruby 3.2 as well.
+
+**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/aliases.md

@@ -0,0 +1,79 @@
+# Aliases
+
+This document explains module/class aliases and type aliases.
+
+## Module/class alias
+
+Module/class aliases give another name to a module/class.
+This is useful for some syntaxes that has lexical constraints.
+
+```rbs
+class C
+end
+
+class D = C         # ::D is an alias for ::C
+
+class E < D         # ::E inherits from ::D, which is actually ::C
+end
+```
+
+Note that module/class aliases cannot be recursive.
+
+So, we can define a *normalization* of aliased module/class names.
+Normalization follows the chain of alias definitions and resolves them to the original module/class defined with `module`/`class` syntax.
+
+```rbs
+class C
+end
+
+class D = C
+class E = D
+```
+
+`::E` is defined as an alias, and it can be normalized to `::C`.
+
+## Type alias
+
+The biggest difference from module/class alias is that type alias can be recursive.
+
+```rbs
+# cons_cell type is defined recursively
+type cons_cell = nil
+               | [Integer, cons_cell]
+```
+
+This means type aliases *cannot be* normalized generally.
+So, we provide another operation for type alias, `DefinitionBuilder#expand_alias` and its family.
+It substitutes with the immediate right hand side of a type alias.
+
+```
+cons_cell ===> nil | [Integer, cons_cell]                   (expand 1 step)
+          ===> nil | [Integer, nil | [Integer, cons_cell]]  (expand 2 steps)
+          ===> ...                                          (expand will go infinitely)
+```
+
+Note that the namespace of a type alias *can be* normalized, because they are module names.
+
+```rbs
+module M
+  type t = String
+end
+
+module N = M
+```
+
+With the type definition above, a type `::N::t` can be normalized to `::M::t`.
+And then it can be expanded to `::String`.
+
+> [!NOTE]
+> This is something like an *unfold* operation in type theory.
+
+## Type name resolution
+
+Type name resolution in RBS usually rewrites *relative* type names to *absolute* type names.
+`Environment#resolve_type_names` converts all type names in the RBS type definitions, and returns a new `Environment` object.
+
+It also *normalizes* modules names in type names.
+
+- If the type name can be resolved and normalized successfully, the AST has *absolute* type names.
+- If the type name resolution/normalization fails, the AST has *relative* type names.