defmacro

Type:	-	special form (fsubr)
Source:	-	xlcont.c

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) that are executed in order.
returns - the macro symbol

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: 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.

See the defmacro special form in the XLISP 2.0 manual.

  Back to Top