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:



681
682
683
684
685
686
687
688
 
# File 'proc.c', line 681

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

#arity ⇒ Fixnum

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. Keywords arguments will 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   { |x=0| }.arity         #=>  0
lambda { |x=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
proc   { |a, x:0, y:0| }.arity #=>  1
lambda { |a, x:0, y:0| }.arity #=> -2

Returns:



882
883
884
885
886
887
 
# File 'proc.c', line 882

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:



2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
 
# File 'proc.c', line 2638

static VALUE
proc_binding(VALUE self)
{
    VALUE bindval, envval;
    const rb_proc_t *proc;
    const rb_iseq_t *iseq;
    rb_binding_t *bind;

    GetProcPtr(self, proc);
    envval = rb_vm_proc_envval(proc);
    iseq = proc->block.iseq;
    if (SYMBOL_P(iseq)) goto error;
    if (RUBY_VM_IFUNC_P(iseq)) {
	struct vm_ifunc *ifunc = (struct vm_ifunc *)iseq;
	if (IS_METHOD_PROC_IFUNC(ifunc)) {
	    VALUE method = (VALUE)ifunc->data;
	    envval = env_clone(envval, method_receiver(method), method_cref(method));
	    iseq = rb_method_iseq(method);
	}
	else {
	  error:
	    rb_raise(rb_eArgError, "Can't create Binding from C level Proc");
	}
    }

    bindval = rb_binding_alloc(rb_cBinding);
    GetBindingPtr(bindval, bind);
    bind->env = envval;

    if (iseq) {
	rb_iseq_check(iseq);
	bind->path = iseq->body->location.path;
	bind->first_lineno = FIX2INT(rb_iseq_first_lineno(iseq));
    }
    else {
	bind->path = Qnil;
	bind->first_lineno = 0;
    }

    return bindval;
}

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

Overloads:



2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
 
# File 'proc.c', line 2764

static VALUE
proc_curry(int argc, const 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:



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

static VALUE
proc_dup(VALUE self)
{
    VALUE procval;
    rb_proc_t *src;
    rb_proc_t *dst;

    GetProcPtr(self, src);
    procval = rb_proc_alloc(rb_cProc);
    GetProcPtr(procval, dst);
    *dst = *src;
    dst->block.proc = procval;
    RB_GC_GUARD(self); /* for: body = proc_dup(body) */

    return procval;
}

#hash ⇒ Integer

Returns a hash value corresponding to proc body.

See also Object#hash.

Returns:



1118
1119
1120
1121
1122
1123
1124
1125
1126
 
# File 'proc.c', line 1118

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:



1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
 
# File 'proc.c', line 1058

static VALUE
rb_proc_parameters(VALUE self)
{
    int is_proc;
    const rb_iseq_t *iseq = rb_proc_get_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:



1023
1024
1025
1026
1027
 
# File 'proc.c', line 1023

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

#to_proc ⇒ Proc

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

Returns:



1182
1183
1184
1185
1186
 
# File 'proc.c', line 1182

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:



1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
 
# File 'proc.c', line 1136

static VALUE
proc_to_s(VALUE self)
{
    VALUE str = 0;
    rb_proc_t *proc;
    const char *cname = rb_obj_classname(self);
    const 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) && rb_iseq_check(iseq)) {
	int first_lineno = 0;

	if (iseq->body->line_info_table) {
	    first_lineno = FIX2INT(rb_iseq_first_lineno(iseq));
	}
	str = rb_sprintf("#<%s:%p@%"PRIsVALUE":%d%s>", cname, (void *)self,
			 iseq->body->location.path, first_lineno, is_lambda);
    }
    else if (SYMBOL_P(iseq)) {
	str = rb_sprintf("#<%s:%p(&%+"PRIsVALUE")%s>", cname, (void *)self,
			 (VALUE)iseq, 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;
}