rbs 2.8.4 → 3.8.1

data/core/module.rbs

@@ -85,13 +85,41 @@ class Module < Object
   #
   def self.used_modules: () -> ::Array[Module]
 
+  # <!--
+  #   rdoc-file=eval.c
+  #   - used_refinements -> array
+  # -->
+  # Returns an array of all modules used in the current scope. The ordering of
+  # modules in the resulting array is not defined.
+  #
+  #     module A
+  #       refine Object do
+  #       end
+  #     end
+  #
+  #     module B
+  #       refine Object do
+  #       end
+  #     end
+  #
+  #     using A
+  #     using B
+  #     p Module.used_refinements
+  #
+  # *produces:*
+  #
+  #     [#<refinement:Object@B>, #<refinement:Object@A>]
+  #
+  def self.used_refinements: () -> Array[Refinement]
+
   # <!--
   #   rdoc-file=object.c
   #   - mod < other   ->  true, false, or nil
   # -->
-  # Returns true if *mod* is a subclass of *other*. Returns `nil` if there's no
-  # relationship between the two. (Think of the relationship in terms of the class
-  # definition: "class A < B" implies "A < B".)
+  # Returns true if *mod* is a subclass of *other*. Returns `false` if *mod* is
+  # the same as *other* or *mod* is an ancestor of *other*. Returns `nil` if
+  # there's no relationship between the two. (Think of the relationship in terms
+  # of the class definition: "class A < B" implies "A < B".)
   #
   def <: (Module other) -> bool?
 
@@ -169,9 +197,10 @@ class Module < Object
   #   rdoc-file=object.c
   #   - mod > other   ->  true, false, or nil
   # -->
-  # Returns true if *mod* is an ancestor of *other*. Returns `nil` if there's no
-  # relationship between the two. (Think of the relationship in terms of the class
-  # definition: "class A < B" implies "B > A".)
+  # Returns true if *mod* is an ancestor of *other*. Returns `false` if *mod* is
+  # the same as *other* or *mod* is a descendant of *other*. Returns `nil` if
+  # there's no relationship between the two. (Think of the relationship in terms
+  # of the class definition: "class A < B" implies "B > A".)
   #
   def >: (Module other) -> bool?
 
@@ -206,7 +235,7 @@ class Module < Object
   #
   #     Exiting with code 99
   #
-  def alias_method: (::Symbol | ::String new_name, ::Symbol | ::String old_name) -> ::Symbol
+  def alias_method: (interned new_name, interned old_name) -> ::Symbol
 
   # <!--
   #   rdoc-file=object.c
@@ -255,7 +284,7 @@ class Module < Object
   #     end
   #     Mod.instance_methods.sort   #=> [:one, :one=, :two, :two=]
   #
-  def attr_accessor: (*Symbol | String arg0) -> NilClass
+  def attr_accessor: (*interned arg0) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=object.c
@@ -269,7 +298,7 @@ class Module < Object
   # in turn. String arguments are converted to symbols. Returns an array of
   # defined method names as symbols.
   #
-  def attr_reader: (*Symbol | String arg0) -> NilClass
+  def attr_reader: (*interned arg0) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=object.c
@@ -280,14 +309,14 @@ class Module < Object
   # *symbol*`.id2name`. String arguments are converted to symbols. Returns an
   # array of defined method names as symbols.
   #
-  def attr_writer: (*Symbol | String arg0) -> NilClass
+  def attr_writer: (*interned arg0) -> Array[Symbol]
 
   # <!--
   #   rdoc-file=load.c
-  #   - mod.autoload(module, filename)   -> nil
+  #   - mod.autoload(const, filename)   -> nil
   # -->
   # Registers *filename* to be loaded (using Kernel::require) the first time that
-  # *module* (which may be a String or a symbol) is accessed in the namespace of
+  # *const* (which may be a String or a symbol) is accessed in the namespace of
   # *mod*.
   #
   #     module A
@@ -295,7 +324,11 @@ class Module < Object
   #     A.autoload(:B, "b")
   #     A::B.doit            # autoloads "b"
   #
