ContextQMD
Back to Mruby

mruby-binding

mrbgems/mruby-binding/README.md

4.0.09.4 KB
Original Source

mruby-binding

The mruby-binding mrbgem provides the Binding class for mruby. This class allows you to encapsulate the execution context (variables, methods, and self) at a particular point in your code, making it available for later use. It is similar in purpose to the Binding class in standard Ruby.

Obtaining a Binding Object

You can obtain a Binding object using the Kernel#binding method:

Kernel#binding -> Binding

Returns a Binding object that encapsulates the execution context (including local variables, self, and any active block) at the point of the call.

Example:

ruby
def get_binding(param)
  local_var = 42
  binding # This will capture param, local_var, and self
end

b = get_binding("hello")
# b now holds the context from inside get_binding

Note: Kernel#binding cannot be called from a C function or a Proc defined in C. Attempting to do so will raise a RuntimeError.

Binding Class Methods

A Binding object has the following methods:

local_variables -> Array of Symbol

Returns an array of symbols representing the names of the local variables defined in the binding's context.

Example:

ruby
def my_method
  a = 10
  b = 20
  binding.local_variables # => [:a, :b]
end

local_variable_get(symbol) -> Object

Retrieves the value of the local variable named by symbol. Raises a NameError if the variable is not defined in the binding's context.

Example:

ruby
def my_method
  a = 10
  b = binding
  b.local_variable_get(:a) # => 10
end

local_variable_set(symbol, value) -> Object

Sets the local variable named by symbol to value. If the variable is not already defined, it will be defined in the binding's scope. Returns the value that was set.

Example:

ruby
def my_method
  a = 10
  b = binding
  b.local_variable_set(:a, 20) # a is now 20
  b.local_variable_set(:c, 30) # c is now defined as 30 in this scope
  a # => 20
  c # => 30
end

local_variable_defined?(symbol) -> Boolean

Returns true if the local variable named by symbol is defined in the binding's context, false otherwise.

Example:

ruby
def my_method
  a = 10
  b = binding
  b.local_variable_defined?(:a) # => true
  b.local_variable_defined?(:c) # => false
end

receiver -> Object

Returns the receiver object (self) of the binding.

Example:

ruby
class MyClass
  def get_binding
    @x = "instance var"
    binding
  end
end

obj = MyClass.new
b = obj.get_binding
b.receiver # => obj (the instance of MyClass)
b.receiver.instance_variable_get(:@x) # => "instance var" (Not directly using eval)

source_location -> [String, Integer] | nil

Returns a two-element array containing the filename and line number where the binding was created. Returns nil if the source location cannot be determined (e.g., for bindings created from C).

Example:

ruby
# In a file named 'test.rb'
b = binding # Assuming this is line 2
b.source_location # => ["test.rb", 2] (approximately)

dup / clone -> Binding

Creates a shallow copy of the binding. Modifications to local variables in one binding object can affect the other if the variables themselves are mutable objects, but setting a variable in one binding will not create it in the other after duplication. The internal state concerning local variable storage is also duplicated.

(The C code refers to binding_initialize_copy, which is what dup and clone would use.)

ruby
def my_method
  x = 1
  original_binding = binding
  original_binding.local_variable_set(:y, 2)

  copied_binding = original_binding.dup

  original_binding.local_variable_set(:x, 10)
  original_binding.local_variable_set(:y, 20)
  original_binding.local_variable_set(:z, 30) # New variable in original

  puts copied_binding.local_variable_get(:x) # => 1 (Original value before duplication for variables existing at duplication time)
                                             # Correction: The tests show that changes to existing variables are reflected.
                                             # Let's re-verify test behavior for `dup`.

  # Re-checking test `Binding#dup`:
  # x = 5
  # bind1 = binding
  # bind1.local_variable_set(:y, 10)
  # bind2 = bind1.dup
  # assert_equal 5, bind2.local_variable_get(:x)
  # assert_equal 10, bind2.local_variable_get(:y)
  # x = 50 # x is changed in the original scope AFTER duplication
  # assert_equal 50, bind1.local_variable_get(:x)
  # assert_equal 50, bind2.local_variable_get(:x) # bind2 sees the change to x!
  # bind1.local_variable_set(:y, 20) # y is changed in bind1 AFTER duplication
  # assert_equal 20, bind1.local_variable_get(:y)
  # assert_equal 20, bind2.local_variable_get(:y) # bind2 sees the change to y!
  # bind1.local_variable_set(:z, 30) # z is added to bind1
  # assert_raise(NameError) { bind2.local_variable_get(:z) } # bind2 does not see new z
  # bind2.local_variable_set(:z, 40) # z is added to bind2
  # assert_equal 30, bind1.local_variable_get(:z)
  # assert_equal 40, bind2.local_variable_get(:z)

  # Corrected explanation for dup/clone:
  # Creates a copy of the binding. Both the original and copied bindings share the same
  # underlying environment for local variables that existed at the time of duplication.
  # This means:
  # - If a variable that existed when `dup` was called is modified (either in the original
  #   scope or via `local_variable_set` on either binding), the change is visible in both bindings.
  # - If a *new* local variable is added to one binding using `local_variable_set` *after*
  #   duplication, it is not visible in the other binding.
