REF IO                                    Titch Le Bek, Rob Duncan, 1986

       COPYRIGHT University of Sussex 1993. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<    LISP INPUT AND OUTPUT    >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<        PROCEDURES           >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This file  briefly  describes  the functions,  variables  and  constants
documented in Chapter 22  of the standard Common  Lisp guide, which  is:
Common Lisp: The Language (Guy L. Steele, Digital Press, 1984).


-------------------------------------------------
1  A Listing of Functions Variables and Constants
-------------------------------------------------

*print-array*                                                 [variable]
        Controls the printing of array values. If nil, then the contents
        of arrays other than strings are never printed; if non-nil, then
        all arrays are fully displayed. Initial value: t


*print-base*                                                  [variable]
        The value of *print-base*,  which must  be an integer from 2  to
        36 inclusive, determines in what radix the printer will  display
        rationals. For radices above 10, the letters A to Z are used  to
        represent digits above 9. Initial value: 10


*print-case*                                                  [variable]
        Controls the case in which upper-case characters in the internal
        print names of symbols are displayed.  Its value must be one  of
        :upcase, :downcase or :capitalize, and any upper-case characters
        are accordingly displayed in upper-case, lower-case or in  mixed
        case so as to capitalize words. Initial value: :upcase.


*print-circle*                                                [variable]
        If  nil,  the  printer  will  not  attempt  to  spot  cycles  in
        structures being printed and will fail to terminate on  circular
        structures. If non-nil,  cycles will be  detected and  displayed
        using the `#n=' and `#n#' syntax. Initial value: nil.


*print-escape*                                                [variable]
        Controls the printing of escape  characters in symbols. If  nil,
        then escape characters are not  printed at all; if non-nil,  the
        output is  such that  a subsequent  read would  return an  equal
        structure. The function  princ effectively binds  *print-escape*
        to nil; prin1 binds it to t. Initial value: t


*print-gensym*                                                [variable]
        Controls the printing of symbols which have no home package:  if
        the value is non-nil, such  symbols are printed with the  prefix
        `#:'. Initial value: t.


*print-length*                                                [variable]
        If this variable is  set to an integer  value, then the  printer
        will display at most that number of elements from each structure
        printed; extra elements are indicated  by three dots. If set  to
        nil then all elements are displayed. Initial value: nil.


*print-level*                                                 [variable]
        If this variable is  set to an integer  value, then the  printer
        will display  at  most that  number  of levels  of  each  nested
        structure printed, where the  initial structure counts as  level
        0, each of its components as level 1 and so on. Any object which
        occurs at a  level greater  than or equal  to *print-level*  and
        which itself has components is printed as `#'. If  *print-level*
        is nil  then all  structures are  completely displayed.  Initial
        value: nil.


*print-lines*                                                 [variable]
        When given  a  value  other  than  its  initial  value  of  nil,
        *print-lines* limits the  number of output  lines produced  when
        something is pretty printed. If an attempt is made to go  beyond
        *print-lines* lines, ` ..' (a space and two periods) is  printed
        at the end  of the  last line followed  by all  of the  suffixes
        (closing delimiters) that are pending to be printed.


*print-miser-width*                                           [variable]
        If *print-miser-width* 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 *print-miser-width*.


*print-pprint-dispatch*                                       [variable]
        When *print-pretty* is  not nil, printing  is controlled by  the
        `pprint dispatch table'  stored in *print-pprint-dispatch*.  The
        initial-value is implementation-dependent and causes traditional
        pretty printing of Lisp code.


*print-pretty*                                                [variable]
        If this  variable  is  nil,  then only  the  minimum  amount  of
        whitespace is output when an expression is printed. If set  to a
        non-nil value, the n the printer will use extra whitespace  (and
        make some  other  minor changes)  to  make the  expression  more
        readable. Initial value: t.


*print-radix*                                                 [variable]
        If this variable is non-nil,  the printer will indicate  against
        each rational number displayed, the radix which it has used. For
        a number n printed  with radix r, the  general output format  is
        `#rrn'; for binary, octal and  hex numbers this is shortened  to
        `#bn', `#on' and `#xn' as appropriate. Integers printed in  base
        10 are indicated  simply by  a trailing  decimal point.  Initial
        value: nil.


*print-readably*                                              [variable]
        The initial value  of *print-readably*  is nil. If  it is  true,
        then  printing  any  object   must  either  produce  a   printed
        representation that the  reader will accept  or signal an  error
        (of type print-not-readable).


