summaryrefslogtreecommitdiff
path: root/doc/ref/api-evaluation.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2012-01-26 16:22:35 +0100
committerAndy Wingo <wingo@pobox.com>2012-01-26 16:22:35 +0100
commit68c31a42ab137a5a54a577f19a69dfcbcfd33271 (patch)
tree6c83aaf43344ecad2fa14e25ebb9efebd1247ab6 /doc/ref/api-evaluation.texi
parent6dc8c138f902abeeabde23dc6fb29bd11e29da3b (diff)
downloadguile-68c31a42ab137a5a54a577f19a69dfcbcfd33271.tar.gz
update local-eval docs
* doc/ref/api-evaluation.texi (Local Evaluation): Update docs, add some examples.
Diffstat (limited to 'doc/ref/api-evaluation.texi')
-rw-r--r--doc/ref/api-evaluation.texi67
1 files changed, 46 insertions, 21 deletions
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index cc62270b0..f2b539e8f 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -984,6 +984,14 @@ value.
@node Local Evaluation
@subsection Local Evaluation
+Guile includes a facility to capture a lexical environment, and later
+evaluate a new expression within that environment. This code is
+implemented in a module.
+
+@example
+(use-modules (ice-9 local-eval))
+@end example
+
@deffn syntax the-environment
Captures and returns a lexical environment for use with
@code{local-eval} or @code{local-compile}.
@@ -991,27 +999,44 @@ Captures and returns a lexical environment for use with
@deffn {Scheme Procedure} local-eval exp env
@deffnx {C Function} scm_local_eval (exp, env)
-Evaluate the expression @var{exp} in the lexical environment @var{env}.
-This mostly behaves as if @var{exp} had been wrapped in a lambda
-expression @code{`(lambda () ,@var{exp})} and put in place of
-@code{(the-environment)}, with the resulting procedure called by
-@code{local-eval}. In other words, @var{exp} is evaluated within the
-lexical environment of @code{(the-environment)}, but within the dynamic
-environment of the call to @code{local-eval}.
-@end deffn
-
-@deffn {Scheme Procedure} local-compile exp env [opts=()]
-Compile the expression @var{exp} in the lexical environment @var{env}.
-If @var{exp} is a procedure, the result will be a compiled procedure;
-otherwise @code{local-compile} is mostly equivalent to
-@code{local-eval}. @var{opts} specifies the compilation options.
-@end deffn
-
-Note that the current implementation of @code{(the-environment)} does
-not capture local syntax transformers bound by @code{let-syntax},
-@code{letrec-syntax} or non-top-level @code{define-syntax} forms. Any
-attempt to reference such captured syntactic keywords via
-@code{local-eval} or @code{local-compile} produces an error.
+@deffnx {Scheme Procedure} local-compile exp env [opts=()]
+Evaluate or compile the expression @var{exp} in the lexical environment
+@var{env}.
+@end deffn
+
+Here is a simple example, illustrating that it is the variable
+that gets captured, not just its value at one point in time.
+
+@example
+(define e (let ((x 100)) (the-environment)))
+(define fetch-x (local-eval '(lambda () x) e))
+(fetch-x)
+@result{} 100
+(local-eval '(set! x 42) e)
+(fetch-x)
+@result{} 42
+@end example
+
+While @var{exp} is evaluated within the lexical environment of
+@code{(the-environment)}, it has the dynamic environment of the call to
+@code{local-eval}.
+
+@code{local-eval} and @code{local-compile} can only evaluate
+expressions, not definitions.
+
+@example
+(local-eval '(define foo 42)
+ (let ((x 100)) (the-environment)))
+@result{} syntax error: definition in expression context
+@end example
+
+Note that the current implementation of @code{(the-environment)} only
+captures ``normal'' lexical bindings, and pattern variables bound by
+@code{syntax-case}. It does not currently capture local syntax
+transformers bound by @code{let-syntax}, @code{letrec-syntax} or
+non-top-level @code{define-syntax} forms. Any attempt to reference such
+captured syntactic keywords via @code{local-eval} or
+@code{local-compile} produces an error.
@c Local Variables: