summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2009-10-15 21:29:42 +0200
committerLudovic Courtès <ludo@gnu.org>2009-10-15 21:29:42 +0200
commit1ebe6a63686b341b55848b0dc0532e7b0d665c15 (patch)
tree732acb7a69202132a0353b62463fd580c6f05e86
parent30e73c7698daa038a3fce2135781166d1edfa4e0 (diff)
downloadguile-1ebe6a63686b341b55848b0dc0532e7b0d665c15.tar.gz
Document the interaction of the "compilee" with the compiler's current module.
This is a followup to 87c595c757b7db84ffdcfda96f736ab235e674a8 ("Compile in a fresh module by default.") and f65e2b1ec5ae1962e57322ac3085ab4d44025694 ("Honor and confine expansion-time side-effects to `current-reader'."). * doc/ref/api-evaluation.texi (Loading): Explain how to change `current-reader' in a compiler-friendly way. * doc/ref/compiler.texi (The Scheme Compiler): Explain use of a fresh compilation module and separate `current-reader' fluid. * test-suite/tests/compiler.test ("current-reader")["with eval-when"]: New test.
-rw-r--r--doc/ref/api-evaluation.texi15
-rw-r--r--doc/ref/compiler.texi37
-rw-r--r--test-suite/tests/compiler.test8
3 files changed, 59 insertions, 1 deletions
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index c4849529e..8abd9f9cf 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -572,6 +572,21 @@ that they are loading). @code{current-reader} is a fluid, so it has an
independent value in each dynamic root and should be read and set using
@code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
States}).
+
+Changing @code{current-reader} is typically useful to introduce local
+syntactic changes, such that code following the @code{fluid-set!} call
+is read using the newly installed reader. The @code{current-reader}
+change should take place at evaluation time when the code is evaluated,
+or at compilation time when the code is compiled:
+
+@findex eval-when
+@example
+(eval-when (compile eval)
+ (fluid-set! current-reader my-own-reader))
+@end example
+
+The @code{eval-when} form above ensures that the @code{current-reader}
+change occurs at the right time.
@end defvar
@defvar %load-hook
diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi
index d749fc1f3..67a8ab481 100644
--- a/doc/ref/compiler.texi
+++ b/doc/ref/compiler.texi
@@ -236,12 +236,49 @@ which puts the user in the @code{(foo)} module. That is purpose of the
when compiling the subsequent expression.
For Scheme, an environment may be one of two things:
+
@itemize
@item @code{#f}, in which case compilation is performed in the context
of the current module; or
@item a module, which specifies the context of the compilation.
@end itemize
+By default, the @code{compile} and @code{compile-file} procedures
+compile in a fresh module, such that bindings and macros introduced by
+the expression being compiled are isolated:
+
+@example
+(eq? (current-module) (compile '(current-module)))
+@result{} #f
+
+(compile '(define hello 'world))
+(defined? 'hello)
+@result{} #f
+
+(define / *)
+(eq? (compile '/) /)
+@result{} #f
+@end example
+
+Similarly, changes to the @code{current-reader} fluid (@pxref{Loading,
+@code{current-reader}}) are isolated:
+
+@example
+(compile '(fluid-set! current-reader (lambda args 'fail)))
+(fluid-ref current-reader)
+@result{} #f
+@end example
+
+Nevertheless, having the compiler and @dfn{compilee} share the same name
+space can be achieved by explicitly passing @code{(current-module)} as
+the compilation environment:
+
+@example
+(define hello 'world)
+(compile 'hello #:env (current-module))
+@result{} world
+@end example
+
@node Tree-IL
@subsection Tree-IL
diff --git a/test-suite/tests/compiler.test b/test-suite/tests/compiler.test
index ed6f03325..6d433ebac 100644
--- a/test-suite/tests/compiler.test
+++ b/test-suite/tests/compiler.test
@@ -98,4 +98,10 @@
this-should-be-ignored")))
(and (eq? (vm-load (the-vm) (read-and-compile input))
'ok)
- (eq? r (fluid-ref current-reader))))))
+ (eq? r (fluid-ref current-reader)))))
+
+ (pass-if "with eval-when"
+ (let ((r (fluid-ref current-reader)))
+ (compile '(eval-when (compile eval)
+ (fluid-set! current-reader (lambda args 'chbouib))))
+ (eq? (fluid-ref current-reader) r))))