*print-right-margin*                                          [variable]
        When *print-right-margin*  is not  nil, it  specifies the  right
        margin   to   use   when    making   layout   decisions.    When
        *print-right-margin* is  nil  (the  initial  value),  the  right
        margin is set at the maximum  line length that can be  displayed
        by the output stream without  wraparound or truncation. If  this
        cannot  be  determined,   the  right   margin  is   set  to   an
        implementation-dependent value.


*read-base*                                                   [variable]
        The value of this variable controls the interpretation of tokens
        by read as  being integers or  ratios. It may  take any  integer
        value between 2 and 36 inclusive, and the value is the radix  in
        which integers and ratios are to be read. It does not change the
        interpretation of floating-point numbers, which are always  read
        as decimals, nor does it  affect numbers which are entered  with
        an explicit  radix specifier  (#O,  #X, #B,  #nR or  a  trailing
        decimal point). For radices greater than 10, the letters A  to Z
        are used to  stand for digits  greater than 9;  this means  that
        tokens which would normally  be read as symbols  can be read  as
        numbers. Initial value: 10.


*read-default-float-format*                                   [variable]
        Must be  set  to a  type  specifier symbol  for  floating  point
        numbers. It  indicates the  format in  which the  reader  should
        interpret floating-point  numbers  without exponent  markers  or
        with the  e  or E  marker;  numbers which  have  other  exponent
        markers are always read in  the format specified by the  marker.
        The printer also  uses this  variable to guide  the printing  of
        exponent  markers  on  floating-point  numbers.  Initial  value:
        single-float.


*read-eval*                                                   [variable]
        If nil,  the read  macro `#.'  does not  evaluate the  following
        form, but signals an error instead. Initial value: t.


*read-suppress*                                               [variable]
        If this variable is set to a non-nil value, most of the features
        of the reader are suppressed;  input characters are parsed,  but
        much of what is read is not interpreted. Its primary function is
        to support the constructs `#+' and  `#-' which may want to  skip
        over portions  of  input  text which  are  not  strictly  legal.
        Initial value: nil.


*readtable*                                                   [variable]
        The value of *readtable* is  the current readtable. Its  initial
        value is a  table set up  for the standard  Common Lisp  syntax;
        rebinding it will change the readtable being used.


(clear-input &optional stream)                                [function]
        Clears any  buffered input  associated with  stream and  returns
        nil.


(clear-output &optional stream)                               [function]
        Attempts to ensure that  all output sent  to stream has  reached
        its destination and only then returns nil.


(copy-readtable &optional from-readtable to-readtable)        [function]
        A copy is made of from-readtable. If it is nil then a copy  of a
        standard Common  Lisp  readtable  is made.  If  to-readtable  is
        unsupplied  or  nil,   a  new  readtable   is  made.   Otherwise
        to-readtable must be a  readtable which is destructively  copied
        into.


(finish-output &optional stream)                              [function]
        Returns nil  when all  output  sent to  stream has  reached  its
        destination.


(force-output &optional stream)                               [function]
        Initiates the emptying  of any  internal buffers  in the  output
        stream stream (which defaults to *standard-output*) but  returns
        nil without waiting for completion.


(format destination string &rest args)                        [function]
        Formats  string  and  sends  it  to  destination.  The   printed
        representation of args may occur in the result.


(fresh-line &optional stream)                                 [function]
        Outputs a new  line unless the  output stream stream  is at  the
        start of a line.


(get-dispatch-macro-character disp-character sub-character    [function]
                                function &optional readtable)
        Returns the  macro-character  function for  sub-character  under
        disp-character or nil  if there is  no such function  associated
        with sub-character.


(get-macro-character character &optional readtable)           [function]
        Returns  the  function   associated  with   character  and   the
        non-terminating-p flag. Returns nil  if character does not  have
        macro-character  status.  Readtable  defaults  to  the   current
        readtable.


(listen &optional stream)                                     [function]
        Returns true if there is a character immediately available  from
        the input stream  stream and  false if not.  It is  particularly
        useful when stream obtains characters from an interactive device
        such as a keyboard.


(make-dispatch-macro-character character &optional            [function]
                               non-terminating-p readtable)
        This causes character  to be  a dispatching  macro character  in
        readtable. If non-terminating-p  is not  nil then  it will  be a
        non-terminating macro  character.  make-dispatch-macro-character
        returns t.


