This is gcl.info, produced by makeinfo version 6.7 from gcl.texi.

This is a Texinfo GNU Common Lisp Manual based on the draft ANSI
standard for Common Lisp.

   Copyright 1994 William F. Schelter

INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl: (gcl.info). GNU Common Lisp Manual
END-INFO-DIR-ENTRY


File: gcl.info,  Node: Printer,  Next: Reader,  Prev: Streams,  Up: Top

22 Printer
**********

* Menu:

* The Lisp Printer::
* The Lisp Pretty Printer::
* Formatted Output::
* Printer Dictionary::


File: gcl.info,  Node: The Lisp Printer,  Next: The Lisp Pretty Printer,  Prev: Printer,  Up: Printer

22.1 The Lisp Printer
=====================

* Menu:

* Overview of The Lisp Printer::
* Printer Dispatching::
* Default Print-Object Methods::
* Examples of Printer Behavior::


File: gcl.info,  Node: Overview of The Lisp Printer,  Next: Printer Dispatching,  Prev: The Lisp Printer,  Up: The Lisp Printer

22.1.1 Overview of The Lisp Printer
-----------------------------------

Common Lisp provides a representation of most objects in the form of
printed text called the printed representation.  Functions such as print
take an object and send the characters of its printed representation to
a stream.  The collection of routines that does this is known as the
(Common Lisp) printer.

   Reading a printed representation typically produces an object that is
equal to the originally printed object.

* Menu:

* Multiple Possible Textual Representations::
* Printer Escaping::


File: gcl.info,  Node: Multiple Possible Textual Representations,  Next: Printer Escaping,  Prev: Overview of The Lisp Printer,  Up: Overview of The Lisp Printer

22.1.1.1 Multiple Possible Textual Representations
..................................................

Most objects have more than one possible textual representation.  For
example, the positive integer with a magnitude of twenty-seven can be
textually expressed in any of these ways:

      27    27.    #o33    #x1B    #b11011    #.(* 3 3 3)    81/3

   A list containing the two symbols A and B can also be textually
expressed in a variety of ways:

      (A B)    (a b)    (  a  b )    (\A |B|)
     (|\A|
       B
     )

   In general,

   from the point of view of the Lisp reader,

   wherever whitespace is permissible in a textual representation, any
number of spaces and newlines can appear in standard syntax.

   When a function such as print produces a printed representation, it
must choose from among many possible textual representations.  In most
cases, it chooses a program readable representation, but in certain
cases it might use a more compact notation that is not program-readable.

   A number of option variables, called printer control variables , are
provided to permit control of individual aspects of the printed
representation of objects.  Figure 22-1 shows the standardized printer
control variables; there might also be implementation-defined printer
control variables.

  *print-array*   *print-gensym*       *print-pprint-dispatch*  
  *print-base*    *print-length*       *print-pretty*           
  *print-case*    *print-level*        *print-radix*            
  *print-circle*  *print-lines*        *print-readably*         
  *print-escape*  *print-miser-width*  *print-right-margin*     

       Figure 22-1: Standardized Printer Control Variables     


   In addition to the printer control variables, the following
additional defined names relate to or affect the behavior of the Lisp
printer:

  *package*                    *read-eval*  readtable-case  
  *read-default-float-format*  *readtable*                  

   Figure 22-2: Additional Influences on the Lisp printer. 



File: gcl.info,  Node: Printer Escaping,  Prev: Multiple Possible Textual Representations,  Up: Overview of The Lisp Printer

22.1.1.2 Printer Escaping
.........................

The variable *print-escape* controls whether the Lisp printer tries to
produce notations such as escape characters and package prefixes.

   The variable *print-readably* can be used to override many of the
individual aspects controlled by the other printer control variables
when program-readable output is especially important.

   One of the many effects of making the value of *print-readably* be
true is that the Lisp printer behaves as if *print-escape* were also
true.  For notational convenience, we say that if the value of either
*print-readably* or *print-escape* is true, then printer escaping is
"enabled"; and we say that if the values of both *print-readably* and
*print-escape* are false, then printer escaping is "disabled".


File: gcl.info,  Node: Printer Dispatching,  Next: Default Print-Object Methods,  Prev: Overview of The Lisp Printer,  Up: The Lisp Printer

22.1.2 Printer Dispatching
--------------------------

The Lisp printer makes its determination of how to print an object as
follows:

   If the value of *print-pretty* is true, printing is controlled by the
current pprint dispatch table; see *note Pretty Print Dispatch Tables::.

   Otherwise (if the value of *print-pretty* is false), the object's
print-object method is used; see *note Default Print-Object Methods::.


File: gcl.info,  Node: Default Print-Object Methods,  Next: Examples of Printer Behavior,  Prev: Printer Dispatching,  Up: The Lisp Printer

22.1.3 Default Print-Object Methods
-----------------------------------

This section describes the default behavior of print-object methods for
the standardized types.

* Menu:

* Printing Numbers::
* Printing Integers::
* Printing Ratios::
* Printing Floats::
* Printing Complexes::
* Note about Printing Numbers::
* Printing Characters::
* Printing Symbols::
* Package Prefixes for Symbols::
* Effect of Readtable Case on the Lisp Printer::
* Examples of Effect of Readtable Case on the Lisp Printer::
* Printing Strings::
* Printing Lists and Conses::
* Printing Bit Vectors::
* Printing Other Vectors::
* Printing Other Arrays::
* Examples of Printing Arrays::
* Printing Random States::
* Printing Pathnames::
* Printing Structures::
* Printing Other Objects::


File: gcl.info,  Node: Printing Numbers,  Next: Printing Integers,  Prev: Default Print-Object Methods,  Up: Default Print-Object Methods

22.1.3.1 Printing Numbers
.........................


File: gcl.info,  Node: Printing Integers,  Next: Printing Ratios,  Prev: Printing Numbers,  Up: Default Print-Object Methods

22.1.3.2 Printing Integers
..........................

Integers are printed in the radix specified by the current output base
in positional notation, most significant digit first.  If appropriate, a
radix specifier can be printed; see *print-radix*.  If an integer is
negative, a minus sign is printed and then the absolute value of the
integer is printed.  The integer zero is represented by the single digit
0 and never has a sign.  A decimal point might be printed, depending on
the value of *print-radix*.

   For related information about the syntax of an integer, see *note
Syntax of an Integer::.


File: gcl.info,  Node: Printing Ratios,  Next: Printing Floats,  Prev: Printing Integers,  Up: Default Print-Object Methods

22.1.3.3 Printing Ratios
........................

Ratios are printed as follows: the absolute value of the numerator is
printed, as for an integer; then a /; then the denominator.  The
numerator and denominator are both printed in the radix specified by the
current output base; they are obtained as if by numerator and
denominator, and so ratios are printed in reduced form (lowest terms).
If appropriate, a radix specifier can be printed; see *print-radix*.  If
the ratio is negative, a minus sign is printed before the numerator.

   For related information about the syntax of a ratio, see *note Syntax
of a Ratio::.


File: gcl.info,  Node: Printing Floats,  Next: Printing Complexes,  Prev: Printing Ratios,  Up: Default Print-Object Methods

22.1.3.4 Printing Floats
........................

If the magnitude of the float is either zero or between 10^-3
(inclusive) and 10^7 (exclusive), it is printed as the integer part of
the number, then a decimal point, followed by the fractional part of the
number; there is always at least one digit on each side of the decimal
point.  If the sign of the number (as determined by float-sign) is
negative, then a minus sign is printed before the number.  If the format
of the number does not match that specified by
*read-default-float-format*, then the exponent marker for that format
and the digit 0 are also printed.  For example, the base of the natural
logarithms as a short float might be printed as 2.71828S0.

   For non-zero magnitudes outside of the range 10^-3 to 10^7, a float
is printed in computerized scientific notation.  The representation of
the number is scaled to be between 1 (inclusive) and 10 (exclusive) and
then printed, with one digit before the decimal point and at least one
digit after the decimal point.  Next the exponent marker for the format
is printed, except that if the format of the number matches that
specified by *read-default-float-format*, then the exponent marker E is
used.  Finally, the power of ten by which the fraction must be
multiplied to equal the original number is printed as a decimal integer.
For example, Avogadro's number as a short float is printed as 6.02S23.

   For related information about the syntax of a float, see *note Syntax
of a Float::.


File: gcl.info,  Node: Printing Complexes,  Next: Note about Printing Numbers,  Prev: Printing Floats,  Up: Default Print-Object Methods

22.1.3.5 Printing Complexes
...........................

A complex is printed as #C, an open parenthesis, the printed
representation of its real part, a space, the printed representation of
its imaginary part, and finally a close parenthesis.

   For related information about the syntax of a complex, see *note
Syntax of a Complex:: and *note Sharpsign C::.


File: gcl.info,  Node: Note about Printing Numbers,  Next: Printing Characters,  Prev: Printing Complexes,  Up: Default Print-Object Methods

22.1.3.6 Note about Printing Numbers
....................................

The printed representation of a number must not contain escape
characters; see *note Escape Characters and Potential Numbers::.


File: gcl.info,  Node: Printing Characters,  Next: Printing Symbols,  Prev: Note about Printing Numbers,  Up: Default Print-Object Methods

22.1.3.7 Printing Characters
............................

When printer escaping is disabled,

   a character prints as itself; it is sent directly to the output
stream.

   When printer escaping is enabled,

   then #\ syntax is used.

   When the printer types out the name of a character, it uses the same
table as the #\ reader macro would use; therefore any character name
that is typed out is acceptable as input (in that implementation).  If a
non-graphic character has a standardized name_5, that name is preferred
over non-standard names for printing in #\ notation.  For the graphic
standard characters, the character itself is always used for printing in
#\ notation--even if the character also has a name_5.

   For details about the #\ reader macro, see *note Sharpsign
Backslash::.


File: gcl.info,  Node: Printing Symbols,  Next: Package Prefixes for Symbols,  Prev: Printing Characters,  Up: Default Print-Object Methods

22.1.3.8 Printing Symbols
.........................

When printer escaping is disabled,

   only the characters of the symbol's name are output

   (but the case in which to print characters in the name is controlled
by *print-case*; see *note Effect of Readtable Case on the Lisp
Printer::).

   The remainder of this section applies only

   when printer escaping is enabled.

   When printing a symbol, the printer inserts enough single escape
and/or multiple escape characters (backslashes and/or vertical-bars) so
that if read were called with the same *readtable* and with *read-base*
bound to the current output base, it would return the same symbol (if it
is not apparently uninterned) or an uninterned symbol with the same
print name (otherwise).

   For example, if the value of *print-base* were 16 when printing the
symbol face, it would have to be printed as \FACE or \Face or |FACE|,
because the token face would be read as a hexadecimal number (decimal
value 64206) if the value of *read-base* were 16.

   For additional restrictions concerning characters with nonstandard
syntax types in the current readtable, see the variable *print-readably*

   For information about how the Lisp reader parses symbols, see *note
Symbols as Tokens:: and *note Sharpsign Colon::.

   nil might be printed as ()

   when *print-pretty* is true and printer escaping is enabled.


File: gcl.info,  Node: Package Prefixes for Symbols,  Next: Effect of Readtable Case on the Lisp Printer,  Prev: Printing Symbols,  Up: Default Print-Object Methods

22.1.3.9 Package Prefixes for Symbols
.....................................

Package prefixes are printed if necessary.  The rules for package
prefixes are as follows.  When the symbol is printed, if it is in the
KEYWORD package, then it is printed with a preceding colon; otherwise,
if it is accessible in the current package, it is printed without any
package prefix; otherwise, it is printed with a package prefix.

   A symbol that is apparently uninterned is printed preceded by "#:"

   if *print-gensym* is true and printer escaping is enabled; if
*print-gensym* is false or printer escaping is disabled,

   then the symbol is printed without a prefix, as if it were in the
current package.

   Because the #: syntax does not intern the following symbol, it is
