summaryrefslogtreecommitdiff
path: root/doc/ref/api-macros.texi
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2014-02-07 14:51:42 +0100
committerAndy Wingo <wingo@pobox.com>2014-02-07 14:51:42 +0100
commita1aae2c3a03afc542ab6a7c6672c5a645ac77b09 (patch)
treedc37d3ae3855ecc10dee96ab97eb807e830cf403 /doc/ref/api-macros.texi
parent0dbc5e571aa3bdb73fd0b9b1631e502167c4325a (diff)
parentf6ddf827f8f192af7a8cd255bd8374a0d38bbb74 (diff)
downloadguile-a1aae2c3a03afc542ab6a7c6672c5a645ac77b09.tar.gz
Merge commit 'f6ddf827f8f192af7a8cd255bd8374a0d38bbb74'
Conflicts: module/ice-9/boot-9.scm module/oop/goops.scm
Diffstat (limited to 'doc/ref/api-macros.texi')
-rw-r--r--doc/ref/api-macros.texi35
1 files changed, 30 insertions, 5 deletions
diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index 39c0f244b..9964e6b06 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -1194,17 +1194,42 @@ The fix is to use @code{eval-when}.
@example
;; correct: using eval-when
(use-modules (srfi srfi-19))
-(eval-when (compile load eval)
+(eval-when (expand load eval)
(define (date) (date->string (current-date))))
(define-syntax %date (identifier-syntax (date)))
(define *compilation-date* %date)
@end example
@deffn {Syntax} eval-when conditions exp...
-Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
-@code{eval}, @code{load}, and @code{compile}. If you need to use
-@code{eval-when}, use it with all three conditions, as in the above example.
-Other uses of @code{eval-when} may void your warranty or poison your cat.
+Evaluate @var{exp...} under the given @var{conditions}. Valid
+conditions include:
+
+@table @code
+@item expand
+Evaluate during macro expansion, whether compiling or not.
+
+@item load
+Evaluate during the evaluation phase of compiled code, e.g. when loading
+a compiled module or running compiled code at the REPL.
+
+@item eval
+Evaluate during the evaluation phase of non-compiled code.
+
+@item compile
+Evaluate during macro expansion, but only when compiling.
+@end table
+
+In other words, when using the primitive evaluator, @code{eval-when}
+expressions with @code{expand} are run during macro expansion, and those
+with @code{eval} are run during the evaluation phase.
+
+When using the compiler, @code{eval-when} expressions with either
+@code{expand} or @code{compile} are run during macro expansion, and
+those with @code{load} are run during the evaluation phase.
+
+When in doubt, use the three conditions @code{(expand load eval)}, as in
+the example above. Other uses of @code{eval-when} may void your
+warranty or poison your cat.
@end deffn
@node Macro Expansion