[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.9-168-gfc1cb3f

[Mark H Weaver]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=fc1cb3fad4c9186974edd7f899465e07c6377c8b

The branch, stable-2.0 has been updated
       via  fc1cb3fad4c9186974edd7f899465e07c6377c8b (commit)
      from  45a28515c13348dfd18e53038ad63dd091a5a3c1 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit fc1cb3fad4c9186974edd7f899465e07c6377c8b
Author: Mark H Weaver <address@hidden>
Date:   Thu Jan 23 03:49:21 2014 -0500

    Improve docs for 'eval-when'.
    
    * doc/ref/api-macros.texi (Eval When): Explain in detail what each
      condition means, including 'expand' which was previously undocumented.
      Change the example to use (expand load eval) and recommend that set of
      conditions, instead of (compile load eval) which was previously
      recommended and shown in the example.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/api-macros.texi |   35 ++++++++++++++++++++++++++++++-----
 1 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index acfbc65..c2910a4 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -1186,17 +1186,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
address@hidden, @code{load}, and @code{compile}. If you need to use
address@hidden, 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:
+
address@hidden @code
address@hidden expand
+Evaluate during macro expansion, whether compiling or not.
+
address@hidden load
+Evaluate during the evaluation phase of compiled code, e.g. when loading
+a compiled module or running compiled code at the REPL.
+
address@hidden eval
+Evaluate during the evaluation phase of non-compiled code.
+
address@hidden compile
+Evaluate during macro expansion, but only when compiling.
address@hidden 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
address@hidden 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 Internal Macros


hooks/post-receive
-- 
GNU Guile