Class: Proc

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

Instance Method Summary collapse

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:

  • .new ⇒ Proc

    Returns:



603
604
605
606
607
608
609
610
 
# File 'proc.c', line 603

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

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



693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
 
# File 'proc.c', line 693

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
    VALUE vret;
    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;
	}
    }

    vret = rb_vm_invoke_proc(GET_THREAD(), proc, argc, argv, blockptr);
    RB_GC_GUARD(procval);
    return vret;
}

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



693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
 
# File 'proc.c', line 693

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
    VALUE vret;
    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;
	}
    }

    vret = rb_vm_invoke_proc(GET_THREAD(), proc, argc, argv, blockptr);
    RB_GC_GUARD(procval);
    return vret;
}

#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 {}.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 = 0| }.arity       #=> 0
lambda { |a = 0| }.arity       #=> -1
proc   { |x=0, y| }.arity      #=> 1
lambda { |x=0, y| }.arity      #=> -2
proc   { |x=0, y=0| }.arity    #=> 0
lambda { |x=0, y=0| }.arity    #=> -1
proc   { |x, y=0| }.arity      #=> 1
lambda { |x, y=0| }.arity      #=> -2
proc   { |(x, y), z=0| }.arity #=> 1
lambda { |(x, y), z=0| }.arity #=> -2

Returns:



797
798
799
800
801
802
 
# File 'proc.c', line 797

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:



2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
 
# File 'proc.c', line 2387

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

    GetProcPtr(self, proc);
    if (RB_TYPE_P((VALUE)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");
	}
    }

    bindval = rb_binding_alloc(rb_cBinding);
    GetBindingPtr(bindval, bind);
    bind->env = proc->envval;
    bind->blockprocval = proc->blockprocval;
    if (RUBY_VM_NORMAL_ISEQ_P(proc->block.iseq)) {
	bind->path = proc->block.iseq->location.path;
	bind->first_lineno = FIX2INT(rb_iseq_first_lineno(proc->block.iseq->self));
    }
    else {
	bind->path = Qnil;
	bind->first_lineno = 0;
    }
    return bindval;
}

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



693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
 
# File 'proc.c', line 693

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
    VALUE vret;
    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;
	}
    }

    vret = rb_vm_invoke_proc(GET_THREAD(), proc, argc, argv, blockptr);
    RB_GC_GUARD(procval);
    return vret;
}

#clone ⇒ Object

:nodoc:



124
125
126
127
128
129
130
 
# File 'proc.c', line 124

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:



2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
 
# File 'proc.c', line 2500

static VALUE
proc_curry(int argc, VALUE *argv, VALUE self)
{
    int sarity, max_arity, min_arity = rb_proc_min_max_arity(self, &max_arity);
    VALUE arity;

    rb_scan_args(argc, argv, "01", &arity);
    if (NIL_P(arity)) {
	arity = INT2FIX(min_arity);
    }
    else {
	sarity = FIX2INT(arity);
	if (rb_proc_lambda_p(self)) {
	    rb_check_arity(sarity, min_arity, max_arity);
	}
    }

    return make_curry_proc(self, rb_ary_new(), arity);
}

#dup ⇒ Object

:nodoc:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'proc.c', line 105

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;
}

#hash ⇒ Integer

Returns a hash value corresponding to proc body.

Returns:



990
991
992
993
994
995
996
997
998
 
# File 'proc.c', line 990

static VALUE
proc_hash(VALUE self)
{
    st_index_t hash;
    hash = rb_hash_start(0);
    hash = rb_hash_proc(hash, self);
    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)

Returns:

  • (Boolean) 


233
234
235
236
237
238
239
240
 
# File 'proc.c', line 233

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:



962
963
964
965
966
967
968
969
970
971
 
# File 'proc.c', line 962

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));
    }
    return rb_iseq_parameters(iseq, is_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)

Returns ].

Returns:



927
928
929
930
931
 
# File 'proc.c', line 927

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:



1050
1051
1052
1053
1054
 
# File 'proc.c', line 1050

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

#to_s ⇒ String Also known as: inspect

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

Returns:



1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
 
# File 'proc.c', line 1008

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 first_lineno = 0;

	if (iseq->line_info_table) {
	    first_lineno = FIX2INT(rb_iseq_first_lineno(iseq->self));
	}
	str = rb_sprintf("#<%s:%p@%"PRIsVALUE":%d%s>", cname, (void *)self,
			 iseq->location.path, first_lineno, is_lambda);
    }
    else {
	str = rb_sprintf("#<%s:%p%s>", cname, (void *)proc->block.iseq,
			 is_lambda);
    }

    if (OBJ_TAINTED(self)) {
	OBJ_TAINT(str);
    }
    return str;
}

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



693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
 
# File 'proc.c', line 693

static VALUE
proc_call(int argc, VALUE *argv, VALUE procval)
{
    VALUE vret;
    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;
	}
    }

    vret = rb_vm_invoke_proc(GET_THREAD(), proc, argc, argv, blockptr);
    RB_GC_GUARD(procval);
    return vret;
}