(require 'stdlib)

;;Well, here is a bit of an example.  The key idea is that when you write
;;a macro, what you are doing is writing a program or function that is
;;executed at macro-expansion time.  This function returns code which
;;conceptually replaces the macro invocation in the source code.  The
;;resulting source code is then processed (compiled or executed) normally.

;;In the example below, one print statement will execute at macro
;;expansion time and the other at run time.  The trace comes from ACL
;;5.0.1 under Sparc/Solaris.  Other Lisp systems may differ a bit in
;;details.

;;    USER +> (defmacro example ()
;;	      (print "Macro-expansion time")
;;	      '(progn (print "Run time") t))
;;    EXAMPLE

(puts "a")
(defmacro example-1 ()
  (puts "macro expansion time")
  '(progn (puts "run time")))

;;    USER +> (example)

(puts "b")
(example-1)

;;    "Macro-expansion time" 
;;    "Run time" 
;;    T
;;If you just invoke the macro at top level, it is macro-expanded and then
;;executed.  The results follow directly on one another.

;;    USER +> (defun foo () (example))

(puts "c")
(defun foo ()
  (example-1))

(puts "d")
(foo)

;;    FOO
;;If you use the macro in a function definition, then the exact behavior
;;you will see depends on details of your implementation.  In Allegro CL5,
;;the function is interpreted, so nothing happend during the definition.

;;In other lisps, for example LispWorks 4, the macro is expanded when
;;processing the defintion.  In such a lisp you would see:

;;    LW +> (defun foo () (example))

;;    "Macro-expansion time" 
;;    FOO
;;which indicates that the macro was expanded while processing the
;;definition.  This is also true of lisps like MCL which automatically
;;compile definitions.  But returning the ACL:

;;    USER +> (foo)

;;    "Macro-expansion time" 
;;    "Run time" 
;;    T

;;    USER +> (foo)

;;    "Macro-expansion time" 
;;    "Run time" 
;;    T
;;Each time the interpreted function is called, the macro is expanded, and
;;then the resulting code is executed.


;;    USER +> (compile 'foo)

(require 'compiler)
(puts "e")
(compile-function foo)

;;    "Macro-expansion time" 
;;    FOO
;;    ()
;;    ()
;;Compiling the function forces the macro to be expanded by the compiler.
;;The message is seen when that expansion takes place.

;;    USER +> (foo)

(puts "f")
(foo)

;;    "Run time" 
;;    T
;;Running the compiled function only produces the run-time result, because
;;the expansion has already been done during the compilation stage.  Note
;;that in a lisp that expands macros while processing definitions (or one
;;that compiles all definitions) you would see this behavior for the calls
;;before calling the compiler as well.


;;-- Thomas A. Russ, USC/Information Sciences Institute tar@isi.edu