diff options
author | Andy Wingo <wingo@pobox.com> | 2012-01-26 16:22:35 +0100 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2012-01-26 16:22:35 +0100 |
commit | 68c31a42ab137a5a54a577f19a69dfcbcfd33271 (patch) | |
tree | 6c83aaf43344ecad2fa14e25ebb9efebd1247ab6 /doc/ref/api-evaluation.texi | |
parent | 6dc8c138f902abeeabde23dc6fb29bd11e29da3b (diff) | |
download | guile-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.texi | 67 |
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: |