rbs 2.0.0 → 2.1.0

data/core/method.rbs

@@ -1,79 +1,116 @@
+# <!-- rdoc-file=proc.c -->
+# Method objects are created by Object#method, and are associated with a
+# particular object (not just with a class).  They may be used to invoke the
+# method within the object, and as a block associated with an iterator.  They
+# may also be unbound from one object (creating an UnboundMethod) and bound to
+# another.
+#
+#     class Thing
+#       def square(n)
+#         n*n
+#       end
+#     end
+#     thing = Thing.new
+#     meth  = thing.method(:square)
+#
+#     meth.call(9)                 #=> 81
+#     [ 1, 2, 3 ].collect(&meth)   #=> [1, 4, 9]
+#
+#     [ 1, 2, 3 ].each(&method(:puts)) #=> prints 1, 2, 3
+#
+#     require 'date'
+#     %w[2017-03-01 2017-03-02].collect(&Date.method(:parse))
+#     #=> [#<Date: 2017-03-01 ((2457814j,0s,0n),+0s,2299161j)>, #<Date: 2017-03-02 ((2457815j,0s,0n),+0s,2299161j)>]
+#
 class Method < Object
-  # Returns a `Proc` object corresponding to this method.
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.to_proc    -> proc
+  # -->
+  # Returns a Proc object corresponding to this method.
+  #
   def to_proc: () -> Proc
 
-  # Invokes the *meth* with the specified arguments, returning the method’s
-  # return value.
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.call(args, ...)    -> obj
+  # -->
+  # Invokes the *meth* with the specified arguments, returning the method's return
+  # value.
+  #
+  #     m = 12.method("+")
+  #     m.call(3)    #=> 15
+  #     m.call(20)   #=> 32
   #
-  # ```ruby
-  # m = 12.method("+")
-  # m.call(3)    #=> 15
-  # m.call(20)   #=> 32
-  # ```
   def call: (*untyped args) -> untyped
 
-  # Returns a proc that is the composition of this method and the given *g*
-  # . The returned proc takes a variable number of arguments, calls *g* with
-  # them then calls this method with the result.
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth << g -> a_proc
+  # -->
+  # Returns a proc that is the composition of this method and the given *g*. The
+  # returned proc takes a variable number of arguments, calls *g* with them then
+  # calls this method with the result.
   #
-  # ```ruby
-  # def f(x)
-  #   x * x
-  # end
+  #     def f(x)
+  #       x * x
+  #     end
+  #
+  #     f = self.method(:f)
+  #     g = proc {|x| x + x }
+  #     p (f << g).call(2) #=> 16
   #
-  # f = self.method(:f)
-  # g = proc {|x| x + x }
-  # p (f << g).call(2) #=> 16
-  # ```
   def <<: (Proc g) -> Proc
 
-  # Invokes the method with `obj` as the parameter like
-  # [call](Method.downloaded.ruby_doc#method-i-call). This allows a method
-  # object to be the target of a `when` clause in a case statement.
+  # <!-- rdoc-file=proc.c -->
+  # Invokes the *meth* with the specified arguments, returning the method's return
+  # value.
   #
-  # ```ruby
-  # require 'prime'
+  #     m = 12.method("+")
+  #     m.call(3)    #=> 15
+  #     m.call(20)   #=> 32
   #
-  # case 1373
-  # when Prime.method(:prime?)
-  #   # ...
-  # end
-  # ```
   alias === call
 
-  # Returns a proc that is the composition of this method and the given *g*
-  # . The returned proc takes a variable number of arguments, calls *g* with
-  # them then calls this method with the result.
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth >> g -> a_proc
+  # -->
+  # Returns a proc that is the composition of this method and the given *g*. The
+  # returned proc takes a variable number of arguments, calls this method with
+  # them then calls *g* with the result.
   #
-  # ```ruby
-  # def f(x)
-  #   x * x
-  # end
+  #     def f(x)
+  #       x * x
+  #     end
+  #
+  #     f = self.method(:f)
+  #     g = proc {|x| x + x }
+  #     p (f >> g).call(2) #=> 8
   #
-  # f = self.method(:f)
-  # g = proc {|x| x + x }
-  # p (f >> g).call(2) #=> 8
-  # ```
   def >>: (Proc g) -> Proc
 
-  # Invokes the *meth* with the specified arguments, returning the method’s
-  # return value.
+  # <!-- rdoc-file=proc.c -->
+  # Invokes the *meth* with the specified arguments, returning the method's return
+  # value.
+  #
+  #     m = 12.method("+")
+  #     m.call(3)    #=> 15
+  #     m.call(20)   #=> 32
   #
-  # ```ruby
-  # m = 12.method("+")
-  # m.call(3)    #=> 15
-  # m.call(20)   #=> 32
-  # ```
   alias [] call
 