(parse-integer string &key :start :end :radix :junk-allowed)  [function]
        Examines the substring of string  delimited by :start and  :end.
        It skips over whitespace characters  and then attempts to  parse
        an integer. :radix defaults to 10 and must be an integer between
        2 and  36. If  :junk-allowed is  not nil  then the  first  value
        returned is the value of the number parsed as an integer or  nil
        if no syntactically correct  integer was seen. If  :junk-allowed
        is nil then the  entire substring is scanned.  The value of  the
        substring parsed as an integer is returned. An error is signaled
        if the substring does not consist entirely of the representation
        of an integer. In either case  the second value returned is  the
        index into string of the delimiter that terminated the parse, or
        it is the index beyond the substring if the parse terminated  at
        the end of the substring.


(peek-char &optional type stream error value recursive-p)     [function]
        If the  peek  type  type  is nil,  peek-char  returns  the  next
        character to be read from the input stream stream. The next time
        input is done from stream the character will still be there.  If
        type is t  then peek-char skips  over whitespace characters  and
        performs the  peeking operation  on the  next character.  It  is
        useful  for   finding  the   beginning  of   the  next   printed
        representation of a Lisp object.  If type is a character  object
        then peek-char  skips over  input characters  until a  character
        that is char= to that object is found; that character is left in
        stream.


(pprint object &optional stream)                              [function]
        Like print except that the trailing space is omitted and  object
        is printed  with  the  *print-pretty* flag  non-nil  to  produce
        "pretty" output. pprint returns no values.


(prin1 object &optional stream)                               [function]
        prin1 outputs the printed representation of object to the output
        stream stream.


(prin1-to-string object)                                      [function]
        object is printed as if by  prin1 but the characters that  would
        be output are made into a string which is returned.


(princ object &optional stream)                               [function]
        Like prin1 except  that the output  has no escape  characters. A
        symbol is printed as simply the characters of its print  name; a
        string is printed without surrounding double quotes. The  output
        looks good to people whereas  the output from prin1 is  intended
        to be acceptable to the function read. princ returns object.


(princ-to-string object)                                      [function]
        object is printed as if by  princ but the characters that  would
        be output are made into a string which is returned.


(print object &optional stream)                               [function]
        Like prin1 except that the  printed representation of object  is
        preceded by a new  line and followed by  a space. print  returns
        object.


(print-unreadable-object (object stream &key :type identity)     [macro]
                         {declaration}*
                         {form}*)

        This macro is used to output a terse non-readable representation
        of object to stream. print-unreadable-object first writes #<  to
        stream, then executes {form}*, and finally writes a closing > to
        stream.

        If :type  is  true, the  body  output  is preceded  by  a  brief
        description  of  object's  type,  and  a  space  character.   If
        :identity is  true,  the body  output  is followed  by  a  space
        character and then an indication of the objects unique  identity
        (typically an integer derived from its storage address).

        If *print-readably* is true, print-unreadable-object signals  an
        error of type print-not-readable.


(read &optional stream error value recursive)                 [function]
        read reads in the printed  representation of a Lisp object  from
        the input stream stream, builds a corresponding Lisp object, and
        returns the object. error controls what happens if input is from
        a file and  the end of  the file is  reached. If it  is true  an
        error is signaled at end  of file, otherwise value is  returned.
        recursive, if not nil,  specifies that this  is not a  top-level
        call to read but an  embedded call, typically from the  function
        for a macro character.


(readtable-case readtable)                                    [function]
        Returns a keyword symbol that indicates how readtable  processes
        unescaped  upper  or  lower  case  characters.  There  are  four
        possible values: :upcase, :downcase, :preserve, and :invert.


(read-byte stream &optional error value)                      [function]
        Reads one byte from the  binary input stream stream and  returns
        it in the  form of an  integer. error controls  what happens  if
        input is from a file and the end of the file is reached. If  the
        value of error is true then an error is signaled at end of file,
        otherwise value is returned.


(read-char &optional stream error value recursive)            [function]
        read-char inputs one character from the input stream stream  and
        returns it  as  a  character object.  The  corresponding  output
        function is write-char. error controls what happens if input  is
        from a file and the end of the file is reached. If error is true
        an  error  is  signaled  at  end-of-file,  otherwise  value   is
        returned. recursive, if  not nil, specifies  that this is  not a
        top-level call to read but an embedded call, typically from  the
        function for a macro character.


(read-char-no-hang &optional stream error value recursive)    [function]
        read-char-no-hang is exactly like read-char except that if it is
        necessary  to  wait  in  order  to  get  a  character,  nil   is
        immediately returned without waiting. This allows for  efficient
        checking for input availability.  If error is  true an error  is
        signaled at end of file, otherwise value is returned. recursive,
        if not nil, specifies that this is not a top-level call to  read
        but an embedded call,  typically from the  function for a  macro
        character.