-  def autoload: (Symbol _module, String filename) -> NilClass
+  # If *const* in *mod* is defined as autoload, the file name to be loaded is
+  # replaced with *filename*.  If *const* is defined but not as autoload, does
+  # nothing.
+  #
+  def autoload: (interned _module, String filename) -> NilClass
 
   # <!--
   #   rdoc-file=load.c
@@ -321,7 +354,7 @@ class Module < Object
   #     B.autoload?(:CONST)          #=> "const.rb", found in A (ancestor)
   #     B.autoload?(:CONST, false)   #=> nil, not found in B itself
   #
-  def autoload?: (Symbol name, ?boolish inherit) -> String?
+  def autoload?: (interned name, ?boolish inherit) -> String?
 
   # <!-- rdoc-file=vm_eval.c -->
   # Evaluates the string or block in the context of *mod*, except that when a
@@ -344,7 +377,7 @@ class Module < Object
   #         or method `code' for Thing:Class
   #
   def class_eval: (String arg0, ?String filename, ?Integer lineno) -> untyped
-                | [U] () { (self m) -> U } -> U
+                | [U] () { (self m) [self: self] -> U } -> U
 
   # <!-- rdoc-file=vm_eval.c -->
   # Evaluates the given block in the context of the class/module. The method
@@ -363,7 +396,7 @@ class Module < Object
   #
   #     Hello there!
   #
-  def class_exec: [U] (*untyped args) { () -> U } -> U
+  def class_exec: [U] (*untyped, **untyped) { (?) [self: self] -> U } -> U
 
   # <!--
   #   rdoc-file=object.c
@@ -379,7 +412,7 @@ class Module < Object
   #     Fred.class_variable_defined?(:@@foo)    #=> true
   #     Fred.class_variable_defined?(:@@bar)    #=> false
   #
-  def class_variable_defined?: (Symbol | String arg0) -> bool
+  def class_variable_defined?: (interned arg0) -> bool
 
   # <!--
   #   rdoc-file=object.c
@@ -395,7 +428,7 @@ class Module < Object
   #     end
   #     Fred.class_variable_get(:@@foo)     #=> 99
   #
-  def class_variable_get: (Symbol | String arg0) -> untyped
+  def class_variable_get: (interned arg0) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -414,7 +447,7 @@ class Module < Object
   #     Fred.class_variable_set(:@@foo, 101)     #=> 101
   #     Fred.new.foo                             #=> 101
   #
-  def class_variable_set: (Symbol | String arg0, untyped arg1) -> untyped
+  def class_variable_set: (interned arg0, untyped arg1) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -436,6 +469,26 @@ class Module < Object
   #
   def class_variables: (?boolish inherit) -> ::Array[Symbol]
 
+  # <!--
+  #   rdoc-file=object.c
+  #   - const_added(const_name)
+  # -->
+  # Invoked as a callback whenever a constant is assigned on the receiver
+  #
+  #     module Chatty
+  #       def self.const_added(const_name)
+  #         super
+  #         puts "Added #{const_name.inspect}"
+  #       end
+  #       FOO = 1
+  #     end
+  #
+  # *produces:*
+  #
+  #     Added :FOO
+  #
+  def const_added: (Symbol) -> void
+
   # <!--
   #   rdoc-file=object.c
   #   - mod.const_defined?(sym, inherit=true)   -> true or false
@@ -474,7 +527,7 @@ class Module < Object
   #
   #     Hash.const_defined? 'foobar'   #=> NameError: wrong constant name foobar
   #
-  def const_defined?: (Symbol | String name, ?boolish inherit) -> bool
+  def const_defined?: (interned name, ?boolish inherit) -> bool
 
   # <!--
   #   rdoc-file=object.c
@@ -513,7 +566,7 @@ class Module < Object
   #
   #     Object.const_get 'foobar' #=> NameError: wrong constant name foobar
   #
