1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
<html><head><title>XLISP defmacro</title>
<link rel="stylesheet" type="text/css" href="reference.css">
</head>
<body>
<a href="../start.htm">Nyquist / XLISP 2.0</a> -
<a href="../manual/contents.htm">Contents</a> |
<a href="../tutorials/tutorials.htm">Tutorials</a> |
<a href="../examples/examples.htm">Examples</a> |
<a href="reference-index.htm">Reference</a>
<hr>
<h1>defmacro</h1>
<hr>
<p><table cellpadding="0" cellspacing="0" style="margin-left:10px"><tbody>
<tr valign="top">
<td><nobr>Type:</nobr></td>
<td><nobr> - </nobr></td>
<td width="100%"><nobr>special form (fsubr)</nobr></td>
</tr>
<tr valign="top">
<td><nobr>Source:</nobr></td>
<td><nobr> - </nobr></td>
<td width="100%"><nobr>xlcont.c</nobr></td>
</tr>
</tbody></table></p>
<h2>Syntax</h2>
<dl>
<dt>(defmacro <i>symbol arg-list body</i>)</dt>
<dd><i>symbol</i> - the name of the macro being defined<br>
<i>arg-list</i> - a list of the formal arguments to the macro of the form:<br>
<dl>
<dd>([<i>arg1</i> ... ]<br>
[<a href="lambda-keyword-optional.htm">&optional</a> <i>oarg1</i> ... ]<br>
[<a href="lambda-keyword-rest.htm">&rest</a> <i>rarg</i>]<br>
[<a href="lambda-keyword-key.htm">&key</a> ... ]<br>
[<a href="lambda-keyword-aux.htm">&aux</a> <i>aux1</i> ... ])<br></dd>
</dl>
<i>body</i> - a series of LISP forms (expressions) that are executed in order.<br>
returns - the macro <i>symbol</i></dd>
</dl>
<h2>Description</h2>
<p>'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.</p>
<p>All of the 'argN' formal arguments that are defined are required to
appear in the invocation of the macro expansion.</p>
<p>If there are any
<a href="lambda-keyword-optional.htm">&optional</a> arguments defined, they will
be filled in order.</p>
<p>If there is a <a href="lambda-keyword-rest.htm">&rest</a>
argument defined, and all the required formal arguments and
<a href="lambda-keyword-optional.htm">&optional</a> arguments are filled, any and
all further parameters will be passed into the function via the 'rarg'
argument. <b>Note</b> that there can be only one 'rarg' argument for
<a href="lambda-keyword-rest.htm">&rest</a>.</p>
<p>If there are insufficient parameters for any of the
<a href="lambda-keyword-optional.htm">&optional</a> or
<a href="lambda-keyword-rest.htm">&rest</a> arguments, they will contain
<a href="nil.htm">NIL</a>.</p>
<p>The <a href="lambda-keyword-aux.htm">&aux</a> 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.</p>
<h2>Examples</h2>
<pre class="example">
(defmacro plus (num1 num2) <font color="#008844">; define PLUS macro</font>
`(+ ,num1 ,num2)) <font color="#008844">; which is a 2 number add</font>
(plus 1 2) <font color="#008844">; returns 3</font>
(setq x 10) <font color="#008844">; set x to 10</font>
(setq y 20) <font color="#008844">; set y to 20</font>
(plus x y) <font color="#008844">; returns 30</font>
(defmacro betterplus (num &rest nlist) <font color="#008844">; define a BETTERPLUS macro</font>
`(+ ,num ,@nlist)) <font color="#008844">; which can take many numbers</font>
(betterplus 1) <font color="#008844">; returns 1</font>
(betterplus 1 2 3) <font color="#008844">; returns 6</font>
(betterplus 1 2 3 4 5) <font color="#008844">; returns 15</font>
(defmacro atest (x &optional y &rest z) <font color="#008844">; define ATEST macro</font>
(princ " x: ") (princ x) <font color="#008844">; \</font>
(princ " y: ") (princ y) <font color="#008844">; print out the parameters</font>
(princ " z: ") (princ z) (terpri) <font color="#008844">; / (un-evaluated)</font>
`(print (+ ,x ,y ,@z))) <font color="#008844">; add them together (eval'ed)</font>
(atest 1) <font color="#008844">; prints - x: 1 y: NIL z: NIL</font>
<font color="#008844">; error: bad argument type</font>
<font color="#008844">; because (+ 1 NIL) isn't valid</font>
(atest 1 2) <font color="#008844">; prints - x: 1 y: 2 z: NIL</font>
<font color="#008844">; returns 3</font>
(atest 1 2 3) <font color="#008844">; prints - x: 1 y: 2 z: (3)</font>
<font color="#008844">; returns 6</font>
(atest 1 2 3 4 5) <font color="#008844">; prints - x: 1 y: 2 z: (3 4 5)</font>
<font color="#008844">; returns 15</font>
(setq a 99) <font color="#008844">; set A to 99</font>
(setq b 101) <font color="#008844">; set B to 101</font>
(atest a b) <font color="#008844">; prints - x: A y: B z: NIL</font>
<font color="#008844">; returns 200</font>
(atest a b 9 10 11) <font color="#008844">; prints - x: A y: B z: (9 10 11)</font>
<font color="#008844">; returns 230</font>
</pre>
<p><b>Common Lisp:</b> Common Lisp supports an optional documentation
string as the first form in the 'body' of a 'defmacro' or
<a href="defun.htm">defun</a>. XLISP will accept this string
as a valid form, but it will not do anything special with it.</p>
<p>See the
<a href="../manual/xlisp-man-013.htm#defmacro">defmacro</a>
special form in the <nobr>XLISP 2.0</nobr> manual.</p>
<p><nobr> <a href="#top">Back to Top</nobr></a></p>
<hr>
<a href="../start.htm">Nyquist / XLISP 2.0</a> -
<a href="../manual/contents.htm">Contents</a> |
<a href="../tutorials/tutorials.htm">Tutorials</a> |
<a href="../examples/examples.htm">Examples</a> |
<a href="reference-index.htm">Reference</a>
</body></html>
|
