Info Catalog elisp: Simple Macro elisp: Macros elisp: Compiling Macros

elisp: Expansion

 
 13.2 Expansion of a Macro Call
 ==============================
 
 A macro call looks just like a function call in that it is a list which
 starts with the name of the macro.  The rest of the elements of the list
 are the arguments of the macro.
 
    Evaluation of the macro call begins like evaluation of a function
 call except for one crucial difference: the macro arguments are the
 actual expressions appearing in the macro call.  They are not evaluated
 before they are given to the macro definition.  By contrast, the
 arguments of a function are results of evaluating the elements of the
 function call list.
 
    Having obtained the arguments, Lisp invokes the macro definition just
 as a function is invoked.  The argument variables of the macro are bound
 to the argument values from the macro call, or to a list of them in the
 case of a ‘&rest’ argument.  And the macro body executes and returns its
 value just as a function body does.
 
    The second crucial difference between macros and functions is that
 the value returned by the macro body is an alternate Lisp expression,
 also known as the “expansion” of the macro.  The Lisp interpreter
 proceeds to evaluate the expansion as soon as it comes back from the
 macro.
 
    Since the expansion is evaluated in the normal manner, it may contain
 calls to other macros.  It may even be a call to the same macro, though
 this is unusual.
 
    Note that Emacs tries to expand macros when loading an uncompiled
 Lisp file.  This is not always possible, but if it is, it speeds up
 subsequent execution.  How Programs Do Loading.
 
    You can see the expansion of a given macro call by calling
 ‘macroexpand’.
 
  -- Function: macroexpand form &optional environment
      This function expands FORM, if it is a macro call.  If the result
      is another macro call, it is expanded in turn, until something
      which is not a macro call results.  That is the value returned by
      ‘macroexpand’.  If FORM is not a macro call to begin with, it is
      returned as given.
 
      Note that ‘macroexpand’ does not look at the subexpressions of FORM
      (although some macro definitions may do so).  Even if they are
      macro calls themselves, ‘macroexpand’ does not expand them.
 
      The function ‘macroexpand’ does not expand calls to inline
      functions.  Normally there is no need for that, since a call to an
      inline function is no harder to understand than a call to an
      ordinary function.
 
      If ENVIRONMENT is provided, it specifies an alist of macro
      definitions that shadow the currently defined macros.  Byte
      compilation uses this feature.
 
           (defmacro inc (var)
               (list 'setq var (list '1+ var)))
 
           (macroexpand '(inc r))
                ⇒ (setq r (1+ r))
 
           (defmacro inc2 (var1 var2)
               (list 'progn (list 'inc var1) (list 'inc var2)))
 
           (macroexpand '(inc2 r s))
                ⇒ (progn (inc r) (inc s))  ; ‘inc’ not expanded here.
 
  -- Function: macroexpand-all form &optional environment
      ‘macroexpand-all’ expands macros like ‘macroexpand’, but will look
      for and expand all macros in FORM, not just at the top-level.  If
      no macros are expanded, the return value is ‘eq’ to FORM.
 
      Repeating the example used for ‘macroexpand’ above with
      ‘macroexpand-all’, we see that ‘macroexpand-all’ _does_ expand the
      embedded calls to ‘inc’:
 
           (macroexpand-all '(inc2 r s))
                ⇒ (progn (setq r (1+ r)) (setq s (1+ s)))
 
  -- Function: macroexpand-1 form &optional environment
      This function expands macros like ‘macroexpand’, but it only
      performs one step of the expansion: if the result is another macro
      call, ‘macroexpand-1’ will not expand it.
 

Info Catalog elisp: Simple Macro elisp: Macros elisp: Compiling Macros