Implement SRFI-64 - A Scheme API for test suites.

[bpt/guile.git] / doc / ref / api-macros.texi

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index 0d60400..c2910a4 100644 (file)
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011, 2012, 2013
-@c   Free Software Foundation, Inc.
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2011,
+@c   2012, 2013, 2014 Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node Macros
@@ -363,12 +363,36 @@ Cast into this form, our @code{when} example is significantly shorter:
   (if c (begin e ...)))
 @end example
 
+@subsubsection Reporting Syntax Errors in Macros
+
+@deffn {Syntax} syntax-error message [arg ...]
+Report an error at macro-expansion time.  @var{message} must be a string
+literal, and the optional @var{arg} operands can be arbitrary expressions
+providing additional information.
+@end deffn
+
+@code{syntax-error} is intended to be used within @code{syntax-rules}
+templates.  For example:
+
+@example
+(define-syntax simple-let
+  (syntax-rules ()
+    ((_ (head ... ((x . y) val) . tail)
+        body1 body2 ...)
+     (syntax-error
+      "expected an identifier but got"
+      (x . y)))
+    ((_ ((name val) ...) body1 body2 ...)
+     ((lambda (name ...) body1 body2 ...)
+      val ...))))
+@end example
+
 @subsubsection Specifying a Custom Ellipsis Identifier
 
 When writing macros that generate macro definitions, it is convenient to
 use a different ellipsis identifier at each level.  Guile allows the
 desired ellipsis identifier to be specified as the first operand to
-@code{syntax-rules}, as per R7RS.  For example:
+@code{syntax-rules}, as specified by SRFI-46 and R7RS.  For example:
 
 @example
 (define-syntax define-quotation-macros
@@ -1162,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
-@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 Internal Macros