User Tools


Differences

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

Link to this comparison view

cl:macros:do-symbols [2019/07/14 17:00]
cl:macros:do-symbols [2019/10/17 13:00] (current)
Line 1: Line 1:
 +====== Macro DO-SYMBOLS, DO-EXTERNAL-SYMBOLS,​ DO-ALL-SYMBOLS ======
 +
 +====Syntax====
 +  * **do-symbols** (//var// [//​package//​ [//​result-form//​]]) //​declaration//''​*''​ {//tag// | //​statement//​}''​*''​ → //​result//''​*''​
 +  * **do-external-symbols** (//var// [//​package//​ [//​result-form//​]]) //​declaration//''​*''​ {//tag// | //​statement//​}''​*''​ → //​result//''​*''​
 +  * **do-all-symbols** {(//var// [//​result-form//​]) //​declaration//''​*''​ {//tag// | //​statement//​}''​*''​ → //​result//''​*''​
 +
 +====Arguments and Values====
 +  * //var// - a //​[[CL:​Glossary:​variable]]//​ //​[[CL:​Glossary:​name]]//;​ not evaluated.
 +  * //package// - a //​[[CL:​Glossary:​package designator]]//;​ evaluated. The default in **do-symbols** and **do-external-symbols** is the //​[[CL:​Glossary:​current package]]//​.
 +  * //​result-form//​ - a //​[[CL:​Glossary:​form]]//;​ evaluated as described below. The default is **[[CL:​Constant Variables:​nil]]**.
 +  * //​declaration//​ - a **[[CL:​Symbols:​declare]]** //​[[CL:​Glossary:​expression]]//;​ not evaluated.
 +  * //tag// - a //​[[CL:​Glossary:​go tag]]//; not evaluated.
 +  * //​statement//​ - a //​[[CL:​Glossary:​compound form]]//; evaluated as described below.
 +  * //results// - the //​[[CL:​Glossary:​values]]//​ returned by the //​result-form//​ if a //​[[CL:​Glossary:​normal return]]// occurs, or else, if an //​[[CL:​Glossary:​explicit return]]// occurs, the //​[[CL:​Glossary:​values]]//​ that were transferred.
 +
 +====Description====
 +**do-symbols**,​ **do-external-symbols**,​ and **do-all-symbols** iterate over the //​[[CL:​Glossary:​symbol|symbols]]//​ of //​[[CL:​Glossary:​package|packages]]//​. For each //​[[CL:​Glossary:​symbol]]//​ in the set of //​[[CL:​Glossary:​package|packages]]//​ chosen, the //var// is bound to the //​[[CL:​Glossary:​symbol]]//,​ and the //​statements//​ in the body are executed. When all the //​[[CL:​Glossary:​symbol|symbols]]//​ have been processed, //​result-form//​ is evaluated and returned as the value of the macro.
 +
 +**do-symbols** iterates over the //​[[CL:​Glossary:​symbol|symbols]]//​ //​[[CL:​Glossary:​accessible]]//​ in //​package//​.
 +
 +//​statements//​ may execute more than once for //​[[CL:​Glossary:​symbol|symbols]]//​ that are inherited from multiple //​[[CL:​Glossary:​package|packages]]//​.
 +
 +**do-all-symbols** iterates on every //​[[CL:​Glossary:​registered package]]//​. **do-all-symbols** will not process every //​[[CL:​Glossary:​symbol]]//​ whatsoever, because a //​[[CL:​Glossary:​symbol]]//​ not //​[[CL:​Glossary:​accessible]]//​ in any //​[[CL:​Glossary:​registered package]]// will not be processed. **do-all-symbols** may cause a //​[[CL:​Glossary:​symbol]]//​ that is //​[[CL:​Glossary:​present]]//​ in several //​[[CL:​Glossary:​package|packages]]//​ to be processed more than once.
 +
 +**do-external-symbols** iterates on the external symbols of //​package//​.
 +
 +When //​result-form//​ is evaluated, //var// is bound and has the value **[[CL:​Constant Variables:​nil]]**.
 +
 +An //​[[CL:​Glossary:​implicit block]]// named **[[CL:​Constant Variables:​nil]]** surrounds the entire **do-symbols**,​ **do-external-symbols**,​ or **do-all-symbols** //​[[CL:​Glossary:​form]]//​.
 +
 +**[[CL:​Macros:​return]]** or **[[CL:​Special Operators:​return-from]]** may be used to terminate the iteration prematurely.
 +
 +If execution of the body affects which //​[[CL:​Glossary:​symbol|symbols]]//​ are contained in the set of //​[[CL:​Glossary:​package|packages]]//​ over which iteration is occurring, other than to remove the //​[[CL:​Glossary:​symbol]]//​ currently the value of //var// by using **[[CL:​Functions:​unintern]]**,​ the consequences are undefined.
 +
 +For each of these macros, the //​[[CL:​Glossary:​scope]]//​ of the name binding does not include any initial value form, but the optional result forms are included.
 +
 +Any //tag// in the body is treated as with **[[CL:​Special Operators:​tagbody]]**.
 +
 +====Examples====
 +<​blockquote> ​
 +([[CL:​Functions:​make-package]] 'temp :use [[CL:​Constant Variables:​nil]]) → #<​PACKAGE "​TEMP"> ​
 +([[CL:​Functions:​intern]] "​SHY"​ 'temp)
 +<​r>​TEMP::​SHY ; SHY will be an internal symbol in the package TEMP 
 +[[CL:​Constant Variables:​NIL]] </r>
 +([[CL:​Functions:​export]] ([[CL:​Functions:​intern]] "​BOLD"​ 'temp) 'temp)
 +<​r>​[[CL:​Constant Variables:​T]] ; BOLD will be external </r>
 +([[CL:​Special Operators:​let]] ((list ())) 
 +  (do-symbols (s ([[CL:​Functions:​find-package]] '​temp))
 +    ([[CL:​Macros:​push]] s list))
 +  list) 
 +<​r>​(TEMP::​SHY TEMP:BOLD) </r>
 +<​r>//​or//​ (TEMP:BOLD TEMP::​SHY)</​r>​
 +([[CL:​Macros:​let]] ((list ())) 
 +  (do-external-symbols (s ([[CL:​Functions:​find-package]] 'temp) list) 
 +    ([[CL:​Macros:​push]] s list))
 +  list) → (TEMP:BOLD)
 +([[CL:​Functions:​let]] ((list ())) 
 +  (do-all-symbols (s list) 
 +    ([[CL:​Macros:​when]] ([[CL:​Functions:​eq]] ([[CL:​Functions:​find-package]] 'temp) ([[CL:​Functions:​symbol-package]] s)) 
 +      ([[CL:​Macros:​push]] s list)))
 +  list) <​r>​(TEMP::​SHY TEMP:BOLD) </r>
 +<​r>//​or//​ (TEMP:BOLD TEMP::​SHY)</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​intern|Function INTERN]]**
 +  * **[[CL:​Functions:​export|Function EXPORT]]**
 +  * {\secref\TraversalRules}
 +
 +====Notes====
 +None.
 +
 +\issue{MAPPING-DESTRUCTIVE-INTERACTION:​EXPLICITLY-VAGUE} \issue{DECLS-AND-DOC} \issue{PACKAGE-FUNCTION-CONSISTENCY:​MORE-PERMISSIVE} \issue{DO-SYMBOLS-DUPLICATES} \issue{DO-SYMBOLS-BLOCK-SCOPE:​ENTIRE-FORM}