-  # 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.
+  # <!--
+  #   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
@@ -103,83 +140,170 @@ class Method < Object
   #     "cat".method(:replace).arity   #=> 1
   #     "cat".method(:squeeze).arity   #=> -1
   #     "cat".method(:count).arity     #=> -1
+  #
   def arity: () -> Integer
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - method.clone -> new_method
+  # -->
   # Returns a clone of this method.
   #
-  # ```ruby
-  # class A
-  #   def foo
-  #     return "bar"
-  #   end
-  # end
-  #
-  # m = A.new.method(:foo)
-  # m.call # => "bar"
-  # n = m.clone.call # => "bar"
-  # ```
+  #     class A
+  #       def foo
+  #         return "bar"
+  #       end
+  #     end
+  #
+  #     m = A.new.method(:foo)
+  #     m.call # => "bar"
+  #     n = m.clone.call # => "bar"
+  #
   def clone: () -> Method
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.curry        -> proc
+  #   - meth.curry(arity) -> proc
+  # -->
+  # Returns a curried proc based on the method. When the proc is called with a
+  # number of arguments that is lower than the method's arity, then another
+  # curried proc is returned. Only when enough arguments have been supplied to
+  # satisfy the method signature, will the method actually be called.
+  #
+  # The optional *arity* argument should be supplied when currying methods with
+  # variable arguments to determine how many arguments are needed before the
+  # method is called.
+  #
+  #     def foo(a,b,c)
+  #       [a, b, c]
+  #     end
+  #
+  #     proc  = self.method(:foo).curry
+  #     proc2 = proc.call(1, 2)          #=> #<Proc>
+  #     proc2.call(3)                    #=> [1,2,3]
+  #
+  #     def vararg(*args)
+  #       args
+  #     end
+  #
+  #     proc = self.method(:vararg).curry(4)
+  #     proc2 = proc.call(:x)      #=> #<Proc>
+  #     proc3 = proc2.call(:y, :z) #=> #<Proc>
+  #     proc3.call(:a)             #=> [:x, :y, :z, :a]
+  #
   def curry: (?Integer arity) -> Proc
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.name    -> symbol
+  # -->
   # Returns the name of the method.
+  #
   def name: () -> Symbol
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.original_name    -> symbol
+  # -->
   # Returns the original name of the method.
   #
-  # ```ruby
-  # class C
-  #   def foo; end
-  #   alias bar foo
-  # end
-  # C.instance_method(:bar).original_name # => :foo
-  # ```
+  #     class C
+  #       def foo; end
+  #       alias bar foo
+  #     end
+  #     C.instance_method(:bar).original_name # => :foo
+  #
   def original_name: () -> Symbol
 
-  # Returns the class or module that defines the method. See also receiver.
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.owner    -> class_or_module
+  # -->
+  # Returns the class or module that defines the method. See also Method#receiver.
+  #
+  #     (1..3).method(:map).owner #=> Enumerable
   #
-  # ```ruby
-  # (1..3).method(:map).owner #=> Enumerable
-  # ```
   def owner: () -> (Class | Module)
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.parameters  -> array
+  # -->
   # Returns the parameter information of this method.
   #
-  # ```ruby
-  # def foo(bar); end
-  # method(:foo).parameters #=> [[:req, :bar]]
+  #     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, 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, *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: () -> ::Array[[ :req | :opt | :rest | :keyreq | :key | :keyrest | :block, Symbol ] | [ :rest | :keyrest ]]
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.private? -> true or false
+  # -->
+  # Returns whether the method is private.
   #
-  # def foo(bar, baz, *args, &blk); end
-  # method(:foo).parameters #=> [[:req, :bar], [:req, :baz], [:rest, :args], [:block, :blk]]
-  # ```
-  def parameters: () -> ::Array[
-    [:req | :opt | :rest | :keyreq | :key | :keyrest | :block, Symbol] |
-    [:rest | :keyrest]
-  ]
+  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
+
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.receiver    -> object
+  # -->
   # Returns the bound receiver of the method object.
   #
-  # ```ruby
-  # (1..3).method(:map).receiver # => 1..3
-  # ```
+  #     (1..3).method(:map).receiver # => 1..3
+  #
   def receiver: () -> untyped
 
-  # 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.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 ]?
 
-  # Returns a [Method](Method.downloaded.ruby_doc) of superclass which would
-  # be called when super is used or nil if there is no method on superclass.
+  # <!--
+  #   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: () -> Method?
 
-  # Dissociates *meth* from its current receiver. The resulting
-  # `UnboundMethod` can subsequently be bound to a new object of the same
-  # class (see `UnboundMethod` ).
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.unbind    -> unbound_method
+  # -->
+  # Dissociates *meth* from its current receiver. The resulting UnboundMethod can
+  # subsequently be bound to a new object of the same class (see UnboundMethod).
+  #
   def unbind: () -> UnboundMethod
 end