class Binding - RDoc Documentation (original) (raw)

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)
eval("@secret", b2)
eval("@secret")

Binding objects have no class-specific methods.

Public Instance Methods

eval(string [, filename [,lineno]]) → obj click to toggle source

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")

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) → obj click to toggle source

Returns true if a local variable symbol exists.

def foo a = 1 binding.local_variable_defined?(:a) binding.local_variable_defined?(:b) end

This method is the short version of the following code:

binding.eval("defined?(#{symbol}) == 'local-variable'")

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 RBOOL(get_local_variable_ptr(&env, lid));

}

local_variable_get(symbol) → obj click to toggle source

Returns the value of the local variable symbol.

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

This method is the short version of the following code:

binding.eval("#{symbol}")

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) {
    return *ptr;
}

sym = ID2SYM(lid);

undefined: rb_name_err_raise("local variable '%1$s' is not defined for %2$s", bindval, sym); UNREACHABLE_RETURN(Qundef); }

local_variable_set(symbol, obj) → obj click to toggle source

Set local variable named symbol as obj.

def foo a = 1 bind = binding bind.local_variable_set(:a, 2) bind.local_variable_set(:b, 3)

p bind.local_variable_get(:a)
p bind.local_variable_get(:b)
p a
p b
end

This method behaves similarly to the following code:

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

if obj can be dumped in Ruby code.

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

#if YJIT_STATS rb_yjit_collect_binding_set(); #endif

RB_OBJ_WRITE(env, ptr, val);

return val;

}

local_variables → Array click to toggle source

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

def foo a = 1 2.times do |n| binding.local_variables end end

This method is the short version of the following code:

binding.eval("local_variables")

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 click to toggle source

Returns the bound receiver of the binding object.

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

source_location → [String, Integer] click to toggle source

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

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

}