256 lines
9.4 KiB
Markdown
Vendored
256 lines
9.4 KiB
Markdown
Vendored
# 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.
|
|
|
|
```
|
|
|
|
```
|