rbs 3.2.2 → 3.3.0.pre.1

data/core/process.rbs

@@ -401,7 +401,7 @@ module Process
   # Process::RLIM_SAVED_MAX or Process::RLIM_SAVED_CUR. See Process.setrlimit and
   # the system getrlimit(2) manual for details.
   #
-  def self.getrlimit: (Symbol | String | Integer resource) -> [ Integer, Integer ]
+  def self.getrlimit: (interned | Integer resource) -> [ Integer, Integer ]
 
   # <!--
   #   rdoc-file=process.c
@@ -523,7 +523,7 @@ module Process
   # because of no privilege, will be raised.  In these cases, signals may have
   # been sent to preceding processes.
   #
-  def self.kill: (Integer | Symbol | String signal, *Integer pids) -> Integer
+  def self.kill: (Integer | interned signal, *Integer pids) -> Integer
 
   # <!--
   #   rdoc-file=process.c
@@ -673,7 +673,7 @@ module Process
   #
   #     Process.setrlimit(:CORE, Process.getrlimit(:CORE)[1])
   #
-  def self.setrlimit: (Symbol | String | Integer resource, Integer cur_limit, ?Integer max_limit) -> nil
+  def self.setrlimit: (interned | Integer resource, Integer cur_limit, ?Integer max_limit) -> nil
 
   # <!--
   #   rdoc-file=process.c

data/core/ractor.rbs

@@ -599,7 +599,7 @@ class Ractor
   # -->
   # get a value from ractor-local storage
   #
-  def []: (Symbol | String sym) -> untyped
+  def []: (interned sym) -> untyped
 
   # <!--
   #   rdoc-file=ractor.rb
@@ -607,7 +607,7 @@ class Ractor
   # -->
   # set a value in ractor-local storage
   #
-  def []=: [T] (Symbol | String sym, T val) -> T
+  def []=: [T] (interned sym, T val) -> T
 
   # <!--
   #   rdoc-file=ractor.rb

data/core/rb_config.rbs

@@ -7,6 +7,49 @@
 # built.
 #
 module RbConfig
+  # <!-- rdoc-file=rbconfig.rb -->
+  # The hash configurations stored.
+  #
+  CONFIG: Hash[String, String]
+
+  # <!-- rdoc-file=rbconfig.rb -->
+  # DESTDIR on make install.
+  #
+  DESTDIR: String
+
+  # <!-- rdoc-file=rbconfig.rb -->
+  # Almost same with CONFIG. MAKEFILE_CONFIG has other variable reference like
+  # below.
+  #
+  #     MAKEFILE_CONFIG["bindir"] = "$(exec_prefix)/bin"
+  #
+  # The values of this constant is used for creating Makefile.
+  #
+  #     require 'rbconfig'
+  #
+  #     print <<-END_OF_MAKEFILE
+  #     prefix = #{RbConfig::MAKEFILE_CONFIG['prefix']}
+  #     exec_prefix = #{RbConfig::MAKEFILE_CONFIG['exec_prefix']}
+  #     bindir = #{RbConfig::MAKEFILE_CONFIG['bindir']}
+  #     END_OF_MAKEFILE
+  #
+  #     => prefix = /usr/local
+  #        exec_prefix = $(prefix)
+  #        bindir = $(exec_prefix)/bin  MAKEFILE_CONFIG = {}
+  #
+  # RbConfig.expand is used for resolving references like above in rbconfig.
+  #
+  #     require 'rbconfig'
+  #     p RbConfig.expand(RbConfig::MAKEFILE_CONFIG["bindir"])
+  #     # => "/usr/local/bin"
+  #
+  MAKEFILE_CONFIG: Hash[String, String]
+
+  # <!-- rdoc-file=rbconfig.rb -->
+  # Ruby installed directory.
+  #
+  TOPDIR: String
+
   # <!--
   #   rdoc-file=rbconfig.rb
   #   - RbConfig.expand(val)         -> string
@@ -18,50 +61,28 @@ module RbConfig
   #
   def self.expand: (String val, ?Hash[String, String] config) -> String
 