-  def const_get: (Symbol | String name, ?boolish inherit) -> untyped
+  def const_get: (interned name, ?boolish inherit) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -521,7 +574,7 @@ class Module < Object
   # -->
   # Invoked when a reference is made to an undefined constant in *mod*. It is
   # passed a symbol for the undefined constant, and returns a value to be used for
-  # that constant. The following code is an example of the same:
+  # that constant. For example, consider:
   #
   #     def Foo.const_missing(name)
   #       name # return the constant name as Symbol
@@ -529,22 +582,27 @@ class Module < Object
   #
   #     Foo::UNDEFINED_CONST    #=> :UNDEFINED_CONST: symbol returned
   #
-  # In the next example when a reference is made to an undefined constant, it
-  # attempts to load a file whose name is the lowercase version of the constant
-  # (thus class `Fred` is assumed to be in file `fred.rb`).  If found, it returns
-  # the loaded class. It therefore implements an autoload feature similar to
-  # Kernel#autoload and Module#autoload.
+  # As the example above shows, `const_missing` is not required to create the
+  # missing constant in *mod*, though that is often a side-effect. The caller gets
+  # its return value when triggered. If the constant is also defined, further
+  # lookups won't hit `const_missing` and will return the value stored in the
+  # constant as usual. Otherwise, `const_missing` will be invoked again.
+  #
+  # In the next example, when a reference is made to an undefined constant,
+  # `const_missing` attempts to load a file whose path is the lowercase version of
+  # the constant name (thus class `Fred` is assumed to be in file `fred.rb`). If
+  # defined as a side-effect of loading the file, the method returns the value
+  # stored in the constant. This implements an autoload feature similar to
+  # Kernel#autoload and Module#autoload, though it differs in important ways.
   #
   #     def Object.const_missing(name)
   #       @looked_for ||= {}
   #       str_name = name.to_s
-  #       raise "Class not found: #{name}" if @looked_for[str_name]
+  #       raise "Constant not found: #{name}" if @looked_for[str_name]
   #       @looked_for[str_name] = 1
   #       file = str_name.downcase
   #       require file
-  #       klass = const_get(name)
-  #       return klass if klass
-  #       raise "Class not found: #{name}"
+  #       const_get(name, false)
   #     end
   #
   def const_missing: (Symbol arg0) -> untyped
@@ -565,7 +623,7 @@ class Module < Object
   #
   #     Object.const_set('foobar', 42) #=> NameError: wrong constant name foobar
   #
-  def const_set: (Symbol | String arg0, untyped arg1) -> untyped
+  def const_set: (interned arg0, untyped arg1) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -615,7 +673,7 @@ class Module < Object
   #     p Object.const_source_location('A::C1')   # => ["test.rb", 2]  -- nesting is supported
   #     p Object.const_source_location('String')  # => []  -- constant is defined in C code
   #
-  def const_source_location: (Symbol | String name, ?boolish inherit) -> ([ String, Integer ] | [ ] | nil)
+  def const_source_location: (interned name, ?boolish inherit) -> ([ String, Integer ] | [ ] | nil)
 
   # <!--
   #   rdoc-file=object.c
@@ -673,8 +731,8 @@ class Module < Object
   #     I'm Dino!
   #     #<B:0x401b39e8>
   #
-  def define_method: (Symbol | String arg0, ?Proc | Method | UnboundMethod arg1) -> Symbol
-                   | (Symbol | String arg0) { () -> untyped } -> Symbol
+  def define_method: (interned symbol, ^() [self: instance] -> untyped | Method | UnboundMethod method) -> Symbol
+                   | (interned symbol) { () [self: instance] -> untyped } -> Symbol
 
   # <!--
   #   rdoc-file=object.c
@@ -693,7 +751,7 @@ class Module < Object
   #     HTTP::NOT_FOUND
   #     # warning: constant HTTP::NOT_FOUND is deprecated
   #
-  def deprecate_constant: (*Symbol) -> self
+  def deprecate_constant: (*interned) -> self
 
   def eql?: (untyped other) -> bool
 
