User Tools


Differences

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

Link to this comparison view

cl:macros:pprint-pop [2019/08/16 12:00]
cl:macros:pprint-pop [2019/12/07 04:00] (current)
Line 1: Line 1:
 +====== Local Macro PPRINT-POP ======
 +
 +====Syntax====
 +  * **pprint-pop** → //object//
 +
 +====Arguments and Values====
 +  * //object// - an //​[[CL:​Glossary:​element]]//​ of the //​[[CL:​Glossary:​list]]//​ being printed in the //​[[CL:​Glossary:​lexically current logical block]]//, or **[[CL:​Constant Variables:​nil]]**.
 +
 +====Description====
 +Pops one //​[[CL:​Glossary:​element]]//​ from the //​[[CL:​Glossary:​list]]//​ being printed in the //​[[CL:​Glossary:​lexically current logical block]]//, obeying **[[CL:​Variables:​star-print-length-star|*print-length*]]** and **[[CL:​Variables:​star-print-circle-star|*print-circle*]]** as described below.
 +
 +Each time **pprint-pop** is called, it pops the next value off the //​[[CL:​Glossary:​list]]//​ passed to the //​[[CL:​Glossary:​lexically current logical block]]// and returns it. However, before doing this, it performs three tests:
 +
 +  * If the remaining `list' is not a //​[[CL:​Glossary:​list]]//,​ ''​.''​ is printed followed by the remaining `list.'​ (This makes it easier to write printing functions that are robust in the face of malformed arguments.)
 +  * If **[[CL:​Variables:​star-print-length-star|*print-length*]]** is //​[[CL:​Glossary:​non-nil]]//,​ and **pprint-pop** has already been called **[[CL:​Variables:​star-print-length-star|*print-length*]]** times within the immediately containing logical block, ''​...''​ is printed. (This makes it easy to write printing functions that properly handle **[[CL:​Variables:​star-print-length-star|*print-length*]]**.)
 +  * If **[[CL:​Variables:​star-print-circle-star|*print-circle*]]** is //​[[CL:​Glossary:​non-nil]]//,​ and the remaining list is a circular (or shared) reference, then ''​. ''​ is printed followed by an appropriate ''#​n#''​ marker. (This catches instances of //​[[CL:​Glossary:​cdr]]//​ circularity and sharing in lists.)
 +
 +If either of the three conditions above occurs, the indicated output is printed on the //​[[CL:​Glossary:​pretty printing stream]]// created by the immediately containing **[[CL:​Macros:​pprint-logical-block]]** and the execution of the immediately containing **[[CL:​Macros:​pprint-logical-block]]** is terminated except for the printing of the suffix.
 +
 +If **[[CL:​Macros:​pprint-logical-block]]** is given a `list' argument of **[[CL:​Constant Variables:​nil]]**---because it is not processing a list - **pprint-pop** can still be used to obtain support for **[[CL:​Variables:​star-print-length-star|*print-length*]]**. In this situation, the first and third tests above are disabled and **pprint-pop** always returns **[[CL:​Constant Variables:​nil]]**. see section {\secref\PrettyPrinterExamples} - specifically,​ the **[[CL:​Functions:​pprint-vector]]** example.
 +
 +Whether or not **pprint-pop** is //​[[CL:​Glossary:​fbound]]//​ in the //​[[CL:​Glossary:​global environment]]//​ is //​[[CL:​Glossary:​implementation-dependent]]//;​ however, the restrictions on redefinition and //​[[CL:​Glossary:​shadowing]]//​ of **pprint-pop** are the same as for //​[[CL:​Glossary:​symbols]]//​ in the **''​common-lisp''​** //​[[CL:​Glossary:​package]]//​ which are //​[[CL:​Glossary:​fbound]]//​ in the //​[[CL:​Glossary:​global environment]]//​. The consequences of attempting to use **pprint-pop** outside of **[[CL:​Macros:​pprint-logical-block]]** are undefined.
 +
 +====Examples====
 +None.
 +
 +====Side Effects====
 +Might cause output to the //​[[CL:​Glossary:​pretty printing stream]]// associated with the lexically current logical block.
 +
 +====Affected By====
 +**[[CL:​Variables:​star-print-length-star|*print-length*]]**,​ **[[CL:​Variables:​star-print-circle-star|*print-circle*]]**.
 +
 +====Exceptional Situations====
 +An error is signaled (either at macro expansion time or at run time) if a usage of **pprint-pop** occurs where there is no lexically containing **[[CL:​Macros:​pprint-logical-block]]** //​[[CL:​Glossary:​form]]//​.
 +
 +The consequences are undefined if **pprint-pop** is executed outside of the //​[[CL:​Glossary:​dynamic extent]]// of this **[[CL:​Macros:​pprint-logical-block]]**.
 +
 +====See Also====
 +  * **[[CL:​Macros:​pprint-exit-if-list-exhausted|Local Macro PPRINT-EXIT-IF-LIST-EXHAUSTED]]**,​
 +  * **[[CL:​Macros:​pprint-logical-block|Macro PPRINT-LOGICAL-BLOCK]]**.
 +
 +====Notes====
 +It is frequently a good idea to call **[[CL:​Macros:​pprint-exit-if-list-exhausted]]** before calling **pprint-pop**.
 +
 +\issue{PRETTY-PRINT-INTERFACE} \issue{LEXICAL-CONSTRUCT-GLOBAL-DEFINITION:​UNDEFINED}