From 0bd5f846df2f6268f653773e0cd4a20e2a944646 Mon Sep 17 00:00:00 2001
From: Jeremy Evans <code@jeremyevans.net>
Date: Mon, 24 Jun 2019 13:55:31 -0700
Subject: [PATCH] Document local variable interactions with eval

Fixes [Bug #13337]
---
 doc/syntax/assignment.rdoc | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

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.