@@ -761,7 +819,7 @@ class Module < Object
   # -->
   # Invokes Module.append_features on each parameter in reverse order.
   #
-  def include: (*Module arg0) -> self
+  def include: (Module, *Module arg0) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -851,7 +909,7 @@ class Module < Object
   # Assign the module to a constant (name starting uppercase) if you want to treat
   # it like a regular module.
   #
-  def initialize: () -> Object
+  def initialize: () -> void
                 | () { (Module arg0) -> untyped } -> void
 
   # <!--
@@ -883,7 +941,7 @@ class Module < Object
   #
   #     Hello there, Dave!
   #
-  def instance_method: (Symbol arg0) -> UnboundMethod
+  def instance_method: (interned arg0) -> UnboundMethod
 
   # <!--
   #   rdoc-file=object.c
@@ -911,6 +969,15 @@ class Module < Object
   #     C.instance_methods(false)                   #=> [:method3]
   #     C.instance_methods.include?(:method2)       #=> true
   #
+  # Note that method visibility changes in the current class, as well as aliases,
+  # are considered as methods of the current class by this method:
+  #
+  #     class C < B
+  #       alias method4 method2
+  #       protected :method2
+  #     end
+  #     C.instance_methods(false).sort               #=> [:method2, :method3, :method4]
+  #
   def instance_methods: (?boolish include_super) -> ::Array[Symbol]
 
   # <!--
@@ -967,7 +1034,7 @@ class Module < Object
   #     C.method_defined? "method4"             #=> false
   #     C.method_defined? "private_method2"     #=> false
   #
-  def method_defined?: (Symbol | String name, ?boolish inherit) -> bool
+  def method_defined?: (interned name, ?boolish inherit) -> bool
 
   # <!--
   #   rdoc-file=object.c
@@ -1021,7 +1088,7 @@ class Module < Object
   #         or method `code' for Thing:Class
   #
   def module_eval: (String arg0, ?String filename, ?Integer lineno) -> untyped
-                 | [U] () { (self m) -> U } -> U
+                 | [U] () { (self m) [self: self] -> U } -> U
 
   # <!--
   #   rdoc-file=vm_eval.c
@@ -1044,7 +1111,7 @@ class Module < Object
   #
   #     Hello there!
   #
-  def module_exec: [U] (*untyped args) { (*untyped args) -> U } -> U
+  def module_exec: [U] (*untyped, **untyped) { (?) [self: self] -> U } -> U
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1085,13 +1152,17 @@ class Module < Object
   #     Mod.one     #=> "This is one"
   #     c.call_one  #=> "This is the new one"
   #
-  def module_function: (*Symbol | String arg0) -> self
+  def module_function: () -> nil
+                     | (Symbol method_name) -> Symbol
+                     | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
+                     | (string method_name) -> string
+                     | (interned, interned, *interned method_name) -> Array[interned]
 
   # <!--
   #   rdoc-file=object.c
-  #   - mod.name    -> string
+  #   - mod.name    -> string or nil
   # -->
-  # Returns the name of the module *mod*.  Returns nil for anonymous modules.
+  # Returns the name of the module *mod*.  Returns `nil` for anonymous modules.
   #
   def name: () -> String?
 
@@ -1101,7 +1172,7 @@ class Module < Object
   # -->
   # Invokes Module.prepend_features on each parameter in reverse order.
   #
-  def prepend: (*Module arg0) -> self
+  def prepend: (Module, *Module arg0) -> self
 
   # <!--
   #   rdoc-file=eval.c
@@ -1162,7 +1233,8 @@ class Module < Object
              | (Symbol method_name) -> Symbol
              | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
              | (string method_name) -> string
-             | (string | Symbol, string | Symbol, *string | Symbol method_name) -> Array[string | Symbol]
+             | (interned, interned, *interned method_name) -> Array[interned]
+             | (Array[interned]) -> Array[interned]
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1184,7 +1256,8 @@ class Module < Object
   #       end
   #     end
   #
