1
0
Fork 0
cl-sites/novaspec.org/cl/f_defmacro.html
2025-02-05 18:52:26 +01:00

655 lines
No EOL
15 KiB
HTML

<!DOCTYPE HTML>
<HTML LANG="en-us"
><HEAD
><TITLE
>defmacro | Common Lisp Nova Spec</TITLE
><META CHARSET="US-ASCII"
><LINK REL="canonical" HREF="f_defmacro.html"
><LINK REL="next" HREF="f_macro-function.html" TYPE="text/html" TITLE="macro-function"
><LINK REL="prev" HREF="f_define-compiler-macro.html" TYPE="text/html" TITLE="define-compiler-macro"
><LINK REL="up" HREF="3_8_Evaluation_and_Compilation_Dictionary.html" TYPE="text/html" TITLE="3.8 Evaluation and Compilation Dictionary"
><LINK REL="start" HREF="index.html" TYPE="text/html" TITLE="Common Lisp Nova Spec"
><META NAME="VIEWPORT" CONTENT="width=device-width, initial-scale=1.0"
><LINK REL="STYLESHEET" HREF="dpans.css%3F3909942064.css"
><SCRIPT SRC="dpans.js%3F3909942064"
></SCRIPT
><SCRIPT SRC="apropos.js%3F3909942064"
></SCRIPT
></HEAD
><BODY
><DIV
><DIV CLASS="topnav"
><DIV CLASS="breadcrumb"
><SPAN CLASS="breadcrumb-item"
><A HREF="index.html"
>Common Lisp Nova Spec</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="3_Evaluation_and_Compilation.html"
>3. Evaluation and Compilation</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="3_8_Evaluation_and_Compilation_Dictionary.html"
>3.8 Evaluation and Compilation Dictionary</A
></SPAN
> <SPAN CLASS="breadcrumb-item"
>&#8594; <A HREF="f_defmacro.html"
>defmacro</A
></SPAN
></DIV
><DIV CLASS="apropos"
><DIV CLASS="apropos-io"
><A HREF="f_define-compiler-macro.html" CLASS="prev"
>&#8592;</A
><SPAN ID="apropos-label"
>Apropos </SPAN
><INPUT ID="apropos" AUTOFOCUS="AUTOFOCUS" PLACEHOLDER="Type here to search" ONINPUT="aproposInput(this);" ONKEYUP="aproposKeyup(event);" ONCHANGE="aproposChange(this);" ONFOCUS="aproposFocus(this);" ONFOCUSOUT="aproposFocusout(this);"
><A HREF="f_macro-function.html" CLASS="next"
>&#8594;</A
></DIV
><DIV ID="apropos-res"
></DIV
></DIV
></DIV
><DIV CLASS="matter"
><DIV CLASS="com"
><DIV CLASS="begincom"
><HR
><TABLE WIDTH="100%" CELLSPACING="0" CELLPADDING="0"
><TR
><TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="100%" CLASS="name"
><SPAN CLASS="idx" DATA-KIND="idxref" DATA-TERM="defmacro"
></SPAN
><B
>defmacro</B
></TD
><TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="0" NOWRAP="NOWRAP" CLASS="ftype"
><I
>Macro</I
></TD
></TR
></TABLE
><HR
></DIV
><UL CLASS="subtoc"
></UL
><DL
><DT
><B
>Syntax</B
></DT
><DD
><DIV CLASS="DefmacWithValuesNewline"
><DIV
><B
>defmacro</B
> <SPAN CLASS="cmssi"
>name</SPAN
> <SPAN CLASS="cmssi"
>lambda-list</SPAN
> <SPAN CLASS="cmr"
>&#10214;&#8201;</SPAN
><SPAN CLASS="cmsy"
>{</SPAN
><VAR CLASS="param"
>declaration</VAR
><SPAN CLASS="cmsy"
>}</SPAN
><SPAN CLASS="cmr"
>*</SPAN
> <SPAN CLASS="cmsy"
>|</SPAN
> <VAR CLASS="param"
>documentation</VAR
>&#8201;<SPAN CLASS="cmr"
>&#8201;&#10215;</SPAN
>&#8201;<SPAN CLASS="cmsy"
>{</SPAN
><VAR CLASS="param"
>form</VAR
><SPAN CLASS="cmsy"
>}</SPAN
><SPAN CLASS="cmr"
>*</SPAN
> </DIV
><DIV
><SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> <SPAN CLASS="cmssi"
>name</SPAN
></DIV
></DIV
></DD
><DT
><B
>Arguments and Values</B
></DT
><DD
><P CLASS="j"
><VAR CLASS="param"
>name</VAR
> &#8212; a <A HREF="26_1_Glossary.html#symbol"
><EM CLASS="term"
>symbol</EM
></A
>. </P
><P CLASS="j"
><VAR CLASS="param"
>lambda-list</VAR
> &#8212; a <A HREF="26_1_Glossary.html#macro_lambda_list"
><EM CLASS="term"
>macro lambda list</EM
></A
>. </P
><P CLASS="j"
><VAR CLASS="param"
>declaration</VAR
> &#8212; a <A HREF="m_declare.html" CLASS="misc"
><B
>declare</B
></A
> <A HREF="26_1_Glossary.html#expression"
><EM CLASS="term"
>expression</EM
></A
>; not evaluated. </P
><P CLASS="j"
><VAR CLASS="param"
>documentation</VAR
> &#8212; a <A HREF="26_1_Glossary.html#string"
><EM CLASS="term"
>string</EM
></A
>; not evaluated. </P
><P CLASS="j"
><VAR CLASS="param"
>form</VAR
> &#8212; a <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>.</P
></DD
><DT
><B
>Description</B
></DT
><DD
><P CLASS="j"
>Defines <VAR CLASS="param"
>name</VAR
> as a <A HREF="26_1_Glossary.html#macro"
><EM CLASS="term"
>macro</EM
></A
> by associating a <A HREF="26_1_Glossary.html#macro_function"
><EM CLASS="term"
>macro function</EM
></A
> with that <VAR CLASS="param"
>name</VAR
> in the global environment. The <A HREF="26_1_Glossary.html#macro_function"
><EM CLASS="term"
>macro function</EM
></A
> is defined in the same <A HREF="26_1_Glossary.html#lexical_environment"
><EM CLASS="term"
>lexical environment</EM
></A
> in which the <A HREF="f_defmacro.html" CLASS="macref"
><B
>defmacro</B
></A
> <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> appears. </P
><P CLASS="j"
>The parameter variables in <VAR CLASS="param"
>lambda-list</VAR
> are bound to destructured portions of the macro call. </P
><P CLASS="j"
>The expansion function accepts two arguments, a <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> and an <A HREF="26_1_Glossary.html#environment"
><EM CLASS="term"
>environment</EM
></A
>. The expansion function returns a <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
>. The body of the expansion function is specified by <VAR CLASS="param"
>forms</VAR
>. <VAR CLASS="param"
>Forms</VAR
> are executed in order. The value of the last <VAR CLASS="param"
>form</VAR
> executed is returned as the expansion of the <A HREF="26_1_Glossary.html#macro"
><EM CLASS="term"
>macro</EM
></A
>. The body <VAR CLASS="param"
>forms</VAR
> of the expansion function (but not the <VAR CLASS="param"
>lambda-list</VAR
>) are implicitly enclosed in a <A HREF="26_1_Glossary.html#block"
><EM CLASS="term"
>block</EM
></A
> whose name is <VAR CLASS="param"
>name</VAR
>. </P
><P CLASS="j"
>The <VAR CLASS="param"
>lambda-list</VAR
> conforms to the requirements described in <A HREF="3_4_Lambda_Lists.html#sec_3_4_4" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>3.4.4</SPAN
> <SPAN CLASS="cmr"
>(Macro</SPAN
> <SPAN CLASS="cmr"
>Lambda</SPAN
> <SPAN CLASS="cmr"
>Lists)</SPAN
></A
>. </P
><P CLASS="j"
><VAR CLASS="param"
>Documentation</VAR
> is attached as a <A HREF="26_1_Glossary.html#documentation_string"
><EM CLASS="term"
>documentation string</EM
></A
> to <VAR CLASS="param"
>name</VAR
> (as kind <A HREF="f_function.html" CLASS="specref"
><B
>function</B
></A
>) and to the <A HREF="26_1_Glossary.html#macro_function"
><EM CLASS="term"
>macro function</EM
></A
>. </P
><P CLASS="j"
><A HREF="f_defmacro.html" CLASS="macref"
><B
>defmacro</B
></A
> can be used to redefine a <A HREF="26_1_Glossary.html#macro"
><EM CLASS="term"
>macro</EM
></A
> or to replace a <A HREF="26_1_Glossary.html#function"
><EM CLASS="term"
>function</EM
></A
> definition with a <A HREF="26_1_Glossary.html#macro"
><EM CLASS="term"
>macro</EM
></A
> definition. </P
><P CLASS="j"
>Recursive expansion of the <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> returned must terminate, including the expansion of other <A HREF="26_1_Glossary.html#macro"
><EM CLASS="term"
>macros</EM
></A
> which are <A HREF="26_1_Glossary.html#subform"
><EM CLASS="term"
>subforms</EM
></A
> of other <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>forms</EM
></A
> returned. </P
><P CLASS="j"
>The consequences are undefined if the result of fully macroexpanding a <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> contains any <A HREF="26_1_Glossary.html#circular"
><EM CLASS="term"
>circular</EM
></A
> <A HREF="26_1_Glossary.html#list_structure"
><EM CLASS="term"
>list structure</EM
></A
> except in <EM CLASS="term"
>literal objects</EM
>. </P
><P CLASS="j"
>If a <A HREF="f_defmacro.html" CLASS="macref"
><B
>defmacro</B
></A
> <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>form</EM
></A
> appears as a <A HREF="26_1_Glossary.html#top_level_form"
><EM CLASS="term"
>top level form</EM
></A
>, the <A HREF="26_1_Glossary.html#compiler"
><EM CLASS="term"
>compiler</EM
></A
> must store the <A HREF="26_1_Glossary.html#macro"
><EM CLASS="term"
>macro</EM
></A
> definition at compile time, so that occurrences of the macro later on in the file can be expanded correctly. Users must ensure that the body of the <A HREF="26_1_Glossary.html#macro"
><EM CLASS="term"
>macro</EM
></A
> can be evaluated at compile time if it is referenced within the <A HREF="26_1_Glossary.html#file"
><EM CLASS="term"
>file</EM
></A
> being <A HREF="26_1_Glossary.html#compile"
><EM CLASS="term"
>compiled</EM
></A
>.</P
></DD
><DT
><B
>Examples</B
></DT
><DD
><PRE CLASS="screen"
>(defmacro mac1 (a b) "Mac1 multiplies and adds"
`(+ ,a (* ,b 3))) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> MAC1
(mac1 4 5) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> 19
(documentation 'mac1 'function) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> "Mac1 multiplies and adds"
(defmacro mac2 (&amp;optional (a 2 b) (c 3 d) &amp;rest x) `'(,a ,b ,c ,d ,x)) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> MAC2
(mac2 6) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (6 T 3 NIL NIL)
(mac2 6 3 8) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (6 T 3 T (8))
(defmacro mac3 (&amp;whole r a &amp;optional (b 3) &amp;rest x &amp;key c (d a))
`'(,r ,a ,b ,c ,d ,x)) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> MAC3
(mac3 1 6 :d 8 :c 9 :d 10) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> ((MAC3 1 6 :D 8 :C 9 :D 10) 1 6 9 8 (:D 8 :C 9 :D 10))</PRE
><P CLASS="j"
>The stipulation that an embedded <A HREF="26_1_Glossary.html#destructuring_lambda_list"
><EM CLASS="term"
>destructuring lambda list</EM
></A
> is permitted only where <A HREF="26_1_Glossary.html#ordinary_lambda_list"
><EM CLASS="term"
>ordinary lambda list</EM
></A
> syntax would permit a parameter name but not a <A HREF="26_1_Glossary.html#list"
><EM CLASS="term"
>list</EM
></A
> is made to prevent ambiguity. For example, the following is not valid:</P
><PRE CLASS="screen"
>(defmacro loser (x &amp;optional (a b &amp;rest c) &amp;rest z)
...)</PRE
><P CLASS="j"
>because <A HREF="26_1_Glossary.html#ordinary_lambda_list"
><EM CLASS="term"
>ordinary lambda list</EM
></A
> syntax does permit a <A HREF="26_1_Glossary.html#list"
><EM CLASS="term"
>list</EM
></A
> following <SPAN CLASS="cmtt"
>&amp;optional</SPAN
>; the list <CODE CLASS="f"
>(a b &amp;rest c)</CODE
> would be interpreted as describing an optional parameter named <CODE CLASS="f"
>a</CODE
> whose default value is that of the form <CODE CLASS="f"
>b</CODE
>, with a supplied-p parameter named <SPAN CLASS="keyref"
><B
>&amp;rest</B
></SPAN
> (not valid), and an extraneous symbol <CODE CLASS="f"
>c</CODE
> in the list (also not valid). An almost correct way to express this is</P
><PRE CLASS="screen"
>(defmacro loser (x &amp;optional ((a b &amp;rest c)) &amp;rest z)
...)</PRE
><P CLASS="j"
>The extra set of parentheses removes the ambiguity. However, the definition is now incorrect because a macro call such as <CODE CLASS="f"
>(loser (car pool))</CODE
> would not provide any argument form for the lambda list <CODE CLASS="f"
>(a b &amp;rest c)</CODE
>, and so the default value against which to match the <A HREF="26_1_Glossary.html#lambda_list"
><EM CLASS="term"
>lambda list</EM
></A
> would be <SPAN CLASS="misc"
><B
>nil</B
></SPAN
> because no explicit default value was specified. The consequences of this are unspecified since the empty list, <SPAN CLASS="misc"
><B
>nil</B
></SPAN
>, does not have <A HREF="26_1_Glossary.html#form"
><EM CLASS="term"
>forms</EM
></A
> to satisfy the parameters <CODE CLASS="f"
>a</CODE
> and <CODE CLASS="f"
>b</CODE
>. The fully correct definition would be either</P
><PRE CLASS="screen"
>(defmacro loser (x &amp;optional ((a b &amp;rest c) '(nil nil)) &amp;rest z)
...)</PRE
><P CLASS="j"
>or</P
><PRE CLASS="screen"
>(defmacro loser (x &amp;optional ((&amp;optional a b &amp;rest c)) &amp;rest z)
...)</PRE
><P CLASS="j"
>These differ slightly: the first requires that if the macro call specifies <CODE CLASS="f"
>a</CODE
> explicitly then it must also specify <CODE CLASS="f"
>b</CODE
> explicitly, whereas the second does not have this requirement. For example,</P
><PRE CLASS="screen"
>(loser (car pool) ((+ x 1)))</PRE
><P CLASS="j"
>would be a valid call for the second definition but not for the first.</P
><PRE CLASS="screen"
>(defmacro dm1a (&amp;whole x) `',x)
(macroexpand '(dm1a)) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (QUOTE (DM1A))
(macroexpand '(dm1a a)) is an error.
(defmacro dm1b (&amp;whole x a &amp;optional b) `'(,x ,a ,b))
(macroexpand '(dm1b)) is an error.
(macroexpand '(dm1b q)) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (QUOTE ((DM1B Q) Q NIL))
(macroexpand '(dm1b q r)) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (QUOTE ((DM1B Q R) Q R))
(macroexpand '(dm1b q r s)) is an error.</PRE
><PRE CLASS="screen"
>(defmacro dm2a (&amp;whole form a b) `'(form ,form a ,a b ,b))
(macroexpand '(dm2a x y)) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (QUOTE (FORM (DM2A X Y) A X B Y))
(dm2a x y) <SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (FORM (DM2A X Y) A X B Y)
(defmacro dm2b (&amp;whole form a (&amp;whole b (c . d) &amp;optional (e 5))
&amp;body f &amp;environment env)
``(,',form ,,a ,',b ,',(macroexpand c env) ,',d ,',e ,',f))
;Note that because backquote is involved, implementations may differ
;slightly in the nature (though not the functionality) of the expansion.
(macroexpand '(dm2b x1 (((incf x2) x3 x4)) x5 x6))
<SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> (LIST* '(DM2B X1 (((INCF X2) X3 X4))
X5 X6)
X1
'((((INCF X2) X3 X4)) (SETQ X2 (+ X2 1)) (X3 X4) 5 (X5 X6))),
T
(let ((x1 5))
(macrolet ((segundo (x) `(cadr ,x)))
(dm2b x1 (((segundo x2) x3 x4)) x5 x6)))
<SPAN CLASS="cmsy"
><SPAN CLASS="arrow"
>&#8594;</SPAN
></SPAN
> ((DM2B X1 (((SEGUNDO X2) X3 X4)) X5 X6)
5 (((SEGUNDO X2) X3 X4)) (CADR X2) (X3 X4) 5 (X5 X6))</PRE
></DD
><DT
><B
>See Also</B
></DT
><DD
><P CLASS="j"
><A HREF="f_define-compiler-macro.html" CLASS="macref"
><B
>define-compiler-macro</B
></A
>, <A HREF="f_destructuring-bind.html" CLASS="macref"
><B
>destructuring-bind</B
></A
>, <A HREF="f_documentation.html" CLASS="funref"
><B
>documentation</B
></A
>, <A HREF="f_macroexpand.html" CLASS="funref"
><B
>macroexpand</B
></A
>, <A HREF="v_macroexpand-hook.html" CLASS="varref"
><B
>*macroexpand-hook*</B
></A
>, <A HREF="f_flet.html" CLASS="specref"
><B
>macrolet</B
></A
>, <A HREF="f_macro-function.html" CLASS="funref"
><B
>macro-function</B
></A
>, <A HREF="3_1_Evaluation.html#sec_3_1" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>3.1</SPAN
> <SPAN CLASS="cmr"
>(Evaluation)</SPAN
></A
>, <A HREF="3_2_Compilation.html#sec_3_2" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>3.2</SPAN
> <SPAN CLASS="cmr"
>(Compilation)</SPAN
></A
>, <A HREF="3_4_Lambda_Lists.html#sec_3_4_11" CLASS="secref"
><SPAN CLASS="cmr"
>Section</SPAN
> <SPAN CLASS="cmr"
>3.4.11</SPAN
> <SPAN CLASS="cmr"
>(Syntactic</SPAN
> <SPAN CLASS="cmr"
>Interaction</SPAN
> <SPAN CLASS="cmr"
>of</SPAN
> <SPAN CLASS="cmr"
>Documentation</SPAN
> <SPAN CLASS="cmr"
>Strings</SPAN
> <SPAN CLASS="cmr"
>and</SPAN
> <SPAN CLASS="cmr"
>Declarations)</SPAN
></A
></P
></DD
></DL
></DIV
></DIV
><DIV CLASS="footer"
><DIV CLASS="btmnav"
><A HREF="f_define-compiler-macro.html" CLASS="prev"
>&#8592;</A
><A HREF="f_macro-function.html" CLASS="next"
>&#8594;</A
></DIV
><DIV CLASS="trail"
>Conversion to HTML copyright 2023 by Gilbert Baumann</DIV
></DIV
></DIV
><SCRIPT
>domReady();</SCRIPT
></BODY
></HTML
>