+# 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.

+

+```

+

+```