-  def private_class_method: (*Symbol | String arg0) -> self
+  def private_class_method: (*interned arg0) -> self
+                          | (Array[interned] arg0) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1192,7 +1265,7 @@ class Module < Object
   # -->
   # Makes a list of existing constants private.
   #
-  def private_constant: (*Symbol arg0) -> self
+  def private_constant: (*interned arg0) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1239,7 +1312,7 @@ class Module < Object
   #     C.private_method_defined? "method2", false   #=> false
   #     C.method_defined? "method2"                  #=> false
   #
-  def private_method_defined?: (Symbol | String name, ?boolish inherit) -> bool
+  def private_method_defined?: (interned name, ?boolish inherit) -> bool
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1264,7 +1337,12 @@ class Module < Object
   #
   # To show a private method on RDoc, use `:doc:` instead of this.
   #
-  def protected: (*Symbol | String arg0) -> self
+  def protected: () -> nil
+               | (Symbol method_name) -> Symbol
+               | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
+               | (string method_name) -> string
+               | (interned, interned, *interned method_name) -> Array[interned]
+               | (Array[interned]) -> Array[interned]
 
   # <!--
   #   rdoc-file=object.c
@@ -1303,7 +1381,7 @@ class Module < Object
   #     C.protected_method_defined? "method2", false  #=> false
   #     C.method_defined? "method2"                   #=> true
   #
-  def protected_method_defined?: (Symbol | String name, ?boolish inherit) -> bool
+  def protected_method_defined?: (interned name, ?boolish inherit) -> bool
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1323,7 +1401,8 @@ class Module < Object
             | (Symbol method_name) -> Symbol
             | (Symbol, Symbol, *Symbol method_name) -> Array[Symbol]
             | (string method_name) -> string
-            | (string | Symbol, string | Symbol, *string | Symbol method_name) -> Array[string | Symbol]
+            | (interned, interned, *interned method_name) -> Array[interned]
+            | (Array[interned]) -> Array[interned]
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1336,7 +1415,8 @@ class Module < Object
   # String arguments are converted to symbols. An Array of Symbols and/or Strings
   # is also accepted.
   #
-  def public_class_method: (*Symbol | String arg0) -> self
+  def public_class_method: (*interned arg0) -> self
+                         | (Array[interned] arg0) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1344,7 +1424,7 @@ class Module < Object
   # -->
   # Makes a list of existing constants public.
   #
-  def public_constant: (*Symbol arg0) -> self
+  def public_constant: (*interned arg0) -> self
 
   # <!--
   #   rdoc-file=proc.c
@@ -1352,7 +1432,7 @@ class Module < Object
   # -->
   # Similar to *instance_method*, searches public method only.
   #
-  def public_instance_method: (Symbol arg0) -> UnboundMethod
+  def public_instance_method: (interned arg0) -> UnboundMethod
 
   # <!--
   #   rdoc-file=object.c
@@ -1391,7 +1471,7 @@ class Module < Object
   #     C.public_method_defined? "method2"         #=> false
   #     C.method_defined? "method2"                #=> true
   #
-  def public_method_defined?: (Symbol | String name, ?boolish inherit) -> bool
+  def public_method_defined?: (interned name, ?boolish inherit) -> bool
 
   # <!--
   #   rdoc-file=eval.c
@@ -1401,7 +1481,29 @@ class Module < Object
   #
   # Returns a module, where refined methods are defined.
   #
-  def refine: (Module mod) { () -> void } -> Refinement
+  def refine: (Module mod) { () [self: Refinement] -> void } -> Refinement
+
+  # <!--
+  #   rdoc-file=eval.c
+  #   - refinements -> array
+  # -->
+  # Returns an array of `Refinement` defined within the receiver.
+  #
+  #     module A
+  #       refine Integer do
+  #       end
+  #
+  #       refine String do
+  #       end
+  #     end
+  #
+  #     p A.refinements
+  #
+  # *produces:*
+  #
+  #     [#<refinement:Integer@A>, #<refinement:String@A>]
+  #
+  def refinements: () -> Array[Refinement]
 
   # <!--
   #   rdoc-file=object.c
