Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

defmacro

defmacro

type: special form (fsubr)
location: built-in
source file: xlcont.c
Common LISP compatible: yes
supported on: all machines

SYNTAX

(defmacro <symbol> <arg-list> <body> )
        <symbol>        -       The name of the macro being defined
        <arg-list>      -       A list of the formal arguments to the macro
                                of the form:    ( [ <arg1> ... ]
                                                  [ &optional <oarg1> ... ]
                                                  [ &rest <rarg> ]
                                                  [ &key ... ]
                                                  [ &aux <aux1> ... ] )
        <body>          -       A series of LISP forms (expressions) 

DESCRIPTION

DEFMACRO defines a macro expansion. When the <symbol> name of the macro expansion is encountered (similar to a function invocation), the <body> of code that was defined in the DEFMACRO is expanded and replaces the macro invocation.

All of the <argN> formal arguments that are defined are required to appear in the invocation of the macro expansion. If there are any &OPTIONAL arguments defined, they will be filled in order. If there is a &REST argument defined, and all the required formal arguments and &OPTIONAL arguments are filled, any and all further parameters will be passed into the function via the <rarg> argument. Note that there can be only one <rarg> argument for &REST. If there are insufficient parameters for any of the &OPTIONAL or &REST arguments, they will contain NIL. The &AUX variables are a mechanism for you to define variables local to the DEFMACRO execution. At the end of the function execution, these local symbols and their values are are removed.

EXAMPLES

(defmacro plus (num1 num2)              ; define PLUS macro
  `(+ ,num1 ,num2))                     ;   which is a 2 number add
(plus 1 2)                              ; returns 3
(setq x 10)                             ; set x to 10
(setq y 20)                             ; set y to 20
(plus x y)                              ; returns 30
(defmacro betterplus (num &rest nlist)  ; define a BETTERPLUS macro
  `(+ ,num ,@nlist))                   ;   which can take many numbers
(betterplus 1)                          ; returns 1
(betterplus 1 2 3)                      ; returns 6
(betterplus 1 2 3 4 5)                  ; returns 15
(defmacro atest (x &optional y &rest z) ; define ATEST macro
  (princ " x: ") (princ x)              ;   \
  (princ " y: ") (princ y)              ;    print out the parameters
  (princ " z: ") (princ z) (terpri)     ;   /      (un-evaluated)
  `(print (+ ,x ,y ,@z)) )             ;   add them together (eval'ed)
                                        ;
(atest 1)                               ; prints - x: 1 y: NIL z: NIL
                                        ;   error: bad argument type 
                                        ; because (+ 1 NIL) isn't valid
(atest 1 2)                             ; prints - x: 1 y: 2 z: NIL
                                        ;   returns 3
(atest 1 2 3)                           ; prints - x: 1 y: 2 z: (3)
                                        ;   returns 6
(atest 1 2 3 4 5)                       ; prints - x: 1 y: 2 z: (3 4 5)
                                        ;   returns 15
                                        ;
(setq a 99)                             ; set A to 99
(setq b 101)                            ; set B to 101
(atest a b)                             ; prints - x: A y: B z: NIL
                                        ;   returns 200
(atest a b 9 10 11)                     ; prints - x: A y: B z: (9 10 11)
                                        ;   returns 230

COMMON LISP COMPATIBILITY: Common LISP supports an optional documentation string as the first form in the <body> of a DEFMACRO or DEFUN. XLISP will accept this string as a valid form, but it will not do anything special with it.


Go to the first, previous, next, last section, table of contents.