60 lines
45 KiB
HTML
60 lines
45 KiB
HTML
|
<!doctype html>
|
|||
|
|
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-chap-22/cc-e-dictionary/pprint-logical-block_macro" data-has-hydrated="false">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="UTF-8">
|
|||
|
|
<meta name="generator" content="Docusaurus v3.0.1">
|
|||
|
|
<title data-rh="true">pprint-logical-block | Common Lisp (New) Language Reference</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://lisp-docs.github.io/cl-language-reference/img/1024px-Lisp_logo.svg.png"><meta data-rh="true" name="twitter:image" content="https://lisp-docs.github.io/cl-language-reference/img/1024px-Lisp_logo.svg.png"><meta data-rh="true" property="og:url" content="https://lisp-docs.github.io/cl-language-reference/chap-22/cc-e-dictionary/pprint-logical-block_macro"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="google-site-verification" content="Vzaw013_bfdKeUVG89Ch3W1zC9_vH9ID2dPB9Dz0vr0"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="pprint-logical-block | Common Lisp (New) Language Reference"><meta data-rh="true" name="description" content="Expanded Reference: pprint-logical-block"><meta data-rh="true" property="og:description" content="Expanded Reference: pprint-logical-block"><link data-rh="true" rel="icon" href="../../img/favicon.ico"><link data-rh="true" rel="canonical" href="pprint-logical-block_macro.html"><link data-rh="true" rel="alternate" href="pprint-logical-block_macro.html" hreflang="en"><link data-rh="true" rel="alternate" href="pprint-logical-block_macro.html" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://C1F2Q5VM6X-dsn.algolia.net" crossorigin="anonymous"><link rel="preconnect" href="https://www.google-analytics.com">
|
|||
|
|
<link rel="preconnect" href="https://www.googletagmanager.com">
|
|||
|
|
<script async src="https://www.googletagmanager.com/gtag/js?id=G-8TJCE4NSF8"></script>
|
|||
|
|
<script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","G-8TJCE4NSF8",{})</script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml" title="Common Lisp (New) Language Reference" href="../../opensearch.xml"><link rel="stylesheet" href="../../assets/css/styles.f13b59fe.css">
|
|||
|
|
<script src="../../assets/js/runtime~main.02699c25.js" defer="defer"></script>
|
|||
|
|
<script src="../../assets/js/main.4f0a7a76.js" defer="defer"></script>
|
|||
|
|
</head>
|
|||
|
|
<body class="navigation-with-keyboard">
|
|||
|
|
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"light")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="pprint-logical-block_macro.html#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a href="../../../index.html" target="_blank" rel="noopener noreferrer" class="navbar__brand"><div class="navbar__logo"><img src="../../img/logo.svg" alt="Lisp Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="../../img/logo.svg" alt="Lisp Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Common Lisp Docs</b></a><a href="../../../docs/tutorial/index.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Tutorial</a><a href="../../index.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Technical Reference</a><a href="../../../docs/whylisp.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Why Lisp?</a><a href="../../../docs/howto.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Guides</a></div><div class="navbar__items navbar__items--right"><a href="../../../docs/contribute.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Contribute!</a><a href="../../../docs/help.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Getting Help</a><a href="../../../docs/about.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">About</a><a href="../../../blog.html" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Blog</a><a href="https://github.com/lisp-docs" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.
|
|||
|
|
<!-- -->
|
|||
|
|
<!-- -->
|
|||
|
|
<p><strong>pprint-logical-block</strong> <span><i>Macro</i></span></p>
|
|||
|
|
<p><strong>Syntax:</strong></p>
|
|||
|
|
<p><span><b>pprint-logical-block</b></span> (<em>stream-symbol object</em> &key <em>prefix per-line-prefix suffix</em>)</p>
|
|||
|
|
<p><span><i>{declaration}</i></span>* <span><i>{form}</i></span>*</p>
|
|||
|
|
<p>→ <span><b>nil</b></span></p>
|
|||
|
|
<p><strong>Arguments and Values:</strong></p>
|
|||
|
|
<p><em>stream-symbol</em>—a <span><i>stream variable designator</i></span> .</p>
|
|||
|
|
<p><span><i>object</i></span>—an <span><i>object</i></span>; evaluated.</p>
|
|||
|
|
<p>:prefix<!-- -->—a <span><i>string</i></span>; evaluated. Complicated defaulting behavior; see below.</p>
|
|||
|
|
<p>:per-line-prefix<!-- -->—a <span><i>string</i></span>; evaluated. Complicated defaulting behavior; see below. <!-- -->:suffix<!-- -->—a <span><i>string</i></span>; evaluated. The default is the <em>null string</em>.</p>
|
|||
|
|
<p><span><i>declaration</i></span>—a <span><b>declare</b></span> <span><i>expression</i></span>; not evaluated.</p>
|
|||
|
|
<p><span><i>forms</i></span>—an <span><i>implicit progn</i></span>.</p>
|
|||
|
|
<span><b>pprint-logical-block</b></span>
|
|||
|
|
<p><strong>Description:</strong></p>
|
|||
|
|
<p>Causes printing to be grouped into a logical block.</p>
|
|||
|
|
<p>The logical block is printed to the <span><i>stream</i></span> that is the <span><i>value</i></span> of the <span><i>variable</i></span> denoted by <em>stream-symbol</em>. During the execution of the <span><i>forms</i></span>, that <span><i>variable</i></span> is <span><i>bound</i></span> to a <span><i>pretty printing stream</i></span> that supports decisions about the arrangement of output and then forwards the output to the destination stream. All the standard printing functions (<em>e.g.</em>, <span><b>write</b></span>, <span><b>princ</b></span>, and <span><b>terpri</b></span>) can be used to print output to the <span><i>pretty printing stream</i></span>. All and only the output sent to this <span><i>pretty printing stream</i></span> is treated as being in the logical block.</p>
|
|||
|
|
<p>The <em>prefix</em> specifies a prefix to be printed before the beginning of the logical block. The <em>per-line-prefix</em> specifies a prefix that is printed before the block and at the beginning of each new line in the block. The <!-- -->:prefix<!-- --> and <!-- -->:pre-line-prefix<!-- --> <span><i>arguments</i></span> are mutually exclusive. If neither <!-- -->:prefix<!-- --> nor <!-- -->:per-line-prefix<!-- --> is specified, a <em>prefix</em> of the <em>null string</em> is assumed.</p>
|
|||
|
|
<p>The <em>suffix</em> specifies a suffix that is printed just after the logical block.</p>
|
|||
|
|
<p>The <span><i>object</i></span> is normally a <span><i>list</i></span> that the body <span><i>forms</i></span> are responsible for printing. If <span><i>object</i></span> is not a <span><i>list</i></span>, it is printed using <span><b>write</b></span>. (This makes it easier to write printing functions that are robust in the face of malformed arguments.) If <span><b>*print-circle*</b></span> is <span><i>non-nil</i></span> and <span><i>object</i></span> is a circular (or shared) reference to a <span><i>cons</i></span>, then an appropriate “#<em>n</em>#” marker is printed. (This makes it easy to write printing</p>
|
|||
|
|
<p>functions that provide full support for circularity and sharing abbreviation.) If <strong>*print-level*</strong> is not <span><b>nil</b></span> and the logical block is at a dynamic nesting depth of greater than <strong>*print-level*</strong> in logical blocks, “#” is printed. (This makes easy to write printing functions that provide full support for depth abbreviation.)</p>
|
|||
|
|
<p>If either of the three conditions above occurs, the indicated output is printed on <em>stream-symbol</em> and the body <span><i>forms</i></span> are skipped along with the printing of the <!-- -->:prefix<!-- --> and <!-- -->:suffix<!-- -->. (If the body <span><i>forms</i></span> are not to be responsible for printing a list, then the first two tests above can be turned off by supplying <span><b>nil</b></span> for the <span><i>object</i></span> argument.)</p>
|
|||
|
|
<p>In addition to the <span><i>object</i></span> argument of <span><b>pprint-logical-block</b></span>, the arguments of the standard printing functions (such as <span><b>write</b></span>, <span><b>print</b></span>, <span><b>prin1</b></span>, and <span><b>pprint</b></span>, as well as the arguments of the standard <span><i>format directives</i></span> such as ~A, ~S, (and ~W) are all checked (when necessary) for circularity and sharing. However, such checking is not applied to the arguments of the functions <span><b>write-line</b></span>, <span><b>write-string</b></span>, and <span><b>write-char</b></span> or to the literal text output by <span><b>format</b></span>. A consequence of this is that you must use one of the latter functions if you want to print some literal text in the output that is not supposed to be checked for circularity or sharing.</p>
|
|||
|
|
<p>The body <span><i>forms</i></span> of a <span><b>pprint-logical-block</b></span> <span><i>form</i></span> must not perform any side-effects on the surrounding environment; for example, no <span><i>variables</i></span> must be assigned which have not been <span><i>bound</i></span> within its scope.</p>
|
|||
|
|
<p>The <span><b>pprint-logical-block</b></span> <span><i>macro</i></span> may be used regardless of the <span><i>value</i></span> of <span><b>*print-pretty*</b></span>.</p>
|
|||
|
|
<p><strong>Affected By:</strong></p>
|
|||
|
|
<p><span><b>*print-circle*</b></span>, <strong>*print-level*</strong>.</p>
|
|||
|
|
<p><strong>Exceptional Situations:</strong></p>
|
|||
|
|
<p>An error of <span><i>type</i></span> <span><b>type-error</b></span> is signaled if any of the <!-- -->:suffix<!-- -->, <!-- -->:prefix<!-- -->, or <!-- -->:per-line-prefix<!-- --> is supplied but does not evaluate to a <span><i>string</i></span>.</p>
|
|||
|
|
<p>An error is signaled if <!-- -->:prefix<!-- --> and <!-- -->:pre-line-prefix<!-- --> are both used.</p>
|
|||
|
|
<p><span><b>pprint-logical-block</b></span> and the <span><i>pretty printing stream</i></span> it creates have <span><i>dynamic extent</i></span>. The consequences are undefined if, outside of this extent, output is attempted to the <span><i>pretty printing stream</i></span> it creates.</p>
|
|||
|
|
<p>It is also unspecified what happens if, within this extent, any output is sent directly to the underlying destination stream.</p>
|
|||
|
|
<p><strong>See Also:</strong></p>
|
|||
|
|
<p><span><b>pprint-pop</b></span>, <span><b>pprint-exit-if-list-exhausted</b></span>, Section 22.3.5.2 (Tilde Less-Than-Sign: Logical Block)</p>
|
|||
|
|
<p><strong>Notes:</strong></p>
|
|||
|
|
<p>One reason for using the <span><b>pprint-logical-block</b></span> <span><i>macro</i></span> when the <span><i>value</i></span> of <span><b>*print-pretty*</b></span> is <span><b>nil</b></span> would be to allow it to perform checking for <span><i>dotted lists</i></span>, as well as (in conjunction with <span><b>pprint-pop</b></span>) checking for <strong>*print-level*</strong> or <span><b>*print-length*</b></span> being exceeded.</p>
|
|||
|
|
<p>Detection of circularity and sharing is supported by the <span><i>pretty printer</i></span> by in essence performing requested output twice. On the first pass, circularities and sharing are detected and the actual outputting of characters is suppressed. On the second pass, the appropriate “#<em>n</em>=” and “#<em>n</em>#” markers are inserted and characters are output. This is why the restriction on side-effects is necessary. Obeying this restriction is facilitated by using <span><b>pprint-pop</b></span>, instead of an ordinary <span><b>pop</b></span> when traversing a list being printed by the body <span><i>forms</i></span> of the <span><b>pprint-logical-block</b></span> <span><i>form</i></span>.)</p>
|
|||
|
|
<h2 class="anchor anchorWithStickyNavbar_LWe7" id="expanded-reference-pprint-logical-block">Expanded Reference: pprint-logical-block<a href="pprint-logical-block_macro.html#expanded-reference-pprint-logical-block" class="hash-link" aria-label="Direct link to Expanded Reference: pprint-logical-block" title="Direct link to Expanded Reference: pprint-logical-block"></a></h2>
|
|||
|
|
<div class="theme-admonition theme-admonition-tip admonition_xJq3 alert alert--success"><div class="admonitionHeading_Gvgb"><span class="admonitionIcon_Rf37"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_BuS1"><p>TODO: Please contribute to this page by adding explanations and examples</p></div></div>
|
|||
|
|
<div class="language-lisp codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-lisp codeBlock_bY9V thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">(</span><span class="token car">pprint-logical-block</span><span class="token plain"> </span><span class="token punctuation" style="color:#393A34">)</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/lisp-docs/cl-language-reference/tree/main/docs/chap-22/cc-e-dictionary/pprint-logical-block_macro.md" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"><span class="theme-last-updated">Last updated<!-- --> by <b>daninus14</b></span></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="pprint-indent_function.html"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">pprint-indent</div></a><a class="pagination-nav__link pagination-nav__link--next" href="pprint-newline_function.html"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">pprint-newline</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="pprint-logical-block_macro.html#expanded-reference-pprint-logical-block" class="table-of-contents__link toc-highlight">Expanded Reference: pprint-logical-block</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a href="../../../docs/tutorial.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Common Lisp Tutorial</a></li><li class="footer__item"><a href="../../index.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Common Lisp Technical Reference</a></li><li class="footer__item"><a href="../../../docs/help.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Help</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://stackoverflow.com/questions/tagged/common-lisp" target="_blank" rel="noopener noreferrer" class="footer__link-item">Stack Overflow<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item
|
|||
|
|
</body>
|
|||
|
|
</html>
|