User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:macros:define-modify-macro [2019/08/16 12:00]
cl:macros:define-modify-macro [2019/08/26 03:00] (current)
Line 1: Line 1:
 +====== Macro DEFINE-MODIFY-MACRO ======
 +
 +====Syntax====
 +  * define-modify-macro //name lambda-list function [documentation]//​ → //name//
 +
 +====Arguments and Values====
 +  * //name// - a //​[[CL:​Glossary:​symbol]]//​.
 +  * //​lambda-list//​ - a //​[[CL:​Glossary:​define-modify-macro lambda list]]//
 +  * //​function//​ - a //​[[CL:​Glossary:​symbol]]//​.
 +  * //​documentation//​ - a //​[[CL:​Glossary:​string]]//;​ not evaluated.
 +
 +====Description====
 +**define-modify-macro** defines a //​[[CL:​Glossary:​macro]]//​ named //name// to //​[[CL:​Glossary:​read]]//​ and //​[[CL:​Glossary:​write]]//​ a //​[[CL:​Glossary:​place]]//​.
 +
 +The arguments to the new //​[[CL:​Glossary:​macro]]//​ are a //​[[CL:​Glossary:​place]]//,​ followed by the arguments that are supplied in //​lambda-list//​.
 +
 +//​[[CL:​Glossary:​macro|macros]]//​ defined with **define-modify-macro** correctly pass the //​[[CL:​Glossary:​environment parameter]]//​ to **[[CL:​Functions:​get-setf-expansion]]**.
 +
 +When the //​[[CL:​Glossary:​macro]]//​ is invoked, //​function//​ is applied to the old contents of the //​[[CL:​Glossary:​place]]//​ and the //​lambda-list//​ arguments to obtain the new value, and the //​[[CL:​Glossary:​place]]//​ is updated to contain the result.
 +
 +Except for the issue of avoiding multiple evaluation (see below), the expansion of a **define-modify-macro** is equivalent to the following:
 +
 +<​blockquote>​
 +([[CL:​Macros:​defmacro]] //name// (reference . //​lambda-list//​) ​
 +  //​documentation// ​
 +  `([[CL:​Macros:​setf]] ,​reference ​
 +         ​(//​function//​ ,reference ,arg1 ,arg2 ...)))
 +</​blockquote>​
 +
 +where ''​arg1'',​ ''​arg2'',​ ''​...'',​ are the parameters appearing in //​lambda-list//;​ appropriate provision is made for a //​[[CL:​Glossary:​rest parameter]]//​.
 +
 +The //​[[CL:​Glossary:​subforms]]//​ of the macro calls defined by **define-modify-macro** are evaluated as specified in \secref\GenRefSubFormEval.
 +
 +//​documentation//​ is attached as a //​[[CL:​Glossary:​documentation string]]// to //name// (as kind **[[CL:​Types:​function]]**) and to the //​[[CL:​Glossary:​macro function]]//​.
 +
 +If a **define-modify-macro** //​[[CL:​Glossary:​form]]//​ appears as a //​[[CL:​Glossary:​top level form]]//, the //​[[CL:​Glossary:​compiler]]//​ must store the //​[[CL:​Glossary:​macro]]//​ definition at compile time, so that occurrences of the macro later on in the file can be expanded correctly.
 +
 +====Examples====
 +<​blockquote>​
 +(define-modify-macro appendf (&rest args) [[CL:​Functions:​append]] "​Append onto list") <​r>​APPENDF</​r>​
 +([[CL:​Macros:​defparameter]] x '(a b c) y x) <r>(A B C)</​r>​
 +(appendf x '(d e f) '(1 2 3)) <r>(A B C D E F 1 2 3) </r>
 +x <r>(A B C D E F 1 2 3) </r>
 +y <r>(A B C) </r>
 +(define-modify-macro new-incf (&​optional (delta 1)) [[CL:​Functions:​math-add|+]]) <​r>​NEW-INCF</​r>​
 +(define-modify-macro unionf (other-set &rest keywords) [[CL:​Functions:​union]]) <​r>​UNIONF</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +A macro definition is assigned to //name//.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Macros:​defsetf|Macro DEFSETF]]**
 +  * **[[CL:​Macros:​define-setf-expander|Macro DEFINE-SETF-EXPANDER]]**
 +  * **[[CL:​Functions:​documentation|Generic Function DOCUMENTATION]]**
 +  * {\secref\DocVsDecls}
 +
 +====Notes====
 +None.
 +
 +\issue{GET-SETF-METHOD-ENVIRONMENT:​ADD-ARG} \issue{SETF-METHOD-VS-SETF-METHOD:​RENAME-OLD-TERMS} \issue{PUSH-EVALUATION-ORDER:​FIRST-ITEM} \issue{DOCUMENTATION-FUNCTION-BUGS:​FIX} \issue{COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:​CLARIFY} \issue{SETF-METHOD-VS-SETF-METHOD:​RENAME-OLD-TERMS}