Class

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)
square.(3)
square[3]

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 }
end
times3 = gen_times(3)
times5 = gen_times(5)
times3.call(12)
times5.call(5)
times3.call(times5.call(4))

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 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:

$a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1 { return }; $a << :m2 end; m2; p $a
$a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1 { break }; $a << :m2 end; m2; p $a
$a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1 { next }; $a << :m2 end; m2; p $a
$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
$a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&proc { next }); $a << :m2 end; m2; p $a
$a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&-> { return }); $a << :m2 end; m2; p $a
$a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&-> { break }); $a << :m2 end; m2; p $a
$a = []; def m1(&b) b.call; $a << :m1 end; def m2() m1(&-> { next }); $a << :m2 end; m2; p $a
p = proc {|x, y| "x=#{x}, y=#{y}" }
p.call(1, 2)
p.call([1, 2])
p.call(1, 2, 8)
p.call(1)
l = lambda {|x, y| "x=#{x}, y=#{y}" }
l.call(1, 2)
l.call([1, 2])
l.call(1, 2, 8)
l.call(1)
def test_return
  -> { return 3 }.call
  proc { return 4 }.call
  return 5
end
test_return

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, 2], [3, 4]].map(&l)

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)
C.new.method(:e).to_proc.lambda?

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)

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)
["Bob", "Jane"].map(&hey)

Of the Ruby core classes, this method is implemented by Symbol, Method, and Hash.

:to_s.to_proc.call(1)
[1, 2].map(&:to_s)
method(:puts).to_proc.call(1)
[1, 2].each(&method(:puts))
{test: 1}.to_proc.call(:test)
%i[test many keys].map(&{test: 1})

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
def m1(&b) b.call end; def m2(); m1 { break } end; m2
def m1(&b) b end; def m2(); m1 { return }.call end; m2
def m1(&b) b end; def m2(); m1 { break }.call end; m2
def m1(&b) b end; def m2(); m1 { return } end; m2.call
def m1(&b) b end; def m2(); m1 { break } end; m2.call

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:

%w[test me please].each { |str| puts str.upcase }
(1..5).map { |i| i**2 }
%w[test me please].each { puts _1.upcase }
(1..5).map { _1**2 }

Parameter names from _1 to _9 are supported:

[10, 20, 30].zip([40, 50, 60], [70, 80, 90]).map { _1 + _2 + _3 }

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
p.arity
l.parameters
l.arity

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 Methods

Creates a new Proc object, bound to the current context.

proc = Proc.new { "hello" }
proc.call

Raises ArgumentError if called without a block.

Proc.new

Instance Methods

Returns a proc that is the composition of this proc and the given g. The returned proc takes a variable number of arguments, calls g with them then calls this proc with the result.

f = proc {|x| x * x }
g = proc {|x| x + x }
p (f << g).call(2)

See Proc#>> for detailed explanations.

Two procs are the same if, and only if, they were created from the same code block.

def return_block(&block)
  block
end
def pass_block_twice(&block)
  [return_block(&block), return_block(&block)]
end
block1, block2 = pass_block_twice { puts 'test' }
block1 == block2
block1 == proc { puts 'test' }

Returns a proc that is the composition of this proc and the given g. The returned proc takes a variable number of arguments, calls this proc with them then calls g with the result.

f = proc {|x| x * x }
g = proc {|x| x + x }
p (f >> g).call(2)

g could be other Proc, or Method, or any other object responding to call method:

class Parser
  def self.call(text)
  end
end
pipeline = File.method(:read) >> Parser >> proc { |data| puts "data size: #{data.count}" }
pipeline.call('data.json')

See also Object#hash.

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)

It provides nil for missing arguments.

proc {|a,b| [a,b] }.call(1)

It expands a single array argument.

proc {|a,b| [a,b] }.call([1,2])

A Proc object generated by lambda doesn’t have such tricks.

lambda {|a,b| [a,b] }.call(1,2,3)
lambda {|a,b| [a,b] }.call(1)
lambda {|a,b| [a,b] }.call([1,2])

Proc#lambda? is a predicate for the tricks. It returns true if no tricks apply.

lambda {}.lambda?
proc {}.lambda?

Proc.new is the same as proc.

Proc.new {}.lambda?

lambda, proc and Proc.new preserve the tricks of a Proc object given by & argument.

lambda(&lambda {}).lambda?
proc(&lambda {}).lambda?
Proc.new(&lambda {}).lambda?
lambda(&proc {}).lambda?
proc(&proc {}).lambda?
Proc.new(&proc {}).lambda?

A Proc object generated by & argument has the tricks

def n(&b) b.lambda? end
n {}

The & argument preserves the tricks if a Proc object is given by & argument.

n(&lambda {})
n(&proc {})
n(&Proc.new {})

A Proc object converted from a method has no tricks.

def m() end
method(:m).to_proc.lambda?
n(&method(:m))
n(&method(:m).to_proc)

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)
C.new.method(:d).to_proc.lambda?

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)
C.new.method(:e).to_proc.lambda?

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)

The wrapper def2 defines a method which has no tricks.

Returns the parameter information of this proc.

prc = lambda{|x, y=42, *other|}
prc.parameters

Marks the proc as passing keywords through a normal argument splat. This should only be called on procs that accept an argument splat (*args) but not explicit keywords or a keyword splat. It marks the proc such that if the proc is called with keyword arguments, the final hash argument is marked with a special flag such that if it is the final element of a normal argument splat to another method call, and that method call does not include explicit keywords or a keyword splat, the final element is interpreted as keywords. In other words, keywords will be passed through the proc to other methods.

This should only be used for procs that delegate keywords to another method, and only for backwards compatibility with Ruby versions before 2.7.

This method will probably be removed at some point, as it exists only for backwards compatibility. As it does not exist in Ruby versions before 2.7, check that the proc responds to this method before calling it. Also, be aware that if this method is removed, the behavior of the proc will change so that it does not pass through keywords.

module Mod
  foo = ->(meth, *args, &block) do
    send(:"do_#{meth}", *args, &block)
  end
  foo.ruby2_keywords if foo.respond_to?(:ruby2_keywords)
end

Returns the Ruby source filename and line number containing this proc or nil if this proc was not defined in Ruby (i.e. native).

Part of the protocol for converting objects to Proc objects. Instances of class Proc simply return themselves.

Returns the unique identifier for this proc, along with an indication of where the proc was defined.

Creation

Lambda and non-lambda semantics

Conversion of other objects to procs

Orphaned Proc

Numbered parameters

Orphaned `Proc`