User Tools


Differences

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

Link to this comparison view

cl:functions:write [2019/09/14 05:00]
cl:functions:write [2019/09/20 08:00] (current)
Line 1: Line 1:
 +====== Function WRITE, PRIN1, PRINT, PPRINT, PRINC ======
 +
 +====Syntax====
 +  *  write //object// ''&​key''​ //array// //base// //case// //circle// //escape// //gensym// //length// //level// //lines// //​miser-width//​ //​pprint-dispatch//​ //pretty// //radix// //​readably//​ //​right-margin//​ //stream// → //object//
 +  * **prin1** //object// ''&​optional''​ //​output-stream//​ → //​object// ​
 +  * **princ** //object// ''&​optional''​ //​output-stream//​ → //​object// ​
 +  * **print** //object// ''&​optional''​ //​output-stream//​ → //​object// ​
 +  * **pprint** //object// ''&​optional''​ //​output-stream//​ → //<no values>//​
 +
 +====Arguments and Values====
 +  * //object// - an //​[[CL:​Glossary:​object]]//​.
 +  * //​output-stream//​ - an //​[[CL:​Glossary:​output]]//​ //​[[CL:​Glossary:​stream designator]]//​. The default is //​[[CL:​Glossary:​standard output]]//.
 +  * //array// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //base// - a //​[[CL:​Glossary:​radix]]//​.
 +  * //case// - a //​[[CL:​Glossary:​symbol]]//​ of //​[[CL:​Glossary:​type]]//​ ''​(member :upcase :downcase :​capitalize)''​.
 +  * //circle// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //escape// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //gensym// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //length// - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //level// - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //lines// - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //​miser-width//​ - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //​pprint-dispatch//​ - a //​[[CL:​Glossary:​pprint dispatch table]]//.
 +  * //pretty// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //radix// - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //​readably//​ - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //​right-margin//​ - a non-negative //​[[CL:​Glossary:​integer]]//,​ or **[[CL:​Constant Variables:​nil]]**.
 +  * //stream// - an //​[[CL:​Glossary:​output]]//​ //​[[CL:​Glossary:​stream designator]]//​. The default is //​[[CL:​Glossary:​standard output]]//.
 +
 +====Description====
 +**write**, **prin1**, **princ**, **print**, and **pprint** write the printed representation of //object// to //​output-stream//​.
 +
 +**write** is the general entry point to the //​[[CL:​Glossary:​Lisp printer]]//​. For each explicitly supplied //​[[CL:​Glossary:​keyword parameter]]//​ named in the below table, the corresponding //​[[CL:​Glossary:​printer control variable]]//​ is dynamically bound to its //​[[CL:​Glossary:​value]]//​ while printing goes on; for each //​[[CL:​Glossary:​keyword parameter]]//​ in the below table that is not explicitly supplied, the value of the corresponding //​[[CL:​Glossary:​printer control variable]]//​ is the same as it was at the time **write** was invoked. Once the appropriate //​[[CL:​Glossary:​binding|bindings]]//​ are //​[[CL:​Glossary:​established]]//,​ the //​[[CL:​Glossary:​object]]//​ is output by the //​[[CL:​Glossary:​Lisp printer]]//​.
 +
 +^ Parameter ​          ^ Corresponding Dynamic Variable ​                                              ^
 +| //​array// ​          | **[[CL:​Variables:​star-print-array-star|*print-array*]]** ​                    |
 +| //​base// ​           | **[[CL:​Variables:​star-print-base-star|*print-base*]]** ​                      |
 +| //​case// ​           | **[[CL:​Variables:​star-print-case-star|*print-case*]]** ​                      |
 +| //​circle// ​         | **[[CL:​Variables:​star-print-circle-star|*print-circle*]]** ​                  |
 +| //​escape// ​         | **[[CL:​Variables:​star-print-escape-star|*print-escape*]]** ​                  |
 +| //​gensym// ​         | **[[CL:​Variables:​star-print-gensym-star|*print-gensym*]]** ​                  |
 +| //​length// ​         | **[[CL:​Variables:​star-print-length-star|*print-length*]]** ​                  |
 +| //​level// ​          | **[[CL:​Variables:​star-print-level-star|*print-level*]]** ​                    |
 +| //​lines// ​          | **[[CL:​Variables:​star-print-lines-star|*print-lines*]]** ​                    |
 +| //​miser-width// ​    | **[[CL:​Variables:​star-print-miser-width-star|*print-miser-width*]]** ​        |
 +| //​pprint-dispatch//​ | **[[CL:​Variables:​star-print-pprint-dispatch-star|*print-pprint-dispatch*]]** |
 +| //​pretty// ​         | **[[CL:​Variables:​star-print-pretty-star|*print-pretty*]]** ​                  |
 +| //​radix// ​          | **[[CL:​Variables:​star-print-radix-star|*print-radix*]]** ​                    |
 +| //​readably// ​       | **[[CL:​Variables:​star-print-readably-star|*print-readably*]]** ​              |
 +| //​right-margin// ​   | **[[CL:​Variables:​star-print-right-margin-star|*print-right-margin*]]** ​      |
 +
 +**prin1**, **princ**, **print**, and **pprint** implicitly //​[[CL:​Glossary:​bind]]//​ certain print parameters to particular values. The remaining parameter values are taken from **[[CL:​Variables:​star-print-array-star|*print-array*]]**,​ **[[CL:​Variables:​star-print-base-star|*print-base*]]**,​ **[[CL:​Variables:​star-print-case-star|*print-case*]]**,​ **[[CL:​Variables:​star-print-circle-star|*print-circle*]]**,​ **[[CL:​Variables:​star-print-escape-star|*print-escape*]]**,​ **[[CL:​Variables:​star-print-gensym-star|*print-gensym*]]**,​ **[[CL:​Variables:​star-print-length-star|*print-length*]]**,​ **[[CL:​Variables:​star-print-level-star|*print-level*]]**,​ **[[CL:​Variables:​star-print-lines-star|*print-lines*]]**,​ **[[CL:​Variables:​star-print-miser-width-star|*print-miser-width*]]**,​ **[[CL:​Variables:​star-print-pprint-dispatch-star|*print-pprint-dispatch*]]**,​ **[[CL:​Variables:​star-print-pretty-star|*print-pretty*]]**,​ **[[CL:​Variables:​star-print-radix-star|*print-radix*]]**,​ and **[[CL:​Variables:​star-print-right-margin-star|*print-right-margin*]]**.
 +
 +**prin1** produces output suitable for input to **[[CL:​Functions:​read]]**. It binds **[[CL:​Variables:​star-print-escape-star|*print-escape*]]** to //​[[CL:​Glossary:​true]]//​.
 +
 +**princ** is just like **prin1** except that the output has no //​[[CL:​Glossary:​escape]]//​ //​[[CL:​Glossary:​characters]]//​. It binds **[[CL:​Variables:​star-print-escape-star|*print-escape*]]** to //​[[CL:​Glossary:​false]]//​ and **[[CL:​Variables:​star-print-readably-star|*print-readably*]]** to //​[[CL:​Glossary:​false]]//​.
 +
 +The general rule is that output from **princ** is intended to look good to people, while output from **prin1** is intended to be acceptable to **[[CL:​Functions:​read]]**.
 +
 +**print** is just like **prin1** except that the printed representation of //object// is preceded by a newline and followed by a space.
 +
 +**pprint** is just like **print** except that the trailing space is omitted and //object// is printed with the **[[CL:​Variables:​star-print-pretty-star|*print-pretty*]]** flag //​[[CL:​Glossary:​non-nil]]//​ to produce pretty output.
 +
 +//​output-stream//​ specifies the //​[[CL:​Glossary:​stream]]//​ to which output is to be sent.
 +
 +====Affected By====
 +**[[CL:​Variables:​star-standard-output-star|*standard-output*]]**,​ **[[CL:​Variables:​star-terminal-io-star|*terminal-io*]]**,​ **[[CL:​Variables:​star-print-escape-star|*print-escape*]]**,​ **[[CL:​Variables:​star-print-radix-star|*print-radix*]]**,​ **[[CL:​Variables:​star-print-base-star|*print-base*]]**,​ **[[CL:​Variables:​star-print-circle-star|*print-circle*]]**,​ **[[CL:​Variables:​star-print-pretty-star|*print-pretty*]]**,​ **[[CL:​Variables:​star-print-level-star|*print-level*]]**,​ **[[CL:​Variables:​star-print-length-star|*print-length*]]**,​ **[[CL:​Variables:​star-print-case-star|*print-case*]]**,​ **[[CL:​Variables:​star-print-gensym-star|*print-gensym*]]**,​ **[[CL:​Variables:​star-print-array-star|*print-array*]]**,​ **[[CL:​Variables:​star-read-default-float-format-star|*read-default-float-format*]]**.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​readtable-case|Function READTABLE-CASE]]**
 +  * {\secref\FORMATPrinterOps}
 +
 +====Notes====
 +The //​[[CL:​Glossary:​function|functions]]//​ **prin1** and **print** do not bind **[[CL:​Variables:​star-print-readably-star|*print-readably*]]**.
 +
 +<​blockquote> ​
 +(prin1 object output-stream) ​
 +  ≡ (write object :stream output-stream :escape [[CL:​Constant Variables:​t]])
 +
 +(princ object output-stream) ​
 +  ≡ (write object stream output-stream :escape nil :readably nil)
 +
 +(print object output-stream) ​
 +  ≡ ([[CL:​Special Operators:​progn]] ([[CL:​Functions:​terpri]] output-stream) ​
 +           ​(write object :stream output-stream :escape [[CL:​Constant Variables:​t]]) ​
 +           ​([[CL:​Functions:​write-char]] #\Space output-stream))
 +
 +(pprint object output-stream) ​
 +  ≡ (write object :stream output-stream :escape [[CL:​Constant Variables:​t]] :pretty [[CL:​Constant Variables:​t]])
 +</​blockquote>​
 +
 +\issue{PRETTY-PRINT-INTERFACE} \issue{PRINC-READABLY:​X3J13-DEC-91} \issue{PRINC-READABLY:​X3J13-DEC-91}