+  # <!--
+  #   rdoc-file=rbconfig.rb
+  #   - RbConfig.fire_update!(key, val)               -> array
+  #   - RbConfig.fire_update!(key, val, mkconf, conf) -> array
+  # -->
+  # updates `key+ in `mkconf` with `val`, and all values depending on
+  # the `key` in `mkconf`.
+  #
+  #   RbConfig::MAKEFILE_CONFIG.values_at("CC", "LDSHARED") # => ["gcc", "$(CC) -shared"]
+  #   RbConfig::CONFIG.values_at("CC", "LDSHARED")          # => ["gcc", "gcc -shared"]
+  #   RbConfig.fire_update!("CC", "gcc-8")                  # => ["CC", "LDSHARED"]
+  #   RbConfig::MAKEFILE_CONFIG.values_at("CC", "LDSHARED") # => ["gcc-8", "$(CC) -shared"]
+  #   RbConfig::CONFIG.values_at("CC", "LDSHARED")          # => ["gcc-8", "gcc-8 -shared"]
+  #
+  # returns updated keys list, or `nil` if nothing changed.
   def self.fire_update!: (String key, String val, ?Hash[String, String] mkconf, ?Hash[String, String] conf) -> Array[String]?
 
+  # <!--
+  #   rdoc-file=rbconfig.rb
+  #   - RbConfig.ruby -> path
+  # -->
+  #
+  # returns the absolute pathname of the ruby command.
   def self.ruby: () -> String
 end
-
-# <!-- rdoc-file=rbconfig.rb -->
-# The hash configurations stored.
-#
-RbConfig::CONFIG: Hash[String, String]
-
-# <!-- rdoc-file=rbconfig.rb -->
-# DESTDIR on make install.
-#
-RbConfig::DESTDIR: String
-
-# <!-- rdoc-file=rbconfig.rb -->
-# Almost same with CONFIG. MAKEFILE_CONFIG has other variable reference like
-# below.
-#
-#     MAKEFILE_CONFIG["bindir"] = "$(exec_prefix)/bin"
-#
-# The values of this constant is used for creating Makefile.
-#
-#     require 'rbconfig'
-#
-#     print <<-END_OF_MAKEFILE
-#     prefix = #{RbConfig::MAKEFILE_CONFIG['prefix']}
-#     exec_prefix = #{RbConfig::MAKEFILE_CONFIG['exec_prefix']}
-#     bindir = #{RbConfig::MAKEFILE_CONFIG['bindir']}
-#     END_OF_MAKEFILE
-#
-#     => prefix = /usr/local
-#        exec_prefix = $(prefix)
-#        bindir = $(exec_prefix)/bin  MAKEFILE_CONFIG = {}
-#
-# RbConfig.expand is used for resolving references like above in rbconfig.
-#
-#     require 'rbconfig'
-#     p RbConfig.expand(RbConfig::MAKEFILE_CONFIG["bindir"])
-#     # => "/usr/local/bin"
-#
-RbConfig::MAKEFILE_CONFIG: Hash[String, String]
-
-# <!-- rdoc-file=rbconfig.rb -->
-# Ruby installed directory.
-#
-RbConfig::TOPDIR: String

data/core/regexp.rbs

@@ -849,7 +849,7 @@ class Regexp
   #
   # Regexp.quote is an alias for Regexp.escape.
   #
-  def self.escape: (String | Symbol str) -> String
+  def self.escape: (interned str) -> String
 
   # <!--
   #   rdoc-file=re.c
@@ -889,7 +889,7 @@ class Regexp
   #
   def self.last_match: () -> MatchData?
                      | (Integer n) -> String?
-                     | (Symbol | String n) -> String?
+                     | (interned n) -> String?
 
   # <!--
   #   rdoc-file=re.c
@@ -928,7 +928,7 @@ class Regexp
   #
   # Regexp.quote is an alias for Regexp.escape.
   #
-  def self.quote: (String | Symbol str) -> String
+  def self.quote: (interned str) -> String
 
   # <!--
   #   rdoc-file=re.c

data/core/signal.rbs

