JezK
Edit File: proc.rbs
# <!-- rdoc-file=proc.c --> # A `Proc` object is an encapsulation of a block of code, which can be stored in # a local variable, passed to a method or another Proc, and can be called. Proc # is an essential concept in Ruby and a core of its functional programming # features. # # square = Proc.new {|x| x**2 } # # square.call(3) #=> 9 # # shorthands: # square.(3) #=> 9 # square[3] #=> 9 # # Proc objects are *closures*, meaning they remember and can use the entire # context in which they were created. # # def gen_times(factor) # Proc.new {|n| n*factor } # remembers the value of factor at the moment of creation # end # # times3 = gen_times(3) # times5 = gen_times(5) # # times3.call(12) #=> 36 # times5.call(5) #=> 25 # times3.call(times5.call(4)) #=> 60 # # ## Creation # # There are several methods to create a Proc # # * Use the Proc class constructor: # # proc1 = Proc.new {|x| x**2 } # # * Use the Kernel#proc method as a shorthand of Proc.new: # # proc2 = proc {|x| x**2 } # # * Receiving a block of code into proc argument (note the `&`): # # def make_proc(&block) # block # end # # proc3 = make_proc {|x| x**2 } # # * Construct a proc with lambda semantics using the Kernel#lambda method (see # below for explanations about lambdas): # # lambda1 = lambda {|x| x**2 } # # * Use the [Lambda proc # literal](doc/syntax/literals_rdoc.html#label-Lambda+Proc+Literals) syntax # (also constructs a proc with lambda semantics): # # lambda2 = ->(x) { x**2 } # # # ## Lambda and non-lambda semantics # # Procs are coming in two flavors: lambda and non-lambda (regular procs). # Differences are: # # * In lambdas, `return` and `break` means exit from this lambda; # * In non-lambda procs, `return` means exit from embracing method (and will # throw `LocalJumpError` if invoked outside the method); # * In non-lambda procs, `break` means exit from the method which the block # given for. (and will throw `LocalJumpError` if invoked after the method # returns); # * In lambdas, arguments are treated in the same way as in methods: strict, # with `ArgumentError` for mismatching argument number, and no additional # argument processing; # * Regular procs accept arguments more generously: missing arguments are # filled with `nil`, single Array arguments are deconstructed if the proc # has multiple arguments, and there is no error raised on extra arguments. # # # Examples: # # # +return+ in non-lambda proc, +b+, exits +m2+. # # (The block +{ return }+ is given for +m1+ and embraced by +m2+.) # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1 { return }; $a << :m2 end; m2; p $a # #=> [] # # # +break+ in non-lambda proc, +b+, exits +m1+. # # (The block +{ break }+ is given for +m1+ and embraced by +m2+.) # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1 { break }; $a << :m2 end; m2; p $a # #=> [:m2] # # # +next+ in non-lambda proc, +b+, exits the block. # # (The block +{ next }+ is given for +m1+ and embraced by +m2+.) # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1 { next }; $a << :m2 end; m2; p $a # #=> [:m1, :m2] # # # Using +proc+ method changes the behavior as follows because # # The block is given for +proc+ method and embraced by +m2+. # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&proc { return }); $a << :m2 end; m2; p $a # #=> [] # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&proc { break }); $a << :m2 end; m2; p $a # # break from proc-closure (LocalJumpError) # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&proc { next }); $a << :m2 end; m2; p $a # #=> [:m1, :m2] # # # +return+, +break+ and +next+ in the stubby lambda exits the block. # # (+lambda+ method behaves same.) # # (The block is given for stubby lambda syntax and embraced by +m2+.) # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&-> { return }); $a << :m2 end; m2; p $a # #=> [:m1, :m2] # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&-> { break }); $a << :m2 end; m2; p $a # #=> [:m1, :m2] # $a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&-> { next }); $a << :m2 end; m2; p $a # #=> [:m1, :m2] # # p = proc {|x, y| "x=#{x}, y=#{y}" } # p.call(1, 2) #=> "x=1, y=2" # p.call([1, 2]) #=> "x=1, y=2", array deconstructed # p.call(1, 2, 8) #=> "x=1, y=2", extra argument discarded # p.call(1) #=> "x=1, y=", nil substituted instead of error # # l = lambda {|x, y| "x=#{x}, y=#{y}" } # l.call(1, 2) #=> "x=1, y=2" # l.call([1, 2]) # ArgumentError: wrong number of arguments (given 1, expected 2) # l.call(1, 2, 8) # ArgumentError: wrong number of arguments (given 3, expected 2) # l.call(1) # ArgumentError: wrong number of arguments (given 1, expected 2) # # def test_return # -> { return 3 }.call # just returns from lambda into method body # proc { return 4 }.call # returns from method # return 5 # end # # test_return # => 4, return from proc # # Lambdas are useful as self-sufficient functions, in particular useful as # arguments to higher-order functions, behaving exactly like Ruby methods. # # Procs are useful for implementing iterators: # # def test # [[1, 2], [3, 4], [5, 6]].map {|a, b| return a if a + b > 10 } # # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ # end # # Inside `map`, the block of code is treated as a regular (non-lambda) proc, # which means that the internal arrays will be deconstructed to pairs of # arguments, and `return` will exit from the method `test`. That would not be # possible with a stricter lambda. # # You can tell a lambda from a regular proc by using the #lambda? instance # method. # # Lambda semantics is typically preserved during the proc lifetime, including # `&`-deconstruction to a block of code: # # p = proc {|x, y| x } # l = lambda {|x, y| x } # [[1, 2], [3, 4]].map(&p) #=> [1, 3] # [[1, 2], [3, 4]].map(&l) # ArgumentError: wrong number of arguments (given 1, expected 2) # # The only exception is dynamic method definition: even if defined by passing a # non-lambda proc, methods still have normal semantics of argument checking. # # class C # define_method(:e, &proc {}) # end # C.new.e(1,2) #=> ArgumentError # C.new.method(:e).to_proc.lambda? #=> true # # This exception ensures that methods never have unusual argument passing # conventions, and makes it easy to have wrappers defining methods that behave # as usual. # # class C # def self.def2(name, &body) # define_method(name, &body) # end # # def2(:f) {} # end # C.new.f(1,2) #=> ArgumentError # # The wrapper `def2` receives *body* as a non-lambda proc, yet defines a method # which has normal semantics. # # ## Conversion of other objects to procs # # Any object that implements the `to_proc` method can be converted into a proc # by the `&` operator, and therefore can be consumed by iterators. # # class Greeter # def initialize(greeting) # @greeting = greeting # end # # def to_proc # proc {|name| "#{@greeting}, #{name}!" } # end # end # # hi = Greeter.new("Hi") # hey = Greeter.new("Hey") # ["Bob", "Jane"].map(&hi) #=> ["Hi, Bob!", "Hi, Jane!"] # ["Bob", "Jane"].map(&hey) #=> ["Hey, Bob!", "Hey, Jane!"] # # Of the Ruby core classes, this method is implemented by Symbol, Method, and # Hash. # # :to_s.to_proc.call(1) #=> "1" # [1, 2].map(&:to_s) #=> ["1", "2"] # # method(:puts).to_proc.call(1) # prints 1 # [1, 2].each(&method(:puts)) # prints 1, 2 # # {test: 1}.to_proc.call(:test) #=> 1 # %i[test many keys].map(&{test: 1}) #=> [1, nil, nil] # # ## Orphaned Proc # # `return` and `break` in a block exit a method. If a Proc object is generated # from the block and the Proc object survives until the method is returned, # `return` and `break` cannot work. In such case, `return` and `break` raises # LocalJumpError. A Proc object in such situation is called as orphaned Proc # object. # # Note that the method to exit is different for `return` and `break`. There is a # situation that orphaned for `break` but not orphaned for `return`. # # def m1(&b) b.call end; def m2(); m1 { return } end; m2 # ok # def m1(&b) b.call end; def m2(); m1 { break } end; m2 # ok # # def m1(&b) b end; def m2(); m1 { return }.call end; m2 # ok # def m1(&b) b end; def m2(); m1 { break }.call end; m2 # LocalJumpError # # def m1(&b) b end; def m2(); m1 { return } end; m2.call # LocalJumpError # def m1(&b) b end; def m2(); m1 { break } end; m2.call # LocalJumpError # # Since `return` and `break` exits the block itself in lambdas, lambdas cannot # be orphaned. # # ## Numbered parameters # # Numbered parameters are implicitly defined block parameters intended to # simplify writing short blocks: # # # Explicit parameter: # %w[test me please].each { |str| puts str.upcase } # prints TEST, ME, PLEASE # (1..5).map { |i| i**2 } # => [1, 4, 9, 16, 25] # # # Implicit parameter: # %w[test me please].each { puts _1.upcase } # prints TEST, ME, PLEASE # (1..5).map { _1**2 } # => [1, 4, 9, 16, 25] # # Parameter names from `_1` to `_9` are supported: # # [10, 20, 30].zip([40, 50, 60], [70, 80, 90]).map { _1 + _2 + _3 } # # => [120, 150, 180] # # Though, it is advised to resort to them wisely, probably limiting yourself to # `_1` and `_2`, and to one-line blocks. # # Numbered parameters can't be used together with explicitly named ones: # # [10, 20, 30].map { |x| _1**2 } # # SyntaxError (ordinary parameter is defined) # # To avoid conflicts, naming local variables or method arguments `_1`, `_2` and # so on, causes a warning. # # _1 = 'test' # # warning: `_1' is reserved as numbered parameter # # Using implicit numbered parameters affects block's arity: # # p = proc { _1 + _2 } # l = lambda { _1 + _2 } # p.parameters # => [[:opt, :_1], [:opt, :_2]] # p.arity # => 2 # l.parameters # => [[:req, :_1], [:req, :_2]] # l.arity # => 2 # # Blocks with numbered parameters can't be nested: # # %w[test me].each { _1.each_char { p _1 } } # # SyntaxError (numbered parameter is already used in outer block here) # # %w[test me].each { _1.each_char { p _1 } } # # ^~ # # Numbered parameters were introduced in Ruby 2.7. # class Proc < Object def clone: () -> self # <!-- # rdoc-file=proc.c # - prc.arity -> integer # --> # Returns the number of mandatory arguments. If the block is declared to take no # arguments, returns 0. If the block is known to take exactly n arguments, # returns n. If the block has optional arguments, returns -n-1, where n is the # number of mandatory arguments, with the exception for blocks that are not # lambdas and have only a finite number of optional arguments; in this latter # case, returns n. Keyword arguments will be considered as a single additional # argument, that argument being mandatory if any keyword argument is mandatory. # A #proc with no argument declarations is the same as a block declaring `||` as # its arguments. # # proc {}.arity #=> 0 # proc { || }.arity #=> 0 # proc { |a| }.arity #=> 1 # proc { |a, b| }.arity #=> 2 # proc { |a, b, c| }.arity #=> 3 # proc { |*a| }.arity #=> -1 # proc { |a, *b| }.arity #=> -2 # proc { |a, *b, c| }.arity #=> -3 # proc { |x:, y:, z:0| }.arity #=> 1 # proc { |*a, x:, y:0| }.arity #=> -2 # # proc { |a=0| }.arity #=> 0 # lambda { |a=0| }.arity #=> -1 # proc { |a=0, b| }.arity #=> 1 # lambda { |a=0, b| }.arity #=> -2 # proc { |a=0, b=0| }.arity #=> 0 # lambda { |a=0, b=0| }.arity #=> -1 # proc { |a, b=0| }.arity #=> 1 # lambda { |a, b=0| }.arity #=> -2 # proc { |(a, b), c=0| }.arity #=> 1 # lambda { |(a, b), c=0| }.arity #=> -2 # proc { |a, x:0, y:0| }.arity #=> 1 # lambda { |a, x:0, y:0| }.arity #=> -2 # def arity: () -> Integer # <!-- # rdoc-file=proc.c # - prc.binding -> binding # --> # Returns the binding associated with *prc*. # # def fred(param) # proc {} # end # # b = fred(99) # eval("param", b.binding) #=> 99 # def binding: () -> Binding # <!-- # rdoc-file=proc.c # - prc.call(params,...) -> obj # - prc[params,...] -> obj # - prc.(params,...) -> obj # - prc.yield(params,...) -> obj # --> # Invokes the block, setting the block's parameters to the values in *params* # using something close to method calling semantics. Returns the value of the # last expression evaluated in the block. # # a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } } # a_proc.call(9, 1, 2, 3) #=> [9, 18, 27] # a_proc[9, 1, 2, 3] #=> [9, 18, 27] # a_proc.(9, 1, 2, 3) #=> [9, 18, 27] # a_proc.yield(9, 1, 2, 3) #=> [9, 18, 27] # # Note that `prc.()` invokes `prc.call()` with the parameters given. It's # syntactic sugar to hide "call". # # For procs created using #lambda or `->()` an error is generated if the wrong # number of parameters are passed to the proc. For procs created using Proc.new # or Kernel.proc, extra parameters are silently discarded and missing parameters # are set to `nil`. # # a_proc = proc {|a,b| [a,b] } # a_proc.call(1) #=> [1, nil] # # a_proc = lambda {|a,b| [a,b] } # a_proc.call(1) # ArgumentError: wrong number of arguments (given 1, expected 2) # # See also Proc#lambda?. # def call: (*untyped arg0) -> untyped # <!-- rdoc-file=proc.c --> # Invokes the block, setting the block's parameters to the values in *params* # using something close to method calling semantics. Returns the value of the # last expression evaluated in the block. # # a_proc = Proc.new {|scalar, *values| values.map {|value| value*scalar } } # a_proc.call(9, 1, 2, 3) #=> [9, 18, 27] # a_proc[9, 1, 2, 3] #=> [9, 18, 27] # a_proc.(9, 1, 2, 3) #=> [9, 18, 27] # a_proc.yield(9, 1, 2, 3) #=> [9, 18, 27] # # Note that `prc.()` invokes `prc.call()` with the parameters given. It's # syntactic sugar to hide "call". # # For procs created using #lambda or `->()` an error is generated if the wrong # number of parameters are passed to the proc. For procs created using Proc.new # or Kernel.proc, extra parameters are silently discarded and missing parameters # are set to `nil`. # # a_proc = proc {|a,b| [a,b] } # a_proc.call(1) #=> [1, nil] # # a_proc = lambda {|a,b| [a,b] } # a_proc.call(1) # ArgumentError: wrong number of arguments (given 1, expected 2) # # See also Proc#lambda?. # def []: (*untyped arg0) -> untyped # <!-- # rdoc-file=proc.c # - prc.curry -> a_proc # - prc.curry(arity) -> a_proc # --> # Returns a curried proc. If the optional *arity* argument is given, it # determines the number of arguments. A curried proc receives some arguments. If # a sufficient number of arguments are supplied, it passes the supplied # arguments to the original proc and returns the result. Otherwise, returns # another curried proc that takes the rest of arguments. # # b = proc {|x, y, z| (x||0) + (y||0) + (z||0) } # p b.curry[1][2][3] #=> 6 # p b.curry[1, 2][3, 4] #=> 6 # p b.curry(5)[1][2][3][4][5] #=> 6 # p b.curry(5)[1, 2][3, 4][5] #=> 6 # p b.curry(1)[1] #=> 1 # # b = proc {|x, y, z, *w| (x||0) + (y||0) + (z||0) + w.inject(0, &:+) } # p b.curry[1][2][3] #=> 6 # p b.curry[1, 2][3, 4] #=> 10 # p b.curry(5)[1][2][3][4][5] #=> 15 # p b.curry(5)[1, 2][3, 4][5] #=> 15 # p b.curry(1)[1] #=> 1 # # b = lambda {|x, y, z| (x||0) + (y||0) + (z||0) } # p b.curry[1][2][3] #=> 6 # p b.curry[1, 2][3, 4] #=> wrong number of arguments (given 4, expected 3) # p b.curry(5) #=> wrong number of arguments (given 5, expected 3) # p b.curry(1) #=> wrong number of arguments (given 1, expected 3) # # b = lambda {|x, y, z, *w| (x||0) + (y||0) + (z||0) + w.inject(0, &:+) } # p b.curry[1][2][3] #=> 6 # p b.curry[1, 2][3, 4] #=> 10 # p b.curry(5)[1][2][3][4][5] #=> 15 # p b.curry(5)[1, 2][3, 4][5] #=> 15 # p b.curry(1) #=> wrong number of arguments (given 1, expected 3) # # b = proc { :foo } # p b.curry[] #=> :foo # def curry: (?_ToInt arity) -> Proc # <!-- # rdoc-file=proc.c # - prc.hash -> integer # --> # Returns a hash value corresponding to proc body. # # See also Object#hash. # def hash: () -> Integer # <!-- # rdoc-file=proc.c # - Proc.new {|...| block } -> a_proc # --> # Creates a new Proc object, bound to the current context. # # proc = Proc.new { "hello" } # proc.call #=> "hello" # # Raises ArgumentError if called without a block. # # Proc.new #=> ArgumentError # def initialize: () { (*untyped) -> untyped } -> void # <!-- # rdoc-file=proc.c # - prc.lambda? -> true or false # --> # Returns `true` if a Proc object is lambda. `false` if non-lambda. # # The lambda-ness affects argument handling and the behavior of `return` and # `break`. # # A Proc object generated by `proc` ignores extra arguments. # # proc {|a,b| [a,b] }.call(1,2,3) #=> [1,2] # # It provides `nil` for missing arguments. # # proc {|a,b| [a,b] }.call(1) #=> [1,nil] # # It expands a single array argument. # # proc {|a,b| [a,b] }.call([1,2]) #=> [1,2] # # A Proc object generated by `lambda` doesn't have such tricks. # # lambda {|a,b| [a,b] }.call(1,2,3) #=> ArgumentError # lambda {|a,b| [a,b] }.call(1) #=> ArgumentError # lambda {|a,b| [a,b] }.call([1,2]) #=> ArgumentError # # Proc#lambda? is a predicate for the tricks. It returns `true` if no tricks # apply. # # lambda {}.lambda? #=> true # proc {}.lambda? #=> false # # Proc.new is the same as `proc`. # # Proc.new {}.lambda? #=> false # # `lambda`, `proc` and Proc.new preserve the tricks of a Proc object given by # `&` argument. # # lambda(&lambda {}).lambda? #=> true # proc(&lambda {}).lambda? #=> true # Proc.new(&lambda {}).lambda? #=> true # # lambda(&proc {}).lambda? #=> false # proc(&proc {}).lambda? #=> false # Proc.new(&proc {}).lambda? #=> false # # A Proc object generated by `&` argument has the tricks # # def n(&b) b.lambda? end # n {} #=> false # # The `&` argument preserves the tricks if a Proc object is given by `&` # argument. # # n(&lambda {}) #=> true # n(&proc {}) #=> false # n(&Proc.new {}) #=> false # # A Proc object converted from a method has no tricks. # # def m() end # method(:m).to_proc.lambda? #=> true # # n(&method(:m)) #=> true # n(&method(:m).to_proc) #=> true # # `define_method` is treated the same as method definition. The defined method # has no tricks. # # class C # define_method(:d) {} # end # C.new.d(1,2) #=> ArgumentError # C.new.method(:d).to_proc.lambda? #=> true # # `define_method` always defines a method without the tricks, even if a # non-lambda Proc object is given. This is the only exception for which the # tricks are not preserved. # # class C # define_method(:e, &proc {}) # end # C.new.e(1,2) #=> ArgumentError # C.new.method(:e).to_proc.lambda? #=> true # # This exception ensures that methods never have tricks and makes it easy to # have wrappers to define methods that behave as usual. # # class C # def self.def2(name, &body) # define_method(name, &body) # end # # def2(:f) {} # end # C.new.f(1,2) #=> ArgumentError # # The wrapper *def2* defines a method which has no tricks. # def lambda?: () -> bool # <!-- # rdoc-file=proc.c # - prc.parameters -> array # --> # Returns the parameter information of this proc. # # prc = lambda{|x, y=42, *other|} # prc.parameters #=> [[:req, :x], [:opt, :y], [:rest, :other]] # def parameters: () -> ::Array[[ Symbol, Symbol ]] # <!-- # rdoc-file=proc.c # - prc.source_location -> [String, Integer] # --> # Returns the Ruby source filename and line number containing this proc or `nil` # if this proc was not defined in Ruby (i.e. native). # def source_location: () -> [ String, Integer ] # <!-- # rdoc-file=proc.c # - prc.to_proc -> proc # --> # Part of the protocol for converting objects to Proc objects. Instances of # class Proc simply return themselves. # def to_proc: () -> self # <!-- # rdoc-file=proc.c # - prc.to_s -> string # --> # Returns the unique identifier for this proc, along with an indication of where # the proc was defined. # def to_s: () -> String # <!-- rdoc-file=proc.c --> # Returns the unique identifier for this proc, along with an indication of where # the proc was defined. # def inspect: () -> String end