end

Note on eval: While the Binding object is often used with eval in standard Ruby to execute code within the binding's context, mruby-binding itself does not provide an eval method directly on the Binding object. You would typically use Binding with mruby's core eval method if you need to evaluate a string of code within a captured context. The mruby-binding gem provides the necessary infrastructure (like mrb_binding_extract_proc and mrb_binding_extract_env in C) that can be utilized by an eval implementation.

ruby
# Conceptual example (actual eval might vary based on mruby core)
def my_method
  a = 10
  b = binding
  # eval("puts a", b) # => would print 10
  # eval("a = 20", b) # a in my_method's scope would become 20
end

Usage Example

Here's a more complete example demonstrating some of the Binding object's capabilities:

ruby
class Greeter
  def initialize(name)
    @name = name
  end

  def get_binding_for_greeting(additional_message)
    greeting_type = "Hello"
    # Capture the binding here
    binding
  end
end

# Create an instance and get a binding
greeter_instance = Greeter.new("World")
captured_binding = greeter_instance.get_binding_for_greeting("Have a nice day!")

# Access the receiver (self)
puts "Receiver: #{captured_binding.receiver}"
# => Receiver: #<Greeter:0x...> (actual object id will vary)
puts "Receiver's name: #{captured_binding.receiver.instance_variable_get(:@name)}"
# => Receiver's name: World

# List local variables in the binding
puts "Local variables: #{captured_binding.local_variables.inspect}"
# => Local variables: [:additional_message, :greeting_type] (order may vary)

# Get local variable values
puts "Greeting type: #{captured_binding.local_variable_get(:greeting_type)}"
# => Greeting type: Hello
puts "Additional message: #{captured_binding.local_variable_get(:additional_message)}"
# => Additional message: Have a nice day!

# Set a local variable within the binding's context
captured_binding.local_variable_set(:greeting_type, "Hi")
puts "New greeting type: #{captured_binding.local_variable_get(:greeting_type)}"
# => New greeting type: Hi

# Check if a variable is defined
puts "Is 'greeting_type' defined? #{captured_binding.local_variable_defined?(:greeting_type)}"
# => Is 'greeting_type' defined? true
puts "Is 'non_existent_var' defined? #{captured_binding.local_variable_defined?(:non_existent_var)}"
# => Is 'non_existent_var' defined? false

# Source location (will vary based on where the code is run)
location = captured_binding.source_location
if location
  puts "Binding created at: #{location[0]}:#{location[1]}"
else
  puts "Source location not available for this binding."
end

This example illustrates how a Binding object captures the state of local variables and self from the scope where it was created, and how these can be inspected and manipulated.

Limitations and mruby-specific Considerations

  • Nesting Depth for Local Variables: mruby has an internal limit on how deeply nested Procs (blocks) can be while still allowing the Binding object to access and manage their local variables. This limit is defined by the BINDING_UPPER_MAX constant (defaulting to 20, with a minimum of 10 and a maximum of 100, configurable at compile time via MRB_BINDING_UPPER_MAX). If you exceed this nesting depth, attempting to create or manipulate a binding that needs to access variables across too many Proc scopes might result in a RuntimeError ("too many upper procs for local variables").

  • eval Method: As noted earlier, this gem provides the Binding object itself, not a Binding#eval method. You would use Kernel.eval(string, binding) if you need to evaluate code within the context of a binding, relying on mruby's core eval capabilities.

  • C Function Callers: Kernel#binding cannot create a Binding object if the direct caller is a C function. It must be called from Ruby code.