necessary to use circular-list syntax if *print-circle* is true and the
same uninterned symbol appears several times in an expression to be
printed.  For example, the result of

      (let ((x (make-symbol "FOO"))) (list x x))

   would be printed as (#:foo #:foo) if *print-circle* were false, but
as (#1=#:foo #1#) if *print-circle* were true.

   A summary of the preceding package prefix rules follows:

foo:bar
     foo:bar is printed when symbol bar is external in its home package
     foo and is not accessible in the current package.

foo::bar
     foo::bar is printed when bar is internal in its home package foo
     and is not accessible in the current package.

:bar
     :bar is printed when the home package of bar is the KEYWORD
     package.

#:bar
     #:bar is printed when bar is apparently uninterned, even in the
     pathological case that bar has no home package but is nevertheless
     somehow accessible in the current package.


File: gcl.info,  Node: Effect of Readtable Case on the Lisp Printer,  Next: Examples of Effect of Readtable Case on the Lisp Printer,  Prev: Package Prefixes for Symbols,  Up: Default Print-Object Methods

22.1.3.10 Effect of Readtable Case on the Lisp Printer
......................................................

When printer escaping is disabled, or the characters under consideration
are not already quoted specifically by single escape or multiple escape
syntax,

   the readtable case of the current readtable affects the way the Lisp
printer writes symbols in the following ways:

:upcase
     When the readtable case is :upcase, uppercase characters are
     printed in the case specified by *print-case*, and lowercase
     characters are printed in their own case.

:downcase
     When the readtable case is :downcase, uppercase characters are
     printed in their own case, and lowercase characters are printed in
     the case specified by *print-case*.

:preserve
     When the readtable case is :preserve, all alphabetic characters are
     printed in their own case.

:invert
     When the readtable case is :invert, the case of all alphabetic
     characters in single case symbol names is inverted.  Mixed-case
     symbol names are printed as is.

   The rules for escaping alphabetic characters in symbol names are
affected by the readtable-case

   if printer escaping is enabled.

   Alphabetic characters are escaped as follows:

:upcase
     When the readtable case is :upcase, all lowercase characters must
     be escaped.

:downcase
     When the readtable case is :downcase, all uppercase characters must
     be escaped.

:preserve
     When the readtable case is :preserve, no alphabetic characters need
     be escaped.

:invert
     When the readtable case is :invert, no alphabetic characters need
     be escaped.


File: gcl.info,  Node: Examples of Effect of Readtable Case on the Lisp Printer,  Next: Printing Strings,  Prev: Effect of Readtable Case on the Lisp Printer,  Up: Default Print-Object Methods

22.1.3.11 Examples of Effect of Readtable Case on the Lisp Printer
..................................................................

      (defun test-readtable-case-printing ()
        (let ((*readtable* (copy-readtable nil))
              (*print-case* *print-case*))
          (format t "READTABLE-CASE *PRINT-CASE*  Symbol-name  Output~
                   ~
                   ~
          (dolist (readtable-case '(:upcase :downcase :preserve :invert))
            (setf (readtable-case *readtable*) readtable-case)
            (dolist (print-case '(:upcase :downcase :capitalize))
              (dolist (symbol '(|ZEBRA| |Zebra| |zebra|))
                (setq *print-case* print-case)
                (format t "~&:~A~15T:~A~29T~A~42T~A"
                        (string-upcase readtable-case)
                        (string-upcase print-case)
                        (symbol-name symbol)
                        (prin1-to-string symbol)))))))

   The output from (test-readtable-case-printing) should be as follows:

         READTABLE-CASE *PRINT-CASE*  Symbol-name  Output
         --------------------------------------------------
         :UPCASE        :UPCASE       ZEBRA        ZEBRA
         :UPCASE        :UPCASE       Zebra        |Zebra|
         :UPCASE        :UPCASE       zebra        |zebra|
         :UPCASE        :DOWNCASE     ZEBRA        zebra
         :UPCASE        :DOWNCASE     Zebra        |Zebra|
         :UPCASE        :DOWNCASE     zebra        |zebra|
         :UPCASE        :CAPITALIZE   ZEBRA        Zebra
         :UPCASE        :CAPITALIZE   Zebra        |Zebra|
         :UPCASE        :CAPITALIZE   zebra        |zebra|
         :DOWNCASE      :UPCASE       ZEBRA        |ZEBRA|
         :DOWNCASE      :UPCASE       Zebra        |Zebra|
         :DOWNCASE      :UPCASE       zebra        ZEBRA
         :DOWNCASE      :DOWNCASE     ZEBRA        |ZEBRA|
         :DOWNCASE      :DOWNCASE     Zebra        |Zebra|
         :DOWNCASE      :DOWNCASE     zebra        zebra
         :DOWNCASE      :CAPITALIZE   ZEBRA        |ZEBRA|
         :DOWNCASE      :CAPITALIZE   Zebra        |Zebra|
         :DOWNCASE      :CAPITALIZE   zebra        Zebra
         :PRESERVE      :UPCASE       ZEBRA        ZEBRA
         :PRESERVE      :UPCASE       Zebra        Zebra
         :PRESERVE      :UPCASE       zebra        zebra
         :PRESERVE      :DOWNCASE     ZEBRA        ZEBRA
         :PRESERVE      :DOWNCASE     Zebra        Zebra
         :PRESERVE      :DOWNCASE     zebra        zebra
         :PRESERVE      :CAPITALIZE   ZEBRA        ZEBRA
         :PRESERVE      :CAPITALIZE   Zebra        Zebra
         :PRESERVE      :CAPITALIZE   zebra        zebra
         :INVERT        :UPCASE       ZEBRA        zebra
         :INVERT        :UPCASE       Zebra        Zebra
         :INVERT        :UPCASE       zebra        ZEBRA
         :INVERT        :DOWNCASE     ZEBRA        zebra
         :INVERT        :DOWNCASE     Zebra        Zebra
         :INVERT        :DOWNCASE     zebra        ZEBRA
         :INVERT        :CAPITALIZE   ZEBRA        zebra
         :INVERT        :CAPITALIZE   Zebra        Zebra
         :INVERT        :CAPITALIZE   zebra        ZEBRA


File: gcl.info,  Node: Printing Strings,  Next: Printing Lists and Conses,  Prev: Examples of Effect of Readtable Case on the Lisp Printer,  Up: Default Print-Object Methods

22.1.3.12 Printing Strings
..........................

The characters of the string are output in order.

   If printer escaping is enabled,

   a double-quote is output before and after, and all double-quotes and
single escapes are preceded by backslash.  The printing of strings is
not affected by *print-array*.  Only the active elements of the string
are printed.

   For information on how the Lisp reader parses strings, see *note
Double-Quote::.


File: gcl.info,  Node: Printing Lists and Conses,  Next: Printing Bit Vectors,  Prev: Printing Strings,  Up: Default Print-Object Methods

22.1.3.13 Printing Lists and Conses
...................................

Wherever possible, list notation is preferred over dot notation.
Therefore the following algorithm is used to print a cons x:

1.
     A left-parenthesis is printed.

2.
     The car of x is printed.

3.
     If the cdr of x is itself a cons, it is made to be the current cons
     (i.e., x becomes that cons),

     a space

     is printed, and step 2 is re-entered.

4.
     If the cdr of x is not null,

     a space,

     a dot,

     a space,

     and the cdr of x are printed.

5.
     A right-parenthesis is printed.

   Actually, the above algorithm is only used when *print-pretty* is
false.  When *print-pretty* is true (or when pprint is used), additional
whitespace_1 may replace the use of a single space, and a more elaborate
algorithm with similar goals but more presentational flexibility is
used; see *note Printer Dispatching::.

   Although the two expressions below are equivalent, and the reader
accepts either one and produces the same cons, the printer always prints
such a cons in the second form.

      (a . (b . ((c . (d . nil)) . (e . nil))))
      (a b (c d) e)

   The printing of conses is affected by *print-level*, *print-length*,
and *print-circle*.

   Following are examples of printed representations of lists:

      (a . b)     ;A dotted pair of a and b
      (a.b)       ;A list of one element, the symbol named a.b
      (a. b)      ;A list of two elements a. and b
      (a .b)      ;A list of two elements a and .b
      (a b . c)   ;A dotted list of a and b with c at the end; two conses
      .iot        ;The symbol whose name is .iot
      (. b)       ;Invalid -- an error is signaled if an attempt is made to read
                  ;this syntax.
      (a .)       ;Invalid -- an error is signaled.
      (a .. b)    ;Invalid -- an error is signaled.
      (a . . b)   ;Invalid -- an error is signaled.
      (a b c ...) ;Invalid -- an error is signaled.
      (a \. b)    ;A list of three elements a, ., and b
      (a |.| b)   ;A list of three elements a, ., and b
      (a \... b)  ;A list of three elements a, ..., and b
      (a |...| b) ;A list of three elements a, ..., and b

   For information on how the Lisp reader parses lists and conses, see
*note Left-Parenthesis::.


File: gcl.info,  Node: Printing Bit Vectors,  Next: Printing Other Vectors,  Prev: Printing Lists and Conses,  Up: Default Print-Object Methods

22.1.3.14 Printing Bit Vectors
..............................

A bit vector is printed as #* followed by the bits of the bit vector in
order.  If *print-array* is false, then the bit vector is printed in a
format (using #<) that is concise but not readable.  Only the active
elements of the bit vector are printed.

   [Reviewer Note by Barrett: Need to provide for #5*0 as an alternate
notation for #*00000.]

   For information on Lisp reader parsing of bit vectors, see *note
Sharpsign Asterisk::.


File: gcl.info,  Node: Printing Other Vectors,  Next: Printing Other Arrays,  Prev: Printing Bit Vectors,  Up: Default Print-Object Methods

22.1.3.15 Printing Other Vectors
................................

If *print-array* is true and *print-readably* is false, any

   vector other than a string or bit vector is printed using
general-vector syntax; this means that information about specialized
vector representations does not appear.  The printed representation of a
zero-length vector is #().  The printed representation of a
non-zero-length vector begins with #(.  Following that, the first
element of the vector is printed.

   If there are any other elements, they are printed in turn, with each
such additional element preceded by a space if *print-pretty* is false,
or whitespace_1 if *print-pretty* is true.

   A right-parenthesis after the last element terminates the printed
representation of the vector.  The printing of vectors is affected by
*print-level* and *print-length*.  If the vector has a fill pointer,
then only those elements below the fill pointer are printed.

   If both *print-array* and *print-readably* are false,

   the vector is not printed as described above, but in a format (using
#<) that is concise but not readable.

   If *print-readably* is true, the vector prints in an
implementation-defined manner; see the variable *print-readably*.

   For information on how the Lisp reader parses these "other vectors,"
see *note Sharpsign Left-Parenthesis::.


File: gcl.info,  Node: Printing Other Arrays,  Next: Examples of Printing Arrays,  Prev: Printing Other Vectors,  Up: Default Print-Object Methods

22.1.3.16 Printing Other Arrays
...............................

If *print-array* is true and *print-readably* is false, any

   array other than a vector is printed using #nA format.  Let n be the
rank of the array.  Then # is printed, then n as a decimal integer, then
A, then n open parentheses.  Next the elements are scanned in row-major
order, using write on each element, and separating elements from each
other with whitespace_1.  The array's dimensions are numbered 0 to n-1
from left to right, and are enumerated with the rightmost index changing
fastest.  Every time the index for dimension j is incremented, the
following actions are taken:

*
     If j < n-1, then a close parenthesis is printed.

*
     If incrementing the index for dimension j caused it to equal
     dimension j, that index is reset to zero and the index for
     dimension j-1 is incremented (thereby performing these three steps
     recursively), unless j=0, in which case the entire algorithm is
     terminated.  If incrementing the index for dimension j did not
     cause it to equal dimension j, then a space is printed.

*
     If j < n-1, then an open parenthesis is printed.

   This causes the contents to be printed in a format suitable for
:initial-contents to make-array.  The lists effectively printed by this
procedure are subject to truncation by *print-level* and *print-length*.

   If the array is of a specialized type, containing bits or characters,
then the innermost lists generated by the algorithm given above can
instead be printed using bit-vector or string syntax, provided that
these innermost lists would not be subject to truncation by
*print-length*.

   If both *print-array* and *print-readably* are false,

   then the array is printed in a format (using #<) that is concise but
not readable.

   If *print-readably* is true, the array prints in an
implementation-defined manner; see the variable *print-readably*.

   In particular, this may be important for arrays having some dimension
0.

   For information on how the Lisp reader parses these "other arrays,"
see *note Sharpsign A::.


File: gcl.info,  Node: Examples of Printing Arrays,  Next: Printing Random States,  Prev: Printing Other Arrays,  Up: Default Print-Object Methods

22.1.3.17 Examples of Printing Arrays
.....................................

      (let ((a (make-array '(3 3)))
            (*print-pretty* t)
            (*print-array* t))
        (dotimes (i 3) (dotimes (j 3) (setf (aref a i j) (format nil "<~D,~D>" i j))))
        (print a)
        (print (make-array 9 :displaced-to a)))
      |>  #2A(("<0,0>" "<0,1>" "<0,2>")
      |>      ("<1,0>" "<1,1>" "<1,2>")
      |>      ("<2,0>" "<2,1>" "<2,2>"))
      |>  #("<0,0>" "<0,1>" "<0,2>" "<1,0>" "<1,1>" "<1,2>" "<2,0>" "<2,1>" "<2,2>")
     =>  #<ARRAY 9 indirect 36363476>


File: gcl.info,  Node: Printing Random States,  Next: Printing Pathnames,  Prev: Examples of Printing Arrays,  Up: Default Print-Object Methods

22.1.3.18 Printing Random States
................................

A specific syntax for printing objects of type random-state is not
specified.  However, every implementation must arrange to print a random
state object in such a way that, within the same implementation, read
can construct from the printed representation a copy of the random state
object as if the copy had been made by make-random-state.

   If the type random state is effectively implemented by using the
machinery for defstruct, the usual structure syntax can then be used for
printing random state objects; one might look something like

      #S(RANDOM-STATE :DATA #(14 49 98436589 786345 8734658324 ... ))

   where the components are implementation-dependent.


File: gcl.info,  Node: Printing Pathnames,  Next: Printing Structures,  Prev: Printing Random States,  Up: Default Print-Object Methods

22.1.3.19 Printing Pathnames
............................

When printer escaping is enabled,

   the syntax #P"..." is how a pathname is printed by write and the
other functions herein described.  The "..." is the namestring
representation of the pathname.

   When printer escaping is disabled,

   write writes a pathname P by writing (namestring P) instead.

   For information on how the Lisp reader parses pathnames, see *note
Sharpsign P::.


File: gcl.info,  Node: Printing Structures,  Next: Printing Other Objects,  Prev: Printing Pathnames,  Up: Default Print-Object Methods

22.1.3.20 Printing Structures
.............................

By default, a structure of type S is printed using #S syntax.  This
behavior can be customized by specifying a :print-function or
:print-object option to the defstruct form that defines S, or by writing
a print-object method that is specialized for objects of type S.

   Different structures might print out in different ways; the default
notation for structures is:

      #S(structure-name {slot-key slot-value}*)

   where #S indicates structure syntax, structure-name is a structure
name, each slot-key is an initialization argument name for a slot in the
structure, and each corresponding slot-value is a representation of the
object in that slot.

   For information on how the Lisp reader parses structures, see *note
Sharpsign S::.


File: gcl.info,  Node: Printing Other Objects,  Prev: Printing Structures,  Up: Default Print-Object Methods

22.1.3.21 Printing Other Objects
................................

Other objects are printed in an implementation-dependent manner.  It is
not required that an implementation print those objects readably.

   For example, hash tables, readtables, packages, streams, and
functions might not print readably.

   A common notation to use in this circumstance is #<...>.  Since #< is
not readable by the Lisp reader, the precise format of the text which
follows is not important, but a common format to use is that provided by
the print-unreadable-object macro.

   For information on how the Lisp reader treats this notation, see
*note Sharpsign Less-Than-Sign::.  For information on how to notate
objects that cannot be printed readably, see *note Sharpsign Dot::.


File: gcl.info,  Node: Examples of Printer Behavior,  Prev: Default Print-Object Methods,  Up: The Lisp Printer

22.1.4 Examples of Printer Behavior
-----------------------------------

      (let ((*print-escape* t)) (fresh-line) (write #\a))
      |>  #\a
     =>  #\a
      (let ((*print-escape* nil) (*print-readably* nil))
        (fresh-line)
        (write #\a))
      |>  a
     =>  #\a
      (progn (fresh-line) (prin1 #\a))
      |>  #\a
     =>  #\a
      (progn (fresh-line) (print #\a))
      |>
      |>  #\a
     =>  #\a
      (progn (fresh-line) (princ #\a))
      |>  a
     =>  #\a

      (dolist (val '(t nil))
        (let ((*print-escape* val) (*print-readably* val))
          (print '#\a)
          (prin1 #\a) (write-char #\Space)
          (princ #\a) (write-char #\Space)
          (write #\a)))
      |>  #\a #\a a #\a
      |>  #\a #\a a a
     =>  NIL

      (progn (fresh-line) (write '(let ((a 1) (b 2)) (+ a b))))
      |>  (LET ((A 1) (B 2)) (+ A B))
     =>  (LET ((A 1) (B 2)) (+ A B))

      (progn (fresh-line) (pprint '(let ((a 1) (b 2)) (+ a b))))
      |>  (LET ((A 1)
      |>        (B 2))
      |>    (+ A B))
     =>  (LET ((A 1) (B 2)) (+ A B))

      (progn (fresh-line)
             (write '(let ((a 1) (b 2)) (+ a b)) :pretty t))
      |>  (LET ((A 1)
      |>        (B 2))
      |>    (+ A B))
     =>  (LET ((A 1) (B 2)) (+ A B))

      (with-output-to-string (s)
         (write 'write :stream s)
         (prin1 'prin1 s))
     =>  "WRITEPRIN1"


File: gcl.info,  Node: The Lisp Pretty Printer,  Next: Formatted Output,  Prev: The Lisp Printer,  Up: Printer

22.2 The Lisp Pretty Printer
============================

* Menu:

* Pretty Printer Concepts::
* Examples of using the Pretty Printer::
* Notes about the Pretty Printer`s Background::


File: gcl.info,  Node: Pretty Printer Concepts,  Next: Examples of using the Pretty Printer,  Prev: The Lisp Pretty Printer,  Up: The Lisp Pretty Printer

22.2.1 Pretty Printer Concepts
------------------------------

The facilities provided by the pretty printer permit programs to
redefine the way in which code is displayed, and allow the full power of
pretty printing to be applied to complex combinations of data
structures.

   Whether any given style of output is in fact "pretty" is inherently a
somewhat subjective issue.  However, since the effect of the pretty
printer can be customized by conforming programs, the necessary
flexibility is provided for individual programs to achieve an arbitrary
degree of aesthetic control.

   By providing direct access to the mechanisms within the pretty
printer that make dynamic decisions about layout, the macros and
functions pprint-logical-block, pprint-newline, and pprint-indent make
it possible to specify pretty printing layout rules as a part of any
function that produces output.  They also make it very easy for the
detection of circularity and sharing, and abbreviation based on length
and nesting depth to be supported by the function.

   The pretty printer is driven entirely by dispatch based on the value
of *print-pprint-dispatch*.  The function set-pprint-dispatch makes it
possible for conforming programs to associate new pretty printing
functions with a type.

* Menu:

* Dynamic Control of the Arrangement of Output::
* Format Directive Interface::
* Compiling Format Strings::
* Pretty Print Dispatch Tables::
* Pretty Printer Margins::


File: gcl.info,  Node: Dynamic Control of the Arrangement of Output,  Next: Format Directive Interface,  Prev: Pretty Printer Concepts,  Up: Pretty Printer Concepts

22.2.1.1 Dynamic Control of the Arrangement of Output
.....................................................

The actions of the pretty printer when a piece of output is too large to
fit in the space available can be precisely controlled.  Three concepts
underlie the way these operations work--logical blocks , conditional
newlines , and sections .  Before proceeding further, it is important to
define these terms.

   The first line of Figure 22-3 shows a schematic piece of output.
Each of the characters in the output is represented by "-".  The
positions of conditional newlines are indicated by digits.  The
beginnings and ends of logical blocks are indicated by "<" and ">"
respectively.

   The output as a whole is a logical block and the outermost section.
This section is indicated by the 0's on the second line of Figure 1.
Logical blocks nested within the output are specified by the macro
pprint-logical-block.  Conditional newline positions are specified by
calls to pprint-newline.  Each conditional newline defines two sections
(one before it and one after it) and is associated with a third (the
section immediately containing it).

   The section after a conditional newline consists of: all the output
up to, but not including, (a) the next conditional newline immediately
contained in the same logical block; or if (a) is not applicable, (b)
the next newline that is at a lesser level of nesting in logical blocks;
or if (b) is not applicable, (c) the end of the output.

   The section before a conditional newline consists of: all the output
back to, but not including, (a) the previous conditional newline that is
immediately contained in the same logical block; or if (a) is not
applicable, (b) the beginning of the immediately containing logical
block.  The last four lines in Figure 1 indicate the sections before and
after the four conditional newlines.

   The section immediately containing a conditional newline is the
shortest section that contains the conditional newline in question.  In
Figure 22-3, the first conditional newline is immediately contained in
the section marked with 0's, the second and third conditional newlines
are immediately contained in the section before the fourth conditional
newline, and the fourth conditional newline is immediately contained in
the section after the first conditional newline.

      <-1---<--<--2---3->--4-->->
      000000000000000000000000000
      11 111111111111111111111111
                22 222
                   333 3333
             44444444444444 44444

     Figure 22-2: Example of Logical Blocks, Conditional Newlines, and Sections

   Whenever possible, the pretty printer displays the entire contents of
a section on a single line.  However, if the section is too long to fit
in the space available, line breaks are inserted at conditional newline
positions within the section.


File: gcl.info,  Node: Format Directive Interface,  Next: Compiling Format Strings,  Prev: Dynamic Control of the Arrangement of Output,  Up: Pretty Printer Concepts

22.2.1.2 Format Directive Interface
...................................

The primary interface to operations for dynamically determining the
arrangement of output is provided through the functions and macros of
the pretty printer.  Figure 22-3 shows the defined names related to
pretty printing.

  *print-lines*            pprint-dispatch                pprint-pop           
  *print-miser-width*      pprint-exit-if-list-exhausted  pprint-tab           
  *print-pprint-dispatch*  pprint-fill                    pprint-tabular       
  *print-right-margin*     pprint-indent                  set-pprint-dispatch  
  copy-pprint-dispatch     pprint-linear                  write                
  format                   pprint-logical-block                                
  formatter                pprint-newline                                      

             Figure 22-3: Defined names related to pretty printing.           


   Figure 22-4 identifies a set of format directives which serve as an
alternate interface to the same pretty printing operations in a more
textually compact form.

  ~I   ~W      ~<...~:>  
  ~:T  ~/.../  ~_        

  Figure 22-4: Format directives related to Pretty Printing



File: gcl.info,  Node: Compiling Format Strings,  Next: Pretty Print Dispatch Tables,  Prev: Format Directive Interface,  Up: Pretty Printer Concepts

22.2.1.3 Compiling Format Strings
.................................

A format string is essentially a program in a special-purpose language
that performs printing, and that is interpreted by the function format.
The formatter macro provides the efficiency of using a compiled function
to do that same printing but without losing the textual compactness of
format strings.

   A format control is either a format string or a function that was
returned by the the formatter macro.


File: gcl.info,  Node: Pretty Print Dispatch Tables,  Next: Pretty Printer Margins,  Prev: Compiling Format Strings,  Up: Pretty Printer Concepts

22.2.1.4 Pretty Print Dispatch Tables
.....................................

A pprint dispatch table is a mapping from keys to pairs of values.  Each
key is a type specifier.  The values associated with a key are a
"function" (specifically, a function designator or nil) and a "numerical
priority" (specifically, a real).  Basic insertion and retrieval is done
based on the keys with the equality of keys being tested by equal.

   When *print-pretty* is true, the current pprint dispatch table (in
*print-pprint-dispatch*) controls how objects are printed.  The
information in this table takes precedence over all other mechanisms for
specifying how to print objects.  In particular, it has priority over
user-defined print-object methods

   because the current pprint dispatch table is consulted first.

   The function is chosen from the current pprint dispatch table by
finding the highest priority function that is associated with a type
specifier that matches the object; if there is more than one such
function, it is implementation-dependent which is used.

   However, if there is no information in the table about how to pretty
print a particular kind of object, a function is invoked which uses
print-object to print the object.  The value of *print-pretty* is still
true when this function is called, and individual methods for
print-object might still elect to produce output in a special format
conditional on the value of *print-pretty*.


File: gcl.info,  Node: Pretty Printer Margins,  Prev: Pretty Print Dispatch Tables,  Up: Pretty Printer Concepts

22.2.1.5 Pretty Printer Margins
...............................

A primary goal of pretty printing is to keep the output between a pair
of margins.  The column where the output begins is taken as the left
margin.  If the current column cannot be determined at the time output
begins, the left margin is assumed to be zero.  The right margin is
controlled by *print-right-margin*.


File: gcl.info,  Node: Examples of using the Pretty Printer,  Next: Notes about the Pretty Printer`s Background,  Prev: Pretty Printer Concepts,  Up: The Lisp Pretty Printer

22.2.2 Examples of using the Pretty Printer
-------------------------------------------

As an example of the interaction of logical blocks, conditional
newlines, and indentation, consider the function simple-pprint-defun
below.  This function prints out lists whose cars are defun in the
standard way assuming that the list has exactly length 4.

     (defun simple-pprint-defun (*standard-output* list)
       (pprint-logical-block (*standard-output* list :prefix "(" :suffix ")")
         (write (first list))
         (write-char #\Space)
         (pprint-newline :miser)
         (pprint-indent :current 0)
         (write (second list))
         (write-char #\Space)
         (pprint-newline :fill)
         (write (third list))
         (pprint-indent :block 1)
         (write-char #\Space)
         (pprint-newline :linear)
         (write (fourth list))))

   Suppose that one evaluates the following:

     (simple-pprint-defun *standard-output* '(defun prod (x y) (* x y)))

   If the line width available is greater than or equal to 26, then all
of the output appears on one line.  If the line width available is
reduced to 25, a line break is inserted at the linear-style conditional
newline

   before the expression (* x y), producing the output shown.  The
(pprint-indent :block 1) causes (* x y) to be printed at a relative
indentation of 1 in the logical block.

      (DEFUN PROD (X Y)
        (* X Y))

   If the line width available is 15, a line break is also inserted at
the fill style conditional newline before the argument list.  The call
on (pprint-indent :current 0) causes the argument list to line up under
the function name.

     (DEFUN PROD
            (X Y)
       (* X Y))

   If *print-miser-width* were greater than or equal to 14, the example
output above would have been as follows, because all indentation changes
are ignored in miser mode and line breaks are inserted at miser-style
conditional newlines.

      (DEFUN
       PROD
       (X Y)
       (* X Y))

   As an example of a per-line prefix, consider that evaluating the
following produces the output shown with a line width of 20 and
*print-miser-width* of nil.

      (pprint-logical-block (*standard-output* nil :per-line-prefix ";;; ")
        (simple-pprint-defun *standard-output* '(defun prod (x y) (* x y))))

      ;;; (DEFUN PROD
      ;;;        (X Y)
      ;;;   (* X Y))

   As a more complex (and realistic) example, consider the function
pprint-let below.  This specifies how to print a let form in the
traditional style.  It is more complex than the example above, because
it has to deal with nested structure.  Also, unlike the example above it
contains complete code to readably print any possible list that begins
with the symbol let.  The outermost pprint-logical-block form handles
the printing of the input list as a whole and specifies that parentheses
should be printed in the output.  The second pprint-logical-block form
handles the list of binding pairs.  Each pair in the list is itself
printed by the innermost pprint-logical-block.  (A loop form is used
instead of merely decomposing the pair into two objects so that readable
output will be produced no matter whether the list corresponding to the
pair has one element, two elements, or (being malformed) has more than
two elements.)  A space and a fill-style conditional newline

   are placed after each pair except the last.  The loop at the end of
the topmost pprint-logical-block form prints out the forms in the body
of the let form separated by spaces and linear-style conditional
newlines.

      (defun pprint-let (*standard-output* list)
        (pprint-logical-block (nil list :prefix "(" :suffix ")")
          (write (pprint-pop))
          (pprint-exit-if-list-exhausted)
          (write-char #\Space)
          (pprint-logical-block (nil (pprint-pop) :prefix "(" :suffix ")")
            (pprint-exit-if-list-exhausted)
            (loop (pprint-logical-block (nil (pprint-pop) :prefix "(" :suffix ")")
                    (pprint-exit-if-list-exhausted)
                    (loop (write (pprint-pop))
                          (pprint-exit-if-list-exhausted)
                          (write-char #\Space)
                          (pprint-newline :linear)))
                  (pprint-exit-if-list-exhausted)
                  (write-char #\Space)
                  (pprint-newline :fill)))
          (pprint-indent :block 1)
          (loop (pprint-exit-if-list-exhausted)
                (write-char #\Space)
                (pprint-newline :linear)
                (write (pprint-pop)))))

   Suppose that one evaluates the following with *print-level* being 4,
and *print-circle* being true.

      (pprint-let *standard-output*
                  '#1=(let (x (*print-length* (f (g 3)))
                            (z . 2) (k (car y)))
                        (setq x (sqrt z)) #1#))

   If the line length is greater than or equal to 77, the output
produced appears on one line.  However, if the line length is 76, line
breaks are inserted at the linear-style conditional newlines separating
the forms in the body and the output below is produced.  Note that, the
degenerate binding pair x is printed readably even though it fails to be
a list; a depth abbreviation marker is printed in place of (g 3); the
binding pair (z . 2) is printed readably even though it is not a proper
list; and appropriate circularity markers are printed.

      #1=(LET (X (*PRINT-LENGTH* (F #)) (Z . 2) (K (CAR Y)))
           (SETQ X (SQRT Z))
           #1#)

   If the line length is reduced to 35, a line break is inserted at one
of the fill-style conditional newlines separating the binding pairs.

      #1=(LET (X (*PRINT-PRETTY* (F #))
               (Z . 2) (K (CAR Y)))
           (SETQ X (SQRT Z))
           #1#)

   Suppose that the line length is further reduced to 22 and
*print-length* is set to 3.  In this situation, line breaks are inserted
after both the first and second binding pairs.  In addition, the second
binding pair is itself broken across two lines.  Clause (b) of the
description of fill-style conditional newlines (see the function
pprint-newline) prevents the binding pair (z . 2) from being printed at
the end of the third line.  Note that the length abbreviation hides the
circularity from view and therefore the printing of circularity markers
disappears.

      (LET (X
            (*PRINT-LENGTH*
             (F #))
            (Z . 2) ...)
        (SETQ X (SQRT Z))
        ...)

   The next function prints a vector using "#(...)" notation.

     (defun pprint-vector (*standard-output* v)
       (pprint-logical-block (nil nil :prefix "#(" :suffix ")")
         (let ((end (length v)) (i 0))
           (when (plusp end)
             (loop (pprint-pop)
                   (write (aref v i))
                   (if (= (incf i) end) (return nil))
                   (write-char #\Space)
                   (pprint-newline :fill))))))

   Evaluating the following with a line length of 15 produces the output
shown.

      (pprint-vector *standard-output* '#(12 34 567 8 9012 34 567 89 0 1 23))

      #(12 34 567 8
        9012 34 567
        89 0 1 23)

   As examples of the convenience of specifying pretty printing with
format strings, consider that the functions simple-pprint-defun and
pprint-let used as examples above can be compactly defined as follows.
(The function pprint-vector cannot be defined using format because the
data structure it traverses is not a list.)

     (defun simple-pprint-defun (*standard-output* list)
       (format T "~:<~W ~@_~:I~W ~:_~W~1I ~_~W~:>" list))

     (defun pprint-let (*standard-output* list)
       (format T "~:<~W~^~:<~@{~:<~@{~W~^~_~}~:>~^~:_~}~:>~1I~@{~^~_~W~}~:>" list))

   In the following example, the first form restores
*print-pprint-dispatch* to the equivalent of its initial value.  The
next two forms then set up a special way to pretty print ratios.  Note
that the more specific type specifier has to be associated with a higher
priority.

      (setq *print-pprint-dispatch* (copy-pprint-dispatch nil))

      (set-pprint-dispatch 'ratio
        #'(lambda (s obj)
            (format s "#.(/ ~W ~W)"
                      (numerator obj) (denominator obj))))

      (set-pprint-dispatch '(and ratio (satisfies minusp))
        #'(lambda (s obj)
            (format s "#.(- (/ ~W ~W))"
                    (- (numerator obj)) (denominator obj)))
        5)

      (pprint '(1/3 -2/3))
      (#.(/ 1 3) #.(- (/ 2 3)))

   The following two forms illustrate the definition of pretty printing
functions for types of code.  The first form illustrates how to specify
the traditional method for printing quoted objects using single-quote.
Note the care taken to ensure that data lists that happen to begin with
quote will be printed readably.  The second form specifies that lists
beginning with the symbol my-let should print the same way that lists
beginning with let print when the initial pprint dispatch table is in
effect.

      (set-pprint-dispatch '(cons (member quote)) ()
        #'(lambda (s list)
            (if (and (consp (cdr list)) (null (cddr list)))
               (funcall (formatter "'~W") s (cadr list))
               (pprint-fill s list))))

      (set-pprint-dispatch '(cons (member my-let))
                           (pprint-dispatch '(let) nil))

   The next example specifies a default method for printing lists that
do not correspond to function calls.  Note that the functions
pprint-linear, pprint-fill, and pprint-tabular are all defined with
optional colon-p and at-sign-p arguments so that they can be used as
pprint dispatch functions as well as ~/.../ functions.

      (set-pprint-dispatch '(cons (not (and symbol (satisfies fboundp))))
                           #'pprint-fill -5)

      ;; Assume a line length of 9
      (pprint '(0 b c d e f g h i j k))
      (0 b c d
       e f g h
       i j k)

   This final example shows how to define a pretty printing function for
a user defined data structure.

      (defstruct family mom kids)

      (set-pprint-dispatch 'family
        #'(lambda (s f)
            (funcall (formatter "~@<#<~;~W and ~2I~_~/pprint-fill/~;>~:>")
                    s (family-mom f) (family-kids f))))

   The pretty printing function for the structure family specifies how
to adjust the layout of the output so that it can fit aesthetically into
a variety of line widths.  In addition, it obeys the printer control
variables *print-level*, *print-length*, *print-lines*, *print-circle*
and *print-escape*, and can tolerate several different kinds of
malformity in the data structure.  The output below shows what is
printed out with a right margin of 25, *print-pretty* being true,
*print-escape* being false, and a malformed kids list.

      (write (list 'principal-family
                   (make-family :mom "Lucy"
                                :kids '("Mark" "Bob" . "Dan")))
             :right-margin 25 :pretty T :escape nil :miser-width nil)
      (PRINCIPAL-FAMILY
       #<Lucy and
           Mark Bob . Dan>)

   Note that a pretty printing function for a structure is different
from the structure's print-object method.  While print-object methods
are permanently associated with a structure, pretty printing functions
are stored in pprint dispatch tables and can be rapidly changed to
reflect different printing needs.  If there is no pretty printing
function for a structure in the current pprint dispatch table, its
print-object method is used instead.


File: gcl.info,  Node: Notes about the Pretty Printer`s Background,  Prev: Examples of using the Pretty Printer,  Up: The Lisp Pretty Printer

22.2.3 Notes about the Pretty Printer's Background
--------------------------------------------------

For a background reference to the abstract concepts detailed in this
section, see XP: A Common Lisp Pretty Printing System.  The details of
that paper are not binding on this document, but may be helpful in
establishing a conceptual basis for understanding this material.


File: gcl.info,  Node: Formatted Output,  Next: Printer Dictionary,  Prev: The Lisp Pretty Printer,  Up: Printer

22.3 Formatted Output
=====================

[Editorial Note by KMP: This is transplanted from FORMAT and will need a
bit of work before it looks good standing alone.  Bear with me.]

   format is useful for producing nicely formatted text, producing
good-looking messages, and so on.  format can generate and return a
string or output to destination.

   The control-string argument to format is actually a format control.
That is, it can be either a format string or a function, for example a
function returned by the formatter macro.

   If it is a function, the function is called with the appropriate
output stream as its first argument and the data arguments to format as
its remaining arguments.  The function should perform whatever output is
necessary and return the unused tail of the arguments (if any).

   The compilation process performed by formatter produces a function
that would do with its arguments as the format interpreter would do with
those arguments.

   The remainder of this section describes what happens if the
control-string is a format string.

   Control-string is composed of simple text (characters) and embedded
directives.

   format writes the simple text as is; each embedded directive
specifies further text output that is to appear at the corresponding
point within the simple text.  Most directives use one or more elements
of args to create their output.

   A directive consists of a tilde, optional prefix parameters separated
by commas, optional colon and at-sign modifiers, and a single character
indicating what kind of directive this is.

   There is no required ordering between the at-sign and colon modifier.

   The case of the directive character is ignored.  Prefix parameters
are notated as signed (sign is optional) decimal numbers, or as a
single-quote followed by a character.  For example, ~5,'0d can be used
to print an integer in decimal radix in five columns with leading zeros,
or ~5,'*d to get leading asterisks.

   In place of a prefix parameter to a directive, V (or v) can be used.
In this case, format takes an argument from args as a parameter to the
directive.  The argument should be an integer or character.  If the arg
used by a V parameter is nil, the effect is as if the parameter had been
omitted.  # can be used in place of a prefix parameter; it represents
the number of args remaining to be processed.  When used within a
recursive format, in the context of ~? or ~{, the # prefix parameter
represents the number of format arguments remaining within the recursive
call.

   Examples of format strings:

  "~S"        ;This is an S directive with no parameters or modifiers.  
  "~3,-4:@s"  ;This is an S directive with two parameters, 3 and -4,    
              ; and both the colon and at-sign flags.                   
  "~,+4S"     ;Here the first prefix parameter is omitted and takes     
              ; on its default value, while the second parameter is 4.  

             Figure 22-5: Examples of format control strings           


   format sends the output to destination.  If destination is nil,
format creates and returns a string containing the output from
control-string.  If destination is non-nil, it must be a string with a
fill pointer, a stream, or the symbol t.  If destination is a string
with a fill pointer, the output is added to the end of the string.  If
destination is a stream, the output is sent to that stream.  If
destination is t, the output is sent to standard output.

   In the description of the directives that follows, the term arg in
general refers to the next item of the set of args to be processed.  The
word or phrase at the beginning of each description is a mnemonic for
the directive.

   format directives do not bind any of the printer control variables
(*print-...*) except as specified in the following descriptions.
Implementations may specify the binding of new, implementation-specific
printer control variables for each format directive, but they may
neither bind any standard printer control variables not specified in
description of a format directive nor fail to bind any standard printer
control variables as specified in the description.

* Menu:

* FORMAT Basic Output::
* FORMAT Radix Control::
* FORMAT Floating-Point Printers::
* FORMAT Printer Operations::
* FORMAT Pretty Printer Operations::
* FORMAT Layout Control::
* FORMAT Control-Flow Operations::
* FORMAT Miscellaneous Operations::
* FORMAT Miscellaneous Pseudo-Operations::
* Additional Information about FORMAT Operations::
* Examples of FORMAT::
* Notes about FORMAT::


File: gcl.info,  Node: FORMAT Basic Output,  Next: FORMAT Radix Control,  Prev: Formatted Output,  Up: Formatted Output

22.3.1 FORMAT Basic Output
--------------------------

* Menu:

* Tilde C-> Character::
* Tilde Percent-> Newline::
* Tilde Ampersand-> Fresh-Line::
* Tilde Vertical-Bar-> Page::
* Tilde Tilde-> Tilde::


File: gcl.info,  Node: Tilde C-> Character,  Next: Tilde Percent-> Newline,  Prev: FORMAT Basic Output,  Up: FORMAT Basic Output

22.3.1.1 Tilde C: Character
...........................

The next arg should be a character; it is printed according to the
modifier flags.

   ~C prints the character as if by using write-char if it is a simple
character.  Characters that are not simple are not necessarily printed
as if by write-char, but are displayed in an implementation-defined,
abbreviated format.  For example,

      (format nil "~C" #\A) =>  "A"
      (format nil "~C" #\Space) =>  " "

   ~:C is the same as ~C for printing characters, but other characters
are "spelled out."  The intent is that this is a "pretty" format for
printing characters.  For simple characters that are not printing, what
is spelled out is the name of the character (see char-name).  For
characters that are not simple and not printing, what is spelled out is
implementation-defined.  For example,

      (format nil "~:C" #\A) =>  "A"
      (format nil "~:C" #\Space) =>  "Space"
     ;; This next example assumes an implementation-defined "Control" attribute.
      (format nil "~:C" #\Control-Space)
     =>  "Control-Space"
     OR=> "c-Space"

   ~:@C prints what ~:C would, and then if the character requires
unusual shift keys on the keyboard to type it, this fact is mentioned.
For example,

      (format nil "~:@C" #\Control-Partial) =>  "Control-\partial (Top-F)"

   This is the format used for telling the user about a key he is
expected to type, in prompts, for instance.  The precise output may
depend not only on the implementation, but on the particular I/O devices
in use.

   ~@C prints the character in a way that the Lisp reader can
understand, using #\ syntax.

   ~@C binds *print-escape* to t.


File: gcl.info,  Node: Tilde Percent-> Newline,  Next: Tilde Ampersand-> Fresh-Line,  Prev: Tilde C-> Character,  Up: FORMAT Basic Output

22.3.1.2 Tilde Percent: Newline
...............................

This outputs a #\Newline character, thereby terminating the current
output line and beginning a new one.  ~n% outputs n newlines.  No arg is
used.


File: gcl.info,  Node: Tilde Ampersand-> Fresh-Line,  Next: Tilde Vertical-Bar-> Page,  Prev: Tilde Percent-> Newline,  Up: FORMAT Basic Output

22.3.1.3 Tilde Ampersand: Fresh-Line
....................................

Unless it can be determined that the output stream is already at the
beginning of a line, this outputs a newline.  ~n& calls fresh-line and
then outputs n- 1 newlines.  ~0& does nothing.


File: gcl.info,  Node: Tilde Vertical-Bar-> Page,  Next: Tilde Tilde-> Tilde,  Prev: Tilde Ampersand-> Fresh-Line,  Up: FORMAT Basic Output

22.3.1.4 Tilde Vertical-Bar: Page
.................................

This outputs a page separator character, if possible.  ~n| does this n
times.


File: gcl.info,  Node: Tilde Tilde-> Tilde,  Prev: Tilde Vertical-Bar-> Page,  Up: FORMAT Basic Output

22.3.1.5 Tilde Tilde: Tilde
...........................

This outputs a tilde.  ~n~ outputs n tildes.


File: gcl.info,  Node: FORMAT Radix Control,  Next: FORMAT Floating-Point Printers,  Prev: FORMAT Basic Output,  Up: Formatted Output

22.3.2 FORMAT Radix Control
---------------------------

* Menu:

* Tilde R-> Radix::
* Tilde D-> Decimal::
* Tilde B-> Binary::
* Tilde O-> Octal::
* Tilde X-> Hexadecimal::


File: gcl.info,  Node: Tilde R-> Radix,  Next: Tilde D-> Decimal,  Prev: FORMAT Radix Control,  Up: FORMAT Radix Control

22.3.2.1 Tilde R: Radix
.......................

~nR prints arg in radix n.  The modifier flags and any remaining
parameters are used as for the ~D directive.  ~D is the same as ~10R.
The full form is ~radix,mincol,padchar,commachar,comma-intervalR.

   If no prefix parameters are given to ~R, then a different
interpretation is given.  The argument should be an integer.  For
example, if arg is 4:

*
     ~R prints arg as a cardinal English number: four.

*
     ~:R prints arg as an ordinal English number: fourth.

*
     ~@R prints arg as a Roman numeral: IV.

*
     ~:@R prints arg as an old Roman numeral: IIII.

   For example:

      (format nil "~,,' ,4:B" 13) =>  "1101"
      (format nil "~,,' ,4:B" 17) =>  "1 0001"
      (format nil "~19,0,' ,4:B" 3333) =>  "0000 1101 0000 0101"
      (format nil "~3,,,' ,2:R" 17) =>  "1 22"
      (format nil "~,,'|,2:D" #xFFFF) =>   "6|55|35"

   If and only if the first parameter, n, is supplied, ~R binds
*print-escape* to false, *print-radix* to false, *print-base* to n,

   and *print-readably* to false.

   If and only if no parameters are supplied, ~R binds *print-base* to
10.


File: gcl.info,  Node: Tilde D-> Decimal,  Next: Tilde B-> Binary,  Prev: Tilde R-> Radix,  Up: FORMAT Radix Control

22.3.2.2 Tilde D: Decimal
.........................

An arg, which should be an integer, is printed in decimal radix.  ~D
will never put a decimal point after the number.

   ~mincolD uses a column width of mincol; spaces are inserted on the
left if the number requires fewer than mincol columns for its digits and
sign.  If the number doesn't fit in mincol columns, additional columns
are used as needed.

   ~mincol,padcharD uses padchar as the pad character instead of space.

   If arg is not an integer, it is printed in ~A format and decimal
base.

   The @ modifier causes the number's sign to be printed always; the
default is to print it only if the number is negative.

   The : modifier causes commas to be printed between groups of digits;
commachar may be used to change the character used as the comma.
comma-interval must be an integer and defaults to 3.  When the :
modifier is given to any of these directives, the commachar is printed
between groups of comma-interval digits.

   Thus the most general form of ~D is
~mincol,padchar,commachar,comma-intervalD.

   ~D binds *print-escape* to false, *print-radix* to false,
*print-base* to 10,

   and *print-readably* to false.


File: gcl.info,  Node: Tilde B-> Binary,  Next: Tilde O-> Octal,  Prev: Tilde D-> Decimal,  Up: FORMAT Radix Control

22.3.2.3 Tilde B: Binary
........................

This is just like ~D but prints in binary radix (radix 2) instead of
decimal.  The full form is therefore
~mincol,padchar,commachar,comma-intervalB.

   ~B binds *print-escape* to false, *print-radix* to false,
*print-base* to 2,

   and *print-readably* to false.


File: gcl.info,  Node: Tilde O-> Octal,  Next: Tilde X-> Hexadecimal,  Prev: Tilde B-> Binary,  Up: FORMAT Radix Control

22.3.2.4 Tilde O: Octal
.......................

This is just like ~D but prints in octal radix (radix 8) instead of
decimal.  The full form is therefore
~mincol,padchar,commachar,comma-intervalO.

   ~O binds *print-escape* to false, *print-radix* to false,
*print-base* to 8,

   and *print-readably* to false.


File: gcl.info,  Node: Tilde X-> Hexadecimal,  Prev: Tilde O-> Octal,  Up: FORMAT Radix Control

22.3.2.5 Tilde X: Hexadecimal
.............................

This is just like ~D but prints in hexadecimal radix (radix 16) instead
of decimal.  The full form is therefore
~mincol,padchar,commachar,comma-intervalX.

   ~X binds *print-escape* to false, *print-radix* to false,
*print-base* to 16,

   and *print-readably* to false.


File: gcl.info,  Node: FORMAT Floating-Point Printers,  Next: FORMAT Printer Operations,  Prev: FORMAT Radix Control,  Up: Formatted Output

22.3.3 FORMAT Floating-Point Printers
-------------------------------------

* Menu:

* Tilde F-> Fixed-Format Floating-Point::
* Tilde E-> Exponential Floating-Point::
* Tilde G-> General Floating-Point::
* Tilde Dollarsign-> Monetary Floating-Point::


File: gcl.info,  Node: Tilde F-> Fixed-Format Floating-Point,  Next: Tilde E-> Exponential Floating-Point,  Prev: FORMAT Floating-Point Printers,  Up: FORMAT Floating-Point Printers

22.3.3.1 Tilde F: Fixed-Format Floating-Point
.............................................

The next arg is printed as a float.

   The full form is ~w,d,k,overflowchar,padcharF.  The parameter w is
the width of the field to be printed; d is the number of digits to print
after the decimal point; k is a scale factor that defaults to zero.

   Exactly w characters will be output.  First, leading copies of the
character padchar (which defaults to a space) are printed, if necessary,
to pad the field on the left.  If the arg is negative, then a minus sign
is printed; if the arg is not negative, then a plus sign is printed if
and only if the @ modifier was supplied.  Then a sequence of digits,
containing a single embedded decimal point, is printed; this represents
the magnitude of the value of arg times 10^k, rounded to d fractional
digits.  When rounding up and rounding down would produce printed values
equidistant from the scaled value of arg, then the implementation is
free to use either one.  For example, printing the argument 6.375 using
the format ~4,2F may correctly produce either 6.37 or 6.38.  Leading
zeros are not permitted, except that a single zero digit is output
before the decimal point if the printed value is less than one, and this
single zero digit is not output at all if w=d+1.

   If it is impossible to print the value in the required format in a
field of width w, then one of two actions is taken.  If the parameter
overflowchar is supplied, then w copies of that parameter are printed
instead of the scaled value of arg.  If the overflowchar parameter is
omitted, then the scaled value is printed using more than w characters,
as many more as may be needed.

   If the w parameter is omitted, then the field is of variable width.
In effect, a value is chosen for w in such a way that no leading pad
characters need to be printed and exactly d characters will follow the
decimal point.  For example, the directive ~,2F will print exactly two
digits after the decimal point and as many as necessary before the
decimal point.

   If the parameter d is omitted, then there is no constraint on the
number of digits to appear after the decimal point.  A value is chosen
for d in such a way that as many digits as possible may be printed
subject to the width constraint imposed by the parameter w and the
constraint that no trailing zero digits may appear in the fraction,
except that if the fraction to be printed is zero, then a single zero
digit should appear after the decimal point if permitted by the width
constraint.

   If both w and d are omitted, then the effect is to print the value
using ordinary free-format output; prin1 uses this format for any number
whose magnitude is either zero or between 10^-3 (inclusive) and 10^7
(exclusive).

   If w is omitted, then if the magnitude of arg is so large (or, if d
is also omitted, so small) that more than 100 digits would have to be
printed, then an implementation is free, at its discretion, to print the
number using exponential notation instead, as if by the directive ~E
(with all parameters to ~E defaulted, not taking their values from the
~F directive).

   If arg is a rational number, then it is coerced to be a single float
and then printed.  Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids loss of precision or overflow because of the
coercion.  If w and d are not supplied and the number has no exact
decimal representation, for example 1/3, some precision cutoff must be
chosen by the implementation since only a finite number of digits may be
printed.

   If arg is a complex number or some non-numeric object, then it is
printed using the format directive ~wD, thereby printing it in decimal
radix and a minimum field width of w.

   ~F binds *print-escape* to false

   and *print-readably* to false.


File: gcl.info,  Node: Tilde E-> Exponential Floating-Point,  Next: Tilde G-> General Floating-Point,  Prev: Tilde F-> Fixed-Format Floating-Point,  Up: FORMAT Floating-Point Printers

22.3.3.2 Tilde E: Exponential Floating-Point
............................................

The next arg is printed as a float in exponential notation.

   The full form is ~w,d,e,k,overflowchar,padchar,exponentcharE.  The
parameter w is the width of the field to be printed; d is the number of
digits to print after the decimal point; e is the number of digits to
use when printing the exponent; k is a scale factor that defaults to one
(not zero).

   Exactly w characters will be output.  First, leading copies of the
character padchar (which defaults to a space) are printed, if necessary,
to pad the field on the left.  If the arg is negative, then a minus sign
is printed; if the arg is not negative, then a plus sign is printed if
and only if the @ modifier was supplied.  Then a sequence of digits
containing a single embedded decimal point is printed.  The form of this
sequence of digits depends on the scale factor k.  If k is zero, then d
digits are printed after the decimal point, and a single zero digit
appears before the decimal point if the total field width will permit
it.  If k is positive, then it must be strictly less than d+2; k
significant digits are printed before the decimal point, and d- k+1
digits are printed after the decimal point.  If k is negative, then it
must be strictly greater than - d; a single zero digit appears before
the decimal point if the total field width will permit it, and after the
decimal point are printed first - k zeros and then d+k significant
digits.  The printed fraction must be properly rounded.  When rounding
up and rounding down would produce printed values equidistant from the
scaled value of arg, then the implementation is free to use either one.
For example, printing the argument 637.5 using the format ~8,2E may
correctly produce either 6.37E+2 or 6.38E+2.

   Following the digit sequence, the exponent is printed.  First the
character parameter exponentchar is printed; if this parameter is
omitted, then the exponent marker that prin1 would use is printed, as
determined from the type of the float and the current value of
*read-default-float-format*.  Next, either a plus sign or a minus sign
is printed, followed by e digits representing the power of ten by which
the printed fraction must be multiplied to properly represent the
rounded value of arg.

   If it is impossible to print the value in the required format in a
field of width w, possibly because k is too large or too small or
because the exponent cannot be printed in e character positions, then
one of two actions is taken.  If the parameter overflowchar is supplied,
then w copies of that parameter are printed instead of the scaled value
of arg.  If the overflowchar parameter is omitted, then the scaled value
is printed using more than w characters, as many more as may be needed;
if the problem is that d is too small for the supplied k or that e is
too small, then a larger value is used for d or e as may be needed.

   If the w parameter is omitted, then the field is of variable width.
In effect a value is chosen for w in such a way that no leading pad
characters need to be printed.

   If the parameter d is omitted, then there is no constraint on the
number of digits to appear.  A value is chosen for d in such a way that
as many digits as possible may be printed subject to the width
constraint imposed by the parameter w, the constraint of the scale
factor k, and the constraint that no trailing zero digits may appear in
the fraction, except that if the fraction to be printed is zero then a
single zero digit should appear after the decimal point.

   If the parameter e is omitted, then the exponent is printed using the
smallest number of digits necessary to represent its value.

   If all of w, d, and e are omitted, then the effect is to print the
value using ordinary free-format exponential-notation output; prin1 uses

   a similar

   format for any non-zero number whose magnitude is less than 10^-3 or
greater than or equal to 10^7.

   The only difference is that the ~E directive always prints a plus or
minus sign in front of the exponent, while prin1 omits the plus sign if
the exponent is non-negative.

   If arg is a rational number, then it is coerced to be a single float
and then printed.  Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids loss of precision or overflow because of the
coercion.  If w and d are unsupplied and the number has no exact decimal
representation, for example 1/3, some precision cutoff must be chosen by
the implementation since only a finite number of digits may be printed.

   If arg is a complex number or some non-numeric object, then it is
printed using the format directive ~wD, thereby printing it in decimal
radix and a minimum field width of w.

   ~E binds *print-escape* to false

   and *print-readably* to false.


File: gcl.info,  Node: Tilde G-> General Floating-Point,  Next: Tilde Dollarsign-> Monetary Floating-Point,  Prev: Tilde E-> Exponential Floating-Point,  Up: FORMAT Floating-Point Printers

22.3.3.3 Tilde G: General Floating-Point
........................................

The next arg is printed as a float in either fixed-format or exponential
notation as appropriate.

   The full form is ~w,d,e,k,overflowchar,padchar,exponentcharG.  The
format in which to print arg depends on the magnitude (absolute value)
of the arg.  Let n be an integer such that 10^n-1 \le |arg| < 10^n.  Let
ee equal e+2, or 4 if e is omitted.  Let ww equal w- ee, or nil if w is
omitted.  If d is omitted, first let q be the number of digits needed to
print arg with no loss of information and without leading or trailing
zeros; then let d equal (max q (min n 7)).  Let dd equal d- n.

   If 0 \le dd \le d, then arg is printed as if by the format directives

   ~ww,dd,,overflowchar,padcharF~ee@T

   Note that the scale factor k is not passed to the ~F directive.  For
all other values of dd, arg is printed as if by the format directive

   ~w,d,e,k,overflowchar,padchar,exponentcharE

   In either case, an @ modifier is supplied to the ~F or ~E directive
if and only if one was supplied to the ~G directive.

   ~G binds *print-escape* to false

   and *print-readably* to false.


File: gcl.info,  Node: Tilde Dollarsign-> Monetary Floating-Point,  Prev: Tilde G-> General Floating-Point,  Up: FORMAT Floating-Point Printers

22.3.3.4 Tilde Dollarsign: Monetary Floating-Point
..................................................

The next arg is printed as a float in fixed-format notation.

   The full form is ~d,n,w,padchar$.  The parameter d is the number of
digits to print after the decimal point (default value 2); n is the
minimum number of digits to print before the decimal point (default
value 1); w is the minimum total width of the field to be printed
(default value 0).

   First padding and the sign are output.  If the arg is negative, then
a minus sign is printed; if the arg is not negative, then a plus sign is
printed if and only if the @ modifier was supplied.  If the : modifier
is used, the sign appears before any padding, and otherwise after the
padding.  If w is supplied and the number of other characters to be
output is less than w, then copies of padchar (which defaults to a
space) are output to make the total field width equal w.  Then n digits
are printed for the integer part of arg, with leading zeros if
necessary; then a decimal point; then d digits of fraction, properly
rounded.

   If the magnitude of arg is so large that more than m digits would
have to be printed, where m is the larger of w and 100, then an
implementation is free, at its discretion, to print the number using
exponential notation instead, as if by the directive ~w,q,,,,padcharE,
where w and padchar are present or omitted according to whether they
were present or omitted in the ~$ directive, and where q=d+n- 1, where d
and n are the (possibly default) values given to the ~$ directive.

   If arg is a rational number, then it is coerced to be a single float
and then printed.  Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids loss of precision or overflow because of the
coercion.

   If arg is a complex number or some non-numeric object, then it is
printed using the format directive ~wD, thereby printing it in decimal
radix and a minimum field width of w.

   ~$ binds *print-escape* to false

   and *print-readably* to false.


File: gcl.info,  Node: FORMAT Printer Operations,  Next: FORMAT Pretty Printer Operations,  Prev: FORMAT Floating-Point Printers,  Up: Formatted Output

22.3.4 FORMAT Printer Operations
--------------------------------

* Menu:

* Tilde A-> Aesthetic::
* Tilde S-> Standard::
* Tilde W-> Write::


File: gcl.info,  Node: Tilde A-> Aesthetic,  Next: Tilde S-> Standard,  Prev: FORMAT Printer Operations,  Up: FORMAT Printer Operations

22.3.4.1 Tilde A: Aesthetic
...........................

An arg, any object, is printed without escape characters (as by princ).
If arg is a string, its characters will be output verbatim.  If arg is
nil it will be printed as nil; the colon modifier (~:A) will cause an
arg of nil to be printed as (), but if arg is a composite structure,
such as a list or vector, any contained occurrences of nil will still be
printed as nil.

   ~mincolA inserts spaces on the right, if necessary, to make the width
at least mincol columns.  The @ modifier causes the spaces to be
inserted on the left rather than the right.

   ~mincol,colinc,minpad,padcharA is the full form of ~A, which allows
control of the padding.  The string is padded on the right (or on the
left if the @ modifier is used) with at least minpad copies of padchar;
padding characters are then inserted colinc characters at a time until
the total width is at least mincol.  The defaults are 0 for mincol and
minpad, 1 for colinc, and the space character for padchar.

   ~A binds *print-escape* to false,

   and *print-readably* to false.


File: gcl.info,  Node: Tilde S-> Standard,  Next: Tilde W-> Write,  Prev: Tilde A-> Aesthetic,  Up: FORMAT Printer Operations

22.3.4.2 Tilde S: Standard
..........................

This is just like ~A, but arg is printed with escape characters (as by
prin1 rather than princ).  The output is therefore suitable for input to
read.  ~S accepts all the arguments and modifiers that ~A does.

   ~S binds *print-escape* to t.


File: gcl.info,  Node: Tilde W-> Write,  Prev: Tilde S-> Standard,  Up: FORMAT Printer Operations

22.3.4.3 Tilde W: Write
.......................

An argument, any object, is printed obeying every printer control
variable (as by write).  In addition, ~W interacts correctly with depth
abbreviation, by not resetting the depth counter to zero.  ~W does not
accept parameters.  If given the colon modifier, ~W binds *print-pretty*
to true.  If given the at-sign modifier, ~W binds *print-level* and
*print-length* to nil.

   ~W provides automatic support for the detection of circularity and
sharing.  If the value of *print-circle* is not nil and ~W is applied to
an argument that is a circular (or shared) reference, an appropriate #n#
marker is inserted in the output instead of printing the argument.


File: gcl.info,  Node: FORMAT Pretty Printer Operations,  Next: FORMAT Layout Control,  Prev: FORMAT Printer Operations,  Up: Formatted Output

22.3.5 FORMAT Pretty Printer Operations
---------------------------------------

The following constructs provide access to the pretty printer:

* Menu:

* Tilde Underscore-> Conditional Newline::
* Tilde Less-Than-Sign-> Logical Block::
* Tilde I-> Indent::
* Tilde Slash-> Call Function::


File: gcl.info,  Node: Tilde Underscore-> Conditional Newline,  Next: Tilde Less-Than-Sign-> Logical Block,  Prev: FORMAT Pretty Printer Operations,  Up: FORMAT Pretty Printer Operations

22.3.5.1 Tilde Underscore: Conditional Newline
..............................................

Without any modifiers, ~_ is the same as (pprint-newline :linear).  ~@_
is the same as (pprint-newline :miser).  ~:_ is the same as
(pprint-newline :fill).  ~:@_ is the same as (pprint-newline
:mandatory).


File: gcl.info,  Node: Tilde Less-Than-Sign-> Logical Block,  Next: Tilde I-> Indent,  Prev: Tilde Underscore-> Conditional Newline,  Up: FORMAT Pretty Printer Operations

22.3.5.2 Tilde Less-Than-Sign: Logical Block
............................................

~<...~:>

   If ~:> is used to terminate a ~<...~>, the directive is equivalent to
a call to pprint-logical-block.  The argument corresponding to the
~<...~:> directive is treated in the same way as the list argument to
pprint-logical-block, thereby providing automatic support for non-list
arguments and the detection of circularity, sharing, and depth
abbreviation.  The portion of the control-string nested within the
~<...~:> specifies the :prefix (or :per-line-prefix), :suffix, and body
of the pprint-logical-block.

   The control-string portion enclosed by ~<...~:> can be divided into
segments ~<prefix~;body~;suffix~:> by ~; directives.  If the first
section is terminated by ~@;, it specifies a per-line prefix rather than
a simple prefix.  The prefix and suffix cannot contain format
directives.  An error is signaled if either the prefix or suffix fails
to be a constant string or if the enclosed portion is divided into more
than three segments.

   If the enclosed portion is divided into only two segments, the suffix
defaults to the null string.  If the enclosed portion consists of only a
single segment, both the prefix and the suffix default to the null
string.  If the colon modifier is used (i.e., ~:<...~:>), the prefix and
suffix default to "(" and ")" (respectively) instead of the null string.

   The body segment can be any arbitrary format string.  This format
string is applied to the elements of the list corresponding to the
~<...~:> directive as a whole.  Elements are extracted from this list
using pprint-pop, thereby providing automatic support for malformed
lists, and the detection of circularity, sharing, and length
abbreviation.  Within the body segment, ~^ acts like
pprint-exit-if-list-exhausted.

   ~<...~:> supports a feature not supported by pprint-logical-block.
If ~:@> is used to terminate the directive (i.e., ~<...~:@>), then a
fill-style conditional newline is automatically inserted after each
group of blanks immediately contained in the body (except for blanks
after a ~<Newline> directive).  This makes it easy to achieve the
equivalent of paragraph filling.

   If the at-sign modifier is used with ~<...~:>, the entire remaining
argument list is passed to the directive as its argument.  All of the
remaining arguments are always consumed by ~@<...~:>, even if they are
not all used by the format string nested in the directive.  Other than
the difference in its argument, ~@<...~:> is exactly the same as
~<...~:> except that circularity detection is not applied if ~@<...~:>
is encountered at top level in a format string.  This ensures that
circularity detection is applied only to data lists, not to format
argument lists.

   " . #n#" is printed if circularity or sharing has to be indicated for
its argument as a whole.

   To a considerable extent, the basic form of the directive ~<...~> is
incompatible with the dynamic control of the arrangement of output by
~W, ~_, ~<...~:>, ~I, and ~:T.  As a result, an error is signaled if any
of these directives is nested within ~<...~>.  Beyond this, an error is
also signaled if the ~<...~:;...~> form of ~<...~> is used in the same
format string with ~W, ~_, ~<...~:>, ~I, or ~:T.

   See also *note Tilde Less-Than-Sign-> Justification::.


File: gcl.info,  Node: Tilde I-> Indent,  Next: Tilde Slash-> Call Function,  Prev: Tilde Less-Than-Sign-> Logical Block,  Up: FORMAT Pretty Printer Operations

22.3.5.3 Tilde I: Indent
........................

~nI is the same as (pprint-indent :block n).

   ~n:I is the same as (pprint-indent :current n).  In both cases, n
defaults to zero, if it is omitted.


File: gcl.info,  Node: Tilde Slash-> Call Function,  Prev: Tilde I-> Indent,  Up: FORMAT Pretty Printer Operations

22.3.5.4 Tilde Slash: Call Function
...................................

~/name/

   User defined functions can be called from within a format string by
using the directive ~/name/.  The colon modifier, the at-sign modifier,
and arbitrarily many parameters can be specified with the ~/name/
directive.  name can be any arbitrary string that does not contain a
"/".  All of the characters in name are treated as if they were upper
case.  If name contains a single colon (:) or double colon (::), then
everything up to but not including the first ":" or "::" is taken to be
a string that names a package.  Everything after the first ":" or "::"
(if any) is taken to be a string that names a symbol.  The function
corresponding to a ~/name/ directive is obtained by looking up the
symbol that has the indicated name in the indicated package.  If name
does not contain a ":" or "::", then the whole name string is looked up
in the COMMON-LISP-USER package.

   When a ~/name/ directive is encountered, the indicated function is
called with four or more arguments.  The first four arguments are: the
output stream, the format argument corresponding to the directive, a
generalized boolean that is true if the colon modifier was used, and a
generalized boolean that is true if the at-sign modifier was used.  The
remaining arguments consist of any parameters specified with the
directive.  The function should print the argument appropriately.  Any
values returned by the function are ignored.

   The three functions pprint-linear, pprint-fill, and pprint-tabular
are specifically designed so that they can be called by ~/.../ (i.e.,
~/pprint-linear/, ~/pprint-fill/, and ~/pprint-tabular/).  In particular
they take colon and at-sign arguments.


File: gcl.info,  Node: FORMAT Layout Control,  Next: FORMAT Control-Flow Operations,  Prev: FORMAT Pretty Printer Operations,  Up: Formatted Output

22.3.6 FORMAT Layout Control
----------------------------

* Menu:

* Tilde T-> Tabulate::
* Tilde Less-Than-Sign-> Justification::
* Tilde Greater-Than-Sign-> End of Justification::


File: gcl.info,  Node: Tilde T-> Tabulate,  Next: Tilde Less-Than-Sign-> Justification,  Prev: FORMAT Layout Control,  Up: FORMAT Layout Control

22.3.6.1 Tilde T: Tabulate
..........................

This spaces over to a given column.  ~colnum,colincT will output
sufficient spaces to move the cursor to column colnum.  If the cursor is
already at or beyond column colnum, it will output spaces to move it to
column colnum+k*colinc for the smallest positive integer k possible,
unless colinc is zero, in which case no spaces are output if the cursor
is already at or beyond column colnum.  colnum and colinc default to 1.

   If for some reason the current absolute column position cannot be
determined by direct inquiry, format may be able to deduce the current
column position by noting that certain directives (such as ~%, or ~&, or
~A with the argument being a string containing a newline) cause the
column position to be reset to zero, and counting the number of
characters emitted since that point.  If that fails, format may attempt
a similar deduction on the riskier assumption that the destination was
at column zero when format was invoked.  If even this heuristic fails or
is implementationally inconvenient, at worst the ~T operation will
simply output two spaces.

   ~@T performs relative tabulation.  ~colrel,colinc@T outputs colrel
spaces and then outputs the smallest non-negative number of additional
spaces necessary to move the cursor to a column that is a multiple of
colinc.  For example, the directive ~3,8@T outputs three spaces and then
moves the cursor to a "standard multiple-of-eight tab stop" if not at
one already.  If the current output column cannot be determined,
however, then colinc is ignored, and exactly colrel spaces are output.

   If the colon modifier is used with the ~T directive, the tabbing
computation is done relative to the horizontal position where the
section immediately containing the directive begins, rather than with
respect to a horizontal position of zero.  The numerical parameters are
both interpreted as being in units of ems and both default to 1.  ~n,m:T
is the same as (pprint-tab :section n m).  ~n,m:@T is the same as
(pprint-tab :section-relative n m).


File: gcl.info,  Node: Tilde Less-Than-Sign-> Justification,  Next: Tilde Greater-Than-Sign-> End of Justification,  Prev: Tilde T-> Tabulate,  Up: FORMAT Layout Control

22.3.6.2 Tilde Less-Than-Sign: Justification
............................................

~mincol,colinc,minpad,padchar<str~>

   This justifies the text produced by processing str within a field at
least mincol columns wide.  str may be divided up into segments with ~;,
in which case the spacing is evenly divided between the text segments.

   With no modifiers, the leftmost text segment is left justified in the
field, and the rightmost text segment is right justified.  If there is
only one text element, as a special case, it is right justified.  The :
modifier causes spacing to be introduced before the first text segment;
the @ modifier causes spacing to be added after the last.  The minpad
parameter (default 0) is the minimum number of padding characters to be
output between each segment.  The padding character is supplied by
padchar, which defaults to the space character.  If the total width
needed to satisfy these constraints is greater than mincol, then the
width used is mincol+k*colinc for the smallest possible non-negative
integer value k.  colinc defaults to 1, and mincol defaults to 0.

   Note that str may include format directives.  All the clauses in str
are processed in order; it is the resulting pieces of text that are
justified.

   The ~^ directive may be used to terminate processing of the clauses
prematurely, in which case only the completely processed clauses are
justified.

   If the first clause of a ~< is terminated with ~:; instead of ~;,
then it is used in a special way.  All of the clauses are processed
(subject to ~^ , of course), but the first one is not used in performing
the spacing and padding.  When the padded result has been determined,
then if it will fit on the current line of output, it is output, and the
text for the first clause is discarded.  If, however, the padded text
will not fit on the current line, then the text segment for the first
clause is output before the padded text.  The first clause ought to
contain a newline (such as a ~% directive).  The first clause is always
processed, and so any arguments it refers to will be used; the decision
is whether to use the resulting segment of text, not whether to process
the first clause.  If the ~:; has a prefix parameter n, then the padded
text must fit on the current line with n character positions to spare to
avoid outputting the first clause's text.  For example, the control
string

      "~

   can be used to print a list of items separated by commas without
breaking items over line boundaries, beginning each line with ;; .  The
prefix parameter 1 in ~1:; accounts for the width of the comma that will
follow the justified item if it is not the last element in the list, or
the period if it is.  If ~:; has a second prefix parameter, then it is
used as the width of the line, thus overriding the natural line width of
the output stream.  To make the preceding example use a line width of
50, one would write

      "~

   If the second argument is not supplied, then format uses the line
width of the destination output stream.  If this cannot be determined
(for example, when producing a string result), then format uses 72 as
the line length.

   See also *note Tilde Less-Than-Sign-> Logical Block::.


File: gcl.info,  Node: Tilde Greater-Than-Sign-> End of Justification,  Prev: Tilde Less-Than-Sign-> Justification,  Up: FORMAT Layout Control

22.3.6.3 Tilde Greater-Than-Sign: End of Justification
......................................................

~> terminates a ~<.  The consequences of using it elsewhere are
undefined.


File: gcl.info,  Node: FORMAT Control-Flow Operations,  Next: FORMAT Miscellaneous Operations,  Prev: FORMAT Layout Control,  Up: Formatted Output

22.3.7 FORMAT Control-Flow Operations
-------------------------------------

* Menu:

* Tilde Asterisk-> Go-To::
* Tilde Left-Bracket-> Conditional Expression::
* Tilde Right-Bracket-> End of Conditional Expression::
* Tilde Left-Brace-> Iteration::
* Tilde Right-Brace-> End of Iteration::
* Tilde Question-Mark-> Recursive Processing::


File: gcl.info,  Node: Tilde Asterisk-> Go-To,  Next: Tilde Left-Bracket-> Conditional Expression,  Prev: FORMAT Control-Flow Operations,  Up: FORMAT Control-Flow Operations

22.3.7.1 Tilde Asterisk: Go-To
..............................

The next arg is ignored.  ~n* ignores the next n arguments.

   ~:* backs up in the list of arguments so that the argument last
processed will be processed again.  ~n:* backs up n arguments.

   When within a ~{ construct (see below), the ignoring (in either
direction) is relative to the list of arguments being processed by the
iteration.

   ~n@* goes to the nth arg, where 0 means the first one; n defaults to
0, so ~@* goes back to the first arg.  Directives after a ~n@* will take
arguments in sequence beginning with the one gone to.  When within a ~{
construct, the "goto" is relative to the list of arguments being
processed by the iteration.


File: gcl.info,  Node: Tilde Left-Bracket-> Conditional Expression,  Next: Tilde Right-Bracket-> End of Conditional Expression,  Prev: Tilde Asterisk-> Go-To,  Up: FORMAT Control-Flow Operations

22.3.7.2 Tilde Left-Bracket: Conditional Expression
...................................................

~[str0~;str1~;...~;strn~]

   This is a set of control strings, called clauses, one of which is
chosen and used.  The clauses are separated by ~; and the construct is
terminated by ~].  For example,

   "~[Siamese~;Manx~;Persian~] Cat"

   The argth clause is selected, where the first clause is number 0.  If
a prefix parameter is given (as ~n[), then the parameter is used instead
of an argument.  If arg is out of range then no clause is selected and
no error is signaled.  After the selected alternative has been
processed, the control string continues after the ~].

   ~[str0~;str1~;...~;strn~:;default~] has a default case.  If the last
~; used to separate clauses is ~:; instead, then the last clause is an
else clause that is performed if no other clause is selected.  For
example:

   "~[Siamese~;Manx~;Persian~:;Alley~] Cat"

   ~:[alternative~;consequent~] selects the alternative control string
if arg is false, and selects the consequent control string otherwise.

   ~@[consequent~] tests the argument.  If it is true, then the argument
is not used up by the ~[ command but remains as the next one to be
processed, and the one clause consequent is processed.  If the arg is
false, then the argument is used up, and the clause is not processed.
The clause therefore should normally use exactly one argument, and may
expect it to be non-nil.  For example:

      (setq *print-level* nil *print-length* 5)
      (format nil
             "~@[ print level = ~D~]~@[ print length = ~D~]"
             *print-level* *print-length*)
     =>   " print length = 5"

   Note also that

      (format stream "...~@[str~]..." ...)
     == (format stream "...~:[~;~:*str~]..." ...)

   The combination of ~[ and # is useful, for example, for dealing with
English conventions for printing lists:

      (setq foo "Items:~#[ none~; ~S~; ~S and ~S~
                ~:;~@{~#[~; and~] ~S~^ ,~}~].")
      (format nil foo) =>   "Items: none."
      (format nil foo 'foo) =>   "Items: FOO."
      (format nil foo 'foo 'bar) =>   "Items: FOO and BAR."
      (format nil foo 'foo 'bar 'baz) =>   "Items: FOO, BAR, and BAZ."
      (format nil foo 'foo 'bar 'baz 'quux) =>   "Items: FOO, BAR, BAZ, and QUUX."


File: gcl.info,  Node: Tilde Right-Bracket-> End of Conditional Expression,  Next: Tilde Left-Brace-> Iteration,  Prev: Tilde Left-Bracket-> Conditional Expression,  Up: FORMAT Control-Flow Operations

22.3.7.3 Tilde Right-Bracket: End of Conditional Expression
...........................................................

~] terminates a ~[.  The consequences of using it elsewhere are
undefined.


File: gcl.info,  Node: Tilde Left-Brace-> Iteration,  Next: Tilde Right-Brace-> End of Iteration,  Prev: Tilde Right-Bracket-> End of Conditional Expression,  Up: FORMAT Control-Flow Operations

22.3.7.4 Tilde Left-Brace: Iteration
....................................

~{str~}

   This is an iteration construct.  The argument should be a list, which
is used as a set of arguments as if for a recursive call to format.  The
string str is used repeatedly as the control string.  Each iteration can
absorb as many elements of the list as it likes as arguments; if str
uses up two arguments by itself, then two elements of the list will get
used up each time around the loop.  If before any iteration step the
list is empty, then the iteration is terminated.  Also, if a prefix
parameter n is given, then there will be at most n repetitions of
processing of str.  Finally, the ~^ directive can be used to terminate
the iteration prematurely.

   For example:

      (format nil "The winners are:~{ ~S~}."
              '(fred harry jill))
     =>  "The winners are: FRED HARRY JILL."
      (format nil "Pairs:~{ <~S,~S>~}."
              '(a 1 b 2 c 3))
     =>  "Pairs: <A,1> <B,2> <C,3>."

   ~:{ str~} is similar, but the argument should be a list of sublists.
At each repetition step, one sublist is used as the set of arguments for
processing str; on the next repetition, a new sublist is used, whether
or not all of the last sublist had been processed.  For example:

      (format nil "Pairs:~:{ <~S,~S>~} ."
                      '((a 1) (b 2) (c 3)))
     =>  "Pairs: <A,1> <B,2> <C,3>."

   ~@{ str~} is similar to ~{ str~} , but instead of using one argument
that is a list, all the remaining arguments are used as the list of
arguments for the iteration.  Example:

      (format nil "Pairs:~@{ <~S,~S>~} ." 'a 1 'b 2 'c 3)
     =>  "Pairs: <A,1> <B,2> <C,3>."

   If the iteration is terminated before all the remaining arguments are
consumed, then any arguments not processed by the iteration remain to be
processed by any directives following the iteration construct.

   ~:@{ str~} combines the features of ~:{ str~} and ~@{ str~} .  All
the remaining arguments are used, and each one must be a list.  On each
iteration, the next argument is used as a list of arguments to str.
Example:

      (format nil "Pairs:~:@{ <~S,~S>~} ."
                   '(a 1) '(b 2) '(c 3))
     =>  "Pairs: <A,1> <B,2> <C,3>."

   Terminating the repetition construct with ~:} instead of ~} forces
str to be processed at least once, even if the initial list of arguments
is null.  However, this will not override an explicit prefix parameter
of zero.

   If str is empty, then an argument is used as str.  It must be a
format control and precede any arguments processed by the iteration.  As
an example, the following are equivalent:

         (apply #'format stream string arguments)
      == (format stream "~1{~:}" string arguments)

   This will use string as a formatting string.  The ~1{ says it will be
processed at most once, and the ~:} says it will be processed at least
once.  Therefore it is processed exactly once, using arguments as the
arguments.  This case may be handled more clearly by the ~? directive,
but this general feature of ~{ is more powerful than ~?.


File: gcl.info,  Node: Tilde Right-Brace-> End of Iteration,  Next: Tilde Question-Mark-> Recursive Processing,  Prev: Tilde Left-Brace-> Iteration,  Up: FORMAT Control-Flow Operations

22.3.7.5 Tilde Right-Brace: End of Iteration
............................................

~} terminates a ~{.  The consequences of using it elsewhere are
undefined.


File: gcl.info,  Node: Tilde Question-Mark-> Recursive Processing,  Prev: Tilde Right-Brace-> End of Iteration,  Up: FORMAT Control-Flow Operations

22.3.7.6 Tilde Question-Mark: Recursive Processing
..................................................

The next arg must be a format control, and the one after it a list; both
are consumed by the ~? directive.  The two are processed as a
control-string, with the elements of the list as the arguments.  Once
the recursive processing has been finished, the processing of the
control string containing the ~? directive is resumed.  Example:

      (format nil "~? ~D" "<~A ~D>" '("Foo" 5) 7) =>  "<Foo 5> 7"
      (format nil "~? ~D" "<~A ~D>" '("Foo" 5 14) 7) =>  "<Foo 5> 7"

   Note that in the second example three arguments are supplied to the
format string "<~A ~D>", but only two are processed and the third is
therefore ignored.

   With the @ modifier, only one arg is directly consumed.  The arg must
be a string; it is processed as part of the control string as if it had
appeared in place of the ~@? construct, and any directives in the
recursively processed control string may consume arguments of the
control string containing the ~@? directive.  Example:

      (format nil "~@? ~D" "<~A ~D>" "Foo" 5 7) =>  "<Foo 5> 7"
      (format nil "~@? ~D" "<~A ~D>" "Foo" 5 14 7) =>  "<Foo 5> 14"


File: gcl.info,  Node: FORMAT Miscellaneous Operations,  Next: FORMAT Miscellaneous Pseudo-Operations,  Prev: FORMAT Control-Flow Operations,  Up: Formatted Output

22.3.8 FORMAT Miscellaneous Operations
--------------------------------------

* Menu:

* Tilde Left-Paren-> Case Conversion::
* Tilde Right-Paren-> End of Case Conversion::
* Tilde P-> Plural::


File: gcl.info,  Node: Tilde Left-Paren-> Case Conversion,  Next: Tilde Right-Paren-> End of Case Conversion,  Prev: FORMAT Miscellaneous Operations,  Up: FORMAT Miscellaneous Operations

22.3.8.1 Tilde Left-Paren: Case Conversion
..........................................

~(str~)

   The contained control string str is processed, and what it produces
is subject to case conversion.

   With no flags, every uppercase character is converted to the
corresponding lowercase character.

   ~:( capitalizes all words, as if by string-capitalize.

   ~@( capitalizes just the first word and forces the rest to lower
case.

   ~:@( converts every lowercase character to the corresponding
uppercase character.

   In this example ~@( is used to cause the first word produced by ~@R
to be capitalized:

      (format nil "~@R ~(~@R~)" 14 14)
     =>  "XIV xiv"
      (defun f (n) (format nil "~@(~R~) error~:P detected." n)) =>  F
      (f 0) =>  "Zero errors detected."
      (f 1) =>  "One error detected."
      (f 23) =>  "Twenty-three errors detected."

   When case conversions appear nested, the outer conversion dominates,
as illustrated in the following example:

      (format nil "~@(how is ~:(BOB SMITH~)?~)")
      =>  "How is bob smith?"
      NOT=> "How is Bob Smith?"


File: gcl.info,  Node: Tilde Right-Paren-> End of Case Conversion,  Next: Tilde P-> Plural,  Prev: Tilde Left-Paren-> Case Conversion,  Up: FORMAT Miscellaneous Operations

22.3.8.2 Tilde Right-Paren: End of Case Conversion
..................................................

~) terminates a ~(.  The consequences of using it elsewhere are
undefined.


File: gcl.info,  Node: Tilde P-> Plural,  Prev: Tilde Right-Paren-> End of Case Conversion,  Up: FORMAT Miscellaneous Operations

22.3.8.3 Tilde P: Plural
........................

If arg is not eql to the integer 1, a lowercase s is printed; if arg is
eql to 1, nothing is printed.  If arg is a floating-point 1.0, the s is
printed.

   ~:P does the same thing, after doing a ~:* to back up one argument;
that is, it prints a lowercase s if the previous argument was not 1.

   ~@P prints y if the argument is 1, or ies if it is not.  ~:@P does
the same thing, but backs up first.

      (format nil "~D tr~:@P/~D win~:P" 7 1) =>  "7 tries/1 win"
      (format nil "~D tr~:@P/~D win~:P" 1 0) =>  "1 try/0 wins"
      (format nil "~D tr~:@P/~D win~:P" 1 3) =>  "1 try/3 wins"


File: gcl.info,  Node: FORMAT Miscellaneous Pseudo-Operations,  Next: Additional Information about FORMAT Operations,  Prev: FORMAT Miscellaneous Operations,  Up: Formatted Output

22.3.9 FORMAT Miscellaneous Pseudo-Operations
---------------------------------------------

* Menu:

* Tilde Semicolon-> Clause Separator::
* Tilde Circumflex-> Escape Upward::
* Tilde Newline-> Ignored Newline::


File: gcl.info,  Node: Tilde Semicolon-> Clause Separator,  Next: Tilde Circumflex-> Escape Upward,  Prev: FORMAT Miscellaneous Pseudo-Operations,  Up: FORMAT Miscellaneous Pseudo-Operations

22.3.9.1 Tilde Semicolon: Clause Separator
..........................................

This separates clauses in ~[ and ~< constructs.  The consequences of
using it elsewhere are undefined.


File: gcl.info,  Node: Tilde Circumflex-> Escape Upward,  Next: Tilde Newline-> Ignored Newline,  Prev: Tilde Semicolon-> Clause Separator,  Up: FORMAT Miscellaneous Pseudo-Operations

22.3.9.2 Tilde Circumflex: Escape Upward
........................................

~^

   This is an escape construct.  If there are no more arguments
remaining to be processed, then the immediately enclosing ~{ or ~<
construct is terminated.  If there is no such enclosing construct, then
the entire formatting operation is terminated.  In the ~< case, the
formatting is performed, but no more segments are processed before doing
the justification.  ~^ may appear anywhere in a ~{ construct.

      (setq donestr "Done.~^ ~D warning~:P.~^ ~D error~:P.")
     =>  "Done.~^ ~D warning~:P.~^ ~D error~:P."
      (format nil donestr) =>  "Done."
      (format nil donestr 3) =>  "Done. 3 warnings."
      (format nil donestr 1 5) =>  "Done. 1 warning. 5 errors."

   If a prefix parameter is given, then termination occurs if the
parameter is zero.  (Hence ~^ is equivalent to ~#^.)  If two parameters
are given, termination occurs if they are equal.

   [Reviewer Note by Barmar: Which equality predicate?]  If three
parameters are given, termination occurs if the first is less than or
equal to the second and the second is less than or equal to the third.
Of course, this is useless if all the prefix parameters are constants;
at least one of them should be a # or a V parameter.

   If ~^ is used within a ~:{ construct, then it terminates the current
iteration step because in the standard case it tests for remaining
arguments of the current step only; the next iteration step commences
immediately.  ~:^ is used to terminate the iteration process.

   ~:^ may be used only if the command it would terminate is ~:{ or ~:@{
.  The entire iteration process is terminated if and only if the sublist
that is supplying the arguments for the current iteration step is the
last sublist in the case of ~:{ , or the last format argument in the
case of ~:@{ .  ~:^ is not equivalent to ~#:^; the latter terminates the
entire iteration if and only if no arguments remain for the current
iteration step.  For example:

      (format nil "~:{ ~@?~:^ ...~} " '(("a") ("b"))) =>  "a...b"

   If ~^ appears within a control string being processed under the
control of a ~? directive, but not within any ~{ or ~< construct within
that string, then the string being processed will be terminated, thereby
ending processing of the ~? directive.  Processing then continues within
the string containing the ~? directive at the point following that
directive.

   If ~^ appears within a ~[ or ~( construct, then all the commands up
to the ~^ are properly selected or case-converted, the ~[ or ~(
processing is terminated, and the outward search continues for a ~{ or
~< construct to be terminated.  For example:

      (setq tellstr "~@(~@[~R~]~^ ~A!~)")
     =>  "~@(~@[~R~]~^ ~A!~)"
      (format nil tellstr 23) =>  "Twenty-three!"
      (format nil tellstr nil "losers") =>  " Losers!"
      (format nil tellstr 23 "losers") =>  "Twenty-three losers!"

   Following are examples of the use of ~^ within a ~< construct.

      (format nil "~15<~S~;~^~S~;~^~S~>" 'foo)
     =>   "            FOO"
      (format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar)
     =>   "FOO         BAR"
      (format nil "~15<~S~;~^~S~;~^~S~>" 'foo 'bar 'baz)
     =>   "FOO   BAR   BAZ"


File: gcl.info,  Node: Tilde Newline-> Ignored Newline,  Prev: Tilde Circumflex-> Escape Upward,  Up: FORMAT Miscellaneous Pseudo-Operations

22.3.9.3 Tilde Newline: Ignored Newline
.......................................

Tilde immediately followed by a newline ignores the newline and any
following non-newline whitespace_1 characters.  With a :, the newline is
ignored, but any following whitespace_1 is left in place.  With an @,
the newline is left in place, but any following whitespace_1 is ignored.
For example:

      (defun type-clash-error (fn nargs argnum right-type wrong-type)
        (format *error-output*
                "~&~S requires its ~:[~:R~;~*~]~
                argument to be of type ~S,~
                with an argument of type ~S.~
                fn (eql nargs 1) argnum right-type wrong-type))
      (type-clash-error 'aref nil 2 'integer 'vector)  prints:
     AREF requires its second argument to be of type INTEGER,
     but it was called with an argument of type VECTOR.
     NIL
      (type-clash-error 'car 1 1 'list 'short-float)  prints:
     CAR requires its argument to be of type LIST,
     but it was called with an argument of type SHORT-FLOAT.
     NIL

   Note that in this example newlines appear in the output only as
specified by the ~& and ~% directives; the actual newline characters in
the control string are suppressed because each is preceded by a tilde.


File: gcl.info,  Node: Additional Information about FORMAT Operations,  Next: Examples of FORMAT,  Prev: FORMAT Miscellaneous Pseudo-Operations,  Up: Formatted Output

22.3.10 Additional Information about FORMAT Operations
------------------------------------------------------

* Menu:

* Nesting of FORMAT Operations::
* Missing and Additional FORMAT Arguments::
* Additional FORMAT Parameters::
* Undefined FORMAT Modifier Combinations::


File: gcl.info,  Node: Nesting of FORMAT Operations,  Next: Missing and Additional FORMAT Arguments,  Prev: Additional Information about FORMAT Operations,  Up: Additional Information about FORMAT Operations

22.3.10.1 Nesting of FORMAT Operations
......................................

The case-conversion, conditional, iteration, and justification
constructs can contain other formatting constructs by bracketing them.
These constructs must nest properly with respect to each other.  For
example, it is not legitimate to put the start of a case-conversion
construct in each arm of a conditional and the end of the
case-conversion construct outside the conditional:

      (format nil "~:[abc~:@(def~;ghi~
     :@(jkl~]mno~)" x) ;Invalid!

   This notation is invalid because the ~[...~;...~] and ~(...~)
constructs are not properly nested.

   The processing indirection caused by the ~? directive is also a kind
of nesting for the purposes of this rule of proper nesting.  It is not
permitted to start a bracketing construct within a string processed
under control of a ~? directive and end the construct at some point
after the ~? construct in the string containing that construct, or vice
versa.  For example, this situation is invalid:

      (format nil "~@?ghi~)" "abc~@(def") ;Invalid!

   This notation is invalid because the ~? and ~(...~) constructs are
not properly nested.


File: gcl.info,  Node: Missing and Additional FORMAT Arguments,  Next: Additional FORMAT Parameters,  Prev: Nesting of FORMAT Operations,  Up: Additional Information about FORMAT Operations

22.3.10.2 Missing and Additional FORMAT Arguments
.................................................

The consequences are undefined if no arg remains for a directive
requiring an argument.  However, it is permissible for one or more args
to remain unprocessed by a directive; such args are ignored.


File: gcl.info,  Node: Additional FORMAT Parameters,  Next: Undefined FORMAT Modifier Combinations,  Prev: Missing and Additional FORMAT Arguments,  Up: Additional Information about FORMAT Operations

22.3.10.3 Additional FORMAT Parameters
......................................

The consequences are undefined if a format directive is given more
parameters than it is described here as accepting.


File: gcl.info,  Node: Undefined FORMAT Modifier Combinations,  Prev: Additional FORMAT Parameters,  Up: Additional Information about FORMAT Operations

22.3.10.4 Undefined FORMAT Modifier Combinations
................................................

The consequences are undefined if colon or at-sign modifiers are given
to a directive in a combination not specifically described here as being
meaningful.


File: gcl.info,  Node: Examples of FORMAT,  Next: Notes about FORMAT,  Prev: Additional Information about FORMAT Operations,  Up: Formatted Output

22.3.11 Examples of FORMAT
--------------------------

      (format nil "foo") =>  "foo"
      (setq x 5) =>  5
      (format nil "The answer is ~D." x) =>  "The answer is 5."
      (format nil "The answer is ~3D." x) =>  "The answer is   5."
      (format nil "The answer is ~3,'0D." x) =>  "The answer is 005."
      (format nil "The answer is ~:D." (expt 47 x))
     =>  "The answer is 229,345,007."
      (setq y "elephant") =>  "elephant"
      (format nil "Look at the ~A!" y) =>  "Look at the elephant!"
      (setq n 3) =>  3
      (format nil "~D item~:P found." n) =>  "3 items found."
      (format nil "~R dog~:[s are~; is~] here." n (= n 1))
     =>  "three dogs are here."
      (format nil "~R dog~:*~[s are~; is~:;s are~] here." n)
     =>  "three dogs are here."
      (format nil "Here ~[are~;is~:;are~] ~:*~R pupp~:@P." n)
     =>  "Here are three puppies."

      (defun foo (x)
        (format nil "~6,2F|~6,2,1,'*F|~6,2,,'?F|~6F|~,2F|~F"
                x x x x x x)) =>  FOO
      (foo 3.14159)  =>  "  3.14| 31.42|  3.14|3.1416|3.14|3.14159"
      (foo -3.14159) =>  " -3.14|-31.42| -3.14|-3.142|-3.14|-3.14159"
      (foo 100.0)    =>  "100.00|******|100.00| 100.0|100.00|100.0"
      (foo 1234.0)   =>  "1234.00|******|??????|1234.0|1234.00|1234.0"
      (foo 0.006)    =>  "  0.01|  0.06|  0.01| 0.006|0.01|0.006"

      (defun foo (x)
         (format nil
                "~9,2,1,,'*E|~10,3,2,2,'?,,'$E|~
                 ~9,3,2,-2,'
                x x x x))
      (foo 3.14159)  =>  "  3.14E+0| 31.42$-01|+.003E+03|  3.14E+0"
      (foo -3.14159) =>  " -3.14E+0|-31.42$-01|-.003E+03| -3.14E+0"
      (foo 1100.0)   =>  "  1.10E+3| 11.00$+02|+.001E+06|  1.10E+3"
      (foo 1100.0L0) =>  "  1.10L+3| 11.00$+02|+.001L+06|  1.10L+3"
      (foo 1.1E13)   =>  "*********| 11.00$+12|+.001E+16| 1.10E+13"
      (foo 1.1L120)  =>  "*********|??????????|
      (foo 1.1L1200) =>  "*********|??????????|

   As an example of the effects of varying the scale factor, the code

      (dotimes (k 13)
        (format t "~
                (- k 5) (- k 5) 3.14159))

   produces the following output:

     Scale factor -5: | 0.000003E+06|
     Scale factor -4: | 0.000031E+05|
     Scale factor -3: | 0.000314E+04|
     Scale factor -2: | 0.003142E+03|
     Scale factor -1: | 0.031416E+02|
     Scale factor  0: | 0.314159E+01|
     Scale factor  1: | 3.141590E+00|
     Scale factor  2: | 31.41590E-01|
     Scale factor  3: | 314.1590E-02|
     Scale factor  4: | 3141.590E-03|
     Scale factor  5: | 31415.90E-04|
     Scale factor  6: | 314159.0E-05|
     Scale factor  7: | 3141590.E-06|

      (defun foo (x)
        (format nil "~9,2,1,,'*G|~9,3,2,3,'?,,'$G|~9,3,2,0,'
               x x x x))
      (foo 0.0314159) =>  "  3.14E-2|314.2$-04|0.314E-01|  3.14E-2"
      (foo 0.314159)  =>  "  0.31   |0.314    |0.314    | 0.31    "
      (foo 3.14159)   =>  "   3.1   | 3.14    | 3.14    |  3.1    "
      (foo 31.4159)   =>  "   31.   | 31.4    | 31.4    |  31.    "
      (foo 314.159)   =>  "  3.14E+2| 314.    | 314.    |  3.14E+2"
      (foo 3141.59)   =>  "  3.14E+3|314.2$+01|0.314E+04|  3.14E+3"
      (foo 3141.59L0) =>  "  3.14L+3|314.2$+01|0.314L+04|  3.14L+3"
      (foo 3.14E12)   =>  "*********|314.0$+10|0.314E+13| 3.14E+12"
      (foo 3.14L120)  =>  "*********|?????????|
      (foo 3.14L1200) =>  "*********|?????????|

      (format nil "~10<foo~;bar~>")   =>  "foo    bar"
      (format nil "~10:<foo~;bar~>")  =>  "  foo  bar"
      (format nil "~10<foobar~>")     =>  "    foobar"
      (format nil "~10:<foobar~>")    =>  "    foobar"
      (format nil "~10:@<foo~;bar~>") =>  "  foo bar "
      (format nil "~10@<foobar~>")    =>  "foobar    "
      (format nil "~10:@<foobar~>")   =>  "  foobar  "

       (FORMAT NIL "Written to ~A." #P"foo.bin")
       =>  "Written to foo.bin."


File: gcl.info,  Node: Notes about FORMAT,  Prev: Examples of FORMAT,  Up: Formatted Output

22.3.12 Notes about FORMAT
--------------------------

Formatted output is performed not only by format, but by certain other
functions that accept a format control the way format does.  For
example, error-signaling functions such as cerror accept format
controls.

   Note that the meaning of nil and t as destinations to format are
different than those of nil and t as stream designators.

   The ~^ should appear only at the beginning of a ~< clause, because it
aborts the entire clause in which it appears (as well as all following
clauses).


File: gcl.info,  Node: Printer Dictionary,  Prev: Formatted Output,  Up: Printer

22.4 Printer Dictionary
=======================

* Menu:

* copy-pprint-dispatch::
* formatter::
* pprint-dispatch::
* pprint-exit-if-list-exhausted::
* pprint-fill::
* pprint-indent::
* pprint-logical-block::
* pprint-newline::
* pprint-pop::
* pprint-tab::
* print-object::
* print-unreadable-object::
* set-pprint-dispatch::
* write::
* write-to-string::
* *print-array*::
* *print-base*::
* *print-case*::
* *print-circle*::
* *print-escape*::
* *print-gensym*::
* *print-level*::
* *print-lines*::
* *print-miser-width*::
* *print-pprint-dispatch*::
* *print-pretty*::
* *print-readably*::
* *print-right-margin*::
* print-not-readable::
* print-not-readable-object::
* format::


File: gcl.info,  Node: copy-pprint-dispatch,  Next: formatter,  Prev: Printer Dictionary,  Up: Printer Dictionary

22.4.1 copy-pprint-dispatch [Function]
--------------------------------------

'copy-pprint-dispatch' &optional table => new-table

Arguments and Values::
......................

table--a pprint dispatch table, or nil.

   new-table--a fresh pprint dispatch table.

Description::
.............

Creates and returns a copy of the specified table, or of the value of
*print-pprint-dispatch* if no table is specified, or of the initial
value of *print-pprint-dispatch* if nil is specified.

Exceptional Situations::
........................

Should signal an error of type type-error if table is not a pprint
dispatch table.


File: gcl.info,  Node: formatter,  Next: pprint-dispatch,  Prev: copy-pprint-dispatch,  Up: Printer Dictionary

22.4.2 formatter [Macro]
------------------------

'formatter' control-string => function

Arguments and Values::
......................

control-string--a format string; not evaluated.

   function--a function.

Description::
.............

Returns a function which has behavior equivalent to:

       #'(lambda (*standard-output* &rest arguments)
           (apply #'format t control-string arguments)
           arguments-tail)

   where arguments-tail is either the tail of arguments which has as its
car the argument that would be processed next if there were more format
directives in the control-string, or else nil if no more arguments
follow the most recently processed argument.

Examples::
..........

     (funcall (formatter "~&~A~A") *standard-output* 'a 'b 'c)
      |>  AB
     =>  (C)

     (format t (formatter "~&~A~A") 'a 'b 'c)
      |>  AB
     =>  NIL

Exceptional Situations::
........................

Might signal an error (at macro expansion time or at run time) if the
argument is not a valid format string.

See Also::
..........

*note format::


File: gcl.info,  Node: pprint-dispatch,  Next: pprint-exit-if-list-exhausted,  Prev: formatter,  Up: Printer Dictionary

22.4.3 pprint-dispatch [Function]
---------------------------------

'pprint-dispatch' object &optional table => function, found-p

Arguments and Values::
......................

object--an object.

   table--a pprint dispatch table, or nil.  The default is the value of
*print-pprint-dispatch*.

   function--a function designator.

   found-p--a generalized boolean.

Description::
.............

Retrieves the highest priority function in table that is associated with
a type specifier that matches object.  The function is chosen by finding
all of the type specifiers in table that match the object and selecting
the highest priority function associated with any of these type
specifiers.  If there is more than one highest priority function, an
arbitrary choice is made.  If no type specifiers match the object, a
function is returned that prints object

   using print-object.

   The secondary value, found-p, is true if a matching type specifier
was found in table, or false otherwise.

   If table is nil, retrieval is done in the initial pprint dispatch
table.

Affected By::
.............

The state of the table.

Exceptional Situations::
........................

Should signal an error of type type-error if table is neither a
pprint-dispatch-table nor nil.

Notes::
.......

     (let ((*print-pretty* t))
       (write object :stream s))
     == (funcall (pprint-dispatch object) s object)


File: gcl.info,  Node: pprint-exit-if-list-exhausted,  Next: pprint-fill,  Prev: pprint-dispatch,  Up: Printer Dictionary

22.4.4 pprint-exit-if-list-exhausted [Local Macro]
--------------------------------------------------

Syntax::
........

'pprint-exit-if-list-exhausted' <no arguments> => nil

Description::
.............

Tests whether or not the list passed to the lexically current logical
block has been exhausted; see *note Dynamic Control of the Arrangement
of Output::.  If this list has been reduced to nil,
pprint-exit-if-list-exhausted terminates the execution of the lexically
current logical block except for the printing of the suffix.  Otherwise
pprint-exit-if-list-exhausted returns nil.

   Whether or not pprint-exit-if-list-exhausted is fbound in the global
environment is implementation-dependent; however, the restrictions on
redefinition and shadowing of pprint-exit-if-list-exhausted are the same
as for symbols in the COMMON-LISP package which are fbound in the global
environment.  The consequences of attempting to use
pprint-exit-if-list-exhausted outside of pprint-logical-block are
undefined.

Exceptional Situations::
........................

An error is signaled (at macro expansion time or at run time) if
pprint-exit-if-list-exhausted is used anywhere other than lexically
within a call on pprint-logical-block.  Also, the consequences of
executing pprint-if-list-exhausted outside of the dynamic extent of the
pprint-logical-block which lexically contains it are undefined.

See Also::
..........

*note pprint-logical-block:: , *note pprint-pop:: .


File: gcl.info,  Node: pprint-fill,  Next: pprint-indent,  Prev: pprint-exit-if-list-exhausted,  Up: Printer Dictionary

22.4.5 pprint-fill, pprint-linear, pprint-tabular [Function]
------------------------------------------------------------

'pprint-fill' stream object &optional colon-p at-sign-p => nil

   'pprint-linear' stream object &optional colon-p at-sign-p => nil

   'pprint-tabular' stream object &optional colon-p at-sign-p tabsize =>
nil

Arguments and Values::
......................

stream--an output stream designator.

   object--an object.

   colon-p--a generalized boolean.  The default is true.

   at-sign-p--a generalized boolean.  The default is
implementation-dependent.

   tabsize--a non-negative integer.  The default is 16.

Description::
.............

The functions pprint-fill, pprint-linear, and pprint-tabular specify
particular ways of pretty printing a list to stream.  Each function
prints parentheses around the output if and only if colon-p is true.
Each function ignores its at-sign-p argument.  (Both arguments are
included even though only one is needed so that these functions can be
used via ~/.../ and as set-pprint-dispatch functions, as well as
directly.)  Each function handles abbreviation and the detection of
circularity and sharing correctly, and uses write to print object when
it is a non-list.

   If object is a list and if the value of *print-pretty* is false, each
of these functions prints object using a minimum of whitespace, as
described in *note Printing Lists and Conses::.  Otherwise (if object is
a list and if the value of *print-pretty* is true):

*
     The function pprint-linear prints a list either all on one line, or
     with each element on a separate line.

*
     The function pprint-fill prints a list with as many elements as
     possible on each line.

*
     The function pprint-tabular is the same as pprint-fill except that
     it prints the elements so that they line up in columns.  The
     tabsize specifies the column spacing in ems, which is the total
     spacing from the leading edge of one column to the leading edge of
     the next.

Examples::
..........

Evaluating the following with a line length of 25 produces the output
shown.

     (progn (princ "Roads ")
            (pprint-tabular *standard-output* '(elm main maple center) nil nil 8))
     Roads ELM     MAIN
           MAPLE   CENTER

Side Effects::
..............

Performs output to the indicated stream.

Affected By::
.............

The cursor position on the indicated stream, if it can be determined.

Notes::
.......

The function pprint-tabular could be defined as follows:

     (defun pprint-tabular (s list &optional (colon-p t) at-sign-p (tabsize nil))
       (declare (ignore at-sign-p))
       (when (null tabsize) (setq tabsize 16))
       (pprint-logical-block (s list :prefix (if colon-p "(" "")
                                     :suffix (if colon-p ")" ""))
         (pprint-exit-if-list-exhausted)
         (loop (write (pprint-pop) :stream s)
               (pprint-exit-if-list-exhausted)
               (write-char #\Space s)
               (pprint-tab :section-relative 0 tabsize s)
               (pprint-newline :fill s))))

   Note that it would have been inconvenient to specify this function
using format, because of the need to pass its tabsize argument through
to a ~:T format directive nested within an iteration over a list.


File: gcl.info,  Node: pprint-indent,  Next: pprint-logical-block,  Prev: pprint-fill,  Up: Printer Dictionary

22.4.6 pprint-indent [Function]
-------------------------------

'pprint-indent' relative-to n &optional stream => nil

Arguments and Values::
......................

relative-to--either :block or :current.

   n--a real.

   stream--an output stream designator.  The default is standard output.

Description::
.............

pprint-indent specifies the indentation to use in a logical block on
stream.

   If stream is a pretty printing stream and the value of *print-pretty*
is true, pprint-indent sets the indentation in the innermost dynamically
enclosing logical block; otherwise, pprint-indent has no effect.

   N specifies the indentation in ems.  If relative-to is :block, the
indentation is set to the horizontal position of the first character in
the dynamically current logical block plus n ems.  If relative-to is
:current, the indentation is set to the current output position plus n
ems.  (For robustness in the face of variable-width fonts, it is
advisable to use :current with an n of zero whenever possible.)

   N can be negative; however, the total indentation cannot be moved
left of the beginning of the line or left of the end of the rightmost
per-line prefix--an attempt to move beyond one of these limits is
treated the same as an attempt to move to that limit.  Changes in
indentation caused by pprint-indent do not take effect until after the
next line break.  In addition, in miser mode all calls to pprint-indent
are ignored, forcing the lines corresponding to the logical block to
line up under the first character in the block.

Exceptional Situations::
........................

An error is signaled if relative-to is any object other than :block or
:current.

See Also::
..........

*note Tilde I-> Indent::


File: gcl.info,  Node: pprint-logical-block,  Next: pprint-newline,  Prev: pprint-indent,  Up: Printer Dictionary

22.4.7 pprint-logical-block [Macro]
-----------------------------------

'pprint-logical-block' (stream-symbol object &key prefix per-line-prefix
suffix) {declaration}* {form}*
=> nil

Arguments and Values::
......................

stream-symbol--a stream variable designator.

   object--an object; evaluated.

   :prefix--a string; evaluated. 	Complicated defaulting behavior; see
below.

   :per-line-prefix--a string; evaluated. 	Complicated defaulting
behavior; see below.

   :suffix--a string; evaluated. 	The default is the null string.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

Description::
.............

Causes printing to be grouped into a logical block.

   The logical block is printed to the stream that is the value of the
variable denoted by stream-symbol.  During the execution of the forms,
that variable is bound to a pretty printing stream that supports
decisions about the arrangement of output and then forwards the output
to the destination stream.

   All the standard printing functions (e.g., write, princ, and terpri)
can be used to print output to the pretty printing stream.  All and only
the output sent to this pretty printing stream is treated as being in
the logical block.

   The prefix specifies a prefix to be printed before the beginning of
the logical block.  The per-line-prefix 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 arguments are mutually
exclusive.  If neither :prefix nor :per-line-prefix is specified, a
prefix of the null string is assumed.

   The suffix specifies a suffix that is printed just after the logical
block.

   The object is normally a list that the body forms are responsible for
printing.  If object is not a list, it is printed using write.  (This
makes it easier to write printing functions that are robust in the face
of malformed arguments.)  If *print-circle* is non-nil and object is a
circular (or shared) reference to a cons, then an appropriate "#n#"
marker is printed.  (This makes it easy to write printing functions that
provide full support for circularity and sharing abbreviation.)  If
*print-level* is not nil and the logical block is at a dynamic nesting
depth of greater than *print-level* in logical blocks, "#" is printed.
(This makes easy to write printing functions that provide full support
for depth abbreviation.)

   If either of the three conditions above occurs, the indicated output
is printed on stream-symbol and the body forms are skipped along with
the printing of the :prefix and :suffix.  (If the body forms are not to
be responsible for printing a list, then the first two tests above can
be turned off by supplying nil for the object argument.)

   In addition to the object argument of pprint-logical-block, the
arguments of the standard printing functions (such as write, print,
prin1, and pprint, as well as the arguments of the standard format
directives 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 write-line, write-string, and write-char or
to the literal text output by format.  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.

   The body forms of a pprint-logical-block form must not perform any
side-effects on the surrounding environment; for example, no variables
must be assigned which have not been bound within its scope.

   The pprint-logical-block macro may be used regardless of the value of
*print-pretty*.

Affected By::
.............

*print-circle*, *print-level*.

Exceptional Situations::
........................

An error of type type-error is signaled if any of the :suffix, :prefix,
or :per-line-prefix is supplied but does not evaluate to a string.

   An error is signaled if :prefix and :pre-line-prefix are both used.

   pprint-logical-block and the pretty printing stream it creates have
dynamic extent.  The consequences are undefined if, outside of this
extent, output is attempted to the pretty printing stream it creates.

   It is also unspecified what happens if, within this extent, any
output is sent directly to the underlying destination stream.

See Also::
..........

*note pprint-pop:: , *note pprint-exit-if-list-exhausted:: , *note Tilde
Less-Than-Sign-> Logical Block::

Notes::
.......

One reason for using the pprint-logical-block macro when the value of
*print-pretty* is nil would be to allow it to perform checking for
dotted lists, as well as (in conjunction with pprint-pop) checking for
*print-level* or *print-length* being exceeded.

   Detection of circularity and sharing is supported by the pretty
printer 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 "#n="
and "#n#" markers are inserted and characters are output.  This is why
the restriction on side-effects is necessary.  Obeying this restriction
is facilitated by using pprint-pop, instead of an ordinary pop when
traversing a list being printed by the body forms of the
pprint-logical-block form.)


File: gcl.info,  Node: pprint-newline,  Next: pprint-pop,  Prev: pprint-logical-block,  Up: Printer Dictionary

22.4.8 pprint-newline [Function]
--------------------------------

'pprint-newline' kind &optional stream => nil

Arguments and Values::
......................

kind--one of :linear, :fill, :miser, or :mandatory.

   stream--a stream designator.  The default is standard output.

Description::
.............

If stream is a pretty printing stream and the value of *print-pretty* is
true, a line break is inserted in the output when the appropriate
condition below is satisfied; otherwise, pprint-newline has no effect.

   Kind specifies the style of conditional newline.  This parameter is
treated as follows:

:linear
     This specifies a "linear-style" conditional newline.

     A line break is inserted if and only if the immediately containing
     section cannot be printed on one line.  The effect of this is that
     line breaks are either inserted at every linear-style conditional
     newline in a logical block or at none of them.

:miser
     This specifies a "miser-style" conditional newline.

     A line break is inserted if and only if the immediately containing
     section cannot be printed on one line and miser style is in effect
     in the immediately containing logical block.  The effect of this is
     that miser-style conditional newlines act like linear-style
     conditional newlines, but only when miser style is in effect.
     Miser style is in effect for a logical block if and only if the
     starting position of the logical block is less than or equal to
     *print-miser-width* ems from the right margin.

:fill
     This specifies a "fill-style" conditional newline.

     A line break is inserted if and only if either (a) the following
     section cannot be printed on the end of the current line, (b) the
     preceding section was not printed on a single line, or (c) the
     immediately containing section cannot be printed on one line and
     miser style is in effect in the immediately containing logical
     block.  If a logical block is broken up into a number of
     subsections by fill-style conditional newlines, the basic effect is
     that the logical block is printed with as many subsections as
     possible on each line.  However, if miser style is in effect,
     fill-style conditional newlines act like linear-style conditional
     newlines.

:mandatory
     This specifies a "mandatory-style" conditional newline.

     A line break is always inserted.  This implies that none of the
     containing sections can be printed on a single line and will
     therefore trigger the insertion of line breaks at linear-style
     conditional newlines in these sections.

   When a line break is inserted by any type of conditional newline, any
blanks that immediately precede the conditional newline are omitted from
the output and indentation is introduced at the beginning of the next
line.  By default, the indentation causes the following line to begin in
the same horizontal position as the first character in the immediately
containing logical block.  (The indentation can be changed via
pprint-indent.)

   There are a variety of ways unconditional newlines can be introduced
into the output (i.e., via terpri or by printing a string containing a
newline character).  As with mandatory conditional newlines, this
prevents any of the containing sections from being printed on one line.
In general, when an unconditional newline is encountered, it is printed
out without suppression of the preceding blanks and without any
indentation following it.  However, if a per-line prefix has been
specified (see pprint-logical-block), this prefix will always be printed
no matter how a newline originates.

Examples::
..........

See *note Examples of using the Pretty Printer::.

Side Effects::
..............

Output to stream.

Affected By::
.............

*print-pretty*, *print-miser*.  The presence of containing logical
blocks.  The placement of newlines and conditional newlines.

Exceptional Situations::
........................

An error of type type-error is signaled if kind is not one of :linear,
:fill, :miser, or :mandatory.

See Also::
..........

*note Tilde Underscore-> Conditional Newline::, *note Examples of using
the Pretty Printer::


File: gcl.info,  Node: pprint-pop,  Next: pprint-tab,  Prev: pprint-newline,  Up: Printer Dictionary

22.4.9 pprint-pop [Local Macro]
-------------------------------

Syntax::
........

'pprint-pop' <no arguments> => object

Arguments and Values::
......................

object--an element of the list being printed in the lexically current
logical block, or nil.

Description::
.............

Pops one element from the list being printed in the lexically current
logical block, obeying *print-length* and *print-circle* as described
below.

   Each time pprint-pop is called, it pops the next value off the list
passed to the lexically current logical block and returns it.  However,
before doing this, it performs three tests:

*
     If the remaining 'list' is not a list, ". " is printed followed by
     the remaining 'list.'  (This makes it easier to write printing
     functions that are robust in the face of malformed arguments.)

*
     If *print-length* is non-nil, and pprint-pop has already been
     called *print-length* times within the immediately containing
     logical block, "..." is printed.  (This makes it easy to write
     printing functions that properly handle *print-length*.)

*
     If *print-circle* is non-nil, and the remaining list is a circular
     (or shared) reference, then ". " is printed followed by an
     appropriate "#n#" marker.  (This catches instances of cdr
     circularity and sharing in lists.)

   If either of the three conditions above occurs, the indicated output
is printed on the pretty printing stream created by the immediately
containing pprint-logical-block and the execution of the immediately
containing pprint-logical-block is terminated except for the printing of
the suffix.

   If pprint-logical-block is given a 'list' argument of nil--because it
is not processing a list--pprint-pop can still be used to obtain support
for *print-length*.  In this situation, the first and third tests above
are disabled and pprint-pop always returns nil.  See *note Examples of
using the Pretty Printer::--specifically, the pprint-vector example.

   Whether or not pprint-pop is fbound in the global environment is
implementation-dependent; however, the restrictions on redefinition and
shadowing of pprint-pop are the same as for symbols in the COMMON-LISP
package which are fbound in the global environment.  The consequences of
attempting to use pprint-pop outside of pprint-logical-block are
undefined.

Side Effects::
..............

Might cause output to the pretty printing stream associated with the
lexically current logical block.

Affected By::
.............

*print-length*, *print-circle*.

Exceptional Situations::
........................

An error is signaled (either at macro expansion time or at run time) if
a usage of pprint-pop occurs where there is no lexically containing
pprint-logical-block form.

   The consequences are undefined if pprint-pop is executed outside of
the dynamic extent of this pprint-logical-block.

See Also::
..........

*note pprint-exit-if-list-exhausted:: , *note pprint-logical-block:: .

Notes::
.......

It is frequently a good idea to call pprint-exit-if-list-exhausted
before calling pprint-pop.


File: gcl.info,  Node: pprint-tab,  Next: print-object,  Prev: pprint-pop,  Up: Printer Dictionary

22.4.10 pprint-tab [Function]
-----------------------------

'pprint-tab' kind colnum colinc &optional stream => nil

Arguments and Values::
......................

kind--one of :line, :section, :line-relative, or :section-relative.

   colnum--a non-negative integer.

   colinc--a non-negative integer.

   stream--an output stream designator.

Description::
.............

Specifies tabbing to stream as performed by the standard ~T format
directive.

   If stream is a pretty printing stream and the value of *print-pretty*
is true,

   tabbing is performed; otherwise, pprint-tab has no effect.

   The arguments colnum and colinc correspond to the two parameters to
~T and are in terms of ems.  The kind argument specifies the style of
tabbing.  It must be one of :line (tab as by ~T), :section (tab as by
~:T, but measuring horizontal positions relative to the start of the
dynamically enclosing section), :line-relative (tab as by ~@T), or
:section-relative (tab as by ~:@T, but measuring horizontal positions
relative to the start of the dynamically enclosing section).

Exceptional Situations::
........................

An error is signaled if kind is not one of :line, :section,
:line-relative, or :section-relative.

See Also::
..........

*note pprint-logical-block::


File: gcl.info,  Node: print-object,  Next: print-unreadable-object,  Prev: pprint-tab,  Up: Printer Dictionary

22.4.11 print-object [Standard Generic Function]
------------------------------------------------

Syntax::
........

'print-object' object stream => object

Method Signatures::
...................

'print-object' (object standard-object) stream

   'print-object' (object structure-object) stream

Arguments and Values::
......................

object--an object.

   stream--a stream.

Description::
.............

The generic function print-object writes the printed representation of
object to stream.  The function print-object is called by the Lisp
printer; it should not be called by the user.

   Each implementation is required to provide a method on the class
standard-object and on the class structure-object.  In addition, each
implementation must provide methods on enough other classes so as to
ensure that there is always an applicable method.  Implementations are
free to add methods for other classes.  Users may write methods for
print-object for their own classes if they do not wish to inherit an
implementation-dependent method.

   The method on the class structure-object prints the object in the
default #S notation; see *note Printing Structures::.

   Methods on print-object are responsible for implementing their part
of the semantics of the printer control variables, as follows:

*print-readably*
     All methods for print-object must obey *print-readably*.  This
     includes both user-defined methods and implementation-defined
     methods.  Readable printing of structures and standard objects is
     controlled by their print-object method, not by their
     make-load-form method.  Similarity for these objects is application
     dependent and hence is defined to be whatever these methods do; see
     *note Similarity of Literal Objects::.

*print-escape*
     Each method must implement *print-escape*.

*print-pretty*

     The method may wish to perform specialized line breaking or other
     output conditional on the value of *print-pretty*.  For further
     information, see (for example) the macro pprint-fill.  See also
     *note Pretty Print Dispatch Tables:: and *note Examples of using
     the Pretty Printer::.

*print-length*
     Methods that produce output of indefinite length must obey
     *print-length*.

     For further information, see (for example) the macros
     pprint-logical-block and pprint-pop.  See also *note Pretty Print
     Dispatch Tables:: and *note Examples of using the Pretty Printer::.

*print-level*
     The printer takes care of *print-level* automatically, provided
     that each method handles exactly one level of structure and calls
     write (or an equivalent function) recursively if there are more
     structural levels.  The printer's decision of whether an object has
     components (and therefore should not be printed when the printing
     depth is not less than *print-level*) is implementation-dependent.
     In some implementations its print-object method is not called; in
     others the method is called, and the determination that the object
     has components is based on what it tries to write to the stream.

*print-circle*

     When the value of *print-circle* is true, a user-defined

     print-object method

     can print objects to the supplied stream using write, prin1, princ,
     or format and expect circularities to be detected and printed using
     the #n# syntax.  If a user-defined

     print-object method

     prints to a stream other than the one that was supplied, then
     circularity detection starts over for that stream.  See
     *print-circle*.

*print-base*,
     *print-radix*, *print-case*, *print-gensym*, and *print-array*
     These printer control variables apply to specific types of objects
     and are handled by the methods for those 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 implementation-dependent.

   In some implementations the stream argument passed to a print-object
method is not the original stream, but is an intermediate stream that
implements part of the printer.  methods should therefore not depend on
the identity of this stream.

See Also::
..........

*note pprint-fill:: , *note pprint-logical-block:: , *note pprint-pop::
, *note write:: , *print-readably*, *print-escape*, *print-pretty*,
*print-length*, *note Default Print-Object Methods::,

   *note Printing Structures::,

   *note Pretty Print Dispatch Tables::, *note Examples of using the
Pretty Printer::


File: gcl.info,  Node: print-unreadable-object,  Next: set-pprint-dispatch,  Prev: print-object,  Up: Printer Dictionary

22.4.12 print-unreadable-object [Macro]
---------------------------------------

'print-unreadable-object' (object stream &key type identity) {form}* =>
nil

Arguments and Values::
......................

object--an object; evaluated.

   stream-- a stream designator; evaluated.

   type--a generalized boolean; evaluated.

   identity--a generalized boolean; evaluated.

   forms--an implicit progn.

Description::
.............

Outputs a printed representation of object on stream, beginning with
"#<" and ending with ">".  Everything output to stream by the body forms
is enclosed in the the angle brackets.  If type is true, the output from
forms is preceded by a brief description of the object's type and a
space character.  If identity is true, the output from forms is followed
by a space character and a representation of the object's identity,
typically a storage address.

   If either type or identity is not supplied, its value is false.  It
is valid to omit the body forms.  If type and identity are both true and
there are no body forms, only one space character separates the type and
the identity.

Examples::
..........

;; Note that in this example, the precise form of the output ;; is
implementation-dependent.

      (defmethod print-object ((obj airplane) stream)
        (print-unreadable-object (obj stream :type t :identity t)
          (princ (tail-number obj) stream)))

      (prin1-to-string my-airplane)
     =>  "#<Airplane NW0773 36000123135>"
     OR=> "#<FAA:AIRPLANE NW0773 17>"

Exceptional Situations::
........................

If *print-readably* is true, print-unreadable-object signals an error of
type print-not-readable without printing anything.


File: gcl.info,  Node: set-pprint-dispatch,  Next: write,  Prev: print-unreadable-object,  Up: Printer Dictionary

22.4.13 set-pprint-dispatch [Function]
--------------------------------------

'set-pprint-dispatch' type-specifier function &optional priority table
=> nil

Arguments and Values::
......................

type-specifier--a type specifier.

   function--a function, a function name, or nil.

   priority--a real.  The default is 0.

   table--a pprint dispatch table.  The default is the value of
*print-pprint-dispatch*.

Description::
.............

Installs an entry into the pprint dispatch table which is table.

   Type-specifier is the key of the entry.  The first action of
set-pprint-dispatch is to remove any pre-existing entry associated with
type-specifier.  This guarantees that there will never be two entries
associated with the same type specifier in a given pprint dispatch
table.  Equality of type specifiers is tested by equal.

   Two values are associated with each type specifier in a pprint
dispatch table: a function and a priority.  The function must accept two
arguments: the stream to which output is sent and the object to be
printed.  The function should pretty print the object to the stream.
The function can assume that object satisfies the type given by
type-specifier.  The function must obey *print-readably*.  Any values
returned by the function are ignored.

   Priority is a priority to resolve conflicts when an object matches
more than one entry.

   It is permissible for function to be nil.  In this situation, there
will be no type-specifier entry in table after set-pprint-dispatch
returns.

Exceptional Situations::
........................

An error is signaled if priority is not a real.

Notes::
.......

Since pprint dispatch tables are often used to control the pretty
printing of Lisp code, it is common for the type-specifier to be an
expression of the form

      (cons car-type cdr-type)

   This signifies that the corresponding object must be a cons cell
whose car matches the type specifier car-type and whose cdr matches the
type specifier cdr-type.  The cdr-type can be omitted in which case it
defaults to t.


File: gcl.info,  Node: write,  Next: write-to-string,  Prev: set-pprint-dispatch,  Up: Printer Dictionary

22.4.14 write, prin1, print, pprint, princ [Function]
-----------------------------------------------------

'write' object &key \writekeysstream
=> object

   'prin' 1 => 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 object.

   output-stream--an output stream designator. 	The default is standard
output.

   \writekeydescriptionsstream--an output stream designator.  The
default is 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 Lisp printer.  For each
explicitly supplied keyword parameter named in Figure 22-6, the
corresponding printer control variable is dynamically bound to its value
while printing goes on; for each keyword parameter in Figure 22-6 that
is not explicitly supplied, the value of the corresponding printer
control variable is the same as it was at the time write was invoked.
Once the appropriate bindings are established, the object is output by
the Lisp printer.

  Parameter        Corresponding Dynamic Variable  
  array            *print-array*                   
  base             *print-base*                    
  case             *print-case*                    
  circle           *print-circle*                  
  escape           *print-escape*                  
  gensym           *print-gensym*                  
  length           *print-length*                  
  level            *print-level*                   
  lines            *print-lines*                   
  miser-width      *print-miser-width*             
  pprint-dispatch  *print-pprint-dispatch*         
  pretty           *print-pretty*                  
  radix            *print-radix*                   
  readably         *print-readably*                
  right-margin     *print-right-margin*            

  Figure 22-6: Argument correspondences for the WRITE function.


   prin1, princ, print, and pprint implicitly bind certain print
parameters to particular values.  The remaining parameter values are
taken from *print-array*, *print-base*, *print-case*, *print-circle*,
*print-escape*, *print-gensym*, *print-length*, *print-level*,
*print-lines*, *print-miser-width*, *print-pprint-dispatch*,
*print-pretty*, *print-radix*, and *print-right-margin*.

   prin1 produces output suitable for input to read.  It binds
*print-escape* to true.

   princ is just like prin1 except that the output has no escape
characters.  It binds *print-escape* to false

   and *print-readably* to 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 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 *print-pretty* flag non-nil to produce
pretty output.

   Output-stream specifies the stream to which output is to be sent.

Affected By::
.............

*standard-output*, *terminal-io*, *print-escape*, *print-radix*,
*print-base*, *print-circle*, *print-pretty*, *print-level*,
*print-length*, *print-case*, *print-gensym*, *print-array*,
*read-default-float-format*.

See Also::
..........

*note readtable-case:: , *note FORMAT Printer Operations::

Notes::
.......

The functions prin1 and print do not bind *print-readably*.

      (prin1 object output-stream)
     == (write object :stream output-stream :escape t)

      (princ object output-stream)
     == (write object stream output-stream :escape nil :readably nil)

      (print object output-stream)
     == (progn (terpri output-stream)
                (write object :stream output-stream
                              :escape t)
                (write-char #\space output-stream))

      (pprint object output-stream)
     == (write object :stream output-stream :escape t :pretty t)


File: gcl.info,  Node: write-to-string,  Next: *print-array*,  Prev: write,  Up: Printer Dictionary

22.4.15 write-to-string, prin1-to-string, princ-to-string [Function]
--------------------------------------------------------------------

'write-to-string' object &key \writekeys
=> string

   'prin' 1 => -to-string object string

   'princ-to-string' object => string

Arguments and Values::
......................

object--an object.

   \writekeydescriptions

   string--a string.

Description::
.............

write-to-string, prin1-to-string, and princ-to-string are used to create
a string consisting of the printed representation of object.  Object is
effectively printed as if by write, prin1, or princ, respectively, and
the characters that would be output are made into a string.

   write-to-string is the general output function.  It has the ability
to specify all the parameters applicable to the printing of object.

   prin1-to-string acts like write-to-string with :escape t, that is,
escape characters are written where appropriate.

   princ-to-string acts like write-to-string with

   :escape nil :readably nil.

   Thus no escape characters are written.

   All other keywords that would be specified to write-to-string are
default values when prin1-to-string or princ-to-string is invoked.

   The meanings and defaults for the keyword arguments to
write-to-string are the same as those for write.

Examples::
..........

      (prin1-to-string "abc") =>  "\"abc\""
      (princ-to-string "abc") =>  "abc"

Affected By::
.............

*print-escape*, *print-radix*, *print-base*, *print-circle*,
*print-pretty*, *print-level*, *print-length*, *print-case*,
*print-gensym*, *print-array*, *read-default-float-format*.

See Also::
..........

*note write::

Notes::
.......

      (write-to-string object {key argument}*)
     == (with-output-to-string (#1=#:string-stream)
          (write object :stream #1# {key argument}*))

      (princ-to-string object)
     == (with-output-to-string (string-stream)
          (princ object string-stream))

      (prin1-to-string object)
     == (with-output-to-string (string-stream)
          (prin1 object string-stream))


File: gcl.info,  Node: *print-array*,  Next: *print-base*,  Prev: write-to-string,  Up: Printer Dictionary

22.4.16 *print-array* [Variable]
--------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

implementation-dependent.

Description::
.............

Controls the format in which arrays are printed.  If it is false, the
contents of arrays other than strings are never printed.  Instead,
arrays are printed in a concise form using #< that gives enough
information for the user to be able to identify the array, but does not
include the entire array contents.  If it is true, non-string arrays are
printed using #(...), #*, or #nA syntax.

Affected By::
.............

The implementation.

See Also::
..........

*note Sharpsign Left-Parenthesis::, *note Sharpsign Less-Than-Sign::


File: gcl.info,  Node: *print-base*,  Next: *print-case*,  Prev: *print-array*,  Up: Printer Dictionary

22.4.17 *print-base*, *print-radix* [Variable]
----------------------------------------------

Value Type::
............

*print-base*--a radix.  *print-radix*--a generalized boolean.

Initial Value::
...............

The initial value of *print-base* is 10.  The initial value of
*print-radix* is false.

Description::
.............

*print-base* and *print-radix* control the printing of rationals.  The
value of *print-base* is called the current output base .

   The value of *print-base* is the radix in which the printer will
print rationals.  For radices above 10, letters of the alphabet are used
to represent digits above 9.

   If the value of *print-radix* is true, the printer will print a radix
specifier to indicate the radix in which it is printing a rational
number.  The radix specifier is always printed using lowercase letters.
If *print-base* is 2, 8, or 16, then the radix specifier used is #b, #o,
or #x, respectively.  For integers, base ten is indicated by a trailing
decimal point instead of a leading radix specifier; for ratios, #10r is
used.

Examples::
..........

      (let ((*print-base* 24.) (*print-radix* t))
        (print 23.))
      |>  #24rN
     =>  23
      (setq *print-base* 10) =>  10
      (setq *print-radix* nil) =>  NIL
      (dotimes (i 35)
         (let ((*print-base* (+ i 2)))           ;print the decimal number 40
           (write 40)                            ;in each base from 2 to 36
           (if (zerop (mod i 10)) (terpri) (format t " "))))
      |>  101000
      |>  1111 220 130 104 55 50 44 40 37 34
      |>  31 2C 2A 28 26 24 22 20 1J 1I
      |>  1H 1G 1F 1E 1D 1C 1B 1A 19 18
      |>  17 16 15 14
     =>  NIL
      (dolist (pb '(2 3 8 10 16))
         (let ((*print-radix* t)                 ;print the integer 10 and
               (*print-base* pb))                ;the ratio 1/10 in bases 2,
          (format t "~&~S  ~S~
      |>  #b1010  #b1/1010
      |>  #3r101  #3r1/101
      |>  #o12  #o1/12
      |>  10.  #10r1/10
      |>  #xA  #x1/A
     =>  NIL

Affected By::
.............

Might be bound by format, and write, write-to-string.

See Also::
..........

*note format:: , *note write:: , *note write-to-string::


File: gcl.info,  Node: *print-case*,  Next: *print-circle*,  Prev: *print-base*,  Up: Printer Dictionary

22.4.18 *print-case* [Variable]
-------------------------------

Value Type::
............

One of the symbols :upcase, :downcase, or :capitalize.

Initial Value::
...............

The symbol :upcase.

Description::
.............

The value of *print-case* controls the case (upper, lower, or mixed) in
which to print any uppercase characters in the names of symbols when
vertical-bar syntax is not used.

   *print-case* has an effect at all times when the value of
*print-escape* is false.  *print-case* also has an effect when the value
of *print-escape* is true unless inside an escape context (i.e., unless
between vertical-bars or after a slash).

Examples::
..........

      (defun test-print-case ()
        (dolist (*print-case* '(:upcase :downcase :capitalize))
          (format t "~&~S ~S~
     =>  TEST-PC
     ;; Although the choice of which characters to escape is specified by
     ;; *PRINT-CASE*, the choice of how to escape those characters
     ;; (i.e., whether single escapes or multiple escapes are used)
     ;; is implementation-dependent.  The examples here show two of the
     ;; many valid ways in which escaping might appear.
      (test-print-case) ;Implementation A
      |>  THIS-AND-THAT |And-something-elSE|
      |>  this-and-that a\n\d-\s\o\m\e\t\h\i\n\g-\e\lse
      |>  This-And-That A\n\d-\s\o\m\e\t\h\i\n\g-\e\lse
     =>  NIL
      (test-print-case) ;Implementation B
      |>  THIS-AND-THAT |And-something-elSE|
      |>  this-and-that a|nd-something-el|se
      |>  This-And-That A|nd-something-el|se
     =>  NIL

See Also::
..........

*note write::

Notes::
.......

read normally converts lowercase characters appearing in symbols to
corresponding uppercase characters, so that internally print names
normally contain only uppercase characters.

   If *print-escape* is true, lowercase characters in the name of a
symbol are always printed in lowercase, and are preceded by a single
escape character or enclosed by multiple escape characters; uppercase
characters in the name of a symbol are printed in upper case, in lower
case, or in mixed case so as to capitalize words, according to the value
of *print-case*.  The convention for what constitutes a "word" is the
same as for string-capitalize.


File: gcl.info,  Node: *print-circle*,  Next: *print-escape*,  Prev: *print-case*,  Up: Printer Dictionary

22.4.19 *print-circle* [Variable]
---------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

false.

Description::
.............

Controls the attempt to detect circularity and sharing in an object
being printed.

   If false, the printing process merely proceeds by recursive descent
without attempting to detect circularity and sharing.

   If true, the printer will endeavor to detect cycles and sharing in
the structure to be printed, and to use #n= and #n# syntax to indicate
the circularities or shared components.

   If true, a user-defined

   print-object method

   can print objects to the supplied stream using write, prin1, princ,
or format and expect circularities and sharing to be detected and
printed using the #n# syntax.

   If a user-defined

   print-object method

   prints to a stream other than the one that was supplied, then
circularity detection starts over for that stream.

   Note that implementations should not use #n# notation when the Lisp
reader would automatically assure sharing without it (e.g., as happens
with interned symbols).

Examples::
..........

      (let ((a (list 1 2 3)))
        (setf (cdddr a) a)
        (let ((*print-circle* t))
          (write a)
          :done))
      |>  #1=(1 2 3 . #1#)
     =>  :DONE

See Also::
..........

*note write::

Notes::
.......

An attempt to print a circular structure with *print-circle* set to nil
may lead to looping behavior and failure to terminate.


File: gcl.info,  Node: *print-escape*,  Next: *print-gensym*,  Prev: *print-circle*,  Up: Printer Dictionary

22.4.20 *print-escape* [Variable]
---------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

true.

Description::
.............

If false, escape characters and package prefixes are not output when an
expression is printed.

   If true, an attempt is made to print an expression in such a way that
it can be read again to produce an equal expression.  (This is only a
guideline; not a requirement.  See *print-readably*.)

   For more specific details of how the value of *print-escape* affects
the printing of certain types, see *note Default Print-Object Methods::.

Examples::
..........

      (let ((*print-escape* t)) (write #\a))
      |>  #\a
     =>  #\a
      (let ((*print-escape* nil)) (write #\a))
      |>  a
     =>  #\a

Affected By::
.............

princ, prin1, format

See Also::
..........

*note write:: , *note readtable-case::

Notes::
.......

princ effectively binds *print-escape* to false.  prin1 effectively
binds *print-escape* to true.


File: gcl.info,  Node: *print-gensym*,  Next: *print-level*,  Prev: *print-escape*,  Up: Printer Dictionary

22.4.21 *print-gensym* [Variable]
---------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

true.

Description::
.............

Controls whether the prefix "#:" is printed before apparently uninterned
symbols.  The prefix is printed before such symbols if and only if the
value of *print-gensym* is true.

Examples::
..........

      (let ((*print-gensym* nil))
        (print (gensym)))
      |>  G6040
     =>  #:G6040

See Also::
..........

*note write:: , *print-escape*


File: gcl.info,  Node: *print-level*,  Next: *print-lines*,  Prev: *print-gensym*,  Up: Printer Dictionary

22.4.22 *print-level*, *print-length* [Variable]
------------------------------------------------

Value Type::
............

a non-negative integer, or nil.

Initial Value::
...............

nil.

Description::
.............

*print-level* controls how many levels deep a nested object will print.
If it is false, then no control is exercised.  Otherwise, it is an
integer indicating the maximum level to be printed.  An object to be
printed is at level 0; its components (as of a list or vector) are at
level 1; and so on.  If an object to be recursively printed has
components and is at a level equal to or greater than the value of
*print-level*, then the object is printed as "#".

   *print-length* controls how many elements at a given level are
printed.  If it is false, there is no limit to the number of components
printed.  Otherwise, it is an integer indicating the maximum number of
elements of an object to be printed.  If exceeded, the printer will
print "..." in place of the other elements.  In the case of a dotted
list, if the list contains exactly as many elements as the value of
*print-length*, the terminating atom is printed rather than printing
"..."

   *print-level* and *print-length* affect the printing of an any object
printed with a list-like syntax.  They do not affect the printing of
symbols, strings, and bit vectors.

Examples::
..........

      (setq a '(1 (2 (3 (4 (5 (6))))))) =>  (1 (2 (3 (4 (5 (6))))))
      (dotimes (i 8)
        (let ((*print-level* i))
          (format t "~&~D -- ~S~
      |>  0 -- #
      |>  1 -- (1 #)
      |>  2 -- (1 (2 #))
      |>  3 -- (1 (2 (3 #)))
      |>  4 -- (1 (2 (3 (4 #))))
      |>  5 -- (1 (2 (3 (4 (5 #)))))
      |>  6 -- (1 (2 (3 (4 (5 (6))))))
      |>  7 -- (1 (2 (3 (4 (5 (6))))))
     =>  NIL

      (setq a '(1 2 3 4 5 6)) =>  (1 2 3 4 5 6)
      (dotimes (i 7)
        (let ((*print-length* i))
          (format t "~&~D -- ~S~
      |>  0 -- (...)
      |>  1 -- (1 ...)
      |>  2 -- (1 2 ...)
      |>  3 -- (1 2 3 ...)
      |>  4 -- (1 2 3 4 ...)
      |>  5 -- (1 2 3 4 5 6)
      |>  6 -- (1 2 3 4 5 6)
     =>  NIL

     (dolist (level-length '((0 1) (1 1) (1 2) (1 3) (1 4)
                             (2 1) (2 2) (2 3) (3 2) (3 3) (3 4)))
      (let ((*print-level*  (first  level-length))
            (*print-length* (second level-length)))
        (format t "~&~D ~D -- ~S~
                *print-level* *print-length*
                '(if (member x y) (+ (car x) 3) '(foo . #(a b c d "Baz"))))))
      |>  0 1 -- #
      |>  1 1 -- (IF ...)
      |>  1 2 -- (IF # ...)
      |>  1 3 -- (IF # # ...)
      |>  1 4 -- (IF # # #)
      |>  2 1 -- (IF ...)
      |>  2 2 -- (IF (MEMBER X ...) ...)
      |>  2 3 -- (IF (MEMBER X Y) (+ # 3) ...)
      |>  3 2 -- (IF (MEMBER X ...) ...)
      |>  3 3 -- (IF (MEMBER X Y) (+ (CAR X) 3) ...)
      |>  3 4 -- (IF (MEMBER X Y) (+ (CAR X) 3) '(FOO . #(A B C D ...)))
     =>  NIL

See Also::
..........

*note write::


File: gcl.info,  Node: *print-lines*,  Next: *print-miser-width*,  Prev: *print-level*,  Up: Printer Dictionary

22.4.23 *print-lines* [Variable]
--------------------------------

Value Type::
............

a non-negative integer, or nil.

Initial Value::
...............

nil.

Description::
.............

When the value of *print-lines* is other than nil, it is a limit on the
number of output lines produced when something is pretty printed.  If an
attempt is made to go beyond that many lines, ".." is printed at the end
of the last line followed by all of the suffixes (closing delimiters)
that are pending to be printed.

Examples::
..........

      (let ((*print-right-margin* 25) (*print-lines* 3))
        (pprint '(progn (setq a 1 b 2 c 3 d 4))))
      |>  (PROGN (SETQ A 1
      |>               B 2
      |>               C 3 ..))
     =>  <no values>

Notes::
.......

The ".." notation is intentionally different than the "..." notation
used for level abbreviation, so that the two different situations can be
visually distinguished.

   This notation is used to increase the likelihood that the Lisp reader
will signal an error if an attempt is later made to read the abbreviated
output.  Note however that if the truncation occurs in a string, as in
"This string has been trunc..", the problem situation cannot be detected
later and no such error will be signaled.


File: gcl.info,  Node: *print-miser-width*,  Next: *print-pprint-dispatch*,  Prev: *print-lines*,  Up: Printer Dictionary

22.4.24 *print-miser-width* [Variable]
--------------------------------------

Value Type::
............

a non-negative integer, or nil.

Initial Value::
...............

implementation-dependent

Description::
.............

If it is not nil, the pretty printer switches to a compact style of
output (called miser style) whenever the width available for printing a
substructure is less than or equal to this many ems.


File: gcl.info,  Node: *print-pprint-dispatch*,  Next: *print-pretty*,  Prev: *print-miser-width*,  Up: Printer Dictionary

22.4.25 *print-pprint-dispatch* [Variable]
------------------------------------------

Value Type::
............

a pprint dispatch table.

Initial Value::
...............

implementation-dependent, but the initial entries all use a special
class of priorities that have the property that they are less than every
priority that can be specified using set-pprint-dispatch, so that the
initial contents of any entry can be overridden.

Description::
.............

The pprint dispatch table which currently controls the pretty printer.

See Also::
..........

*print-pretty*, *note Pretty Print Dispatch Tables::

Notes::
.......

The intent is that the initial value of this variable should cause
'traditional' pretty printing of code.  In general, however, you can put
a value in *print-pprint-dispatch* that makes pretty-printed output look
exactly like non-pretty-printed output.

   Setting *print-pretty* to true just causes the functions contained in
the current pprint dispatch table to have priority over normal
print-object methods; it has no magic way of enforcing that those
functions actually produce pretty output.  For details, see *note Pretty
Print Dispatch Tables::.


File: gcl.info,  Node: *print-pretty*,  Next: *print-readably*,  Prev: *print-pprint-dispatch*,  Up: Printer Dictionary

22.4.26 *print-pretty* [Variable]
---------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

implementation-dependent.

Description::
.............

Controls whether the Lisp printer calls the pretty printer.

   If it is false, the pretty printer is not used and

   a minimum

   of whitespace_1 is output when printing an expression.

   If it is true, the pretty printer is used, and the Lisp printer will
endeavor to insert extra whitespace_1 where appropriate to make
expressions more readable.

   *print-pretty* has an effect even when the value of *print-escape* is
false.

Examples::
..........

      (setq *print-pretty* 'nil) =>  NIL
      (progn (write '(let ((a 1) (b 2) (c 3)) (+ a b c))) nil)
      |>  (LET ((A 1) (B 2) (C 3)) (+ A B C))
     =>  NIL
      (let ((*print-pretty* t))
        (progn (write '(let ((a 1) (b 2) (c 3)) (+ a b c))) nil))
      |>  (LET ((A 1)
      |>        (B 2)
      |>        (C 3))
      |>    (+ A B C))
     =>  NIL
     ;; Note that the first two expressions printed by this next form
     ;; differ from the second two only in whether escape characters are printed.
     ;; In all four cases, extra whitespace is inserted by the pretty printer.
      (flet ((test (x)
               (let ((*print-pretty* t))
                 (print x)
                 (format t "~
                 (terpri) (princ x) (princ " ")
                 (format t "~
       (test '#'(lambda () (list "a" #'c #'d))))
      |>  #'(LAMBDA ()
      |>      (LIST "a" #'C #'D))
      |>  #'(LAMBDA ()
      |>      (LIST "a" #'C #'D))
      |>  #'(LAMBDA ()
      |>      (LIST a b 'C #'D))
      |>  #'(LAMBDA ()
      |>      (LIST a b 'C #'D))
     =>  NIL

See Also::
..........

*note write::


File: gcl.info,  Node: *print-readably*,  Next: *print-right-margin*,  Prev: *print-pretty*,  Up: Printer Dictionary

22.4.27 *print-readably* [Variable]
-----------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

false.

Description::
.............

If *print-readably* is true, some special rules for printing objects go
into effect.  Specifically, printing any object O_1 produces a printed
representation that, when seen by the Lisp reader while the standard
readtable is in effect, will produce an object O_2 that is similar to
O_1.  The printed representation produced might or might not be the same
as the printed representation produced when *print-readably* is false.
If printing an object readably is not possible, an error of type
print-not-readable is signaled rather than using a syntax (e.g., the
"#<" syntax) that would not be readable by the same implementation.  If
the value of some other printer control variable is such that these
requirements would be violated, the value of that other variable is
ignored.

   Specifically, if *print-readably* is true, printing proceeds as if
*print-escape*, *print-array*, and *print-gensym* were also true, and as
if *print-length*, *print-level*, and *print-lines* were false.

   If *print-readably* is false, the normal rules for printing and the
normal interpretations of other printer control variables are in effect.

   Individual methods for print-object, including user-defined methods,
are responsible for implementing these requirements.

   If *read-eval* is false and *print-readably* is true, any such method
that would output a reference to the "#." reader macro will either
output something else or will signal an error (as described above).

Examples::
..........

      (let ((x (list "a" '\a (gensym) '((a (b (c))) d e f g)))
            (*print-escape* nil)
            (*print-gensym* nil)
            (*print-level* 3)
            (*print-length* 3))
        (write x)
        (let ((*print-readably* t))
          (terpri)
          (write x)
          :done))
      |>  (a a G4581 ((A #) D E ...))
      |>  ("a" |a| #:G4581 ((A (B (C))) D E F G))
     =>  :DONE

     ;; This is setup code is shared between the examples
     ;; of three hypothetical implementations which follow.
      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32005763>
      (setf (gethash table 1) 'one) =>  ONE
      (setf (gethash table 2) 'two) =>  TWO

     ;; Implementation A
      (let ((*print-readably* t)) (print table))
      Error: Can't print #<HASH-TABLE EQL 0/120 32005763> readably.

     ;; Implementation B
     ;; No standardized #S notation for hash tables is defined,
     ;; but there might be an implementation-defined notation.
      (let ((*print-readably* t)) (print table))
      |>  #S(HASH-TABLE :TEST EQL :SIZE 120 :CONTENTS (1 ONE 2 TWO))
     =>  #<HASH-TABLE EQL 0/120 32005763>

     ;; Implementation C
     ;; Note that #. notation can only be used if *READ-EVAL* is true.
     ;; If *READ-EVAL* were false, this same implementation might have to
     ;; signal an error unless it had yet another printing strategy to fall
     ;; back on.
      (let ((*print-readably* t)) (print table))
      |>  #.(LET ((HASH-TABLE (MAKE-HASH-TABLE)))
      |>      (SETF (GETHASH 1 HASH-TABLE) ONE)
      |>      (SETF (GETHASH 2 HASH-TABLE) TWO)
      |>      HASH-TABLE)
     =>  #<HASH-TABLE EQL 0/120 32005763>

See Also::
..........

*note write:: , *note print-unreadable-object::

Notes::
.......

The rules for "similarity" imply that #A or #( syntax cannot be used for
arrays of element type other than t.  An implementation will have to use
another syntax or signal an error of type print-not-readable.


File: gcl.info,  Node: *print-right-margin*,  Next: print-not-readable,  Prev: *print-readably*,  Up: Printer Dictionary

22.4.28 *print-right-margin* [Variable]
---------------------------------------

Value Type::
............

a non-negative integer, or nil.

Initial Value::
...............

nil.

Description::
.............

If it is non-nil, it specifies the right margin (as integer number of
ems) to use when the pretty printer is making layout decisions.

   If it is nil, the right margin is taken to be the maximum line length
such that output can be displayed without wraparound or truncation.  If
this cannot be determined, an implementation-dependent value is used.

Notes::
.......

This measure is in units of ems in order to be compatible with
implementation-defined variable-width fonts while still not requiring
the language to provide support for fonts.


File: gcl.info,  Node: print-not-readable,  Next: print-not-readable-object,  Prev: *print-right-margin*,  Up: Printer Dictionary

22.4.29 print-not-readable [Condition Type]
-------------------------------------------

Class Precedence List::
.......................

print-not-readable, error, serious-condition, condition, t

Description::
.............

The type print-not-readable consists of error conditions that occur
during output while *print-readably* is true, as a result of attempting
to write a printed representation with the Lisp printer that would not
be correctly read back with the Lisp reader.  The object which could not
be printed is initialized by the :object initialization argument to
make-condition, and is accessed by the function
print-not-readable-object.

See Also::
..........

*note print-not-readable-object::


File: gcl.info,  Node: print-not-readable-object,  Next: format,  Prev: print-not-readable,  Up: Printer Dictionary

22.4.30 print-not-readable-object [Function]
--------------------------------------------

'print-not-readable-object' condition => object

Arguments and Values::
......................

condition--a condition of type print-not-readable.

   object--an object.

Description::
.............

Returns the object that could not be printed readably in the situation
represented by condition.

See Also::
..........

print-not-readable, *note Conditions::


File: gcl.info,  Node: format,  Prev: print-not-readable-object,  Up: Printer Dictionary

22.4.31 format [Function]
-------------------------

'format' destination control-string &rest args => result

Arguments and Values::
......................

destination--nil, t, a stream, or a string with a fill pointer.

   control-string--a format control.

   args--format arguments for control-string.

   result--if destination is non-nil, then nil; otherwise, a string.

Description::
.............

format produces formatted output by outputting the characters of
control-string and observing that a tilde introduces a directive.  The
character after the tilde, possibly preceded by prefix parameters and
modifiers, specifies what kind of formatting is desired.  Most
directives use one or more elements of args to create their output.

   If destination is a string, a stream, or t, then the result is nil.
Otherwise, the result is a string containing the 'output.'

   format is useful for producing nicely formatted text, producing
good-looking messages, and so on.  format can generate and return a
string or output to destination.

   For details on how the control-string is interpreted, see *note
Formatted Output::.

Affected By::
.............

*standard-output*, *print-escape*, *print-radix*, *print-base*,
*print-circle*, *print-pretty*, *print-level*, *print-length*,
*print-case*, *print-gensym*, *print-array*.

Exceptional Situations::
........................

If destination is a string with a fill pointer, the consequences are
undefined if destructive modifications are performed directly on the
string during the dynamic extent of the call.

See Also::
..........

*note write:: , *note Documentation of Implementation-Defined Scripts::


File: gcl.info,  Node: Reader,  Next: System Construction,  Prev: Printer,  Up: Top

23 Reader
*********

* Menu:

* Reader Concepts::
* Reader Dictionary::


File: gcl.info,  Node: Reader Concepts,  Next: Reader Dictionary,  Prev: Reader,  Up: Reader

23.1 Reader Concepts
====================

* Menu:

* Dynamic Control of the Lisp Reader::
* Effect of Readtable Case on the Lisp Reader::
* Argument Conventions of Some Reader Functions::


File: gcl.info,  Node: Dynamic Control of the Lisp Reader,  Next: Effect of Readtable Case on the Lisp Reader,  Prev: Reader Concepts,  Up: Reader Concepts

23.1.1 Dynamic Control of the Lisp Reader
-----------------------------------------

Various aspects of the Lisp reader can be controlled dynamically.  See
*note Readtables:: and *note Variables that affect the Lisp Reader::.


File: gcl.info,  Node: Effect of Readtable Case on the Lisp Reader,  Next: Argument Conventions of Some Reader Functions,  Prev: Dynamic Control of the Lisp Reader,  Up: Reader Concepts

23.1.2 Effect of Readtable Case on the Lisp Reader
--------------------------------------------------

The readtable case of the current readtable affects the Lisp reader in
the following ways:

:upcase
     When the readtable case is :upcase, unescaped constituent
     characters are converted to uppercase, as specified in *note Reader
     Algorithm::.

:downcase
     When the readtable case is :downcase, unescaped constituent
     characters are converted to lowercase.

:preserve
     When the readtable case is :preserve, the case of all characters
     remains unchanged.

:invert
     When the readtable case is :invert, then if all of the unescaped
     letters in the extended token are of the same case, those
     (unescaped) letters are converted to the opposite case.

* Menu:

* Examples of Effect of Readtable Case on the Lisp Reader::


File: gcl.info,  Node: Examples of Effect of Readtable Case on the Lisp Reader,  Prev: Effect of Readtable Case on the Lisp Reader,  Up: Effect of Readtable Case on the Lisp Reader

23.1.2.1 Examples of Effect of Readtable Case on the Lisp Reader
................................................................

      (defun test-readtable-case-reading ()
        (let ((*readtable* (copy-readtable nil)))
          (format t "READTABLE-CASE  Input   Symbol-name~
                   ~
                   ~
          (dolist (readtable-case '(:upcase :downcase :preserve :invert))
            (setf (readtable-case *readtable*) readtable-case)
            (dolist (input '("ZEBRA" "Zebra" "zebra"))
              (format t "~&:~A~16T~A~24T~A"
                      (string-upcase readtable-case)
                      input
                      (symbol-name (read-from-string input)))))))

   The output from (test-readtable-case-reading) should be as follows:

      READTABLE-CASE     Input Symbol-name
      -------------------------------------
         :UPCASE         ZEBRA   ZEBRA
         :UPCASE         Zebra   ZEBRA
         :UPCASE         zebra   ZEBRA
         :DOWNCASE       ZEBRA   zebra
         :DOWNCASE       Zebra   zebra
         :DOWNCASE       zebra   zebra
         :PRESERVE       ZEBRA   ZEBRA
         :PRESERVE       Zebra   Zebra
         :PRESERVE       zebra   zebra
         :INVERT         ZEBRA   zebra
         :INVERT         Zebra   Zebra
         :INVERT         zebra   ZEBRA


File: gcl.info,  Node: Argument Conventions of Some Reader Functions,  Prev: Effect of Readtable Case on the Lisp Reader,  Up: Reader Concepts

23.1.3 Argument Conventions of Some Reader Functions
----------------------------------------------------

* Menu:

* The EOF-ERROR-P argument::
* The RECURSIVE-P argument::


File: gcl.info,  Node: The EOF-ERROR-P argument,  Next: The RECURSIVE-P argument,  Prev: Argument Conventions of Some Reader Functions,  Up: Argument Conventions of Some Reader Functions

23.1.3.1 The EOF-ERROR-P argument
.................................

Eof-error-p in input function calls controls what happens if input is
from a file (or any other input source that has a definite end) and the
end of the file is reached.  If eof-error-p is true (the default), an
error of type end-of-file is signaled at end of file.  If it is false,
then no error is signaled, and instead the function returns eof-value.

   Functions such as read that read the representation of an object
rather than a single character always signals an error, regardless of
eof-error-p, if the file ends in the middle of an object representation.
For example, if a file does not contain enough right parentheses to
balance the left parentheses in it, read signals an error.  If a file
ends in a symbol or a number immediately followed by end-of-file, read
reads the symbol or number successfully and when called again will act
according to eof-error-p.  Similarly, the function read-line
successfully reads the last line of a file even if that line is
terminated by end-of-file rather than the newline character.  Ignorable
text, such as lines containing only whitespace_2 or comments, are not
considered to begin an object; if read begins to read an expression but
sees only such ignorable text, it does not consider the file to end in
the middle of an object.  Thus an eof-error-p argument controls what
happens when the file ends between objects.


File: gcl.info,  Node: The RECURSIVE-P argument,  Prev: The EOF-ERROR-P argument,  Up: Argument Conventions of Some Reader Functions

23.1.3.2 The RECURSIVE-P argument
.................................

If recursive-p is supplied and not nil, it specifies that this function
call is not an outermost call to read but an embedded call, typically
from a reader macro function.  It is important to distinguish such
recursive calls for three reasons.

1.
     An outermost call establishes the context within which the #n= and
     #n# syntax is scoped.  Consider, for example, the expression

           (cons '#3=(p q r) '(x y . #3#))

     If the single-quote reader macro were defined in this way:

           (set-macro-character #\'       ;incorrect
              #'(lambda (stream char)
                   (declare (ignore char))
                   (list 'quote (read stream))))

     then each call to the single-quote reader macro function would
     establish independent contexts for the scope of read information,
     including the scope of identifications between markers like "#3="
     and "#3#".  However, for this expression, the scope was clearly
     intended to be determined by the outer set of parentheses, so such
     a definition would be incorrect.  The correct way to define the
     single-quote reader macro uses recursive-p:

           (set-macro-character #\'       ;correct
              #'(lambda (stream char)
                   (declare (ignore char))
                   (list 'quote (read stream t nil t))))

2.
     A recursive call does not alter whether the reading process is to
     preserve whitespace_2 or not (as determined by whether the
     outermost call was to read or read-preserving-whitespace).  Suppose
     again that single-quote were to be defined as shown above in the
     incorrect definition.  Then a call to read-preserving-whitespace
     that read the expression 'foo<Space> would fail to preserve the
     space character following the symbol foo because the single-quote
     reader macro function calls read, not read-preserving-whitespace,
     to read the following expression (in this case foo).  The correct
     definition, which passes the value true for recursive-p to read,
     allows the outermost call to determine whether whitespace_2 is
     preserved.

3.
     When end-of-file is encountered and the eof-error-p argument is not
     nil, the kind of error that is signaled may depend on the value of
     recursive-p.  If recursive-p is true, then the end-of-file is
     deemed to have occurred within the middle of a printed
     representation; if recursive-p is false, then the end-of-file may
     be deemed to have occurred between objects rather than within the
     middle of one.


File: gcl.info,  Node: Reader Dictionary,  Prev: Reader Concepts,  Up: Reader

23.2 Reader Dictionary
======================

* Menu:

* readtable::
* copy-readtable::
* make-dispatch-macro-character::
* read::
* read-delimited-list::
* read-from-string::
* readtable-case::
* readtablep::
* set-dispatch-macro-character::
* set-macro-character::
* set-syntax-from-char::
* with-standard-io-syntax::
* *read-base*::
* *read-default-float-format*::
* *read-eval*::
* *read-suppress*::
* *readtable*::
* reader-error::


File: gcl.info,  Node: readtable,  Next: copy-readtable,  Prev: Reader Dictionary,  Up: Reader Dictionary

23.2.1 readtable [System Class]
-------------------------------

Class Precedence List::
.......................

readtable, t

Description::
.............

A readtable maps characters into syntax types for the Lisp reader; see
*note Syntax::.  A readtable also contains associations between macro
characters and their reader macro functions, and records information
about the case conversion rules to be used by the Lisp reader when
parsing symbols.

   Each simple character must be representable in the readtable.  It is
implementation-defined whether non-simple characters can have syntax
descriptions in the readtable.

See Also::
..........

*note Readtables::, *note Printing Other Objects::


File: gcl.info,  Node: copy-readtable,  Next: make-dispatch-macro-character,  Prev: readtable,  Up: Reader Dictionary

23.2.2 copy-readtable [Function]
--------------------------------

'copy-readtable' &optional from-readtable to-readtable => readtable

Arguments and Values::
......................

from-readtable--a readtable designator.  The default is the current
readtable.

   to-readtable--a readtable or nil.  The default is nil.

   readtable--the to-readtable if it is non-nil, or else a fresh
readtable.

Description::
.............

copy-readtable copies from-readtable.

   If to-readtable is nil, a new readtable is created and returned.
Otherwise the readtable specified by to-readtable is modified and
returned.

   copy-readtable copies the setting of readtable-case.

Examples::
..........

      (setq zvar 123) =>  123
      (set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) =>  T
      zvar =>  123
      (copy-readtable table2 *readtable*) =>  #<READTABLE 614000277>
      zvar =>  VAR
      (setq *readtable* (copy-readtable)) =>  #<READTABLE 46210223>
      zvar =>  VAR
      (setq *readtable* (copy-readtable nil)) =>  #<READTABLE 46302670>
      zvar =>  123

See Also::
..........

readtable, *note readtable::

Notes::
.......

     (setq *readtable* (copy-readtable nil))

   restores the input syntax to standard Common Lisp syntax, even if the
initial readtable has been clobbered (assuming it is not so badly
clobbered that you cannot type in the above expression).

   On the other hand,

     (setq *readtable* (copy-readtable))

   replaces the current readtable with a copy of itself.  This is useful
if you want to save a copy of a readtable for later use, protected from
alteration in the meantime.  It is also useful if you want to locally
bind the readtable to a copy of itself, as in:

     (let ((*readtable* (copy-readtable))) ...)


File: gcl.info,  Node: make-dispatch-macro-character,  Next: read,  Prev: copy-readtable,  Up: Reader Dictionary

23.2.3 make-dispatch-macro-character [Function]
-----------------------------------------------

'make-dispatch-macro-character' char &optional non-terminating-p
readtable => t

Arguments and Values::
......................

char--a character.

   non-terminating-p--a generalized boolean.  The default is false.

   readtable--a readtable.  The default is the current readtable.

Description::
.............

make-dispatch-macro-character makes char be a dispatching macro
character in readtable.

   Initially, every character in the dispatch table associated with the
char has an associated function that signals an error of type
reader-error.

   If non-terminating-p is true, the dispatching macro character is made
a non-terminating macro character; if non-terminating-p is false, the
dispatching macro character is made a terminating macro character.

Examples::
..........

      (get-macro-character #\{) =>  NIL, false
      (make-dispatch-macro-character #\{) =>  T
      (not (get-macro-character #\{)) =>  false

   The readtable is altered.

See Also::
..........

*note readtable:: , *note set-dispatch-macro-character::


File: gcl.info,  Node: read,  Next: read-delimited-list,  Prev: make-dispatch-macro-character,  Up: Reader Dictionary

23.2.4 read, read-preserving-whitespace [Function]
--------------------------------------------------

'read' &optional input-stream eof-error-p eof-value recursive-p =>
object

   'read-preserving-whitespace' &optional input-stream eof-error-p
eof-value recursive-p
=> object

Arguments and Values::
......................

input-stream--an input stream designator.

   eof-error-p--a generalized boolean.  The default is true.

   eof-value--an object.

   The default is nil.

   recursive-p--a generalized boolean.  The default is false.

   object--an object (parsed by the Lisp reader) or the eof-value.

Description::
.............

read parses the printed representation of an object from input-stream
and builds such an object.

   read-preserving-whitespace is like read but preserves any
whitespace_2 character that delimits the printed representation of the
object.  read-preserving-whitespace is exactly like read when the
recursive-p argument to read-preserving-whitespace is true.

   When *read-suppress* is false, read throws away the delimiting
character required by certain printed representations if it is a
whitespace_2 character; but read preserves the character (using
unread-char) if it is syntactically meaningful, because it could be the
start of the next expression.

   If a file ends in a symbol or a number immediately followed by an end
of file_1, read reads the symbol or number successfully; when called
again, it sees the end of file_1 and only then acts according to
eof-error-p.  If a file contains ignorable text at the end, such as
blank lines and comments, read does not consider it to end in the middle
of an object.

   If recursive-p is true, the call to read is expected to be made from
within some function that itself has been called from read or from a
similar input function, rather than from the top level.

   Both functions return the object read from input-stream.  Eof-value
is returned if eof-error-p is false and end of file is reached before
the beginning of an object.

Examples::
..........

      (read)
      |>  |>>'a<<|
     =>  (QUOTE A)
      (with-input-from-string (is " ") (read is nil 'the-end)) =>  THE-END
      (defun skip-then-read-char (s c n)
         (if (char= c #\{) (read s t nil t) (read-preserving-whitespace s))
         (read-char-no-hang s)) =>  SKIP-THEN-READ-CHAR
      (let ((*readtable* (copy-readtable nil)))
         (set-dispatch-macro-character #\# #\{ #'skip-then-read-char)
         (set-dispatch-macro-character #\# #\} #'skip-then-read-char)
         (with-input-from-string (is "#{123 x #}123 y")
           (format t "~S ~S" (read is) (read is)))) =>  #\x, #\Space, NIL

   As an example, consider this reader macro definition:

      (defun slash-reader (stream char)
        (declare (ignore char))
        `(path . ,(loop for dir = (read-preserving-whitespace stream t nil t)
                        then (progn (read-char stream t nil t)
                                    (read-preserving-whitespace stream t nil t))
                        collect dir
                        while (eql (peek-char nil stream nil nil t) #\/))))
      (set-macro-character #\/ #'slash-reader)

   Consider now calling read on this expression:

      (zyedh /usr/games/zork /usr/games/boggle)

   The / macro reads objects separated by more / characters; thus
/usr/games/zork is intended to read as (path usr games zork).  The
entire example expression should therefore be read as

      (zyedh (path usr games zork) (path usr games boggle))

   However, if read had been used instead of read-preserving-whitespace,
then after the reading of the symbol zork, the following space would be
discarded; the next call to peek-char would see the following /, and the
loop would continue, producing this interpretation:

      (zyedh (path usr games zork usr games boggle))

   There are times when whitespace_2 should be discarded.  If a command
interpreter takes single-character commands, but occasionally reads an
object then if the whitespace_2 after a symbol is not discarded it might
be interpreted as a command some time later after the symbol had been
read.

Affected By::
.............

*standard-input*, *terminal-io*, *readtable*,
*read-default-float-format*, *read-base*, *read-suppress*, *package*,
*read-eval*.

Exceptional Situations::
........................

read signals an error of type end-of-file, regardless of eof-error-p, if
the file ends in the middle of an object representation.  For example,
if a file does not contain enough right parentheses to balance the left
parentheses in it, read signals an error.  This is detected when read or
read-preserving-whitespace is called with recursive-p and eof-error-p
non-nil, and end-of-file is reached before the beginning of an object.

   If eof-error-p is true, an error of type end-of-file is signaled at
the end of file.

See Also::
..........

*note peek-char:: , *note read-char:: , *note unread-char:: , *note
read-from-string:: , *note read-delimited-list:: , *note parse-integer::
, *note Syntax::, *note Reader Concepts::


File: gcl.info,  Node: read-delimited-list,  Next: read-from-string,  Prev: read,  Up: Reader Dictionary

23.2.5 read-delimited-list [Function]
-------------------------------------

'read-delimited-list' char &optional input-stream recursive-p => list

Arguments and Values::
......................

char--a character.

   input-stream--an input stream designator.  The default is standard
input.

   recursive-p--a generalized boolean.  The default is false.

   list--a list of the objects read.

Description::
.............

read-delimited-list reads objects from input-stream until the next
character after an object's representation (ignoring whitespace_2
characters and comments) is char.

   read-delimited-list looks ahead at each step for the next
non-whitespace_2 character and peeks at it as if with peek-char.  If it
is char, then the character is consumed and the list of objects is
returned.  If it is a constituent or escape character, then read is used
to read an object, which is added to the end of the list.  If it is a
macro character, its reader macro function is called; if the function
returns a value, that value is added to the list.  The peek-ahead
process is then repeated.

   If recursive-p is true, this call is expected to be embedded in a
higher-level call to read or a similar function.

   It is an error to reach end-of-file during the operation of
read-delimited-list.

   The consequences are undefined if char has a syntax type of
whitespace_2 in the current readtable.

Examples::
..........

      (read-delimited-list #\]) 1 2 3 4 5 6 ]
     =>  (1 2 3 4 5 6)

   Suppose you wanted #{a b c ... z} to read as a list of all pairs of
the elements a, b, c, ..., z, for example.

      #{p q z a}  reads as  ((p q) (p z) (p a) (q z) (q a) (z a))

   This can be done by specifying a macro-character definition for #{
that does two things: reads in all the items up to the }, and constructs
the pairs.  read-delimited-list performs the first task.

      (defun |#{-reader| (stream char arg)
        (declare (ignore char arg))
        (mapcon #'(lambda (x)
                   (mapcar #'(lambda (y) (list (car x) y)) (cdr x)))
               (read-delimited-list #\} stream t))) =>  |#{-reader|

      (set-dispatch-macro-character #\# #\{ #'|#{-reader|) =>  T
      (set-macro-character #\} (get-macro-character #\) nil))

   Note that true is supplied for the recursive-p argument.

   It is necessary here to give a definition to the character } as well
to prevent it from being a constituent.  If the line

      (set-macro-character #\} (get-macro-character #\) nil))

   shown above were not included, then the } in

      #{ p q z a}

   would be considered a constituent character, part of the symbol named
a}.  This could be corrected by putting a space before the }, but it is
better to call set-macro-character.

   Giving } the same	definition as the standard definition of the
character ) has the twin benefit of making it terminate tokens for use
with read-delimited-list and also making it invalid for use in any other
context.  Attempting to read a stray } will signal an error.

Affected By::
.............

*standard-input*, *readtable*, *terminal-io*.

See Also::
..........

*note read:: , *note peek-char:: , *note read-char:: , *note
unread-char:: .

Notes::
.......

read-delimited-list is intended for use in implementing reader macros.
Usually it is desirable for char to be a terminating macro character so
that it can be used to delimit tokens; however, read-delimited-list
makes no attempt to alter the syntax specified for char by the current
readtable.  The caller must make any necessary changes to the readtable
syntax explicitly.


File: gcl.info,  Node: read-from-string,  Next: readtable-case,  Prev: read-delimited-list,  Up: Reader Dictionary

23.2.6 read-from-string [Function]
----------------------------------

'read-from-string' string &optional eof-error-p eof-value &key start end
preserve-whitespace
=> object, position

Arguments and Values::
......................

string--a string.

   eof-error-p--a generalized boolean.  The default is true.

   eof-value--an object.

   The default is nil.

   start, end--bounding index designators of string.  The defaults for
start and end are 0 and nil, respectively.

   preserve-whitespace--a generalized boolean.  The default is false.

   object--an object (parsed by the Lisp reader) or the eof-value.

   position--an integer greater than or equal to zero, and less than or
equal to one more than the length of the string.

Description::
.............

Parses the printed representation of an object from the subsequence of
string bounded by start and end, as if read had been called on an input
stream containing those same characters.

   If preserve-whitespace is true, the operation will preserve
whitespace_2 as read-preserving-whitespace would do.

   If an object is successfully parsed, the primary value, object, is
the object that was parsed.  If eof-error-p is false and if the end of
the substring is reached, eof-value is returned.

   The secondary value, position, is the index of the first character in
the bounded string that was not read.  The position may depend upon the
value of preserve-whitespace.  If the entire string was read, the
position returned is either the length of the string or one greater than
the length of the string.

Examples::
..........

      (read-from-string " 1 3 5" t nil :start 2) =>  3, 5
      (read-from-string "(a b c)") =>  (A B C), 7

Exceptional Situations::
........................

If the end of the supplied substring occurs before an object can be
read, an error is signaled if eof-error-p is true.  An error is signaled
if the end of the substring occurs in the middle of an incomplete
object.

See Also::
..........

*note read:: , read-preserving-whitespace

Notes::
.......

The reason that position is allowed to be beyond the length of the
string is to permit (but not require) the implementation to work by
simulating the effect of a trailing delimiter at the end of the bounded
string.  When preserve-whitespace is true, the position might count the
simulated delimiter.


File: gcl.info,  Node: readtable-case,  Next: readtablep,  Prev: read-from-string,  Up: Reader Dictionary

23.2.7 readtable-case [Accessor]
--------------------------------

'readtable-case' readtable => mode

   (setf (' readtable-case' readtable) mode)

Arguments and Values::
......................

readtable--a readtable.

   mode--a case sensitivity mode.

Description::
.............

Accesses the readtable case of readtable, which affects the way in which
the Lisp Reader reads symbols and the way in which the Lisp Printer
writes symbols.

Examples::
..........

See *note Examples of Effect of Readtable Case on the Lisp Reader:: and
*note Examples of Effect of Readtable Case on the Lisp Printer::.

Exceptional Situations::
........................

Should signal an error of type type-error if readtable is not a
readtable.  Should signal an error of type type-error if mode is not a
case sensitivity mode.

See Also::
..........

*note readtable:: , *print-escape*, *note Reader Algorithm::, *note
Effect of Readtable Case on the Lisp Reader::, *note Effect of Readtable
Case on the Lisp Printer::

Notes::
.......

copy-readtable copies the readtable case of the readtable.


File: gcl.info,  Node: readtablep,  Next: set-dispatch-macro-character,  Prev: readtable-case,  Up: Reader Dictionary

23.2.8 readtablep [Function]
----------------------------

'readtablep' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type readtable; otherwise, returns false.

Examples::
..........

      (readtablep *readtable*) =>  true
      (readtablep (copy-readtable)) =>  true
      (readtablep '*readtable*) =>  false

Notes::
.......

      (readtablep object) == (typep object 'readtable)


File: gcl.info,  Node: set-dispatch-macro-character,  Next: set-macro-character,  Prev: readtablep,  Up: Reader Dictionary

23.2.9 set-dispatch-macro-character, get-dispatch-macro-character
-----------------------------------------------------------------

                                                             [Function]

   'get-dispatch-macro-character' disp-char sub-char &optional readtable
=> function

   'set-dispatch-macro-character' disp-char sub-char new-function
&optional readtable => t

Arguments and Values::
......................

disp-char--a character.

   sub-char--a character.

   readtable--a readtable designator.

   The default is the current readtable.

   function--a function designator or nil.

   new-function--a function designator.

Description::
.............

set-dispatch-macro-character causes new-function to be called when
disp-char followed by sub-char is read.  If sub-char is a lowercase
letter, it is converted to its uppercase equivalent.  It is an error if
sub-char is one of the ten decimal digits.

   set-dispatch-macro-character installs a new-function to be called
when a particular dispatching macro character pair is read.
New-function is installed as the dispatch function to be called when
readtable is in use and when disp-char is followed by sub-char.

   For more information about how the new-function is invoked, see *note
Macro Characters::.

   get-dispatch-macro-character retrieves the dispatch function
associated with disp-char and sub-char in readtable.

   get-dispatch-macro-character returns the macro-character function for
sub-char under disp-char, or nil if there is no function associated with
sub-char.  If sub-char is a decimal digit, get-dispatch-macro-character
returns nil.

Examples::
..........

      (get-dispatch-macro-character #\# #\{) =>  NIL
      (set-dispatch-macro-character #\# #\{        ;dispatch on #{
         #'(lambda(s c n)
             (let ((list (read s nil (values) t)))  ;list is object after #n{
               (when (consp list)                   ;return nth element of list
                 (unless (and n (< 0 n (length list))) (setq n 0))
                 (setq list (nth n list)))
              list))) =>  T
      #{(1 2 3 4) =>  1
      #3{(0 1 2 3) =>  3
      #{123 =>  123

   If it is desired that #$foo : as if it were (dollars foo).

     (defun |#$-reader| (stream subchar arg)
        (declare (ignore subchar arg))
        (list 'dollars (read stream t nil t))) =>  |#$-reader|
      (set-dispatch-macro-character #\# #\$ #'|#$-reader|) =>  T

See Also::
..........

*note Macro Characters::

Side Effects::
..............

The readtable is modified.

Affected By::
.............

*readtable*.

Exceptional Situations::
........................

For either function, an error is signaled if disp-char is not a
dispatching macro character in readtable.

See Also::
..........

*note readtable::

Notes::
.......

It is necessary to use make-dispatch-macro-character to set up the
dispatch character before specifying its sub-characters.


File: gcl.info,  Node: set-macro-character,  Next: set-syntax-from-char,  Prev: set-dispatch-macro-character,  Up: Reader Dictionary

23.2.10 set-macro-character, get-macro-character [Function]
-----------------------------------------------------------

'get-macro-character' char &optional readtable => function,
non-terminating-p

   'set-macro-character' char new-function &optional non-terminating-p
readtable => t

Arguments and Values::
......................

char--a character.

   non-terminating-p--a generalized boolean.  The default is false.

   readtable--a readtable designator.

   The default is the current readtable.

   function--nil, or a designator for a function of two arguments.

   new-function--a function designator.

Description::
.............

get-macro-character returns as its primary value, function, the reader
macro function associated with char in readtable (if any), or else nil
if char is not a macro character in readtable.  The secondary value,
non-terminating-p, is true if char is a non-terminating macro character;
otherwise, it is false.

   set-macro-character causes char to be a macro character associated
with the reader macro function new-function (or the designator for
new-function) in readtable.  If non-terminating-p is true, char becomes
a non-terminating macro character; otherwise it becomes a terminating
macro character.

Examples::
..........

      (get-macro-character #\{) =>  NIL, false
      (not (get-macro-character #\;)) =>  false

   The following is a possible definition for the single-quote reader
macro in standard syntax:

      (defun single-quote-reader (stream char)
        (declare (ignore char))
        (list 'quote (read stream t nil t))) =>  SINGLE-QUOTE-READER
      (set-macro-character #\' #'single-quote-reader) =>  T

   Here single-quote-reader reads an object following the single-quote
and returns a list of quote and that object.  The char argument is
ignored.

   The following is a possible definition for the semicolon reader macro
in standard syntax:

      (defun semicolon-reader (stream char)
        (declare (ignore char))
        ;; First swallow the rest of the current input line.
        ;; End-of-file is acceptable for terminating the comment.
        (do () ((char= (read-char stream nil #\Newline t) #\Newline)))
        ;; Return zero values.
        (values)) =>  SEMICOLON-READER
      (set-macro-character #\; #'semicolon-reader) =>  T

Side Effects::
..............

The readtable is modified.

See Also::
..........

*note readtable::


File: gcl.info,  Node: set-syntax-from-char,  Next: with-standard-io-syntax,  Prev: set-macro-character,  Up: Reader Dictionary

23.2.11 set-syntax-from-char [Function]
---------------------------------------

'set-syntax-from-char' to-char from-char &optional to-readtable
from-readtable => t

Arguments and Values::
......................

to-char--a character.

   from-char--a character.

   to-readtable--a readtable.  The default is the current readtable.

   from-readtable--a readtable designator.  The default is the standard
readtable.

Description::
.............

set-syntax-from-char makes the syntax of to-char in to-readtable be the
same as the syntax of from-char in from-readtable.

   set-syntax-from-char copies the syntax types of from-char.  If
from-char is a macro character, its reader macro function is copied
also.  If the character is a dispatching macro character, its entire
dispatch table of reader macro functions is copied.  The constituent
traits of from-char are not copied.

   A macro definition from a character such as " can be copied to
another character; the standard definition for " looks for another
character that is the same as the character that invoked it.  The
definition of ( can not be meaningfully copied to {, on the other hand.
The result is that lists are of the form {a b c), not {a b c}, because
the definition always looks for a closing parenthesis, not a closing
brace.

Examples::
..........

      (set-syntax-from-char #\7 #\;) =>  T
      123579 =>  1235

Side Effects::
..............

The to-readtable is modified.

Affected By::
.............

The existing values in the from-readtable.

See Also::
..........

*note set-macro-character:: , *note make-dispatch-macro-character:: ,
*note Character Syntax Types::

Notes::
.......

The constituent traits of a character are "hard wired" into the parser
for extended tokens.  For example, if the definition of S is copied to
*, then * will become a constituent that is alphabetic_2 but that cannot
be used as a short float exponent marker.  For further information, see
*note Constituent Traits::.


File: gcl.info,  Node: with-standard-io-syntax,  Next: *read-base*,  Prev: set-syntax-from-char,  Up: Reader Dictionary

23.2.12 with-standard-io-syntax [Macro]
---------------------------------------

'with-standard-io-syntax' {form}* => {result}*

Arguments and Values::
......................

forms--an implicit progn.

   results--the values returned by the forms.

Description::
.............

Within the dynamic extent of the body of forms, all reader/printer
control variables, including any implementation-defined ones not
specified by this standard, are bound to values that produce standard
read/print behavior.  The values for the variables specified by this
standard are listed in Figure 23-1.

   [Reviewer Note by Barrett: *print-pprint-dispatch* should probably be
mentioned here, too.]

  Variable                     Value                               
  *package*                    The CL-USER package                 
  *print-array*                t                                   
  *print-base*                 10                                  
  *print-case*                 :upcase                             
  *print-circle*               nil                                 
  *print-escape*               t                                   
  *print-gensym*               t                                   
  *print-length*               nil                                 
  *print-level*                nil                                 
  *print-lines*                nil                                 
  *print-miser-width*          nil                                 
  *print-pprint-dispatch*      The standard pprint dispatch table  
  *print-pretty*               nil                                 
  *print-radix*                nil                                 
  *print-readably*             t                                   
  *print-right-margin*         nil                                 
  *read-base*                  10                                  
  *read-default-float-format*  single-float                        
  *read-eval*                  t                                   
  *read-suppress*              nil                                 
  *readtable*                  The standard readtable              

         Figure 23-1: Values of standard control variables        


Examples::
..........

      (with-open-file (file pathname :direction :output)
        (with-standard-io-syntax
          (print data file)))

     ;;; ... Later, in another Lisp:

      (with-open-file (file pathname :direction :input)
        (with-standard-io-syntax
          (setq data (read file))))


File: gcl.info,  Node: *read-base*,  Next: *read-default-float-format*,  Prev: with-standard-io-syntax,  Up: Reader Dictionary

23.2.13 *read-base* [Variable]
------------------------------

Value Type::
............

a radix.

Initial Value::
...............

10.

Description::
.............

Controls the interpretation of tokens by read as being integers or
ratios.

   The value of *read-base*, called the current input base , is the
radix in which integers and ratios are to be read by the Lisp reader.
The parsing of other numeric types (e.g., floats) is not affected by
this option.

   The effect of *read-base* on the reading of any particular rational
number can be locally overridden by explicit use of the #O, #X, #B, or
#nR syntax or by a trailing decimal point.

Examples::
..........

      (dotimes (i 6)
        (let ((*read-base* (+ 10. i)))
          (let ((object (read-from-string "(\\DAD DAD |BEE| BEE 123. 123)")))
            (print (list *read-base* object)))))
      |>  (10 (DAD DAD BEE BEE 123 123))
      |>  (11 (DAD DAD BEE BEE 123 146))
      |>  (12 (DAD DAD BEE BEE 123 171))
      |>  (13 (DAD DAD BEE BEE 123 198))
      |>  (14 (DAD 2701 BEE BEE 123 227))
      |>  (15 (DAD 3088 BEE 2699 123 258))
     =>  NIL

Notes::
.......

Altering the input radix can be useful when reading data files in
special formats.


File: gcl.info,  Node: *read-default-float-format*,  Next: *read-eval*,  Prev: *read-base*,  Up: Reader Dictionary

23.2.14 *read-default-float-format* [Variable]
----------------------------------------------

Value Type::
............

one of the atomic type specifiers short-float, single-float,
double-float, or long-float, or else some other type specifier defined
by the implementation to be acceptable.

Initial Value::
...............

The symbol single-float.

Description::
.............

Controls the floating-point format that is to be used when reading a
floating-point number that has no exponent marker or that has e or E for
an exponent marker.  Other exponent markers explicitly prescribe the
floating-point format to be used.

   The printer uses *read-default-float-format* to guide the choice of
exponent markers when printing floating-point numbers.

Examples::
..........

      (let ((*read-default-float-format* 'double-float))
        (read-from-string "(1.0 1.0e0 1.0s0 1.0f0 1.0d0 1.0L0)"))
     =>  (1.0   1.0   1.0   1.0 1.0   1.0)   ;Implementation has float format F.
     =>  (1.0   1.0   1.0s0 1.0 1.0   1.0)   ;Implementation has float formats S and F.
     =>  (1.0d0 1.0d0 1.0   1.0 1.0d0 1.0d0) ;Implementation has float formats F and D.
     =>  (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0d0) ;Implementation has float formats S, F, D.
     =>  (1.0d0 1.0d0 1.0   1.0 1.0d0 1.0L0) ;Implementation has float formats F, D, L.
     =>  (1.0d0 1.0d0 1.0s0 1.0 1.0d0 1.0L0) ;Implementation has formats S, F, D, L.


File: gcl.info,  Node: *read-eval*,  Next: *read-suppress*,  Prev: *read-default-float-format*,  Up: Reader Dictionary

23.2.15 *read-eval* [Variable]
------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

true.

Description::
.............

If it is true, the #. reader macro has its normal effect.  Otherwise,
that reader macro signals an error of type reader-error.

See Also::
..........

*print-readably*

Notes::
.......

If *read-eval* is false and *print-readably* is true, any method for
print-object that would output a reference to the #. reader macro either
outputs something different or signals an error of type
print-not-readable.


File: gcl.info,  Node: *read-suppress*,  Next: *readtable*,  Prev: *read-eval*,  Up: Reader Dictionary

23.2.16 *read-suppress* [Variable]
----------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

false.

Description::
.............

This variable is intended primarily to support the operation of the
read-time conditional notations #+ and #-.  It is important for the
reader macros which implement these notations to be able to skip over
the printed representation of an expression despite the possibility that
the syntax of the skipped expression may not be entirely valid for the
current implementation, since #+ and #- exist in order to allow the same
program to be shared among several Lisp implementations (including
dialects other than Common Lisp) despite small incompatibilities of
syntax.

   If it is false, the Lisp reader operates normally.

   If the value of *read-suppress* is true, read,
read-preserving-whitespace, read-delimited-list, and read-from-string
all return a primary value of nil when they complete successfully;
however, they continue to parse the representation of an object in the
normal way, in order to skip over the object, and continue to indicate
end of file in the normal way.  Except as noted below, any standardized
reader macro_2 that is defined to read_2 a following object or token
will do so, but not signal an error if the object read is not of an
appropriate type or syntax.  The standard syntax and its associated
reader macros will not construct any new objects (e.g., when reading the
representation of a symbol, no symbol will be constructed or interned).

Extended tokens
     All extended tokens are completely uninterpreted.  Errors such as
     those that might otherwise be signaled due to detection of invalid
     potential numbers, invalid patterns of package markers, and invalid
     uses of the dot character are suppressed.

Dispatching macro characters (including sharpsign)
     Dispatching macro characters continue to parse an infix numerical
     argument, and invoke the dispatch function.  The standardized
     sharpsign reader macros do not enforce any constraints on either
     the presence of or the value of the numerical argument.

#=
     The #= notation is totally ignored.  It does not read a following
     object.  It produces no object, but is treated as whitespace_2.

##
     The ## notation always produces nil.

   No matter what the value of *read-suppress*, parentheses still
continue to delimit and construct lists; the #( notation continues to
delimit vectors; and comments, strings, and the single-quote and
backquote notations continue to be interpreted properly.  Such
situations as '),	#<, #), and #<Space> continue to signal errors.

Examples::
..........

      (let ((*read-suppress* t))
        (mapcar #'read-from-string
                '("#(foo bar baz)" "#P(:type :lisp)" "#c1.2"
                  "#.(PRINT 'FOO)" "#3AHELLO" "#S(INTEGER)"
                  "#*ABC" "#\GARBAGE" "#RALPHA" "#3R444")))
     =>  (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)

See Also::
..........

*note read:: , *note Syntax::

Notes::
.......

Programmers and implementations that define additional macro characters
are strongly encouraged to make them respect *read-suppress* just as
standardized macro characters do.  That is, when the value of
*read-suppress* is true, they should ignore type errors when reading a
following object and the functions that implement dispatching macro
characters should tolerate nil as their infix parameter value even if a
numeric value would ordinarily be required.


File: gcl.info,  Node: *readtable*,  Next: reader-error,  Prev: *read-suppress*,  Up: Reader Dictionary

23.2.17 *readtable* [Variable]
------------------------------

Value Type::
............

a readtable.

Initial Value::
...............

A readtable that conforms to the description of Common Lisp syntax in
*note Syntax::.

Description::
.............

The value of *readtable* is called the current readtable.  It controls
the parsing behavior of the Lisp reader, and can also influence the Lisp
printer (e.g., see the function readtable-case).

Examples::
..........

      (readtablep *readtable*) =>  true
      (setq zvar 123) =>  123
      (set-syntax-from-char #\z #\' (setq table2 (copy-readtable))) =>  T
      zvar =>  123
      (setq *readtable* table2) =>  #<READTABLE>
      zvar =>  VAR
      (setq *readtable* (copy-readtable nil)) =>  #<READTABLE>
      zvar =>  123

Affected By::
.............

compile-file, load

See Also::
..........

*note compile-file:: , *note load:: , *note readtable:: , *note The
Current Readtable::


File: gcl.info,  Node: reader-error,  Prev: *readtable*,  Up: Reader Dictionary

23.2.18 reader-error [Condition Type]
-------------------------------------

Class Precedence List::
.......................

reader-error, parse-error, stream-error, error, serious-condition,
condition, t

Description::
.............

The type reader-error consists of error conditions that are related to
tokenization and parsing done by the Lisp reader.

See Also::
..........

*note read:: , *note stream-error-stream:: , *note Reader Concepts::


File: gcl.info,  Node: System Construction,  Next: Environment,  Prev: Reader,  Up: Top

24 System Construction
**********************

* Menu:

* System Construction Concepts::
* System Construction Dictionary::


File: gcl.info,  Node: System Construction Concepts,  Next: System Construction Dictionary,  Prev: System Construction,  Up: System Construction

24.1 System Construction Concepts
=================================

* Menu:

* Loading::
* Features::


File: gcl.info,  Node: Loading,  Next: Features,  Prev: System Construction Concepts,  Up: System Construction Concepts

24.1.1 Loading
--------------

To load a file is to treat its contents as code and execute that code.
The file may contain source code or compiled code .

   A file containing source code is called a source file .  Loading a
source file is accomplished essentially by sequentially reading_2 the
forms in the file, evaluating each immediately after it is read.

   A file containing compiled code is called a compiled file .  Loading
a compiled file is similar to loading a source file, except that the
file does not contain text but rather an implementation-dependent
representation of pre-digested expressions created by the compiler.
Often, a compiled file can be loaded more quickly than a source file.
See *note Compilation::.

   The way in which a source file is distinguished from a compiled file
is implementation-dependent.


File: gcl.info,  Node: Features,  Prev: Loading,  Up: System Construction Concepts

24.1.2 Features
---------------

A feature is an aspect or attribute of Common Lisp, of the
implementation, or of the environment.  A feature is identified by a
symbol.

   A feature is said to be present in a Lisp image if and only if the
symbol naming it is an element of the list held by the variable
*features*, which is called the features list .

* Menu:

* Feature Expressions::
* Examples of Feature Expressions::


File: gcl.info,  Node: Feature Expressions,  Next: Examples of Feature Expressions,  Prev: Features,  Up: Features

24.1.2.1 Feature Expressions
............................

Boolean combinations of features, called feature expressions , are used
by the #+ and #- reader macros in order to direct conditional reading of
expressions by the Lisp reader.

   The rules for interpreting a feature expression are as follows:

feature
     If a symbol naming a feature is used as a feature expression, the
     feature expression succeeds if that feature is present; otherwise
     it fails.

(not feature-conditional)
     A not feature expression succeeds if its argument
     feature-conditional fails; otherwise, it succeeds.

(and {feature-conditional}*)
     An and feature expression succeeds if all of its argument
     feature-conditionals succeed; otherwise, it fails.

(or {feature-conditional}*)
     An or feature expression succeeds if any of its argument
     feature-conditionals succeed; otherwise, it fails.


File: gcl.info,  Node: Examples of Feature Expressions,  Prev: Feature Expressions,  Up: Features

24.1.2.2 Examples of Feature Expressions
........................................

For example, suppose that in implementation A, the features spice and
perq are present, but the feature lispm is not present; in
implementation B, the feature lispm is present, but the features spice
and perq are not present; and in implementation C, none of the features
spice, lispm, or perq are present.  Figure 24-1 shows some sample
expressions, and how they would be read_2 in these implementations.

  (cons #+spice "Spice" #-spice "Lispm" x) 
  in implementation A ...    (CONS "Spice" X)             
    in implementation B ...  (CONS "Lispm" X)             
    in implementation C ...  (CONS "Lispm" X)             
  (cons #+spice "Spice" #+LispM "Lispm" x) 
  in implementation A ...    (CONS "Spice" X)             
    in implementation B ...  (CONS "Lispm" X)             
    in implementation C ...  (CONS X)                     
  (setq a '(1 2 #+perq 43 #+(not perq) 27)) 
  in implementation A ...    (SETQ A '(1 2 43))           
    in implementation B ...  (SETQ A '(1 2 27))           
    in implementation C ...  (SETQ A '(1 2 27))           
  (let ((a 3) #+(or spice lispm) (b 3)) (foo a)) 
  in implementation A ...    (LET ((A 3) (B 3)) (FOO A))  
    in implementation B ...  (LET ((A 3) (B 3)) (FOO A))  
    in implementation C ...  (LET ((A 3)) (FOO A))        
  (cons #+Lispm "#+Spice" #+Spice "foo" #-(or Lispm Spice) 7 x) 
  in implementation A ...    (CONS "foo" X)               
    in implementation B ...  (CONS "#+Spice" X)           
    in implementation C ...  (CONS 7 X)                   

              Figure 24-1: Features examples             



File: gcl.info,  Node: System Construction Dictionary,  Prev: System Construction Concepts,  Up: System Construction

24.2 System Construction Dictionary
===================================

* Menu:

* compile-file::
* compile-file-pathname::
* load::
* with-compilation-unit::
* *features*::
* *compile-file-pathname*::
* *load-pathname*::
* *compile-print*::
* *load-print*::
* *modules*::
* provide::


File: gcl.info,  Node: compile-file,  Next: compile-file-pathname,  Prev: System Construction Dictionary,  Up: System Construction Dictionary

24.2.1 compile-file [Function]
------------------------------

'compile-file' input-file &key output-file verbose print external-format
=> output-truename, warnings-p, failure-p

Arguments and Values::
......................

input-file--a pathname designator.  (Default fillers for unspecified
components are taken from *default-pathname-defaults*.)

   output-file--a pathname designator.  The default is
implementation-defined.

   verbose--a generalized boolean.  The default is the value of
*compile-verbose*.

   print--a generalized boolean.  The default is the value of
*compile-print*.

   external-format--an external file format designator.  The default is
:default.

   output-truename--a pathname (the truename of the output file), or
nil.

   warnings-p--a generalized boolean.

   failure-p--a generalized boolean.

Description::
.............

compile-file transforms the contents of the file specified by input-file
into implementation-dependent binary data which are placed in the file
specified by output-file.

   The file to which input-file refers should be a source file.
output-file can be used to specify an output pathname;

   the actual pathname of the compiled file to which compiled code will
be output is computed as if by calling compile-file-pathname.

   If input-file or output-file is a logical pathname, it is translated
into a physical pathname as if by calling translate-logical-pathname.

   If verbose is true, compile-file prints a message in the form of a
comment (i.e., with a leading semicolon) to standard output indicating
what file is being compiled and other useful information.  If verbose is
false, compile-file does not print this information.

   If print is true, information about top level forms in the file being
compiled is printed to standard output.  Exactly what is printed is
implementation-dependent, but nevertheless some information is printed.
If print is nil, no information is printed.

   The external-format specifies the external file format to be used
when opening the file; see the function open.  compile-file and load
must cooperate in such a way that the resulting compiled file can be
loaded without specifying an external file format anew; see the function
load.

   compile-file binds *readtable* and *package* to the values they held
before processing the file.

   *compile-file-truename* is bound by compile-file to hold the truename
of the pathname of the file being compiled.

   *compile-file-pathname* is bound by compile-file to hold a pathname
denoted by the first argument to compile-file, merged against the
defaults; that is, (pathname (merge-pathnames input-file)).

   The compiled functions contained in the compiled file become
available for use when the compiled file is loaded into Lisp.

   Any function definition that is processed by the compiler, including
#'(lambda ...) forms and local function definitions made by flet, labels
and defun forms, result in an object of type compiled-function.

   The primary value returned by compile-file, output-truename, is the
truename of the output file, or nil if the file could not be created.

   The secondary value, warnings-p, is false if no conditions of type
error or warning were detected by the compiler, and true otherwise.

   The tertiary value, failure-p, is false if no conditions of type
error or warning (other than style-warning) were detected by the
compiler, and true otherwise.

   For general information about how files are processed by the file
compiler, see *note File Compilation::.

   Programs to be compiled by the file compiler must only contain
externalizable objects; for details on such objects, see *note Literal
Objects in Compiled Files::.  For information on how to extend the set
of externalizable objects, see the function make-load-form and *note
Additional Constraints on Externalizable Objects::.

Affected By::
.............

*error-output*,

   *standard-output*, *compile-verbose*, *compile-print*

   The computer's file system.

Exceptional Situations::
........................

For information about errors detected during the compilation process,
see *note Exceptional Situations in the Compiler::.

   An error of type file-error might be signaled if (wild-pathname-p
input-file)\/ returns true.

   If either the attempt to open the source file for input or the
attempt to open the compiled file for output fails, an error of type
file-error is signaled.

See Also::
..........

*note compile:: , declare, *note eval-when:: , pathname,
logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: compile-file-pathname,  Next: load,  Prev: compile-file,  Up: System Construction Dictionary

24.2.2 compile-file-pathname [Function]
---------------------------------------

'compile-file-pathname' input-file &key output-file &allow-other-keys =>
pathname

Arguments and Values::
......................

input-file--a pathname designator.  (Default fillers for unspecified
components are taken from *default-pathname-defaults*.)

   output-file--a pathname designator.  The default is
implementation-defined.

   pathname--a pathname.

Description::
.............

Returns the pathname that compile-file would write into, if given the
same arguments.

   The defaults for the output-file are taken from the pathname that
results from merging the input-file with the value of
*default-pathname-defaults*, except that the type component should
default to the appropriate implementation-defined default type for
compiled files.

   If input-file is a logical pathname and output-file is unsupplied,
the result is a logical pathname.

   If input-file is a logical pathname, it is translated into a physical
pathname as if by calling translate-logical-pathname.

   If input-file is a stream, the stream can be either open or closed.
compile-file-pathname returns the same pathname after a file is closed
as it did when the file was open.

   It is an error if input-file is a stream that is created with
make-two-way-stream, make-echo-stream, make-broadcast-stream,
make-concatenated-stream, make-string-input-stream,
make-string-output-stream.

   If an implementation supports additional keyword arguments to
compile-file, compile-file-pathname must accept the same arguments.

Examples::
..........

See logical-pathname-translations.

Exceptional Situations::
........................

An error of type file-error might be signaled if either input-file or
output-file is wild.

See Also::
..........

*note compile-file:: , pathname, logical-pathname, *note File System
Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: load,  Next: with-compilation-unit,  Prev: compile-file-pathname,  Up: System Construction Dictionary

24.2.3 load [Function]
----------------------

'load' filespec &key verbose print if-does-not-exist external-format
=> generalized-boolean

Arguments and Values::
......................

filespec--a stream, or a pathname designator.  The default is taken from
*default-pathname-defaults*.

   verbose--a generalized boolean.  The default is the value of
*load-verbose*.

   print--a generalized boolean.  The default is the value of
*load-print*.

   if-does-not-exist--a generalized boolean.  The default is true.

   external-format--an external file format designator.  The default is
:default.

   generalized-boolean--a generalized boolean.

Description::
.............

load loads the file named by filespec into the Lisp environment.

   The manner in which a source file is distinguished from a compiled
file is implementation-dependent.  If the file specification is not
complete and both a source file and a compiled file exist which might
match, then which of those files load selects is
implementation-dependent.

   If filespec is a stream, load determines what kind of stream it is
and loads directly from the stream.

   If filespec is a logical pathname, it is translated into a physical
pathname as if by calling translate-logical-pathname.

   load sequentially executes each form it encounters in the file named
by filespec.  If the file is a source file and the implementation
chooses to perform implicit compilation, load must recognize top level
forms as described in *note Processing of Top Level Forms:: and arrange
for each top level form to be executed before beginning implicit
compilation of the next.  (Note, however, that processing of eval-when
forms by load is controlled by the :execute situation.)

   If verbose is true, load prints a message in the form of a comment
(i.e., with a leading semicolon) to standard output indicating what file
is being loaded and other useful information.

   If verbose is false, load does not print this information.

   If print is true, load incrementally prints information to standard
output showing the progress of the loading process.  For a source file,
this information might mean printing the values yielded by each form in
the file as soon as those values are returned.  For a compiled file,
what is printed might not reflect precisely the contents of the source
file, but some information is generally printed.  If print is false,
load does not print this information.

   If the file named by filespec is successfully loaded, load returns
true.

   [Reviewer Note by Loosemore: What happens if the file cannot be
loaded for some reason other than that it doesn't exist?]  [Editorial
Note by KMP: i.e., can it return NIL? must it?]

   If the file does not exist, the specific action taken depends on
if-does-not-exist: if it is nil, load returns nil; otherwise, load
signals an error.

   The external-format specifies the external file format to be used
when opening the file (see the function open), except that when the file
named by filespec is a compiled file, the external-format is ignored.
compile-file and load cooperate in an implementation-dependent way to
assure the preservation of the similarity of characters referred to in
the source file at the time the source file was processed by the file
compiler under a given external file format, regardless of the value of
external-format at the time the compiled file is loaded.

   load binds *readtable* and *package* to the values they held before
loading the file.

   *load-truename* is bound by load to hold the truename of the pathname
of the file being loaded.

   *load-pathname* is bound by load to hold a pathname that represents
filespec merged against the defaults.  That is, (pathname
(merge-pathnames filespec)).

Examples::
..........

     ;Establish a data file...
      (with-open-file (str "data.in" :direction :output :if-exists :error)
        (print 1 str) (print '(setq a 888) str) t)
     =>  T
      (load "data.in") =>  true
      a =>  888
      (load (setq p (merge-pathnames "data.in")) :verbose t)
     ; Loading contents of file /fred/data.in
     ; Finished loading /fred/data.in
     =>  true
      (load p :print t)
     ; Loading contents of file /fred/data.in
     ;  1
     ;  888
     ; Finished loading /fred/data.in
     =>  true

      ;----[Begin file SETUP]----
      (in-package "MY-STUFF")
      (defmacro compile-truename () `',*compile-file-truename*)
      (defvar *my-compile-truename* (compile-truename) "Just for debugging.")
      (defvar *my-load-pathname* *load-pathname*)
      (defun load-my-system ()
        (dolist (module-name '("FOO" "BAR" "BAZ"))
          (load (merge-pathnames module-name *my-load-pathname*))))
      ;----[End of file SETUP]----

      (load "SETUP")
      (load-my-system)

Affected By::
.............

The implementation, and the host computer's file system.

Exceptional Situations::
........................

If :if-does-not-exist is supplied and is true, or is not supplied, load
signals an error of type file-error if the file named by filespec does
not exist,

   or if the file system cannot perform the requested operation.

   An error of type file-error might be signaled if (wild-pathname-p
filespec) returns true.

See Also::
..........

*note error:: , *note merge-pathnames:: , *load-verbose*,
*default-pathname-defaults*, pathname, logical-pathname, *note File
System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: with-compilation-unit,  Next: *features*,  Prev: load,  Up: System Construction Dictionary

24.2.4 with-compilation-unit [Macro]
------------------------------------

'with-compilation-unit' ([[!option]]) {form}* => {result}*

   option ::=:override override

Arguments and Values::
......................

override--a generalized boolean; evaluated.  The default is nil.

   forms--an implicit progn.

   results--the values returned by the forms.

Description::
.............

Executes forms from left to right.  Within the dynamic environment of
with-compilation-unit, actions deferred by the compiler until the end of
compilation will be deferred until the end of the outermost call to
with-compilation-unit.

   The set of options permitted may be extended by the implementation,
but the only standardized keyword is :override.

   If nested dynamically only the outer call to with-compilation-unit
has any effect unless the value associated with :override is true, in
which case warnings are deferred only to the end of the innermost call
for which override is true.

   The function compile-file provides the effect of

      (with-compilation-unit (:override nil) ...)

   around its code.

   Any implementation-dependent extensions can only be provided as the
result of an explicit programmer request by use of an
implementation-dependent keyword.  Implementations are forbidden from
attaching additional meaning to a use of this macro which involves
either no keywords or just the keyword :override.

Examples::
..........

If an implementation would normally defer certain kinds of warnings,
such as warnings about undefined functions, to the end of a compilation
unit (such as a file), the following example shows how to cause those
warnings to be deferred to the end of the compilation of several files.

      (defun compile-files (&rest files)
        (with-compilation-unit ()
          (mapcar #'(lambda (file) (compile-file file)) files)))

      (compile-files "A" "B" "C")

   Note however that if the implementation does not normally defer any
warnings, use of with-compilation-unit might not have any effect.

See Also::
..........

*note compile:: , *note compile-file::


File: gcl.info,  Node: *features*,  Next: *compile-file-pathname*,  Prev: with-compilation-unit,  Up: System Construction Dictionary

24.2.5 *features* [Variable]
----------------------------

Value Type::
............

a proper list.

Initial Value::
...............

implementation-dependent.

Description::
.............

The value of *features* is called the features list.  It is a list of
symbols, called features, that correspond to some aspect of the
implementation or environment.

   Most features have implementation-dependent meanings; The following
meanings have been assigned to feature names:

:cltl1
     If present, indicates that the LISP package purports to conform to
     the 1984 specification Common Lisp: The Language.  It is possible,
     but not required, for a conforming implementation to have this
     feature because this specification specifies that its symbols are
     to be in the COMMON-LISP package, not the LISP package.

:cltl2
     If present, indicates that the implementation purports to conform
     to Common Lisp: The Language, Second Edition.  This feature must
     not be present in any conforming implementation, since conformance
     to that document is not compatible with conformance to this
     specification.  The name, however, is reserved by this
     specification in order to help programs distinguish implementations
     which conform to that document from implementations which conform
     to this specification.

:ieee-floating-point
     If present, indicates that the implementation purports to conform
     to the requirements of IEEE Standard for Binary Floating-Point
     Arithmetic.

:x3j13
     If present, indicates that the implementation conforms to some
     particular working draft of this specification, or to some subset
     of features that approximates a belief about what this
     specification might turn out to contain.  A conforming
     implementation might or might not contain such a feature.  (This
     feature is intended primarily as a stopgap in order to provide
     implementors something to use prior to the availability of a draft
     standard, in order to discourage them from introducing the
     :draft-ansi-cl and :ansi-cl features prematurely.)

:draft-ansi-cl
     If present, indicates that the implementation purports to conform
     to the first full draft of this specification, which went to public
     review in 1992.  A conforming implementation which has the
     :draft-ansi-cl-2 or :ansi-cl feature is not permitted to retain the
     :draft-ansi-cl feature since incompatible changes were made
     subsequent to the first draft.

:draft-ansi-cl-2
     If present, indicates that a second full draft of this
     specification has gone to public review, and that the
     implementation purports to conform to that specification.  (If
     additional public review drafts are produced, this keyword will
     continue to refer to the second draft, and additional keywords will
     be added to identify conformance with such later drafts.  As such,
     the meaning of this keyword can be relied upon not to change over
     time.)  A conforming implementation which has the :ansi-cl feature
     is only permitted to retain the :draft-ansi-cl feature if the
     finally approved standard is not incompatible with the draft
     standard.

:ansi-cl
     If present, indicates that this specification has been adopted by
     ANSI as an official standard, and that the implementation purports
     to conform.

:common-lisp
     This feature must appear in *features* for any implementation that
     has one or more of the features :x3j13, :draft-ansi-cl, or
     :ansi-cl.  It is intended that it should also appear in
     implementations which have the features :cltl1 or :cltl2, but this
     specification cannot force such behavior.  The intent is that this
     feature should identify the language family named "Common Lisp,"
     rather than some specific dialect within that family.

See Also::
..........

*note Use of Read-Time Conditionals::, *note Standard Macro Characters::

Notes::
.......

The value of *features* is used by the #+ and #- reader syntax.

   Symbols in the features list may be in any package, but in practice
they are generally in the KEYWORD package.  This is because KEYWORD is
the package used by default when reading_2 feature expressions in the #+
and #- reader macros.  Code that needs to name a feature_2 in a package
P (other than KEYWORD) can do so by making explicit use of a package
prefix for P, but note that such code must also assure that the package
P exists in order for the feature expression to be read_2--even in cases
where the feature expression is expected to fail.

   It is generally considered wise for an implementation to include one
or more features identifying the specific implementation, so that
conditional expressions can be written which distinguish idiosyncrasies
of one implementation from those of another.  Since features are
normally symbols in the KEYWORD package where name collisions might
easily result, and since no uniquely defined mechanism is designated for
deciding who has the right to use which symbol for what reason, a
conservative strategy is to prefer names derived from one's own company
or product name, since those names are often trademarked and are hence
less likely to be used unwittingly by another implementation.


File: gcl.info,  Node: *compile-file-pathname*,  Next: *load-pathname*,  Prev: *features*,  Up: System Construction Dictionary

24.2.6 *compile-file-pathname*, *compile-file-truename* [Variable]
------------------------------------------------------------------

Value Type::
............

The value of *compile-file-pathname* must always be a pathname or nil.
The value of *compile-file-truename* must always be a physical pathname
or nil.

Initial Value::
...............

nil.

Description::
.............

During a call to compile-file, *compile-file-pathname* is bound to the
pathname denoted by the first argument to compile-file, merged against
the defaults; that is, it is bound to (pathname (merge-pathnames
input-file)).  During the same time interval, *compile-file-truename* is
bound to the truename of the file being compiled.

   At other times, the value of these variables is nil.

   If a break loop is entered while compile-file is ongoing, it is
implementation-dependent whether these variables retain the values they
had just prior to entering the break loop or whether they are bound to
nil.

   The consequences are unspecified if an attempt is made to assign or
bind either of these variables.

Affected By::
.............

The file system.

See Also::
..........

*note compile-file::


File: gcl.info,  Node: *load-pathname*,  Next: *compile-print*,  Prev: *compile-file-pathname*,  Up: System Construction Dictionary

24.2.7 *load-pathname*, *load-truename* [Variable]
--------------------------------------------------

Value Type::
............

The value of *load-pathname* must always be a pathname or nil.  The
value of *load-truename* must always be a physical pathname or nil.

Initial Value::
...............

nil.

Description::
.............

During a call to load, *load-pathname* is bound to the pathname denoted
by the the first argument to load, merged against the defaults; that is,
it is bound to (pathname (merge-pathnames filespec)).  During the same
time interval, *load-truename* is bound to the truename of the file
being loaded.

   At other times, the value of these variables is nil.

   If a break loop is entered while load is ongoing, it is
implementation-dependent whether these variables retain the values they
had just prior to entering the break loop or whether they are bound to
nil.

   The consequences are unspecified if an attempt is made to assign or
bind either of these variables.

Affected By::
.............

The file system.

See Also::
..........

*note load::


File: gcl.info,  Node: *compile-print*,  Next: *load-print*,  Prev: *load-pathname*,  Up: System Construction Dictionary

24.2.8 *compile-print*, *compile-verbose* [Variable]
----------------------------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

implementation-dependent.

Description::
.............

The value of *compile-print* is the default value of the :print argument
to compile-file.  The value of *compile-verbose* is the default value of
the :verbose argument to compile-file.

See Also::
..........

*note compile-file::


File: gcl.info,  Node: *load-print*,  Next: *modules*,  Prev: *compile-print*,  Up: System Construction Dictionary

24.2.9 *load-print*, *load-verbose* [Variable]
----------------------------------------------

Value Type::
............

a generalized boolean.

Initial Value::
...............

The initial value of *load-print* is false.  The initial value of
*load-verbose* is implementation-dependent.

Description::
.............

The value of *load-print* is the default value of the :print argument to
load.  The value of *load-verbose* is the default value of the :verbose
argument to load.

See Also::
..........

*note load::


File: gcl.info,  Node: *modules*,  Next: provide,  Prev: *load-print*,  Up: System Construction Dictionary

24.2.10 *modules* [Variable]
----------------------------

Value Type::
............

a list of strings.

Initial Value::
...............

implementation-dependent.

Description::
.............

The value of *modules* is a list of names of the modules that have been
loaded into the current Lisp image.

Affected By::
.............

provide

See Also::
..........

*note provide:: , require

Notes::
.......

The variable *modules* is deprecated.


File: gcl.info,  Node: provide,  Prev: *modules*,  Up: System Construction Dictionary

24.2.11 provide, require [Function]
-----------------------------------

'provide' module-name => implementation-dependent

   'require' module-name &optional pathname-list =>
implementation-dependent

Arguments and Values::
......................

module-name--a string designator.

   pathname-list--nil, or a designator for a non-empty list of pathname
designators.  The default is nil.

Description::
.............

provide adds the module-name to the list held by *modules*, if such a
name is not already present.

   require tests for the presence of the module-name in the list held by
*modules*.  If it is present, require immediately returns.

   Otherwise, an attempt is made to load an appropriate set of files as
follows: The pathname-list argument, if non-nil, specifies a list of
pathnames to be loaded in order, from left to right.  If the
pathname-list is nil, an implementation-dependent mechanism will be
invoked in an attempt to load the module named module-name; if no such
module can be loaded, an error of type error is signaled.

   Both functions use string= to test for the presence of a module-name.

Examples::
..........

     ;;; This illustrates a nonportable use of REQUIRE, because it
     ;;; depends on the implementation-dependent file-loading mechanism.

     (require "CALCULUS")

     ;;; This use of REQUIRE is nonportable because of the literal
     ;;; physical pathname.

     (require "CALCULUS" "/usr/lib/lisp/calculus")

     ;;; One form of portable usage involves supplying a logical pathname,
     ;;; with appropriate translations defined elsewhere.

     (require "CALCULUS" "lib:calculus")

     ;;; Another form of portable usage involves using a variable or
     ;;; table lookup function to determine the pathname, which again
     ;;; must be initialized elsewhere.

     (require "CALCULUS" *calculus-module-pathname*)

Side Effects::
..............

provide modifies *modules*.

Affected By::
.............

The specific action taken by require is affected by calls to provide
(or, in general, any changes to the value of *modules*).

Exceptional Situations::
........................

Should signal an error of type type-error if module-name is not a string
designator.

   If require fails to perform the requested operation due to a problem
while interacting with the file system, an error of type file-error is
signaled.

   An error of type file-error might be signaled if any pathname in
pathname-list is a designator for a wild pathname.

See Also::
..........

*modules*,

   *note Pathnames as Filenames::

Notes::
.......

The functions provide and require are deprecated.

   If a module consists of a single package, it is customary for the
package and module names to be the same.


File: gcl.info,  Node: Environment,  Next: Glossary (Glossary),  Prev: System Construction,  Up: Top

25 Environment
**************

* Menu:

* The External Environment::
* Environment Dictionary::


File: gcl.info,  Node: The External Environment,  Next: Environment Dictionary,  Prev: Environment,  Up: Environment

25.1 The External Environment
=============================

* Menu:

* Top level loop::
* Debugging Utilities::
* Environment Inquiry::
* Time::


File: gcl.info,  Node: Top level loop,  Next: Debugging Utilities,  Prev: The External Environment,  Up: The External Environment

25.1.1 Top level loop
---------------------

The top level loop is the Common Lisp mechanism by which the user
normally interacts with the Common Lisp system.  This loop is sometimes
referred to as the Lisp read-eval-print loop because it typically
consists of an endless loop that reads an expression, evaluates it and
prints the results.

   The top level loop is not completely specified; thus the user
interface is implementation-defined.  The top level loop prints all
values resulting from the evaluation of a form.  Figure 25-1 lists
variables that are maintained by the Lisp read-eval-print loop.

  *    +    /    -  
  **   ++   //      
  ***  +++  ///     

  Figure 25-1: Variables maintained by the Read-Eval-Print Loop



File: gcl.info,  Node: Debugging Utilities,  Next: Environment Inquiry,  Prev: Top level loop,  Up: The External Environment

25.1.2 Debugging Utilities
--------------------------

Figure 25-2 shows defined names relating to debugging.

  *debugger-hook*  documentation    step     
  apropos          dribble          time     
  apropos-list     ed               trace    
  break            inspect          untrace  
  describe         invoke-debugger           

  Figure 25-2: Defined names relating to debugging



File: gcl.info,  Node: Environment Inquiry,  Next: Time,  Prev: Debugging Utilities,  Up: The External Environment

25.1.3 Environment Inquiry
--------------------------

Environment inquiry defined names provide information about the hardware
and software configuration on which a Common Lisp program is being
executed.

   Figure 25-3 shows defined names relating to environment inquiry.

  *features*                   machine-instance  short-site-name   
  lisp-implementation-type     machine-type      software-type     
  lisp-implementation-version  machine-version   software-version  
  long-site-name               room                                

    Figure 25-3: Defined names relating to environment inquiry.   



File: gcl.info,  Node: Time,  Prev: Environment Inquiry,  Up: The External Environment

25.1.4 Time
-----------

Time is represented in four different ways in Common Lisp: decoded time,
universal time, internal time, and seconds.  Decoded time and universal
time are used primarily to represent calendar time, and are precise only
to one second.  Internal time is used primarily to represent
measurements of computer time (such as run time) and is precise to some
implementation-dependent fraction of a second called an internal time
unit, as specified by internal-time-units-per-second.  An internal time
can be used for either absolute and relative time measurements.  Both a
universal time and a decoded time can be used only for absolute time
measurements.  In the case of one function, sleep, time intervals are
represented as a non-negative real number of seconds.

   Figure 25-4 shows defined names relating to time.

  decode-universal-time   get-internal-run-time           
  encode-universal-time   get-universal-time              
  get-decoded-time        internal-time-units-per-second  
  get-internal-real-time  sleep                           

        Figure 25-4: Defined names involving Time.       


* Menu:

* Decoded Time::
* Universal Time::
* Internal Time::
* Seconds::


File: gcl.info,  Node: Decoded Time,  Next: Universal Time,  Prev: Time,  Up: Time

25.1.4.1 Decoded Time
.....................

A decoded time is an ordered series of nine values that, taken together,
represent a point in calendar time (ignoring leap seconds):

Second
     An integer between 0 and~59, inclusive.

Minute
     An integer between 0 and~59, inclusive.

Hour
     An integer between 0 and~23, inclusive.

Date
     An integer between 1 and~31, inclusive (the upper limit actually
     depends on the month and year, of course).

Month
     An integer between 1 and 12, inclusive; 1~means January, 2~means
     February, and so on; 12~means December.

Year
     An integer indicating the year A.D. However, if this integer is
     between 0 and 99, the "obvious" year is used; more precisely, that
     year is assumed that is equal to the integer modulo 100 and within
     fifty years of the current year (inclusive backwards and exclusive
     forwards).  Thus, in the year 1978, year 28 is 1928 but year 27 is
     2027.  (Functions that return time in this format always return a
     full year number.)

Day of week
     An integer between~0 and~6, inclusive; 0~means Monday, 1~means
     Tuesday, and so on; 6~means Sunday.

Daylight saving time flag
     A generalized boolean that, if true, indicates that daylight saving
     time is in effect.

Time zone
     A time zone.

   Figure 25-5 shows defined names relating to decoded time.

  decode-universal-time  get-decoded-time  

  Figure 25-5: Defined names involving time in Decoded Time.



File: gcl.info,  Node: Universal Time,  Next: Internal Time,  Prev: Decoded Time,  Up: Time

25.1.4.2 Universal Time
.......................

Universal time is an absolute time represented as a single non-negative
integer--the number of seconds since midnight, January 1, 1900 GMT
(ignoring leap seconds).  Thus the time 1 is 00:00:01 (that is, 12:00:01
a.m.)  on January 1, 1900 GMT. Similarly, the time 2398291201
corresponds to time 00:00:01 on January 1, 1976 GMT. Recall that the
year 1900 was not a leap year; for the purposes of Common Lisp, a year
is a leap year if and only if its number is divisible by 4, except that
years divisible by 100 are not leap years, except that years divisible
by 400 are leap years.  Therefore the year 2000 will be a leap year.
Because universal time must be a non-negative integer, times before the
base time of midnight, January 1, 1900 GMT cannot be processed by Common
Lisp.

  decode-universal-time  get-universal-time  
  encode-universal-time                      

  Figure 25-6: Defined names involving time in Universal Time.



File: gcl.info,  Node: Internal Time,  Next: Seconds,  Prev: Universal Time,  Up: Time

25.1.4.3 Internal Time
......................

Internal time represents time as a single integer, in terms of an
implementation-dependent unit called an internal time unit.  Relative
time is measured as a number of these units.  Absolute time is relative
to an arbitrary time base.

   Figure 25-7 shows defined names related to internal time.

  get-internal-real-time  internal-time-units-per-second  
  get-internal-run-time                                   

  Figure 25-7: Defined names involving time in Internal Time.



File: gcl.info,  Node: Seconds,  Prev: Internal Time,  Up: Time

25.1.4.4 Seconds
................

One function, sleep, takes its argument as a non-negative real number of
seconds.  Informally, it may be useful to think of this as a relative
universal time, but it differs in one important way: universal times are
always non-negative integers, whereas the argument to sleep can be any
kind of non-negative real, in order to allow for the possibility of
fractional seconds.

  sleep    

  Figure 25-8: Defined names involving time in Seconds.



File: gcl.info,  Node: Environment Dictionary,  Prev: The External Environment,  Up: Environment

25.2 Environment Dictionary
===========================

* Menu:

* decode-universal-time::
* encode-universal-time::
* get-universal-time::
* sleep::
* apropos::
* describe::
* describe-object::
* trace::
* step::
* time::
* internal-time-units-per-second::
* get-internal-real-time::
* get-internal-run-time::
* disassemble::
* documentation::
* room::
* ed::
* inspect::
* dribble::
* - (Variable)::
* + (Variable)::
* * (Variable)::
* / (Variable)::
* lisp-implementation-type::
* short-site-name::
* machine-instance::
* machine-type::
* machine-version::
* software-type::
* user-homedir-pathname::


File: gcl.info,  Node: decode-universal-time,  Next: encode-universal-time,  Prev: Environment Dictionary,  Up: Environment Dictionary

25.2.1 decode-universal-time [Function]
---------------------------------------

'decode-universal-time' universal-time &optional time-zone
=> second, minute, hour, date, month, year, day, daylight-p, zone

Arguments and Values::
......................

universal-time--a universal time.

   time-zone--a time zone.

   second, minute, hour, date, month, year, day, daylight-p, zone--a
decoded time.

Description::
.............

Returns the decoded time represented by the given universal time.

   If time-zone is not supplied, it defaults to the current time zone
adjusted for daylight saving time.

   If time-zone is supplied, daylight saving time information is
ignored.  The daylight saving time flag is nil if time-zone is supplied.

Examples::
..........

      (decode-universal-time 0 0) =>  0, 0, 0, 1, 1, 1900, 0, false, 0

     ;; The next two examples assume Eastern Daylight Time.
      (decode-universal-time 2414296800 5) =>  0, 0, 1, 4, 7, 1976, 6, false, 5
      (decode-universal-time 2414293200) =>  0, 0, 1, 4, 7, 1976, 6, true, 5

     ;; This example assumes that the time zone is Eastern Daylight Time
     ;; (and that the time zone is constant throughout the example).
      (let* ((here (nth 8 (multiple-value-list (get-decoded-time)))) ;Time zone
             (recently (get-universal-time))
             (a (nthcdr 7 (multiple-value-list (decode-universal-time recently))))
             (b (nthcdr 7 (multiple-value-list (decode-universal-time recently here)))))
        (list a b (equal a b))) =>  ((T 5) (NIL 5) NIL)

Affected By::
.............

Implementation-dependent mechanisms for calculating when or if daylight
savings time is in effect for any given session.

See Also::
..........

*note encode-universal-time:: , *note get-universal-time:: , *note
Time::


File: gcl.info,  Node: encode-universal-time,  Next: get-universal-time,  Prev: decode-universal-time,  Up: Environment Dictionary

25.2.2 encode-universal-time [function]
---------------------------------------

Syntax::
........

'encode-universal-time' second minute hour date month year &optional
time-zone
=> universal-time

Arguments and Values::
......................

second, minute, hour, date, month, year, time-zone--the corresponding
parts of a decoded time.  (Note that some of the nine values in a full
decoded time are redundant, and so are not used as inputs to this
function.)

   universal-time--a universal time.

Description::
.............

encode-universal-time converts a time from Decoded Time format to a
universal time.

   If time-zone is supplied, no adjustment for daylight savings time is
performed.

Examples::
..........

      (encode-universal-time 0 0 0 1 1 1900 0) =>  0
      (encode-universal-time 0 0 1 4 7 1976 5) =>  2414296800
     ;; The next example assumes Eastern Daylight Time.
      (encode-universal-time 0 0 1 4 7 1976) =>  2414293200

See Also::
..........

*note decode-universal-time:: , get-decoded-time


File: gcl.info,  Node: get-universal-time,  Next: sleep,  Prev: encode-universal-time,  Up: Environment Dictionary

25.2.3 get-universal-time, get-decoded-time [Function]
------------------------------------------------------

'get-universal-time' <no arguments> => universal-time

   'get-decoded-time' <no arguments>
=> second, minute, hour, date, month, year, day, daylight-p, zone

Arguments and Values::
......................

universal-time--a universal time.

   second, minute, hour, date, month, year, day, daylight-p, zone--a
decoded time.

Description::
.............

get-universal-time returns the current time, represented as a universal
time.

   get-decoded-time returns the current time, represented as a decoded
time.

Examples::
..........

     ;; At noon on July 4, 1976 in Eastern Daylight Time.
      (get-decoded-time) =>  0, 0, 12, 4, 7, 1976, 6, true, 5
     ;; At exactly the same instant.
      (get-universal-time) =>  2414332800
     ;; Exactly five minutes later.
      (get-universal-time) =>  2414333100
     ;; The difference is 300 seconds (five minutes)
      (- * **) =>  300

Affected By::
.............

The time of day (i.e., the passage of time), the system clock's ability
to keep accurate time, and the accuracy of the system clock's initial
setting.

Exceptional Situations::
........................

An error of type error might be signaled if the current time cannot be
determined.

See Also::
..........

*note decode-universal-time:: , *note encode-universal-time:: , *note
Time::

Notes::
.......

      (get-decoded-time) == (decode-universal-time (get-universal-time))

   No implementation is required to have a way to verify that the time
returned is correct.  However, if an implementation provides a validity
check (e.g., the failure to have properly initialized the system clock
can be reliably detected) and that validity check fails, the
implementation is strongly encouraged (but not required) to signal an
error of type error (rather than, for example, returning a
known-to-be-wrong value) that is correctable by allowing the user to
interactively set the correct time.


File: gcl.info,  Node: sleep,  Next: apropos,  Prev: get-universal-time,  Up: Environment Dictionary

25.2.4 sleep [Function]
-----------------------

'sleep' seconds => nil

Arguments and Values::
......................

seconds--a non-negative real.

Description::
.............

Causes execution to cease and become dormant for approximately the
seconds of real time indicated by seconds, whereupon execution is
resumed.

Examples::
..........

      (sleep 1) =>  NIL

     ;; Actually, since SLEEP is permitted to use approximate timing,
     ;; this might not always yield true, but it will often enough that
     ;; we felt it to be a productive example of the intent.
      (let ((then (get-universal-time))
            (now  (progn (sleep 10) (get-universal-time))))
        (>= (- now then) 10))
     =>  true

Side Effects::
..............

Causes processing to pause.

Affected By::
.............

The granularity of the scheduler.

Exceptional Situations::
........................

Should signal an error of type type-error if seconds is not a
non-negative real.


File: gcl.info,  Node: apropos,  Next: describe,  Prev: sleep,  Up: Environment Dictionary

25.2.5 apropos, apropos-list [Function]
---------------------------------------

'apropos' string &optional package => <no values>

   'apropos-list' string &optional package => symbols

Arguments and Values::
......................

string--a string designator.

   package--a package designator or nil.  The default is nil.

   symbols--a list of symbols.

Description::
.............

These functions search for interned symbols whose names contain the
substring string.

   For apropos, as each such symbol is found, its name is printed on
standard output.  In addition, if such a symbol is defined as a function
or dynamic variable, information about those definitions might also be
printed.

   For apropos-list, no output occurs as the search proceeds; instead a
list of the matching symbols is returned when the search is complete.

   If package is non-nil, only the symbols accessible in that package
are searched; otherwise all symbols accessible in any package are
searched.

   Because a symbol might be available by way of more than one
inheritance path, apropos might print information about the same symbol
more than once, or apropos-list might return a list containing duplicate
symbols.

   Whether or not the search is case-sensitive is
implementation-defined.

Affected By::
.............

The set of symbols which are currently interned in any packages being
searched.

   apropos is also affected by *standard-output*.


File: gcl.info,  Node: describe,  Next: describe-object,  Prev: apropos,  Up: Environment Dictionary

25.2.6 describe [Function]
--------------------------

'describe' object &optional stream => <no values>

Arguments and Values::
......................

object--an object.

   stream--an output stream designator.  The default is standard output.

Description::
.............

describe displays information about object

   to stream.

   For example, describe of a symbol might show the symbol's value, its
definition, and each of its properties.  describe of a float might show
the number's internal representation in a way that is useful for
tracking down round-off errors.  In all cases, however, the nature and
format of the output of describe is implementation-dependent.

   describe can describe something that it finds inside the object; in
such cases, a notational device such as increased indentation or
positioning in a table is typically used in order to visually
distinguish such recursive descriptions from descriptions of the
argument object.

   The actual act of describing the object is implemented by
describe-object.  describe exists as an interface primarily to manage
argument defaulting (including conversion of arguments t and nil into
stream objects) and to inhibit any return values from describe-object.

   describe is not intended to be an interactive function.  In a
conforming implementation, describe must not, by default, prompt for
user input.  User-defined methods for describe-object are likewise
restricted.

Side Effects::
..............

Output to standard output or terminal I/O.

Affected By::
.............

*standard-output* and *terminal-io*, methods on describe-object and
print-object for objects having user-defined classes.

See Also::
..........

*note inspect:: , *note describe-object::


File: gcl.info,  Node: describe-object,  Next: trace,  Prev: describe,  Up: Environment Dictionary

25.2.7 describe-object [Standard Generic Function]
--------------------------------------------------

Syntax::
........

'describe-object' object stream => implementation-dependent

Method Signatures::
...................

'describe-object' (object standard-object) stream

Arguments and Values::
......................

object--an object.

   stream--a stream.

Description::
.............

The generic function describe-object prints a description of object to a
stream.  describe-object is called by describe; it must not be called by
the user.

   Each implementation is required to provide a method on the class
standard-object and methods on enough other classes so as to ensure that
there is always an applicable method.  Implementations are free to add
methods for other classes.  Users can write methods for describe-object
for their own classes if they do not wish to inherit an
implementation-supplied method.

   Methods on describe-object can recursively call describe.
Indentation, depth limits, and circularity detection are all taken care
of automatically, provided that each method handles exactly one level of
structure and calls describe recursively if there are more structural
levels.  The consequences are undefined if this rule is not obeyed.

   In some implementations the stream argument passed to a
describe-object method is not the original stream, but is an
intermediate stream that implements parts of describe.  Methods should
therefore not depend on the identity of this stream.

Examples::
..........

      (defclass spaceship ()
        ((captain :initarg :captain :accessor spaceship-captain)
         (serial# :initarg :serial-number :accessor spaceship-serial-number)))

      (defclass federation-starship (spaceship) ())

      (defmethod describe-object ((s spaceship) stream)
        (with-slots (captain serial#) s
          (format stream "~&~S is a spaceship of type ~S,~
                          ~
                            and with serial number ~D.~
                  s (type-of s) captain serial#)))

      (make-instance 'federation-starship
                     :captain "Rachel Garrett"
                     :serial-number "NCC-1701-C")
     =>  #<FEDERATION-STARSHIP 26312465>

      (describe *)
      |>  #<FEDERATION-STARSHIP 26312465> is a spaceship of type FEDERATION-STARSHIP,
      |>  with Rachel Garrett at the helm and with serial number NCC-1701-C.
     =>  <no values>

See Also::
..........

*note describe::

Notes::
.......

The same implementation techniques that are applicable to print-object
are applicable to describe-object.

   The reason for making the return values for describe-object
unspecified is to avoid forcing users to include explicit (values) in
all of their methods.  describe takes care of that.


File: gcl.info,  Node: trace,  Next: step,  Prev: describe-object,  Up: Environment Dictionary

25.2.8 trace, untrace [Macro]
-----------------------------

'trace' {function-name}* => trace-result

   'untrace' {function-name}* => untrace-result

Arguments and Values::
......................

function-name--a function name.

   trace-result--implementation-dependent, unless no function-names are
supplied, in which case trace-result is a list of function names.

   untrace-result--implementation-dependent.

Description::
.............

trace and untrace control the invocation of the trace facility.

   Invoking trace with one or more function-names causes the denoted
functions to be "traced."  Whenever a traced function is invoked,
information about the call, about the arguments passed, and about any
eventually returned values is printed to trace output.  If trace is used
with no function-names, no tracing action is performed; instead, a list
of the functions currently being traced is returned.

   Invoking untrace with one or more function names causes those
functions to be "untraced" (i.e., no longer traced).  If untrace is used
with no function-names, all functions currently being traced are
untraced.

   If a function to be traced has been open-coded (e.g., because it was
declared inline), a call to that function might not produce trace
output.

Examples::
..........

      (defun fact (n) (if (zerop n) 1 (* n (fact (- n 1)))))
     =>  FACT
      (trace fact)
     =>  (FACT)
     ;; Of course, the format of traced output is implementation-dependent.
      (fact 3)
      |>  1 Enter FACT 3
      |>  | 2 Enter FACT 2
      |>  |   3 Enter FACT 1
      |>  |   | 4 Enter FACT 0
      |>  |   | 4 Exit FACT 1
      |>  |   3 Exit FACT 1
      |>  | 2 Exit FACT 2
      |>  1 Exit FACT 6
     =>  6

Side Effects::
..............

Might change the definitions of the functions named by function-names.

Affected By::
.............

Whether the functions named are defined or already being traced.

Exceptional Situations::
........................

Tracing an already traced function, or untracing a function not
currently being traced, should produce no harmful effects, but might
signal a warning.

See Also::
..........

*trace-output*, *note step::

Notes::
.......

trace and untrace may also accept additional implementation-dependent
argument formats.  The format of the trace output is
implementation-dependent.

   Although trace can be extended to permit non-standard options,
implementations are nevertheless encouraged (but not required) to warn
about the use of syntax or options that are neither specified by this
standard nor added as an extension by the implementation, since they
could be symptomatic of typographical errors or of reliance on features
supported in implementations other than the current implementation.


File: gcl.info,  Node: step,  Next: time,  Prev: trace,  Up: Environment Dictionary

25.2.9 step [Macro]
-------------------

'step' form => {result}*

Arguments and Values::
......................

form--a form; evaluated as described below.

   results--the values returned by the form.

Description::
.............

step implements a debugging paradigm wherein the programmer is allowed
to step through the evaluation of a form.  The specific nature of the
interaction,

   including which I/O streams are used and whether the stepping has
lexical or dynamic scope,

   is implementation-defined.

   step evaluates form in the current environment.  A call to step can
be compiled, but it is acceptable for an implementation to interactively
step through only those parts of the computation that are interpreted.

   It is technically permissible for a conforming implementation to take
no action at all other than normal execution of the form.  In such a
situation, (step form) is equivalent to, for example, (let () form).  In
implementations where this is the case, the associated documentation
should mention that fact.

See Also::
..........

*note trace::

Notes::
.......

Implementations are encouraged to respond to the typing of ? or the
pressing of a "help key" by providing help including a list of commands.


File: gcl.info,  Node: time,  Next: internal-time-units-per-second,  Prev: step,  Up: Environment Dictionary

25.2.10 time [Macro]
--------------------

'time' form => {result}*

Arguments and Values::
......................

form--a form; evaluated as described below.

   results--the values returned by the form.

Description::
.............

time evaluates form in the current environment (lexical and dynamic).  A
call to time can be compiled.

   time prints various timing data and other information to trace
output.  The nature and format of the printed information is
implementation-defined.  Implementations are encouraged to provide such
information as elapsed real time, machine run time, and storage
management statistics.

Affected By::
.............

The accuracy of the results depends, among other things, on the accuracy
of the corresponding functions provided by the underlying operating
system.

   The magnitude of the results may depend on the hardware, the
operating system, the lisp implementation, and the state of the global
environment.  Some specific issues which frequently affect the outcome
are hardware speed, nature of the scheduler (if any), number of
competing processes (if any), system paging, whether the call is
interpreted or compiled, whether functions called are compiled, the kind
of garbage collector involved and whether it runs, whether internal data
structures (e.g., hash tables) are implicitly reorganized, etc.

See Also::
..........

*note get-internal-real-time:: , *note get-internal-run-time::

Notes::
.......

In general, these timings are not guaranteed to be reliable enough for
marketing comparisons.  Their value is primarily heuristic, for tuning
purposes.

   For useful background information on the complicated issues involved
in interpreting timing results, see Performance and Evaluation of Lisp
Programs.


File: gcl.info,  Node: internal-time-units-per-second,  Next: get-internal-real-time,  Prev: time,  Up: Environment Dictionary

25.2.11 internal-time-units-per-second [Constant Variable]
----------------------------------------------------------

Constant Value::
................

A positive integer, the magnitude of which is implementation-dependent.

Description::
.............

The number of internal time units in one second.

See Also::
..........

*note get-internal-run-time:: , *note get-internal-real-time::

Notes::
.......

These units form the basis of the Internal Time format representation.


File: gcl.info,  Node: get-internal-real-time,  Next: get-internal-run-time,  Prev: internal-time-units-per-second,  Up: Environment Dictionary

25.2.12 get-internal-real-time [Function]
-----------------------------------------

'get-internal-real-time' <no arguments> => internal-time

Arguments and Values::
......................

internal-time--a non-negative integer.

Description::
.............

get-internal-real-time returns as an integer the current time in
internal time units, relative to an arbitrary time base.  The difference
between the values of two calls to this function is the amount of
elapsed real time (i.e., clock time) between the two calls.

Affected By::
.............

Time of day (i.e., the passage of time).  The time base affects the
result magnitude.

See Also::
..........

*note internal-time-units-per-second::


File: gcl.info,  Node: get-internal-run-time,  Next: disassemble,  Prev: get-internal-real-time,  Up: Environment Dictionary

25.2.13 get-internal-run-time [Function]
----------------------------------------

'get-internal-run-time' <no arguments> => internal-time

Arguments and Values::
......................

internal-time--a non-negative integer.

Description::
.............

Returns as an integer the current run time in internal time units.  The
precise meaning of this quantity is implementation-defined; it may
measure real time, run time, CPU cycles, or some other quantity.  The
intent is that the difference between the values of two calls to this
function be the amount of time between the two calls during which
computational effort was expended on behalf of the executing program.

Affected By::
.............

The implementation, the time of day (i.e., the passage of time).

See Also::
..........

*note internal-time-units-per-second::

Notes::
.......

Depending on the implementation, paging time and garbage collection time
might be included in this measurement.  Also, in a multitasking
environment, it might not be possible to show the time for just the
running process, so in some implementations, time taken by other
processes during the same time interval might be included in this
measurement as well.


File: gcl.info,  Node: disassemble,  Next: documentation,  Prev: get-internal-run-time,  Up: Environment Dictionary

25.2.14 disassemble [Function]
------------------------------

'disassemble' fn => nil

Arguments and Values::
......................

fn--an extended function designator or a lambda expression.

Description::
.............

The function disassemble is a debugging aid that composes symbolic
instructions or expressions in some implementation-dependent language
which represent the code used to produce the function which is or is
named by the argument fn.  The result is displayed to standard output in
an implementation-dependent format.

   If fn is a lambda expression or interpreted function, it is compiled
first and the result is disassembled.

   If the fn designator is a function name, the function that it names
is disassembled.

   (If that function is an interpreted function, it is first compiled
but the result of this implicit compilation is not installed.)

Examples::
..........

      (defun f (a) (1+ a)) =>  F
      (eq (symbol-function 'f)
          (progn (disassemble 'f)
                 (symbol-function 'f))) =>  true

Affected By::
.............

*standard-output*.

Exceptional Situations::
........................

Should signal an error of type type-error if fn is not an extended
function designator or a lambda expression.


File: gcl.info,  Node: documentation,  Next: room,  Prev: disassemble,  Up: Environment Dictionary

25.2.15 documentation, (setf documentation) [Standard Generic Function]
-----------------------------------------------------------------------

Syntax::
........

'documentation' x doc-type => documentation

   '(setf documentation)' new-value x doc-type => new-value

Argument Precedence Order::
...........................

doc-type, object

Method Signatures::
...................

Functions, Macros, and Special Forms
....................................

documentation (x 'function') (doc-type (eql 't))
(setf documentation) new-value(x 'function') (doc-type (eql 't))

   documentation (x 'function') (doc-type (eql 'function))
(setf documentation) new-value(x 'function') (doc-type (eql 'function))

   documentation (x 'list') (doc-type (eql 'function))
(setf documentation) new-value(x 'list') (doc-type (eql 'function))

   documentation (x 'list') (doc-type (eql 'compiler-macro))
(setf documentation) new-value(x 'list') (doc-type (eql
'compiler-macro))

   documentation (x 'symbol') (doc-type (eql 'function))
(setf documentation) new-value(x 'symbol') (doc-type (eql 'function))

   documentation (x 'symbol') (doc-type (eql 'compiler-macro))
(setf documentation) new-value(x 'symbol') (doc-type (eql
'compiler-macro))

   documentation (x 'symbol') (doc-type (eql 'setf))
(setf documentation) new-value(x 'symbol') (doc-type (eql 'setf))

Method Combinations
...................

documentation (x 'method-combination') (doc-type (eql 't))
(setf documentation) new-value(x 'method-combination') (doc-type (eql
't))

   documentation (x 'method-combination') (doc-type (eql
'method-combination))
(setf documentation) new-value(x 'method-combination') (doc-type (eql
'method-combination))

   documentation (x 'symbol') (doc-type (eql 'method-combination))
(setf documentation) new-value(x 'symbol') (doc-type (eql
'method-combination))

Methods
.......

documentation (x 'standard-method') (doc-type (eql 't))
(setf documentation) new-value(x 'standard-method') (doc-type (eql 't))

Packages
........

documentation (x 'package') (doc-type (eql 't))
(setf documentation) new-value(x 'package') (doc-type (eql 't))

Types, Classes, and Structure Names
...................................

documentation (x 'standard-class') (doc-type (eql 't))
(setf documentation) new-value(x 'standard-class') (doc-type (eql 't))

   documentation (x 'standard-class') (doc-type (eql 'type))
(setf documentation) new-value(x 'standard-class') (doc-type (eql
'type))

   documentation (x 'structure-class') (doc-type (eql 't))
(setf documentation) new-value(x 'structure-class') (doc-type (eql 't))

   documentation (x 'structure-class') (doc-type (eql 'type))
(setf documentation) new-value(x 'structure-class') (doc-type (eql
'type))

   documentation (x 'symbol') (doc-type (eql 'type))
(setf documentation) new-value(x 'symbol') (doc-type (eql 'type))

   documentation (x 'symbol') (doc-type (eql 'structure))
(setf documentation) new-value(x 'symbol') (doc-type (eql 'structure))

Variables
.........

documentation (x 'symbol') (doc-type (eql 'variable))
(setf documentation) new-value(x 'symbol') (doc-type (eql 'variable))

Arguments and Values::
......................

x--an object.

   doc-type--a symbol.

   documentation--a string, or nil.

   new-value--a string.

Description::
.............

The generic function documentation returns the documentation string
associated with the given object if it is available; otherwise it
returns nil.

   The generic function (setf documentation) updates the documentation
string associated with x to new-value.  If x is a list, it must be of
the form (setf symbol).

   Documentation strings are made available for debugging purposes.
Conforming programs are permitted to use documentation strings when they
are present, but should not depend for their correct behavior on the
presence of those documentation strings.  An implementation is permitted
to discard documentation strings at any time for implementation-defined
reasons.

   The nature of the documentation string returned depends on the
doc-type, as follows:

compiler-macro
     Returns the documentation string of the compiler macro whose name
     is the function name x.

function
     If x is a function name, returns the documentation string of the
     function, macro, or special operator whose name is x.

     If x is a function, returns the documentation string associated
     with x.

method-combination
     If x is a symbol, returns the documentation string of the method
     combination whose name is x.

     If x is a method combination, returns the documentation string
     associated with x.

setf
     Returns the documentation string of

     the setf expander

     whose name is the symbol x.

structure
     Returns the documentation string associated with the structure name
     x.

t
     Returns a documentation string specialized on the class of the
     argument x itself.  For example, if x is a function, the
     documentation string associated with the function x is returned.

type
     If x is a symbol, returns the documentation string of the class
     whose name is the symbol x, if there is such a class.  Otherwise,
     it returns the documentation string of the type which is the type
     specifier symbol x.

     If x is a structure class or standard class, returns the
     documentation string associated with the class x.

variable
     Returns the documentation string of the dynamic variable or
     constant variable whose name is the symbol x.

   A conforming implementation or a conforming program may extend the
set of symbols that are acceptable as the doc-type.

Notes::
.......

This standard prescribes no means to retrieve the documentation strings
for individual slots specified in a defclass form, but implementations
might still provide debugging tools and/or programming language
extensions which manipulate this information.  Implementors wishing to
provide such support are encouraged to consult the Metaobject Protocol
for suggestions about how this might be done.

