Document local variable interactions with eval

Fixes [Bug #13337]

1 files changed, 22 insertions, 0 deletions

diff --git a/doc/syntax/assignment.rdoc b/doc/syntax/assignment.rdoc
index 83300cbece..08ee6096ef 100644
--- a/doc/syntax/assignment.rdoc
+++ b/doc/syntax/assignment.rdoc
@@ -109,6 +109,28 @@ The confusion comes from the out-of-order execution of the expression.  First
 the local variable is assigned-to then you attempt to call a nonexistent
 method.
 
+== Local Variables and eval
+
+Using +eval+ to evaluate Ruby code will allow access to local variables in
+the same scope, even if the local variables are not assigned until after the
+call to +eval+.  However, local variables assigned inside the call to +eval+
+will not be reflected in the surrounding scope.  Inside the call to +eval+,
+local variables in the scope and local variables assigned inside the call to 
++eval+ will be accessible.  However, you will not be able to access local
+variables assigned in previous or subsequent calls to +eval+ in the same
+scope. Consider each +eval+ call a separate nested scope. Example:
+
+  def m
+    eval "bar = 1"
+    lvs = eval "baz = 2; ary = [local_variables, foo, baz]; x = 2; ary"
+    eval "quux = 3"
+    foo = 1
+    lvs << local_variables
+  end
+
+  m
+  # => [[:baz, :ary, :x, :lvs, :foo], nil, 2, [:lvs, :foo]]
+
 == Instance Variables
 
 Instance variables are shared across all methods for the same object.