@@ -45,7 +45,7 @@ module Signal
   #
   #     Signal.list   #=> {"EXIT"=>0, "HUP"=>1, "INT"=>2, "QUIT"=>3, "ILL"=>4, "TRAP"=>5, "IOT"=>6, "ABRT"=>6, "FPE"=>8, "KILL"=>9, "BUS"=>7, "SEGV"=>11, "SYS"=>31, "PIPE"=>13, "ALRM"=>14, "TERM"=>15, "URG"=>23, "STOP"=>19, "TSTP"=>20, "CONT"=>18, "CHLD"=>17, "CLD"=>17, "TTIN"=>21, "TTOU"=>22, "IO"=>29, "XCPU"=>24, "XFSZ"=>25, "VTALRM"=>26, "PROF"=>27, "WINCH"=>28, "USR1"=>10, "USR2"=>12, "PWR"=>30, "POLL"=>29}
   #
-  def self.list: () -> ::Hash[String, Integer]
+  def self?.list: () -> Hash[String, Integer]
 
   # <!--
   #   rdoc-file=signal.c
@@ -61,7 +61,7 @@ module Signal
   #
   #     INT
   #
-  def self.signame: (Integer arg0) -> String?
+  def self?.signame: (int signo) -> String?
 
   # <!--
   #   rdoc-file=signal.c
@@ -89,6 +89,12 @@ module Signal
   #     Child died
   #     Terminating: 27460
   #
-  def self.trap: (Integer | String | Symbol signal, ?untyped command) -> (String | Proc)
-               | (Integer | String | Symbol signal) { (Integer arg0) -> untyped } -> (String | Proc)
+  def self?.trap: (Integer | interned signal) { (Integer) -> void } -> trap_command
+                | (Integer | interned signal, trap_command command) -> trap_command
+
+  type trap_command = string | bool | nil | _TrapCommand
+
+  interface _TrapCommand
+    def call: (Integer signo) -> void
+  end
 end

data/core/struct.rbs

@@ -115,7 +115,7 @@
 class Struct[Elem] < Object
   include Enumerable[Elem?]
 
-  type attribute_name = Symbol | String
+  type attribute_name = interned
 
   # <!--
   #   rdoc-file=struct.c

data/core/thread.rbs

@@ -226,7 +226,7 @@ class Thread < Object
   # For thread-local variables, please see #thread_variable_get and
   # #thread_variable_set.
   #
-  def []: (String | Symbol key) -> untyped
+  def []: (interned key) -> untyped
 
   # <!--
   #   rdoc-file=thread.c
@@ -240,7 +240,7 @@ class Thread < Object
   # For thread-local variables, please see #thread_variable_set and
   # #thread_variable_get.
   #
-  def []=: (String | Symbol key, untyped value) -> untyped
+  def []=: (interned key, untyped value) -> untyped
 
   # <!--
   #   rdoc-file=thread.c
@@ -676,7 +676,7 @@ class Thread < Object
   # Note that these are not fiber local variables.  Please see Thread#[] and
   # Thread#thread_variable_get for more details.
   #
-  def thread_variable?: (String | Symbol key) -> bool
+  def thread_variable?: (interned key) -> bool
 
   # <!--
   #   rdoc-file=thread.c
@@ -1741,10 +1741,10 @@ class Thread::SizedQueue < Thread::Queue
   def push: (untyped obj, ?boolish non_block, timeout: _ToF?) -> void
 end
 
-ConditionVariable: singleton(Thread::ConditionVariable)
+class ConditionVariable = Thread::ConditionVariable
 
-Mutex: singleton(Thread::Mutex)
+class Mutex = Thread::Mutex
 
-Queue: singleton(Thread::Queue)
+class Queue = Thread::Queue
 
-SizedQueue: singleton(Thread::SizedQueue)
+class SizedQueue = Thread::SizedQueue

data/core/thread_group.rbs

@@ -8,7 +8,13 @@
 # Newly created threads belong to the same group as the thread from which they
 # were created.
 #
