[Guile-commits] branch main updated: doc: Fix eval-when example

[Arne Babenhauserheide]

This is an automated email from the git hooks/post-receive script.

arnebab pushed a commit to branch main
in repository guile.

The following commit(s) were added to refs/heads/main by this push:
     new 7d5ab8fa4 doc: Fix eval-when example
7d5ab8fa4 is described below

commit 7d5ab8fa40d0f1b3dfaf4894325ca84cc36a6d31
Author: Jean Abou Samra <jean@abou-samra.fr>
AuthorDate: Sun Dec 11 12:26:18 2022 +0100

    doc: Fix eval-when example
    
    * doc/ref/api-macros.texi: make the macro expand to the literal
      date, not to a call to the date function.  The example previously
      did not actually need eval-when and did not show the intended
      effect.
---
 doc/ref/api-macros.texi | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index cdb33df31..a353719cb 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -63,7 +63,7 @@ transformers, consider the following example macro definition:
          (begin exp ...)))))
 
 (when #t
-  (display "hey ho\n") 
+  (display "hey ho\n")
   (display "let's go\n"))
 @print{} hey ho
 @print{} let's go
@@ -87,7 +87,7 @@ One can also establish local syntactic bindings with 
@code{let-syntax}.
 Bind each @var{keyword} to its corresponding @var{transformer} while
 expanding @var{exp1} @var{exp2} @enddots{}.
 
-A @code{let-syntax} binding only exists at expansion-time. 
+A @code{let-syntax} binding only exists at expansion-time.
 
 @example
 (let-syntax ((unless
@@ -1236,14 +1236,19 @@ But if a syntactic definition needs to call out to a 
normal procedure at
 expansion-time, it might well need need special declarations to indicate that
 the procedure should be made available at expansion-time.
 
-For example, the following code will work at a REPL, but not in a file:
+For example, the following code tries to embed a compilation
+timestamp in the compiled bytecode using a macro that expands
+to the date as a string literal.  It will work at a REPL, but
+not in a file, as it cannot be byte-compiled:
 
 @example
-;; incorrect
 (use-modules (srfi srfi-19))
-(define (date) (date->string (current-date)))
-(define-syntax %date (identifier-syntax (date)))
-(define *compilation-date* %date)
+(define start-date (date->string (current-date)))
+(define-syntax *compilation-date*
+ (lambda (sintax)
+    start-date))
+(display *compilation-date*)
+(newline)
 @end example
 
 It works at a REPL because the expressions are evaluated one-by-one, in order,
@@ -1253,12 +1258,14 @@ evaluated until the compiled file is loaded.
 The fix is to use @code{eval-when}.
 
 @example
-;; correct: using eval-when
 (use-modules (srfi srfi-19))
 (eval-when (expand load eval)
-  (define (date) (date->string (current-date))))
-(define-syntax %date (identifier-syntax (date)))
-(define *compilation-date* %date)
+  (define start-date (date->string (current-date))))
+(define-syntax *compilation-date*
+ (lambda (sintax)
+    start-date))
+(display *compilation-date*)
+(newline)
 @end example
 
 @deffn {Syntax} eval-when conditions exp...