;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: Introduction =Text: 3INTRODUCTION* People cannot deal directly with Lisp objects, because the objects live inside the machine. In order to let us get at and talk about Lisp objects, Lisp provides a representation of objects in the form of printed text; this is called the 1printed representation*. This is what you have been seeing in the examples throughout this manual. Functions such as 2print*, 2prin1*, and 2princ* take a Lisp object and send the characters of its printed representation to a stream. These functions (and the internal functions they call) are known as the 1printer*. The 2read* function takes characters from a stream, interprets them as a printed representation of a Lisp object, builds a corresponding object, and returns it. It and related functions are known as the 1reader*. (Streams are explained in 4(IOSYSTEM-2)I/O Streams*.) For the rest of the chapter, the phrase `printed representation' is abbreviated as `p.r.' =Node: 4What the Printer Produces* =Text: 3WHAT THE PRINTER PRODUCES* The printed representation of an object depends on its type. In this section, we consider each type of object and explain how it is printed. There are several variables which you can set before calling the printer to control how certain kinds of objects print. They are mentioned where relevant in this section and summarized in the following section, but one of them is so important it must be described now. This is the 1escaping* feature, controlled by the value of 2*print-escape**. Escaping means printing extra syntactical delimiters and 1escape characters* when necessary to avoid ambiguity. Without escaping, a symbol is printed by printing the contents of its name; therefore, the symbol whose name consists of the three characters 21*, 2.* and 25* prints just like the floating point number 21.5*. Escaping causes the symbol to print as 2|1.5|* to differentiate the two. 2|* is a kind of escape character; see 4(READPRINT-2)What The Reader Accepts* for more information on escape characters and what they mean syntactically. Escaping also involves printing package prefixes for symbols, printing double-quotes or suitable delimiters around the contents of strings, pathnames, host names, editor buffers, condition objects, and many other things. For example, without escaping, the pathname 2SYS: SYS; QCP1 LISP* prints as exactly those characters. The string with those contents prints indistinguishably. With escaping, the pathname prints as 3#FS:LOGICAL-PATHNAME "SYS: SYS; QCP1 LISP"* and the string prints as 2"SYS: SYS; QCP1 LISP"*. The non-escaped version is nicer looking in general, but if you give it to 2read* it won't do the right thing. The escaped version is carefully set up so that 2read* will be able to read it in. Printing with escaping is useful in writing expressions into files. Printing without escaping is useful when constructing messages for the user. However, when the purpose of a message printed for the user is to 1mention* an object, the object should be printed with escaping: 3Your output is in the file SYS: SYS; QCP1 QFASL.* vs 3Expected pathname properties missing from* 3 #FS:LOGICAL-PATHNAME "SYS: SYS; QCP1 LISP".* The printed representation of an object also may depend on whether Common Lisp syntax is in use. Common Lisp syntax and traditional Zetalisp syntax are incompatible in some aspects of their specifications. In order to print objects so that they can be read back in, the printer needs to know which syntax rules the reader will use. This decision is based on the current readtable: the value of 2*readtable** at the time printing is done. Now we describe how each type of object is standardly printed. Integers: For an integer (a fixnum or a bignum): the printed representation consists of 2** a possible radix prefix 2** a minus sign, if the number is negative 2** the representation of the number's absolute value 2** a possible radix suffix. The radix used for printing the number's absolute value is found as the value of 2*print-base**. This should be either a positive fixnum or a symbol with an 2si:princ-function* property. In the former case, the number is simply printed in that radix. In the latter case, the property is called as a function with two arguments, minus the absolute value of the number, and the stream to print on. The property is responsible for all printing. If the value of 2*print-base** is unsuitable, an error is signaled. A radix prefix or suffix is used if either 2*nopoint* is 2nil* and the radix used is ten, or if 2*nopoint* is non-2nil* and 2*print-radix** is non-2nil*. For radix ten, a period is used as the suffix. For any other radix, a prefix of the form 3#1radix*r* is used. A radix prefix or suffix is useful to make sure that 2read* parses the number using the same radix used to print it, or for reminding the user how to interpret the number. Ratios: The printed representation of a ratio consists of 2** a possible radix prefix 2** a minus sign, if the number is negative 2** the numerator 2** a ratio delimiter 2** the denominator If Common Lisp syntax is in use, the ratio delimiter is a slash (2/*). If traditional syntax is in use, backslash (2\*) is used. The numerator and denominator are printed according to 2*print-base**. The condition for printing a radix prefix is the same as for integers, but a prefix 3#10r* is used to indicate radix ten, rather than a period suffix. Floating Point Numbers: 2** a minus sign, if the number is negative 2** one or more decimal digits 2** a decimal point 2** one or more decimal digits 2** an exponent, if the number is small enough or large enough to require one. The exponent, if present, consists of 2** a delimiter, the letter 2e*, 2s* or 2f* 2** a minus sign, if the exponent is negative one to three decimal digits The number of digits printed is just enough to represent all the significant mantissa bits the number has. Feeding the p.r. of a float back to the reader is always supposed to produce an equal float. Floats are always printed in decimal; they are not affected by escaping or by 2*print-base**, and there are never any radix prefixes or suffixes. The Lisp Machine supports two floating point number formats. At any time, one of them is the default; this is controlled by the value of 2*read-default-float-format**. When a floating point number whose format is 1not* currently the default is printed, it must be printed with an exponent so that the exponent delimiter can specify the format. The exponent is introduced in this case by 2f* or 2s* to specify the format. To the reader, 2f* specifies 2single-float* format and 2s* specifies 2short-float* format. A floating point number of the default format is printed with no exponent if this looks nice; namely, if this does not require too many extra zeros to be printed before or after the decimal point. Otherwise, an exponent is printed and is delimited with 2e*. To the reader, 2e* means `use the default format'. Normally the default float format is 2single-float*. Therefore, the printer may print full size floats without exponents or with 2e* exponents, but short floats are always printed with exponents introduced by 2s* so as to tell the reader to make a short float. Complex Numbers: The traditional printed representation of a complex number consists of 2** the real part 2** a plus sign, if the imaginary part is positive 2** the imaginary part 2** the letter 2i*, printed in lower case If the imaginary part is negative, the 2+* is omitted since the initial 2-* of the imaginary part serves to separate it from the real part. In Common Lisp syntax, a complex number is printed as 3#C(1realpart* 1imagpart*)*; for example, 2#C(5 3)*. Common Lisp inexplicably does not allow the more natural 25+3i* syntax. The real and imaginary parts are printed individually according to the specifications above. Symbols: If escaping is off, the p.r. is simply the successive characters of the print-name of the symbol. If escaping is on, two changes must be made. First, the symbol might require a package prefix in order that 2read* work correctly, assuming that the package into which 2read* will read the symbol is the one in which it is being printed. See the chapter on packages (4(PACKAGES-0)Packages*) for an explanation of the package name prefix. If the symbol is one which would have another symbol substituted for it if printed normally and read back, such as the symbol 2member* printed using Common Lisp syntax which would be replaced with 2cli:member* if read in thus, it is printed with a package prefix (e.g., 2global:member*) to make it read in properly. See 4(READPRINT-2)What The Reader Accepts* for more information on this. If the symbol is uninterned, 3#:* is printed instead of a package prefix, provided 2*print-gensym** is non-2nil*. Secondly, if the p.r. would not read in as a symbol at all (that is, if the print-name looks like a number, or contains special characters), then escape characters are added so as to suppress the other reading. Two kinds of escape characters may be used: single-character escapes and multiple escapes. A single-character escape can be used in front of a character to overrule its special syntactic meaning. Multiple escapes are used in pairs, and all the characters between the pair have their special syntactic meanings suppressed 1except single-character escapes*. If the symbol name contains escape characters, they are escaped with single-character escapes. If the symbol name contains anything else problematical, a pair of multiple escape characters are printed around it. The single-character and multiple escape characters are determined by the current readtable. Standardly the multiple escape character is vertical bar (2|*), in both traditional and Common Lisp syntax. The single-character escape character is slash (2/*) in traditional syntax and backslash (2\*) in Common Lisp syntax. 3FOO ;2typical symbol, name composed of upper case letters** 3A/|B ;2symbol with a vertical bar in its name** 3|Symbol with lower case and spaces in its name|* 3|One containing slash (//) and vertical bar (/|) also|* Except when multiple escape characters are printed, any upper case letters in the symbol's name may be printed as lower case, according to the value of the variable 2*print-case**. This is true whether escaping is enabled or not. See the next section for details. Conses: The p.r. for conses tends to favor 1lists*. It starts with an open-parenthesis. Then the car of the cons is printed and the cdr of the cons is examined. If it is 2nil*, a close-parenthesis is printed. If it is anything else but a cons, space dot space followed by that object is printed. If it is a cons, we print a space and start all over (from the point 1after* we printed the open-parenthesis) using this new cons. Thus, a list is printed as an open-parenthesis, the p.r.'s of its elements separated by spaces, and a close-parenthesis. This is how the printer produces representations such as 2(a b (foo bar) c)* in preference to synonymous forms such as 2(a . (b . ((foo . (bar . nil)) . (c . nil))))*. The following additional feature is provided for the p.r. of conses: as a list is printed, 2print* maintains the length of the list so far and the depth of recursion of printing lists. If the length exceeds the value of the variable 2*print-length**, 2print* terminates the printed representation of the list with an ellipsis (three periods) and a close-parenthesis. If the depth of recursion exceeds the value of the variable 2*print-level**, then the character 3#* is printed instead of the list. These two features allow a kind of abbreviated printing that is more concise and suppresses detail. Of course, neither the ellipsis nor the 3#* can be interpreted by 2read*, since the relevant information is lost. In Common Lisp read syntax, either one causes 2read* to signal an error. If 2*print-pretty** is non-2nil*, conses are given to the grinder to print. If 2*print-circle** is non-2nil*, a check is made for cars or cdrs that are circular or shared structure, and any object (except for an interned symbol) already mentioned is replaced by a 3#1n*#* label reference. See for more information on them. 3(let ((*print-circle* t))* 3 (prin1 (circular-list 3 4)))* prints 3#1= (3 4 . #1#)* Character Objects: When escaping is off, a character object is printed by printing the character itself, with no delimiters. In Common Lisp syntax, a character object is printed with escaping as 3#1font*\1character-or-name**. 1font* is the character's font number, in decimal, or is omitted if zero. 1character-or-name* begins with prefixes for any modifier bits (control, meta, etc.) present in the character, each followed by a hyphen. Then comes a representation of the character sans font and modifier bits. If this reduced character is a graphic character, it represents itself. Otherwise, it certainly has a standard name; the name is used. If a graphic characters has special syntactic properties (such as whitespace, paretheses, and macro characters) and modifier bit prefixes have been printed then a single-character escape character is printed before it. In traditional syntax, the p.r. is the similar except that the 3\* is replaced by 3/*. Strings: If escaping is off, the p.r. is simply the successive characters of the string. If escaping is on, double-quote characters (`2"*') are printed surrounding the contents, and any single-character escape characters or double-quotes inside the contents are preceded by single-character escapes. If the string contains a Return character followed by an open parenthesis, a single-character escape is printed before the open parenthesis. Examples: 3"Foo"* 3"/"Foo/", he said."* Named Structures: If the named structure type symbol has a 2named-structure-invoke* property, the property is called as a function with four arguments: the symbol 2:print-self*, the named structure itself, the stream to print on, and the current 1depth* of list structure (see below). It is this function's responsibility to output a suitable printed representation to the stream. This allows a user to define his own p.r. for his named structures; more information can be found in the named structure section (see 4(DEFSTRUCT-2)Named Structures*). Typically the printed representation used starts with either 3#2<** if it is not supposed to be readable or 3#* (see 4Sharp-sign Constructs*) if it is supposed to be readable. If the named structure symbol does not have a 2named-structure-invoke* property, the printed-representation depends on whether escaping is in use. If it is, 3#s* syntax is used: 3#s(1named-structure-symbol** 3 1component* 1value** 3 1component* 1value** 3 ...)* Named structure component values are checked for circular or shared structure if 2*print-circle** is non-2nil*. If escaping is off, the p.r. is like that used for miscellaneous data-types: 3#2<**, the named structure symbol, the numerical address of the structure, and 2>*. Other Arrays: If 2*print-array** is non-2nil*, the array is printed in a way which shows the elements of the array. Bit vectors use 3#** syntax, other vectors use 3#(...)* syntax, and arrays of rank other than one use 3#1n*a(...)* syntax. The printed representation does not indicate the array type (that is, what elements it is allowed to contain). If the printed representation is read in, a general array (array type 2art-q*) is always created. See 4(READPRINT-2)Sharp-sign Constructs* for more information on these syntaxes. Examples: 3(vector 1 2 5) => #(1 2 5)* 3(make-array '(2 4) :initial-element t) => #2a((t t t t) (t t t t))* Vector and array groupings count like list groupings in maintaining the depth value that is compared with 2*print-level** for cutting off things that get too deep. More than 2*print-length** elements in a given vector or array grouping level are cut off with an ellipsis just like a list that is so long. Array elements are checked for circular or shared structure if 2*print-circle** is non-2nil*. If 2*print-array** is 2nil*, the p.r. starts with 3#2<**. Then the 2art-* symbol for the array type is printed. Next the dimensions of the array are printed, separated by hyphens. This is followed by a space, the machine address of the array, and a 2>*, as in 2#*. Instances and Entities: If the object says it can handle the 2:print-self* message, that message is sent with three arguments: the stream to print to, the current 1depth* of list structure (see below), and whether escaping is enabled. The object should print a suitable p.r. on the stream. See 4(FLAVOR-0)Objects, Message Passing, and Flavors* for documentation on instances. Most such objects print like ``any other data type'' below, except with additional information such as a name. Some objects print only their name when escaping is not in effect (when 2princ*'ed). Some objects, including pathnames, use a printed representation that begins with 3#*, ends with , and contains sufficient information for the reader to reconstruct an equivalent object. See 4(READPRINT-2)Sharp-sign Constructs*. If the object cannot handle 2:print-self*, it is printed like ``any other data type''. Any Other Data Type: The printed representation starts with 3#2<** and ends with 2>*. This sort of printed representation cannot be read back in. The 3#2<** is followed by the 2dtp-* symbol for this datatype, a space, and the octal machine address of the object. The object's name, if one can be determined, often appears before the address. If this style of printed representation is being used for a named structure or instance, other interesting information may appear as well. Finally a greater-than sign (3>*) is printed in octal. Examples: 3#'equal => #* 3(value-cell-location nil) => #* Including the machine address in the p.r. makes it possible to tell two objects of this kind apart without explicitly calling 2eq* on them. This can be very useful during debugging. It is important to know that if garbage collection is turned on, objects will occasionally be moved, and therefore their octal machine addresses will be changed. It is best to shut off garbage collection temporarily when depending on these numbers. Printed representations that start with `3#2<**' can never be read back. This can be a problem if, for example, you are printing a structure into a file with the intent of reading it in later. The following feature allows you to make sure that what you are printing may indeed be read with the reader. 3si:print-readably* 1Variable* When 2si:print-readably* is bound to 2t*, the printer signals an error if there is an attempt to print an object that cannot be interpreted by 2read*. When the printer sends a 2:print-self* or a 2:print* message, it assumes that this error checking is done for it. Thus it is possible for these messages 1not* to signal an error, if they see fit. 3si:printing-random-object* 1(object* 1stream* 1.* 1keywords)* &body 1body* 1Macro* The vast majority of objects that define 2:print-self* messages have much in common. This macro is provided for convenience so that users do not have to write out that repetitious code. It is also the preferred interface to 2si:print-readably*. With no keywords, 2si:printing-random-object* checks the value of 2si:print-readably* and signals an error if it is not 2nil*. It then prints a number sign and a less-than sign, evaluates the forms in 1body*, then prints a space, the octal machine address of the object and a greater-than sign. A typical use of this macro might look like: 3(si:printing-random-object (ship stream :typep)* 3 (tyo #\space stream)* 3 (prin1 (ship-name ship) stream))* This might print 2#*. The following keywords may be used to modify the behaviour of 2si:printing-random-object*: 2:no-pointer* This suppresses printing of the octal address of the object. 2:type* This prints the result of 2(type-of 1object*)* after the less-than sign. In the example above, this option could have been used instead of the first two forms in the body. 3sys:print-not-readable* (3error*) 1Condition* This condition is signaled by 2si:print-readably* when the object cannot be printed readably. The condition instance supports the operation 2:object*, which returns the object that was being printed. If you want to control the printed representation of some object, usually the right way to do it is to make the object an array that is a named structure (see 4(DEFSTRUCT-2)Named Structures*), or an instance of a flavor (see 4(FLAVOR-0)Objects, Message Passing, and Flavors*). However, occasionally it is desirable to get control over all printing of objects, in order to change, in some way, how they are printed. If you need to do this, the best way to proceed is to customize the behavior of 2si:print-object* (see 4(READPRINT-4)The :read and :print Stream Operations*), which is the main internal function of the printer. All of the printing functions, such as 2print* and 2princ*, as well as 2format*, go through this function. The way to customize it is by using the ``advice'' facility (see 4(DEBUGGING-5)Advising a Function*). =Node: 4Options that Control Printing* =Text: 3OPTIONS THAT CONTROL PRINTING* Several special variables are defined by the system for the user to set or bind before calling 2print* or other printing functions. Their values, as set up by the user, control how various kinds of objects are printed. 3*print-escape** 1Variable* Escaping is done if this variable is non-2nil*. See the previous section for a description of the many effects of escaping. Most of the output functions bind this variable to 2t* or to 2nil*, so you rarely use the variable itself. 3*print-base** 1Variable* 3base* 1Variable* The radix to use for printing integers and ratios. The value must be either an integer from 2 to 36 or a symbol with a valid 2si:princ-function* property, such as 2:roman* or 2:english*. The default value of 2*print-base** is ten. In input from files, the 2Base* attribute (see 4(FILEACCESS-2)File Attribute Lists*) controls the value of 2*print-base** (and of 2*read-base**). The synonym 2base* is from Maclisp. 3*print-radix** 1Variable* If non-2nil*, integers and ratios are output with a prefix or suffix indicating the radix used to print them. For integers and radix ten, a period is printed as a suffix. Otherwise, a prefix such as 3#x* or 3#3r* is printed. The default value of 2*print-radix** is 2nil*. 3*nopoint* 1Variable* If the value of 2*nopoint* is 2nil*, a trailing decimal point is printed when a fixnum is printed out in base 10. This allows the numbers to be read back in correctly even if 2*read-base** is not 10 at the time of reading. The default value of 2*nopoint* is 2t*. 2*nopoint* has no effect if 2*print-radix** is non-2nil*. 2*nopoint* exists for Maclisp compatibility. But to get truly compatible behavior, you must set 2*nopoint* to 2nil* (and, by default, 2base* and 2ibase* to eight). 3*print-circle** 1Variable* If non-2nil*, the printer recognizes circular and shared structure and prints it using 3#1n*=* labels so that it has a finite printed representation (which can be read back in). The default is 2nil*, since 2t* makes printing slower. See for information on the 3#1n*=* construct. 3*print-pretty** 1Variable* If non-2nil*, the printer actually calls 2grind-top-level* so that it prints extra whitespace for the sake of formatting. The default is 2nil*. 3*print-gensym** 1Variable* If non-2nil*, uninterned symbols are printed with the prefix 3#:* to mark them as such (but only when 2*print-escape** is non-2nil*). The prefix causes the reader to construct a similar uninterned symbol when the expression is read. If 2nil*, no prefix is used for uninterned symbols. The default is 2t*. 3*print-array** 1Variable* If non-2nil*, non-string arrays are printed using the 3#2(...)**, 3#** or 3#1n*a2(...)** syntax so that you can see their contents (and so that they can be read back in). If 2nil*, such arrays are printed using 3#2<...>** syntax and do not show their contents. The default is 2nil*. The printing of strings is not affected by this variable. 3*print-case** 1Variable* Controls the case used for printing upper-case letters in the names of symbols. Its value should be 2:upcase*, 2:downcase* or 2:capitalize*. These mean, respectively, to print those letters as upper case, to print them as lower case, or to capitalize each word (see 2string-capitalize*, 4(CHARSTR-2)Conversion to Upper or Lower Case*). Any lower case letters in the symbol name are printed as lower case and escaped suitably; this flag does not affect them. Note that the case used for printing the upper case letters has no effect on reading the symbols back in, since they are case-converted by 2read*. Any upper case letters that happen to be escaped are always printed in upper case. 3(dolist (*print-case* '(:upcase :downcase :capitalize))* 3 (prin1-then-space 'foo)* 3 (prin1-then-space '|Foo|))* prints 2FOO |Foo| foo |Foo| Foo |Foo| *. 3*print-level** 1Variable* 3prinlevel* 1Variable* 2*print-level** can be set to the maximum number of nested lists that can be printed before the printer gives up and just prints a 3#* instead of a list element. If it is 2nil*, which it is initially, any number of nested lists can be printed. Otherwise, the value of 2*print-level** must be a fixnum. Example: 3(let ((*print-level* 2))* 3 (prin1 '(a (b (c (d e))))))* prints 2(a (b #))*. The synonym 2prinlevel* is from Maclisp. 3*print-length** 1Variable* 3prinlength* 1Variable* 2*print-length** can be set to the maximum number of elements of a list that can be printed before the printer gives up and prints an ellipsis (three periods). If it is 2nil*, which it is initially, any length list may be printed. Example: 3(let ((*print-length* 3))* 3 (prin1 '((a b c d) #(e f g h) (i j k l) (m n o p))))* prints 2((a b c ...) #(e f g ...) (i j k ...) ...)*. The synonym 2prinlength* is from Maclisp.