@@ -1421,7 +1523,7 @@ class Module < Object
   #     99
   #     nil
   #
-  def remove_class_variable: (Symbol arg0) -> untyped
+  def remove_class_variable: (interned arg0) -> untyped
 
   # <!--
   #   rdoc-file=object.c
@@ -1431,7 +1533,7 @@ class Module < Object
   # previous value.  If that constant referred to a module, this will not change
   # that module's name and can lead to confusion.
   #
-  def remove_const: (Symbol arg0) -> untyped
+  def remove_const: (interned arg0) -> untyped
 
   # <!--
   #   rdoc-file=vm_method.c
@@ -1441,7 +1543,56 @@ class Module < Object
   # Removes the method identified by *symbol* from the current class. For an
   # example, see Module#undef_method. String arguments are converted to symbols.
   #
-  def remove_method: (*Symbol | String arg0) -> self
+  def remove_method: (*interned arg0) -> self
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - mod.set_temporary_name(string) -> self
+  #   - mod.set_temporary_name(nil) -> self
+  # -->
+  # Sets the temporary name of the module. This name is reflected in introspection
+  # of the module and the values that are related to it, such as instances,
+  # constants, and methods.
+  #
+  # The name should be `nil` or a non-empty string that is not a valid constant
+  # path (to avoid confusing between permanent and temporary names).
+  #
+  # The method can be useful to distinguish dynamically generated classes and
+  # modules without assigning them to constants.
+  #
+  # If the module is given a permanent name by assigning it to a constant, the
+  # temporary name is discarded. A temporary name can't be assigned to modules
+  # that have a permanent name.
+  #
+  # If the given name is `nil`, the module becomes anonymous again.
+  #
+  # Example:
+  #
+  #     m = Module.new # => #<Module:0x0000000102c68f38>
+  #     m.name #=> nil
+  #
+  #     m.set_temporary_name("fake_name") # => fake_name
+  #     m.name #=> "fake_name"
+  #
+  #     m.set_temporary_name(nil) # => #<Module:0x0000000102c68f38>
+  #     m.name #=> nil
+  #
+  #     c = Class.new
+  #     c.set_temporary_name("MyClass(with description)")
+  #
+  #     c.new # => #<MyClass(with description):0x0....>
+  #
+  #     c::M = m
+  #     c::M.name #=> "MyClass(with description)::M"
+  #
+  #     # Assigning to a constant replaces the name with a permanent one
+  #     C = c
+  #
+  #     C.name #=> "C"
+  #     C::M.name #=> "C::M"
+  #     c.new # => #<C:0x0....>
+  #
+  def set_temporary_name: (string?) -> self
 
   # <!--
   #   rdoc-file=object.c
@@ -1505,9 +1656,18 @@ class Module < Object
   #
   #     In child
   #     In parent
-  #     prog.rb:23: undefined method `hello' for #<Child:0x401b3bb4> (NoMethodError)
+  #     prog.rb:23: undefined method 'hello' for #<Child:0x401b3bb4> (NoMethodError)
+  #
+  def undef_method: (*interned arg0) -> self
+
+  # <!--
+  #   rdoc-file=object.c
+  #   - mod.undefined_instance_methods   -> array
+  # -->
+  # Returns a list of the undefined instance methods defined in *mod*. The
+  # undefined methods of any ancestors are not included.
   #
-  def undef_method: (*Symbol | String arg0) -> self
+  def undefined_instance_methods: () -> Array[Symbol]
 
   # <!--
   #   rdoc-file=eval.c
@@ -1536,5 +1696,9 @@ class Module < Object
   # `attr_reader(name)` but deprecated. Returns an array of defined method names
   # as symbols.
   #
-  def attr: (*Symbol | String arg0) -> NilClass
+  def attr: (*interned arg0) -> Array[Symbol]
+
+  # A previous incarnation of `interned` for backward-compatibility (see #1499)
+  %a{steep:deprecated}
+  type id = interned
 end