class Binding - RDoc Documentation

# 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

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")   #=> "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 */);
    }

irb() click to toggle source

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 970
    def irb
      IRB.setup(source_location[0], argv: [])
      workspace = IRB::WorkSpace.new(self)
      STDOUT.print(workspace.code_around_binding)
      binding_irb = IRB::Irb.new(workspace)
      binding_irb.context.irb_path = File.expand_path(source_location[0])
      binding_irb.run(IRB.conf)
    end

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

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

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

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 #=> [: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);
    }

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