-class ThreadGroup < Object
+class ThreadGroup
+  # <!-- rdoc-file=thread.c -->
+  # The default ThreadGroup created when Ruby starts; all Threads belong to it by
+  # default.
+  #
+  Default: ThreadGroup
+
   # <!--
   #   rdoc-file=thread.c
   #   - thgrp.add(thread)   -> thgrp
@@ -34,7 +40,7 @@ class ThreadGroup < Object
   #     Initial group now #<Thread:0x401b3c18>#<Thread:0x401bdf4c>
   #     tg group now #<Thread:0x401b3c90>
   #
-  def add: (Thread thread) -> ThreadGroup
+  def add: (Thread thread) -> self
 
   # <!--
   #   rdoc-file=thread.c
@@ -69,11 +75,5 @@ class ThreadGroup < Object
   #
   #     ThreadGroup::Default.list   #=> [#<Thread:0x401bdf4c run>]
   #
-  def list: () -> ::Array[Thread]
+  def list: () -> Array[Thread]
 end
-
-# <!-- rdoc-file=thread.c -->
-# The default ThreadGroup created when Ruby starts; all Threads belong to it by
-# default.
-#
-ThreadGroup::Default: ThreadGroup

data/core/true_class.rbs

@@ -4,8 +4,6 @@
 # allowing `true` to be used in logical expressions.
 #
 class TrueClass
-  public
-
   def !: () -> false
 
   # <!--
@@ -14,9 +12,8 @@ class TrueClass
   # -->
   # And---Returns `false` if *obj* is `nil` or `false`, `true` otherwise.
   #
-  def &: (nil) -> false
-       | (false) -> false
-       | (untyped obj) -> true
+  def &: (false | nil) -> false
+       | (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=object.c
@@ -27,7 +24,7 @@ class TrueClass
   # statements.
   #
   def ===: (true) -> true
-         | (untyped obj) -> false
+         | (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=object.c
@@ -35,9 +32,8 @@ class TrueClass
   # -->
   # Exclusive Or---Returns `true` if *obj* is `nil` or `false`, `false` otherwise.
   #
-  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".
@@ -67,6 +63,4 @@ class TrueClass
   #     or
   #
   def |: (untyped obj) -> true
-
-  def clone: (?freeze: true?) -> self
 end

data/core/unbound_method.rbs

@@ -60,7 +60,29 @@ class UnboundMethod
   #     Array.instance_method(:sum) == Enumerable.instance_method(:sum)
   #     #=> false, Array redefines the method for efficiency
   #
-  def ==: (untyped) -> bool
+  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
@@ -78,7 +100,7 @@ class UnboundMethod
   #     m.call # => "bar"
   #     n = m.clone.call # => "bar"
   #
-  def clone: () -> self
+  def clone: () -> instance
 
   # <!--
   #   rdoc-file=proc.c
@@ -189,6 +211,34 @@ class UnboundMethod
   #
   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
@@ -213,7 +263,7 @@ class UnboundMethod
   #
   #     (1..3).method(:map).owner #=> Enumerable
   #
-  def owner: () -> Module
+  def owner: () -> (Class | Module)
 
   # <!--
   #   rdoc-file=proc.c
@@ -233,8 +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 ]]
+  def parameters: () -> Method::param_types
 
   # <!--
   #   rdoc-file=proc.c
@@ -243,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
@@ -276,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) -> untyped } -> untyped
 end

data/core/warning.rbs

@@ -29,8 +29,41 @@
 # The `warning` gem provides convenient ways to customize Warning.warn.
 #
 module Warning
+  # The types of categories the `Warning` module understands.
+  #
   type category = :deprecated | :experimental
 
+  # <!--
+  #   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
+  # *   proc/lambda without block
+  #
+  # etc.
+  #
+  # `:experimental`
+  # :   experimental features
+  #
+  # *   Pattern matching
+  #
+  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
   #   - warn(msg, category: nil)  -> nil

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,7 +78,7 @@ sources:
     revision: main
     repo_dir: gems
 
-  # You can also add a local path as a collection source optionaly.
+  # You can also add a local path as a collection source optionally.
   - type: local
     path: path/to/local/dir
 
@@ -99,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,57 @@
+# 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