Class: Proc

Inherits:

Object

Object
Proc

show all

Defined in:: proc.c

Overview

Proc objects are blocks of code that have been bound to a set of local variables. Once bound, the code may be called in different contexts and still access those variables.

def gen_times(factor)
  return Proc.new {|n| n*factor }
end

times3 = gen_times(3)
times5 = gen_times(5)

times3.call(12)               #=> 36
times5.call(5)                #=> 25
times3.call(times5.call(4))   #=> 60

Class Method Summary collapse

.new ⇒ Object

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

Instance Method Summary collapse

#==(other_proc) ⇒ Boolean

Returns true if prc is the same object as other_proc, or if they are both procs with the same body.
#===(obj) ⇒ Object

Invokes the block with obj as the proc's parameter like Proc#call.
#[] ⇒ Object

Invokes the block, setting the block's parameters to the values in params using something close to method calling semantics.
#arity ⇒ Fixnum

Returns the number of arguments that would not be ignored.
#binding ⇒ Binding

Returns the binding associated with prc.
#call ⇒ Object

Invokes the block, setting the block's parameters to the values in params using something close to method calling semantics.
#clone ⇒ Object

:nodoc:.
#curry ⇒ Object

Returns a curried proc.
#dup ⇒ Object

:nodoc:.
#==(other_proc) ⇒ Boolean

Returns true if prc is the same object as other_proc, or if they are both procs with the same body.
#hash ⇒ Integer

Returns a hash value corresponding to proc body.
#lambda? ⇒ Boolean

Returns true for a Proc object for which argument handling is rigid.
#parameters ⇒ Array

Returns the parameter information of this proc.
#source_location ⇒ Array, Fixnum

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

Part of the protocol for converting objects to Proc objects.
#to_s ⇒ String

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

Invokes the block, setting the block's parameters to the values in params using something close to method calling semantics.

Class Method Details

.new {|...| ... } ⇒ `Proc` .new ⇒ `Proc`

Creates a new Proc object, bound to the current context. Proc::new may be called without a block only within a method with an attached block, in which case that block is converted to the Proc object.

def proc_from
  Proc.new
end
proc = proc_from { "hello" }
proc.call   #=> "hello"

Overloads:

.new {|...| ... } ⇒ Proc
Yields:
- (...)
Returns:
- (Proc)
.new ⇒ Proc
Returns:
- (Proc)

# File 'proc.c'

static VALUE
rb_proc_s_new(int argc, VALUE *argv, VALUE klass)
{
    VALUE block = proc_new(klass, FALSE);

    rb_obj_call_init(block, argc, argv);
    return block;
}

Instance Method Details

#==(other_proc) ⇒ `Boolean`

Returns true if prc is the same object as other_proc, or if they are both procs with the same body.

Returns:

(Boolean)

# File 'proc.c'

