class Binding
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.
Public Instance Methods
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"
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 */);
}
Opens an IRB session where binding.irb is called which allows for interactive debugging. You can call any methods or variables available in the current scope, and mutate state if you need to.
Given a Ruby file called potato.rb containing the following code:
class Potato def initialize @cooked = false binding.irb puts "Cooked potato: #{@cooked}" end end Potato.new
Running ruby potato.rb will open an IRB session where binding.irb is called, and you will see the following:
$ ruby potato.rb
From: potato.rb @ line 4 :
1: class Potato
2: def initialize
3: @cooked = false
=> 4: binding.irb
5: puts "Cooked potato: #{@cooked}"
6: end
7: end
8:
9: Potato.new
irb(#<Potato:0x00007feea1916670>):001:0>
You can type any valid Ruby code and it will be evaluated in the current context. This allows you to debug without having to run your code repeatedly:
irb(#<Potato:0x00007feea1916670>):001:0> @cooked => false irb(#<Potato:0x00007feea1916670>):002:0> self.class => Potato irb(#<Potato:0x00007feea1916670>):003:0> caller.first => ".../2.5.1/lib/ruby/2.5.0/irb/workspace.rb:85:in `eval'" irb(#<Potato:0x00007feea1916670>):004:0> @cooked = true => true
You can exit the IRB session with the exit command. Note that exiting will resume execution where binding.irb had paused it, as you can see from the output printed to standard output in this example:
irb(#<Potato:0x00007feea1916670>):005:0> exit Cooked potato: true
See IRB for more information.
# File lib/irb.rb, line 1578 def irb(show_code: true) # Setup IRB with the current file's path and no command line arguments IRB.setup(source_location[0], argv: []) unless IRB.initialized? # Create a new workspace using the current binding workspace = IRB::WorkSpace.new(self) # Print the code around the binding if show_code is true STDOUT.print(workspace.code_around_binding) if show_code # Get the original IRB instance debugger_irb = IRB.instance_variable_get(:@debugger_irb) irb_path = File.expand_path(source_location[0]) if debugger_irb # If we're already in a debugger session, set the workspace and irb_path for the original IRB instance debugger_irb.context.replace_workspace(workspace) debugger_irb.context.irb_path = irb_path # If we've started a debugger session and hit another binding.irb, we don't want # to start an IRB session instead, we want to resume the irb:rdbg session. IRB::Debug.setup(debugger_irb) IRB::Debug.insert_debug_break debugger_irb.debug_break else # If we're not in a debugger session, create a new IRB instance with the current # workspace binding_irb = IRB::Irb.new(workspace, from_binding: true) binding_irb.context.irb_path = irb_path binding_irb.run(IRB.conf) binding_irb.debug_break end end
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'")
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));
}
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}")
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);
}
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.
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;
}
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")
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);
}
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);
}
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);
}