Class: Binding

Inherits:
Object show all
Defined in:
proc.c

Overview

Objects of class Binding encapsulate the execution context at some particular place in the code and retain this context for future use. The variables, methods, value of self, and possibly an iterator block that can be accessed in this context are all retained. Binding objects can be created using Kernel#binding, and are made available to the callback of Kernel#set_trace_func and instances of TracePoint.

These binding objects can be passed as the second argument of the Kernel#eval method, establishing an environment for the evaluation.

class Demo
  def initialize(n)
    @secret = n
  end
  def get_binding
    binding
  end
end

k1 = Demo.new(99)
b1 = k1.get_binding
k2 = Demo.new(-3)
b2 = k2.get_binding

eval("@secret", b1)   #=> 99
eval("@secret", b2)   #=> -3
eval("@secret")       #=> nil

Binding objects have no class-specific methods.

Instance Method Summary collapse

Instance Method Details

#clone ⇒ Object

:nodoc:



360
361
362
363
364
365
366
 
# File 'proc.c', line 360

static VALUE
binding_clone(VALUE self)
{
    VALUE bindval = binding_dup(self);
    CLONESETUP(bindval, self);
    return bindval;
}

#dup ⇒ Object

:nodoc:



346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'proc.c', line 346

static VALUE
binding_dup(VALUE self)
{
    VALUE bindval = rb_binding_alloc(rb_cBinding);
    rb_binding_t *src, *dst;
    GetBindingPtr(self, src);
    GetBindingPtr(bindval, dst);
    rb_vm_block_copy(bindval, &dst->block, &src->block);
    RB_OBJ_WRITE(bindval, &dst->pathobj, src->pathobj);
    dst->first_lineno = src->first_lineno;
    return bindval;
}

#eval(string[, filename [,lineno]]) ⇒ Object

Evaluates the Ruby expression(s) in string, in the binding’s context. If the optional filename and lineno parameters are present, they will be used when reporting syntax errors.

def get_binding(param)
  binding
end
b = get_binding("hello")
b.eval("param")   #=> "hello"

Returns:



413
414
415
416
417
418
419
420
421
 
# File 'proc.c', line 413

static VALUE
bind_eval(int argc, VALUE *argv, VALUE bindval)
{
    VALUE args[4];

    rb_scan_args(argc, argv, "12", &args[0], &args[2], &args[3]);
    args[1] = bindval;
    return rb_f_eval(argc+1, args, Qnil /* self will be searched in eval */);
}

#local_variable_defined?(symbol) ⇒ Object

Returns true if a local variable symbol exists.

def foo a = 1 binding.local_variable_defined?(:a) #=> true binding.local_variable_defined?(:b) #=> false end

This method is the short version of the following code:

binding.eval(“defined?(#symbol) == ‘local-variable’”)

Returns:



622
623
624
625
626
627
628
629
630
631
632
633
634
 
# File 'proc.c', line 622

static VALUE
bind_local_variable_defined_p(VALUE bindval, VALUE sym)
{
    ID lid = check_local_id(bindval, &sym);
    const rb_binding_t *bind;
    const rb_env_t *env;

    if (!lid) return Qfalse;

    GetBindingPtr(bindval, bind);
    env = VM_ENV_ENVVAL_PTR(vm_block_ep(&bind->block));
    return get_local_variable_ptr(&env, lid) ? Qtrue : Qfalse;
}

#local_variable_get(symbol) ⇒ Object

Returns the value of the local variable symbol.

def foo a = 1 binding.local_variable_get(:a) #=> 1 binding.local_variable_get(:b) #=> NameError end

This method is the short version of the following code:

binding.eval(“#symbol”)

Returns:



534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'proc.c', line 534

static VALUE
bind_local_variable_get(VALUE bindval, VALUE sym)
{
    ID lid = check_local_id(bindval, &sym);
    const rb_binding_t *bind;
    const VALUE *ptr;
    const rb_env_t *env;

    if (!lid) goto undefined;

    GetBindingPtr(bindval, bind);

    env = VM_ENV_ENVVAL_PTR(vm_block_ep(&bind->block));
    if ((ptr = get_local_variable_ptr(&env, lid)) == NULL) {
	sym = ID2SYM(lid);
      undefined:
	rb_name_err_raise("local variable `%1$s' is not defined for %2$s",
			  bindval, sym);
    }

    return *ptr;
}

#local_variable_set(symbol, obj) ⇒ Object

Set local variable named symbol as obj.

def foo a = 1 bind = binding bind.local_variable_set(:a, 2) # set existing local variable ‘a’ bind.local_variable_set(:b, 3) # create new local variable ‘b’ # ‘b’ exists only in binding

p bind.local_variable_get(:a) #=> 2 p bind.local_variable_get(:b) #=> 3 p a #=> 2 p b #=> NameError end

This method behaves similarly to the following code:

binding.eval("#{symbol} = #{obj}")

if obj can be dumped in Ruby code.

Returns:



582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
 
# File 'proc.c', line 582

static VALUE
bind_local_variable_set(VALUE bindval, VALUE sym, VALUE val)
{
    ID lid = check_local_id(bindval, &sym);
    rb_binding_t *bind;
    const VALUE *ptr;
    const rb_env_t *env;

    if (!lid) lid = rb_intern_str(sym);

    GetBindingPtr(bindval, bind);
    env = VM_ENV_ENVVAL_PTR(vm_block_ep(&bind->block));
    if ((ptr = get_local_variable_ptr(&env, lid)) == NULL) {
	/* not found. create new env */
	ptr = rb_binding_add_dynavars(bindval, bind, 1, &lid);
	env = VM_ENV_ENVVAL_PTR(vm_block_ep(&bind->block));
    }

    RB_OBJ_WRITE(env, ptr, val);

    return val;
}

#local_variables ⇒ Array

Returns the names of the binding’s local variables as symbols.

def foo a = 1 2.times do |n| binding.local_variables #=> [:a, :n] end end

This method is the short version of the following code:

binding.eval(“local_variables”)

Returns:



506
507
508
509
510
511
512
513
514
515
 
# File 'proc.c', line 506

static VALUE
bind_local_variables(VALUE bindval)
{
    const rb_binding_t *bind;
    const rb_env_t *env;

    GetBindingPtr(bindval, bind);
    env = VM_ENV_ENVVAL_PTR(vm_block_ep(&bind->block));
    return rb_vm_env_local_variables(env);
}

#receiver ⇒ Object

Returns the bound receiver of the binding object.

Returns:



642
643
644
645
646
647
648
 
# File 'proc.c', line 642

static VALUE
bind_receiver(VALUE bindval)
{
    const rb_binding_t *bind;
    GetBindingPtr(bindval, bind);
    return vm_block_self(&bind->block);
}

#source_location ⇒ Array, Integer

Returns the Ruby source filename and line number of the binding object.

Returns ].

Returns:



656
657
658
659
660
661
662
663
664
665
666
 
# File 'proc.c', line 656

static VALUE
bind_location(VALUE bindval)
{
    VALUE loc[2];
    const rb_binding_t *bind;
    GetBindingPtr(bindval, bind);
    loc[0] = pathobj_path(bind->pathobj);
    loc[1] = INT2FIX(bind->first_lineno);

    return rb_ary_new4(2, loc);
}