76 lines
13 KiB
HTML
76 lines
13 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: Macro PPRINT-LOGICAL-BLOCK</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="f_ppr_in.htm">
|
|
<LINK REL=UP HREF="c_printe.htm">
|
|
<LINK REL=NEXT HREF="f_ppr_nl.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="f_ppr_in.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="c_printe.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="f_ppr_nl.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<A NAME="pprint-logical-block"><I>Macro</I> <B>PPRINT-LOGICAL-BLOCK</B></A> <P>
|
|
<P>
|
|
<P>
|
|
<P><B>Syntax:</B><P>
|
|
<P>
|
|
|
|
<B>pprint-logical-block</B> <I>(stream-symbol object <TT>&key</TT> prefix per-line-prefix suffix) <I>declaration</I><B>*</B> <I>form</I><B>*</B></I><P> => <I><A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A></I><P>
|
|
<P>
|
|
<P><B>Arguments and Values:</B><P>
|
|
<P>
|
|
<I>stream-symbol</I>---a <A REL=DEFINITION HREF="26_glo_s.htm#stream_variable_designator"><I>stream variable designator</I></A>. <P>
|
|
<I>object</I>---an <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A>; evaluated. <P>
|
|
<TT>:prefix</TT>---a <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A>; evaluated. Complicated defaulting behavior; see below. <P>
|
|
<TT>:per-line-prefix</TT>---a <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A>; evaluated. Complicated defaulting behavior; see below. <P>
|
|
<TT>:suffix</TT>---a <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A>; evaluated. The default is the <A REL=DEFINITION HREF="26_glo_n.htm#null"><I>null</I></A> <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A>. <P>
|
|
<I>declaration</I>---a <A REL=DEFINITION HREF="s_declar.htm#declare"><B>declare</B></A> <A REL=DEFINITION HREF="26_glo_e.htm#expression"><I>expression</I></A>; not evaluated. <P>
|
|
<I>forms</I>---an <A REL=DEFINITION HREF="26_glo_i.htm#implicit_progn"><I>implicit progn</I></A>. <P>
|
|
<P><B>Description:</B><P>
|
|
<P>
|
|
Causes printing to be grouped into a logical block. <P>
|
|
The logical block is printed to the <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A> that is the <A REL=DEFINITION HREF="26_glo_v.htm#value"><I>value</I></A> of the <A REL=DEFINITION HREF="26_glo_v.htm#variable"><I>variable</I></A> denoted by <I>stream-symbol</I>. During the execution of the <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>forms</I></A>, that <A REL=DEFINITION HREF="26_glo_v.htm#variable"><I>variable</I></A> is <A REL=DEFINITION HREF="26_glo_b.htm#bound"><I>bound</I></A> to a <A REL=DEFINITION HREF="26_glo_p.htm#pretty_printing_stream"><I>pretty printing stream</I></A> that supports decisions about the arrangement of output and then forwards the output to the destination stream. All the standard printing functions (e.g., <A REL=DEFINITION HREF="f_wr_pr.htm#write"><B>write</B></A>, <A REL=DEFINITION HREF="f_wr_pr.htm#princ"><B>princ</B></A>, and <A REL=DEFINITION HREF="f_terpri.htm#terpri"><B>terpri</B></A>) can be used to print output to the <A REL=DEFINITION HREF="26_glo_p.htm#pretty_printing_stream"><I>pretty printing stream</I></A>. All and only the output sent to this <A REL=DEFINITION HREF="26_glo_p.htm#pretty_printing_stream"><I>pretty printing stream</I></A> is treated as being in the logical block. <P>
|
|
The <I>prefix</I> specifies a prefix to be printed before the beginning of the logical block. The <I>per-line-prefix</I> specifies a prefix that is printed before the block and at the beginning of each new line in the block. The <TT>:prefix</TT> and <TT>:pre-line-prefix</TT> <A REL=DEFINITION HREF="26_glo_a.htm#argument"><I>arguments</I></A> are mutually exclusive. If neither <TT>:prefix</TT> nor <TT>:per-line-prefix</TT> is specified, a <I>prefix</I> of the <A REL=DEFINITION HREF="26_glo_n.htm#null"><I>null</I></A> <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A> is assumed. <P>
|
|
The <I>suffix</I> specifies a suffix that is printed just after the logical block. <P>
|
|
The <I>object</I> is normally a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A> that the body <I>forms</I> are responsible for printing. If <I>object</I> is not a <A REL=DEFINITION HREF="26_glo_l.htm#list"><I>list</I></A>, it is printed using <A REL=DEFINITION HREF="f_wr_pr.htm#write"><B>write</B></A>. (This makes it easier to write printing functions that are robust in the face of malformed arguments.) If <A REL=DEFINITION HREF="v_pr_cir.htm#STprint-circleST"><B>*print-circle*</B></A> is <A REL=DEFINITION HREF="26_glo_n.htm#non-nil"><I>non-nil</I></A> and <I>object</I> is a circular (or shared) reference to a <A REL=DEFINITION HREF="26_glo_c.htm#cons"><I>cons</I></A>, then an appropriate ``<TT>#</TT><I>n</I><TT>#</TT>'' marker is printed. (This makes it easy to write printing functions that provide full support for circularity and sharing abbreviation.) If <A REL=DEFINITION HREF="v_pr_lev.htm#STprint-levelST"><B>*print-level*</B></A> is not <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A> and the logical block is at a dynamic nesting depth of greater than <A REL=DEFINITION HREF="v_pr_lev.htm#STprint-levelST"><B>*print-level*</B></A> in logical blocks, ``<TT>#</TT>'' is printed. (This makes easy to write printing functions that provide full support for depth abbreviation.) <P>
|
|
If either of the three conditions above occurs, the indicated output is printed on <I>stream-symbol</I> and the body <I>forms</I> are skipped along with the printing of the <TT>:prefix</TT> and <TT>:suffix</TT>. (If the body <I>forms</I> are not to be responsible for printing a list, then the first two tests above can be turned off by supplying <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A> for the <I>object</I> argument.) <P>
|
|
In addition to the <I>object</I> argument of <A REL=DEFINITION HREF="#pprint-logical-block"><B>pprint-logical-block</B></A>, the arguments of the standard printing functions (such as <A REL=DEFINITION HREF="f_wr_pr.htm#write"><B>write</B></A>, <A REL=DEFINITION HREF="f_wr_pr.htm#print"><B>print</B></A>, <A REL=DEFINITION HREF="f_wr_pr.htm#prin1"><B>prin1</B></A>, and <A REL=DEFINITION HREF="f_wr_pr.htm#pprint"><B>pprint</B></A>, as well as the arguments of the standard <A REL=DEFINITION HREF="26_glo_f.htm#format_directive"><I>format directives</I></A> such as <TT>~A</TT>, <TT>~S</TT>, (and <TT>~W</TT>) are all checked (when necessary) for circularity and sharing. However, such checking is not applied to the arguments of the functions <A REL=DEFINITION HREF="f_wr_stg.htm#write-line"><B>write-line</B></A>, <A REL=DEFINITION HREF="f_wr_stg.htm#write-string"><B>write-string</B></A>, and <A REL=DEFINITION HREF="f_wr_cha.htm#write-char"><B>write-char</B></A> or to the literal text output by <A REL=DEFINITION HREF="f_format.htm#format"><B>format</B></A>. 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>
|
|
The body <I>forms</I> of a <A REL=DEFINITION HREF="#pprint-logical-block"><B>pprint-logical-block</B></A> <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A> must not perform any side-effects on the surrounding environment; for example, no <A REL=DEFINITION HREF="26_glo_v.htm#variable"><I>variables</I></A> must be assigned which have not been <A REL=DEFINITION HREF="26_glo_b.htm#bound"><I>bound</I></A> within its scope. <P>
|
|
The <A REL=DEFINITION HREF="#pprint-logical-block"><B>pprint-logical-block</B></A> <A REL=DEFINITION HREF="26_glo_m.htm#macro"><I>macro</I></A> may be used regardless of the <A REL=DEFINITION HREF="26_glo_v.htm#value"><I>value</I></A> of <A REL=DEFINITION HREF="v_pr_pre.htm#STprint-prettyST"><B>*print-pretty*</B></A>. <P>
|
|
<P><B>Examples:</B> None.
|
|
<P>
|
|
<P><B>Side Effects:</B> None.
|
|
<P>
|
|
<P><B>Affected By:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="v_pr_cir.htm#STprint-circleST"><B>*print-circle*</B></A>, <A REL=DEFINITION HREF="v_pr_lev.htm#STprint-levelST"><B>*print-level*</B></A>. <P>
|
|
<P><B>Exceptional Situations:</B><P>
|
|
<P>
|
|
An error of <A REL=DEFINITION HREF="26_glo_t.htm#type"><I>type</I></A> <A REL=DEFINITION HREF="e_tp_err.htm#type-error"><B>type-error</B></A> is signaled if any of the <TT>:suffix</TT>, <TT>:prefix</TT>, or <TT>:per-line-prefix</TT> is supplied but does not evaluate to a <A REL=DEFINITION HREF="26_glo_s.htm#string"><I>string</I></A>. <P>
|
|
An error is signaled if <TT>:prefix</TT> and <TT>:pre-line-prefix</TT> are both used. <P>
|
|
<A REL=DEFINITION HREF="#pprint-logical-block"><B>pprint-logical-block</B></A> and the <A REL=DEFINITION HREF="26_glo_p.htm#pretty_printing_stream"><I>pretty printing stream</I></A> it creates have <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_extent"><I>dynamic extent</I></A>. The consequences are undefined if, outside of this extent, output is attempted to the <A REL=DEFINITION HREF="26_glo_p.htm#pretty_printing_stream"><I>pretty printing stream</I></A> it creates. <P>
|
|
It is also unspecified what happens if, within this extent, any output is sent directly to the underlying destination stream. <P>
|
|
<P><B>See Also:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="m_ppr_po.htm#pprint-pop"><B>pprint-pop</B></A>, <A REL=DEFINITION HREF="m_ppr_ex.htm#pprint-exit-if-list-exhausted"><B>pprint-exit-if-list-exhausted</B></A>, <A REL=CHILD HREF="22_ceb.htm">Section 22.3.5.2 (Tilde Less-Than-Sign: Logical Block)</A> <P>
|
|
<P><B>Notes:</B><P>
|
|
<P>
|
|
One reason for using the <A REL=DEFINITION HREF="#pprint-logical-block"><B>pprint-logical-block</B></A> <A REL=DEFINITION HREF="26_glo_m.htm#macro"><I>macro</I></A> when the <A REL=DEFINITION HREF="26_glo_v.htm#value"><I>value</I></A> of <A REL=DEFINITION HREF="v_pr_pre.htm#STprint-prettyST"><B>*print-pretty*</B></A> is <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A> would be to allow it to perform checking for <A REL=DEFINITION HREF="26_glo_d.htm#dotted_list"><I>dotted lists</I></A>, as well as (in conjunction with <A REL=DEFINITION HREF="m_ppr_po.htm#pprint-pop"><B>pprint-pop</B></A>) checking for <A REL=DEFINITION HREF="v_pr_lev.htm#STprint-levelST"><B>*print-level*</B></A> or <A REL=DEFINITION HREF="v_pr_lev.htm#STprint-lengthST"><B>*print-length*</B></A> being exceeded. <P>
|
|
Detection of circularity and sharing is supported by the <A REL=DEFINITION HREF="26_glo_p.htm#pretty_printer"><I>pretty printer</I></A> 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 ``<TT>#</TT><I>n</I><TT>=</TT>'' and ``<TT>#</TT><I>n</I><TT>#</TT>'' markers are inserted and characters are output. This is why the restriction on side-effects is necessary. Obeying this restriction is facilitated by using <A REL=DEFINITION HREF="m_ppr_po.htm#pprint-pop"><B>pprint-pop</B></A>, instead of an ordinary <A REL=DEFINITION HREF="m_pop.htm#pop"><B>pop</B></A> when traversing a list being printed by the body <I>forms</I> of the <A REL=DEFINITION HREF="#pprint-logical-block"><B>pprint-logical-block</B></A> <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A>.) <P>
|
|
<P>
|
|
<P>
|
|
<P><HR>The following <A REL=META HREF="../Front/X3J13Iss.htm">X3J13 cleanup issues</A>, <I>not part of the specification</I>, apply to this section:<P><UL><LI> <A REL=CHILD HREF="../Issues/iss180.htm">GENERALIZE-PRETTY-PRINTER:UNIFY</A><LI> <A REL=CHILD HREF="../Issues/iss270.htm">PRETTY-PRINT-INTERFACE</A><LI> <A REL=CHILD HREF="../Issues/iss097.htm">DECLS-AND-DOC</A><P></UL><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|