User Tools


Differences

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

Link to this comparison view

cl:functions:print-object [2019/11/11 05:00]
cl:functions:print-object [2019/11/11 22:00] (current)
Line 1: Line 1:
 +====== Standard Generic Function PRINT-OBJECT ======
 +
 +====Syntax====
 +  * **print-object** //object stream// → //object//
 +
 +====Method Signatures====
 +  * print-object (//object// [[CL:​Types:​standard-object]]) //stream//
 +  * print-object (//object// [[CL:​Types:​structure-object]]) //stream//
 +
 +====Arguments and Values====
 +  * //object// - an //​[[CL:​Glossary:​object]]//​.
 +  * //stream// - a //​[[CL:​Glossary:​stream]]//​.
 +
 +====Description====
 +The **print-object** //​[[CL:​Glossary:​generic function]]//​ writes the printed representation of //object// to //stream//. The //​[[CL:​Glossary:​function]]//​ **print-object** is called by the //​[[CL:​Glossary:​Lisp printer]]//;​ it should not be called by the user.
 +
 +Each implementation is required to provide a //​[[CL:​Glossary:​method]]//​ on the **[[CL:​Types:​standard-object]]** //​[[CL:​Glossary:​class]]//​ and on the **[[CL:​Types:​structure-object]]** //​[[CL:​Glossary:​class]]//​. In addition, each //​[[CL:​Glossary:​implementation]]//​ must provide //​[[CL:​Glossary:​method|methods]]//​ on enough other //​[[CL:​Glossary:​class|classes]]//​ so as to ensure that there is always an applicable //​[[CL:​Glossary:​method]]//​. Implementations are free to add //​[[CL:​Glossary:​method|methods]]//​ for other //​[[CL:​Glossary:​class|classes]]//​. Users may write //​[[CL:​Glossary:​method|methods]]//​ for **print-object** for their own //​[[CL:​Glossary:​class|classes]]//​ if they do not wish to inherit an //​[[CL:​Glossary:​implementation-dependent]]//​ //​[[CL:​Glossary:​method]]//​.
 +
 +The //​[[CL:​Glossary:​method]]//​ on the **[[CL:​Types:​structure-object]]** //​[[CL:​Glossary:​class]]//​ prints the object in the default ''#​S''​ notation; see section {\secref\PrintingStructures}.
 +
 +//​[[CL:​Glossary:​method|Methods]]//​ on **print-object** are responsible for implementing their part of the semantics of the //​[[CL:​Glossary:​printer control variable|printer control variables]]//,​ as follows:
 +
 +===*print-readably*===
 +All methods for **print-object** must obey **[[CL:​Variables:​star-print-readably-star|*print-readably*]]**. This includes both user-defined methods and //​[[CL:​Glossary:​implementation-defined]]//​ methods. Readable printing of //​[[CL:​Glossary:​structures]]//​ and //​[[CL:​Glossary:​standard objects]]// is controlled by their **print-object** method, not by their **[[CL:​Functions:​make-load-form]]** //​[[CL:​Glossary:​method]]//​. //​[[CL:​Glossary:​Similarity]]//​ for these //​[[CL:​Glossary:​object|objects]]//​ is application dependent and hence is defined to be whatever these //​[[CL:​Glossary:​method|methods]]//​ do; see section {\secref\Similarity}.
 +
 +===*print-escape*===
 +Each //​[[CL:​Glossary:​method]]//​ must implement **[[CL:​Variables:​star-print-escape-star|*print-escape*]]**.
 +
 +===*print-pretty*===
 +The //​[[CL:​Glossary:​method]]//​ may wish to perform specialized line breaking or other output conditional on the //​[[CL:​Glossary:​value]]//​ of **[[CL:​Variables:​star-print-pretty-star|*print-pretty*]]**. For further information,​ see (for example) the //​[[CL:​Glossary:​macro]]//​ **[[CL:​Macros:​pprint-fill]]**. See also \secref\PPrintDispatchTables\ and \secref\PrettyPrinterExamples.
 +
 +===*print-length*===
 +//​[[CL:​Glossary:​method|Methods]]//​ that produce output of indefinite length must obey **[[CL:​Variables:​star-print-length-star|*print-length*]]**.
 +
 +For further information,​ see (for example) the //​[[CL:​Glossary:​macros]]//​ **[[CL:​Macros:​pprint-logical-block]]** and **[[CL:​Macros:​pprint-pop]]**. See also \secref\PPrintDispatchTables\ and \secref\PrettyPrinterExamples.
 +
 +===*print-level*===
 +The printer takes care of **[[CL:​Variables:​star-print-level-star|*print-level*]]** automatically,​ provided that each //​[[CL:​Glossary:​method]]//​ handles exactly one level of structure and calls **[[CL:​Functions:​write]]** (or an equivalent //​[[CL:​Glossary:​function]]//​) recursively if there are more structural levels. The printer'​s decision of whether an //​[[CL:​Glossary:​object]]//​ has components (and therefore should not be printed when the printing depth is not less than **[[CL:​Variables:​star-print-level-star|*print-level*]]**) is //​[[CL:​Glossary:​implementation-dependent]]//​. In some implementations its **print-object** //​[[CL:​Glossary:​method]]//​ is not called; in others the //​[[CL:​Glossary:​method]]//​ is called, and the determination that the //​[[CL:​Glossary:​object]]//​ has components is based on what it tries to write to the //stream//.
 +
 +===*print-circle*===
 +When the //​[[CL:​Glossary:​value]]//​ of **[[CL:​Variables:​star-print-circle-star|*print-circle*]]** is //​[[CL:​Glossary:​true]]//,​ a user-defined **print-object** //​[[CL:​Glossary:​method]]//​ can print //​[[CL:​Glossary:​object|objects]]//​ to the supplied //​[[CL:​Glossary:​stream]]//​ using **[[CL:​Functions:​write]]**,​ **[[CL:​Functions:​prin1]]**,​ **[[CL:​Functions:​princ]]**,​ or **[[CL:​Functions:​format]]** and expect circularities to be detected and printed using the ''#​n#''​ syntax. If a user-defined **print-object** //​[[CL:​Glossary:​method]]//​ prints to a //​[[CL:​Glossary:​stream]]//​ other than the one that was supplied, then circularity detection starts over for that //​[[CL:​Glossary:​stream]]//​. See **[[CL:​Variables:​star-print-circle-star|*print-circle*]]**.
 +
 +===*print-base*,​ *print-radix*,​ *print-case*,​ *print-gensym*,​ and *print-array*===
 +These //​[[CL:​Glossary:​printer control variables]]//​ apply to specific types of //​[[CL:​Glossary:​object|objects]]//​ and are handled by the //​[[CL:​Glossary:​method|methods]]//​ for those //​[[CL:​Glossary:​object|objects]]//​.
 +
 +-------
 +
 +If these rules are not obeyed, the results are undefined.
 +
 +In general, the printer and the **print-object** methods should not rebind the print control variables as they operate recursively through the structure, but this is //​[[CL:​Glossary:​implementation-dependent]]//​.
 +
 +In some implementations the //stream// argument passed to a **print-object** //​[[CL:​Glossary:​method]]//​ is not the original //​[[CL:​Glossary:​stream]]//,​ but is an intermediate //​[[CL:​Glossary:​stream]]//​ that implements part of the printer. //​[[CL:​Glossary:​method|methods]]//​ should therefore not depend on the identity of this //​[[CL:​Glossary:​stream]]//​.
 +
 +====Examples====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​pprint-fill|Function PPRINT-FILL]]**
 +  * **[[CL:​Macros:​pprint-logical-block|Macro PPRINT-LOGICAL-BLOCK]]**
 +  * **[[CL:​Macros:​pprint-pop|Local Macro PPRINT-POP]]**
 +  * **[[CL:​Functions:​write|Function WRITE]]**
 +  * **[[CL:​Variables:​star-print-readably-star|Variable *PRINT-READABLY*]]**
 +  * **[[CL:​Variables:​star-print-escape-star|Variable *PRINT-ESCAPE*]]**
 +  * **[[CL:​Variables:​star-print-pretty-star|Variable *PRINT-PRETTY*]]**
 +  * **[[CL:​Variables:​star-print-length-star|Variable *PRINT-LENGTH*]]**
 +  * {\secref\DefaultPrintObjMeths}
 +  * {\secref\PrintingStructures}
 +  * {\secref\PPrintDispatchTables}
 +  * {\secref\PrettyPrinterExamples}
 +
 +====Notes====
 +None.
 +
 +\issue{DEFSTRUCT-PRINT-FUNCTION-AGAIN:​X3J13-MAR-93} \issue{DEFSTRUCT-PRINT-FUNCTION-AGAIN:​X3J13-MAR-93} \issue{DEFSTRUCT-PRINT-FUNCTION-AGAIN:​X3J13-MAR-93} \issue{DEFSTRUCT-PRINT-FUNCTION-AGAIN:​X3J13-MAR-93} \issue{DEFSTRUCT-PRINT-FUNCTION-AGAIN:​X3J13-MAR-93} \issue{DATA-IO:​ADD-SUPPORT} \issue{GENERALIZE-PRETTY-PRINTER:​UNIFY} \issue{GENERALIZE-PRETTY-PRINTER:​UNIFY} \issue{PRINT-CIRCLE-STRUCTURE:​USER-FUNCTIONS-WORK}