static VALUE
proc_eq(VALUE self, VALUE other)
{
if (self == other) {
return Qtrue;
}

#===(obj) ⇒ `Object`

Invokes the block with obj as the proc's parameter like Proc#call. It is to allow a proc object to be a target of when clause in a case statement.

# File 'proc.c'

/*
 *  call-seq:
 *     prc.call(params,...)   -> obj
 *     prc[params,...]        -> obj
 *     prc.(params,...)       -> obj
 *
 *  Invokes the block, setting the block's parameters to the values in
 *  <i>params</i> using something close to method calling semantics.
 *  Generates a warning if multiple values are passed to a proc that
 *  expects just one (previously this silently converted the parameters
 *  to an array).  Note that prc.() invokes prc.call() with the parameters
 *  given.  It's a syntax sugar to hide "call".
 *
 *  For procs created using <code>lambda</code> or <code>->()</code> an error
 *  is generated if the wrong number of parameters are passed to a Proc with
 *  multiple parameters.  For procs created using <code>Proc.new</code> or
 *  <code>Kernel.proc</code>, extra parameters are silently discarded.
 *
 *  Returns the value of the last expression evaluated in the block. See
 *  also <code>Proc#yield</code>.
 *
 *     a_proc = Proc.new {|a, *b| b.collect {|i| i*a }}
 *     a_proc.call(9, 1, 2, 3)   #=> [9, 18, 27]
 *     a_proc[9, 1, 2, 3]        #=> [9, 18, 27]
 *     a_proc = lambda {|a,b| a}
 *     a_proc.call(1,2,3)
 *
 *  <em>produces:</em>
 *
 *     prog.rb:4:in `block in <main>': wrong number of arguments (3 for 2) (ArgumentError)
 *      from prog.rb:5:in `call'
 *      from prog.rb:5:in `<main>'
 *
 */

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
rb_proc_t *proc;
rb_block_t *blockptr = 0;
rb_iseq_t *iseq;
VALUE passed_procval;
GetProcPtr(procval, proc);

iseq = proc->block.iseq;
if (BUILTIN_TYPE(iseq) == T_NODE || iseq->arg_block != -1) {
if (rb_block_given_p()) {
    rb_proc_t *passed_proc;
    RB_GC_GUARD(passed_procval) = rb_block_proc();
    GetProcPtr(passed_procval, passed_proc);
    blockptr = &passed_proc->block;
}

#call(params, ...) ⇒ `Object` #[](params, ...) ⇒ `Object`

Invokes the block, setting the block's parameters to the values in params using something close to method calling semantics. Generates a warning if multiple values are passed to a proc that expects just one (previously this silently converted the parameters to an array). Note that prc.() invokes prc.call() with the parameters given. It's a syntax sugar to hide "call".

For procs created using lambda or ->() an error is generated if the wrong number of parameters are passed to a Proc with multiple parameters. For procs created using Proc.new or Kernel.proc, extra parameters are silently discarded.

Returns the value of the last expression evaluated in the block. See also Proc#yield.

a_proc = Proc.new {|a, *b| b.collect {|i| i*a }}
a_proc.call(9, 1, 2, 3)   #=> [9, 18, 27]
a_proc[9, 1, 2, 3]        #=> [9, 18, 27]
a_proc = lambda {|a,b| a}
a_proc.call(1,2,3)

produces:

prog.rb:4:in `block in <main>': wrong number of arguments (3 for 2) (ArgumentError)
 from prog.rb:5:in `call'
 from prog.rb:5:in `<main>'

Overloads:

#call(params, ...) ⇒ Object
Returns:
- (Object)
#[](params, ...) ⇒ Object
Returns:
- (Object)

# File 'proc.c'

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
rb_proc_t *proc;
rb_block_t *blockptr = 0;
rb_iseq_t *iseq;
VALUE passed_procval;
GetProcPtr(procval, proc);

iseq = proc->block.iseq;
if (BUILTIN_TYPE(iseq) == T_NODE || iseq->arg_block != -1) {
if (rb_block_given_p()) {
    rb_proc_t *passed_proc;
    RB_GC_GUARD(passed_procval) = rb_block_proc();
    GetProcPtr(passed_procval, passed_proc);
    blockptr = &passed_proc->block;
}

#arity ⇒ `Fixnum`

Returns the number of arguments that would not be ignored. 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, return -n-1, where n is the number of mandatory arguments. A proc with no argument declarations is the same a block declaring || as its arguments.

Proc.new {}.arity          #=>  0
Proc.new {||}.arity        #=>  0
Proc.new {|a|}.arity       #=>  1
Proc.new {|a,b|}.arity     #=>  2
Proc.new {|a,b,c|}.arity   #=>  3
Proc.new {|*a|}.arity      #=> -1
Proc.new {|a,*b|}.arity    #=> -2
Proc.new {|a,*b, c|}.arity    #=> -3

Returns:

(Fixnum)

# File 'proc.c'

static VALUE
proc_arity(VALUE self)
{
    int arity = rb_proc_arity(self);
    return INT2FIX(arity);
}

#binding ⇒ `Binding`

Returns the binding associated with prc. Note that Kernel#eval accepts either a Proc or a Binding object as its second parameter.

def fred(param)
  proc {}
end

b = fred(99)
eval("param", b.binding)   #=> 99

Returns:

(Binding)

# File 'proc.c'

static VALUE
proc_binding(VALUE self)
{
rb_proc_t *proc;
VALUE bindval;
rb_binding_t *bind;

GetProcPtr(self, proc);
if (TYPE(proc->block.iseq) == T_NODE) {
if (!IS_METHOD_PROC_NODE((NODE *)proc->block.iseq)) {
    rb_raise(rb_eArgError, "Can't create Binding from C level Proc");
}

#call(params, ...) ⇒ `Object` #[](params, ...) ⇒ `Object`

Returns the value of the last expression evaluated in the block. See also Proc#yield.

a_proc = Proc.new {|a, *b| b.collect {|i| i*a }}
a_proc.call(9, 1, 2, 3)   #=> [9, 18, 27]
a_proc[9, 1, 2, 3]        #=> [9, 18, 27]
a_proc = lambda {|a,b| a}
a_proc.call(1,2,3)

produces:

prog.rb:4:in `block in <main>': wrong number of arguments (3 for 2) (ArgumentError)
 from prog.rb:5:in `call'
 from prog.rb:5:in `<main>'

Overloads:

#call(params, ...) ⇒ Object
Returns:
- (Object)
#[](params, ...) ⇒ Object
Returns:
- (Object)

# File 'proc.c'

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
rb_proc_t *proc;
rb_block_t *blockptr = 0;
rb_iseq_t *iseq;
VALUE passed_procval;
GetProcPtr(procval, proc);

iseq = proc->block.iseq;
if (BUILTIN_TYPE(iseq) == T_NODE || iseq->arg_block != -1) {
if (rb_block_given_p()) {
    rb_proc_t *passed_proc;
    RB_GC_GUARD(passed_procval) = rb_block_proc();
    GetProcPtr(passed_procval, passed_proc);
    blockptr = &passed_proc->block;
}

#clone ⇒ `Object`

:nodoc:

# File 'proc.c'

static VALUE
proc_clone(VALUE self)
{
    VALUE procval = proc_dup(self);
    CLONESETUP(procval, self);
    return procval;
}

#curry ⇒ `Proc` #curry(arity) ⇒ `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 (4 for 3)
p b.curry(5)                 #=> wrong number of arguments (5 for 3)
p b.curry(1)                 #=> wrong number of arguments (1 for 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 (1 for 3)

b = proc { :foo }
p b.curry[]                  #=> :foo

Overloads:

#curry ⇒ Proc
Returns:
- (Proc)
#curry(arity) ⇒ Proc
Returns:
- (Proc)

# File 'proc.c'

static VALUE
proc_curry(int argc, VALUE *argv, VALUE self)
{
int sarity, marity = rb_proc_arity(self);
VALUE arity, opt = Qfalse;

if (marity < 0) {
marity = -marity - 1;
opt = Qtrue;
}

#dup ⇒ `Object`

:nodoc:

# File 'proc.c'

static VALUE
proc_dup(VALUE self)
{
    VALUE procval = rb_proc_alloc(rb_cProc);
    rb_proc_t *src, *dst;
    GetProcPtr(self, src);
    GetProcPtr(procval, dst);

    dst->block = src->block;
    dst->block.proc = procval;
    dst->blockprocval = src->blockprocval;
    dst->envval = src->envval;
    dst->safe_level = src->safe_level;
    dst->is_lambda = src->is_lambda;

    return procval;
}

#==(other_proc) ⇒ `Boolean`

Returns true if prc is the same object as other_proc, or if they are both procs with the same body.

Returns:

(Boolean)

# File 'proc.c'

static VALUE
proc_eq(VALUE self, VALUE other)
{
if (self == other) {
return Qtrue;
}

#hash ⇒ `Integer`

Returns a hash value corresponding to proc body.

Returns:

(Integer)

# File 'proc.c'

static VALUE
proc_hash(VALUE self)
{
    st_index_t hash;
    rb_proc_t *proc;
    GetProcPtr(self, proc);
    hash = rb_hash_start((st_index_t)proc->block.iseq);
    hash = rb_hash_uint(hash, (st_index_t)proc->envval);
    hash = rb_hash_uint(hash, (st_index_t)proc->block.lfp >> 16);
    hash = rb_hash_end(hash);
    return LONG2FIX(hash);
}

#lambda? ⇒ `Boolean`

Returns true for a Proc object for which argument handling is rigid. Such procs are typically generated by lambda.

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 insures 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.

Returns:

(Boolean)

# File 'proc.c'

VALUE
rb_proc_lambda_p(VALUE procval)
{
    rb_proc_t *proc;
    GetProcPtr(procval, proc);

    return proc->is_lambda ? Qtrue : Qfalse;
}

#parameters ⇒ `Array`

Returns the parameter information of this proc.

prc = lambda{|x, y=42, *other|}
prc.parameters  #=> [[:req, :x], [:opt, :y], [:rest, :other]]

Returns:

(Array)

# File 'proc.c'

static VALUE
rb_proc_parameters(VALUE self)
{
int is_proc;
rb_iseq_t *iseq = get_proc_iseq(self, &is_proc);
if (!iseq) {
return unnamed_parameters(rb_proc_arity(self));
}

#source_location ⇒ `Array`, `Fixnum`

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

Returns ].

Returns:

(Array, Fixnum) —

]

# File 'proc.c'

VALUE
rb_proc_location(VALUE self)
{
    return iseq_location(get_proc_iseq(self, 0));
}

#to_proc ⇒ `Proc`

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

Returns:

(Proc)

# File 'proc.c'

static VALUE
proc_to_proc(VALUE self)
{
    return self;
}

#to_s ⇒ `String`

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

Returns:

(String)

# File 'proc.c'

static VALUE
proc_to_s(VALUE self)
{
VALUE str = 0;
rb_proc_t *proc;
const char *cname = rb_obj_classname(self);
rb_iseq_t *iseq;
const char *is_lambda;

GetProcPtr(self, proc);
iseq = proc->block.iseq;
is_lambda = proc->is_lambda ? " (lambda)" : "";

if (RUBY_VM_NORMAL_ISEQ_P(iseq)) {
int line_no = 0;

if (iseq->insn_info_table) {
    line_no = rb_iseq_first_lineno(iseq);
}

#call(params, ...) ⇒ `Object` #[](params, ...) ⇒ `Object`

Returns the value of the last expression evaluated in the block. See also Proc#yield.

a_proc = Proc.new {|a, *b| b.collect {|i| i*a }}
a_proc.call(9, 1, 2, 3)   #=> [9, 18, 27]
a_proc[9, 1, 2, 3]        #=> [9, 18, 27]
a_proc = lambda {|a,b| a}
a_proc.call(1,2,3)

produces:

prog.rb:4:in `block in <main>': wrong number of arguments (3 for 2) (ArgumentError)
 from prog.rb:5:in `call'
 from prog.rb:5:in `<main>'

Overloads:

#call(params, ...) ⇒ Object
Returns:
- (Object)
#[](params, ...) ⇒ Object
Returns:
- (Object)

# File 'proc.c'

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
rb_proc_t *proc;
rb_block_t *blockptr = 0;
rb_iseq_t *iseq;
VALUE passed_procval;
GetProcPtr(procval, proc);

iseq = proc->block.iseq;
if (BUILTIN_TYPE(iseq) == T_NODE || iseq->arg_block != -1) {
if (rb_block_given_p()) {
    rb_proc_t *passed_proc;
    RB_GC_GUARD(passed_procval) = rb_block_proc();
    GetProcPtr(passed_procval, passed_proc);
    blockptr = &passed_proc->block;
}

Class: Proc

Overview

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new {|...| ... } ⇒ Proc .new ⇒ Proc

Instance Method Details

#==(other_proc) ⇒ Boolean

#===(obj) ⇒ Object

#call(params, ...) ⇒ Object #[](params, ...) ⇒ Object

#arity ⇒ Fixnum

#binding ⇒ Binding

#call(params, ...) ⇒ Object #[](params, ...) ⇒ Object

#clone ⇒ Object

#curry ⇒ Proc #curry(arity) ⇒ Proc

#dup ⇒ Object

#==(other_proc) ⇒ Boolean

#hash ⇒ Integer

#lambda? ⇒ Boolean

#parameters ⇒ Array

#source_location ⇒ Array, Fixnum

#to_proc ⇒ Proc

#to_s ⇒ String

#call(params, ...) ⇒ Object #[](params, ...) ⇒ Object

.new {|...| ... } ⇒ `Proc` .new ⇒ `Proc`

#==(other_proc) ⇒ `Boolean`

#===(obj) ⇒ `Object`

#call(params, ...) ⇒ `Object` #[](params, ...) ⇒ `Object`

#arity ⇒ `Fixnum`

#binding ⇒ `Binding`

#call(params, ...) ⇒ `Object` #[](params, ...) ⇒ `Object`

#clone ⇒ `Object`

#curry ⇒ `Proc` #curry(arity) ⇒ `Proc`

#dup ⇒ `Object`

#==(other_proc) ⇒ `Boolean`

#hash ⇒ `Integer`

#lambda? ⇒ `Boolean`

#parameters ⇒ `Array`

#source_location ⇒ `Array`, `Fixnum`

#to_proc ⇒ `Proc`

#to_s ⇒ `String`

#call(params, ...) ⇒ `Object` #[](params, ...) ⇒ `Object`