(read-delimited-list character &optional stream recursive)    [function]
        Reads objects  from stream  until the  next character  after  an
        object's representation is character. A list of the objects read
        is returned. recursive, if not nil, specifies that this is not a
        top-level call to read but an embedded call, typically
        from the function for a macro character.


(read-from-string string &optional error value                [function]
                    &key :start :end :preserve-whitespace)

        The characters  of string  are given  successively to  the  Lisp
        reader, and the Lisp object built by the reader is returned. The
        second value returned is the index of the first character in the
        string not read. error and value  control the action if the  end
        of the (sub)string is reached before the operation is completed.


(read-line &optional stream error value recursive)            [function]
        read-line reads in a  line of text terminated  by a newline.  It
        returns the line as  a character string. It  is usually used  to
        get a line of input from the user. A second returned value  is a
        flag that is false if the line was terminated normally, or  true
        if  end-of-file   terminated  the   line.  If   end-of-file   is
        encountered   immediately   then   end-of-file   processing   is
        controlled by error and value.


(read-preserving-whitespace &optional stream error value      [function]
                                                   recursive)
        This function is provided for some specialized situations  where
        it  is  desireable   to  determine   precisely  what   character
        terminated the extended  token. The distinction  between it  and
        read is established only by calls with recursive equal to nil or
        omitted.


(readtablep object)                                           [function]
        Returns t if object is a readtable; nil otherwise.


(set-dispatch-macro-character disp-character sub-character    [function]
                              function  &optional  readtable)
        Modifies  readtable  so   that  function   is  called   whenever
        disp-character followed  by  sub-character  is  read.  readtable
        defaults to the current readtable. Returns t.


(set-macro-character character function                       [function]
                     &optional non-terminating-p readtable)
        Causes character to be a macro character that when seen by  read
        causes function to  be called. If  non-terminating-p is not  nil
        then it will be a non-terminating macro character. Returns t.


(set-syntax-from-char to-character from-character             [function]
                      &optional to-readtable from-readtable)
        Converts the syntax  of to-character in  to-readtable to be  the
        same as from-character in from-readtable. to-readtable  defaults
        to the  current readtable,  and from-readtable  defaults to  nil
        which means use the syntaxes for the standard Lisp readtable.


(stream-element-type stream)                                  [function]
        Returns a type specifier for the objects that can be read  from,
        or written to, stream.


(terpri &optional stream)                                     [function]
        Outputs a new line to the output stream stream.


(unread-char character &optional stream)                      [function]
        unread-char puts character  onto the front  of the input  stream
        stream. character must be the most recently read character  from
        stream. Returns nil.


(with-standard-io-syntax {form}*)                                [macro]
        Executes  the  body  {form}*  as  an  implicit  progn  with  the
        "*print-xxx"  variables  described  above  locally  bound  their
        standard initial values.


(write object &key :stream :escape :radix :base               [function]
                   :circle :pretty :level :length
                   :case :gensym :array)
        Returns a printed representation of object written to the output
        stream. Returns object.


(write-byte integer stream)                                   [function]
        Writes one byte, the value of integer. It is an error if integer
        is not of  the type  specified as the  element-type argument  to
        open when the binary output stream stream was created. The value
        integer is returned.


(write-char character &optional stream)                       [function]
        Outputs character  to  the  output  stream  stream  and  returns
        character.


(write-line string &optional stream &key :start :end)         [function]
        Writes the characters  of the specified  substring of string  to
        the output stream stream and prints a new line.


(write-string string &optional stream &key :start :end)       [function]
        Writes characters of  the specified substring  of string to  the
        output stream stream.


(write-to-string object &key :escape :radix :base             [function]
                    :circle :pretty :level :length
                    :case :gensym :array)
        object is printed  as if by  write but the  characters that  are
        output are made into a string which is returned.


(y-or-n-p &optional format-string &rest args)                 [function]
        This predicate is for asking the user a question whose answer is
        either "yes" or "no". It prints out a message, reads an  answer,
        and returns t if the answer was "yes", or nil if the answer  was
        "no". If format-string is not  nil, then a fresh-line  operation
        is performed and format-string is printed as if it and args were
        given to format. Otherwise  it is assumed  that any message  has
        already been printed by other means.


(yes-or-no-p &optional format-string &rest args)              [function]
        This predicate is like y-or-n-p.  It is intended that the  reply
        require the  user  to  take  more  action  than  just  a  single
        keystroke, such as typing the full word "yes" or "no". It should
        therefore be used for unanticipated or important questions  that
        need to attract the users attention.



--- C.all/lisp/ref/io
--- Copyright University of Sussex 1993. All rights reserved.
