@node Streams and Reading, Special Forms and Functions, Lists, Top
@chapter Streams and Reading

@defun MAKE-ECHO-STREAM (input-stream output-stream)
Package:LISP

Returns a bidirectional stream which gets its input from INPUT-STREAM and
sends its output to OUTPUT-STREAM.  In addition, all input is echoed to
OUTPUT-STREAM.


@end defun

@defvar *READTABLE* 
Package:LISP
The current readtable.


@end defvar

@defun LOAD (filename &key (verbose *load-verbose*) (print nil) (if-does-not-exist :error))
Package:LISP

Loads the file named by FILENAME into GCL.


@end defun

@defun OPEN (filename &key (direction :input) (element-type 'string-char) (if-exists :error) (if-does-not-exist :error))
Package:LISP

Opens the file specified by FILENAME, which may be a string, a pathname,
or a stream.  Returns a stream for the open file.
DIRECTION is  :INPUT, :OUTPUT, :IO or :PROBE.
ELEMENT-TYPE is  STRING-CHAR, (UNSIGNED-BYTE n),
UNSIGNED-BYTE, (SIGNED-BYTE n), SIGNED-BYTE, CHARACTER, BIT, (MOD n), or
:DEFAULT.
IF-EXISTS is :ERROR, :NEW-VERSION, :RENAME,
:RENAME-AND-DELETE, :OVERWRITE, :APPEND, :SUPERSEDE, or NIL.
IF-DOES-NOT-EXIST is  :ERROR, :CREATE, or NIL.

If FILENAME begins with a vertical pipe sign: '|'  then the resulting
stream is actually a one way pipe.   It will be open for reading
or writing depending on the direction given.   The rest
of FILENAME in this case is passed to the /bin/sh command.   See
the posix description of popen for more details.
@example
(setq pipe (open "| wc < /tmp/jim"))
(format t "File has ~%d lines" (read pipe))
(close pipe)
@end example

@end defun

@defvar *PRINT-BASE* 
Package:LISP
The radix in which the GCL printer prints integers and rationals.
The value must be an integer from 2 to 36, inclusive.


@end defvar

@defun MAKE-STRING-INPUT-STREAM (string &optional (start 0) (end (length string)))
Package:LISP

Returns an input stream which will supply the characters of String between
Start and End in order.


@end defun

@defun PPRINT (object &optional (stream *standard-output*))
Package:LISP

Pretty-prints OBJECT.  Returns OBJECT.  Equivalent to
	(WRITE :STREAM STREAM :PRETTY T)
The SI:PRETTY-PRINT-FORMAT property N (which must be a non-negative integer)
of a symbol SYMBOL controls the pretty-printing of form
	(SYMBOL f1 ... fN fN+1 ... fM)
in such a way that the subforms fN+1, ..., fM are regarded as the 'body' of
the entire form.  For instance, the property value of 2 is initially given
to the symbol DO.


@end defun

@defvar *READ-DEFAULT-FLOAT-FORMAT* 
Package:LISP
The floating-point format the GCL reader uses when reading floating-point
numbers that have no exponent marker or have e or E for an exponent marker.
Must be one of SHORT-FLOAT, SINGLE-FLOAT, DOUBLE-FLOAT, and LONG-FLOAT.


@end defvar

@defun READ-PRESERVING-WHITESPACE (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
Package:LISP

Reads an object from STREAM, preserving the whitespace that followed the
object.


@end defun

@defun STREAMP (x)
Package:LISP

Returns T if X is a stream object; NIL otherwise.


@end defun


@defun SET-DISPATCH-MACRO-CHARACTER (disp-char sub-char function &optional (readtable *readtable*))
Package:LISP

Causes FUNCTION to be called when the DISP-CHAR followed by SUB-CHAR is
read.


@end defun

@deffn {Macro} WITH-OUTPUT-TO-STRING 
Package:LISP

Syntax:
@example
(with-output-to-string (var [string]) @{decl@}* @{form@}*)
@end example

Binds VAR to a string output stream that puts characters into STRING, which
defaults to a new string.  The stream is automatically closed on exit and
the string is returned.


@end deffn

@defun FILE-LENGTH (file-stream)
Package:LISP

Returns the length of the specified file stream.


@end defun

@defvar *PRINT-CASE* 
Package:LISP
The case in which the GCL printer should print ordinary symbols.
The value must be one of the keywords :UPCASE, :DOWNCASE, and :CAPITALIZE.


@end defvar

@defun PRINT (object &optional (stream *standard-output*))
Package:LISP

Outputs a newline character, and then prints OBJECT in the mostly readable
representation.  Returns OBJECT.  Equivalent to
	(PROGN (TERPRI STREAM) (WRITE OBJECT :STREAM STREAM :ESCAPE T)).


@end defun

@defun SET-MACRO-CHARACTER (char function &optional (non-terminating-p nil) (readtable *readtable*))
Package:LISP

Causes CHAR to be a macro character that, when seen by READ, causes FUNCTION
to be called.


@end defun

@defun FORCE-OUTPUT (&optional (stream *standard-output*))
Package:LISP

Attempts to force any buffered output to be sent.


@end defun

@defvar *PRINT-ARRAY* 
Package:LISP
Whether the GCL printer should print array elements.


@end defvar

@defun STREAM-ELEMENT-TYPE (stream)
Package:LISP

Returns a type specifier for the kind of object returned by STREAM.


@end defun

@defun WRITE-BYTE (integer stream)
Package:LISP

Outputs INTEGER to the binary stream STREAM.  Returns INTEGER.


@end defun

@defun MAKE-CONCATENATED-STREAM (&rest streams)
Package:LISP

Returns a stream which takes its input from each of the STREAMs in turn,
going on to the next at end of stream.


@end defun

@defun PRIN1 (object &optional (stream *standard-output*))
Package:LISP

Prints OBJECT in the mostly readable representation.  Returns OBJECT.
Equivalent to (WRITE OBJECT :STREAM STREAM :ESCAPE T).


@end defun

@defun PRINC (object &optional (stream *standard-output*))
Package:LISP

Prints OBJECT without escape characters.  Returns OBJECT.  Equivalent to
	(WRITE OBJECT :STREAM STREAM :ESCAPE NIL).


@end defun

@defun CLEAR-OUTPUT (&optional (stream *standard-output*))
Package:LISP

Clears the output stream STREAM.


@end defun

@defun TERPRI (&optional (stream *standard-output*))
Package:LISP

Outputs a newline character.


@end defun

@defun FINISH-OUTPUT (&optional (stream *standard-output*))
Package:LISP

Attempts to ensure that all output sent to STREAM has reached its destination,
and only then returns.


@end defun

@deffn {Macro} WITH-OPEN-FILE 
Package:LISP

Syntax:
@example
(with-open-file (stream filename @{options@}*) @{decl@}* @{form@}*)
@end example

Opens the file whose name is FILENAME, using OPTIONs, and binds the variable
STREAM to a stream to/from the file.  Then evaluates FORMs as a PROGN.
The file is automatically closed on exit.


@end deffn

@deffn {Special Form} DO 
Package:LISP

Syntax:
@example
(do (@{(var [init [step]])@}*) (endtest @{result@}*)
          @{decl@}* @{tag | statement@}*)
@end example

Creates a NIL block, binds each VAR to the value of the corresponding INIT,
and then executes STATEMENTs repeatedly until ENDTEST is satisfied.  After
each iteration, assigns to each VAR the value of the corresponding STEP.  When
ENDTEST is satisfied, evaluates RESULTs as a PROGN and returns the value(s) of
the last RESULT (or NIL if no RESULTs are supplied).  Performs variable
bindings and assignments all at once, just like LET and PSETQ do.


@end deffn

@defun READ-FROM-STRING (string &optional (eof-error-p t) (eof-value nil) &key (start 0) (end (length string)) (preserve-whitespace nil))
Package:LISP

Reads an object from STRING.


@end defun

@defun WRITE-STRING (string &optional (stream *standard-output*) &key (start 0) (end (length string)))
Package:LISP

Outputs STRING and returns it.


@end defun

@defvar *PRINT-LEVEL* 
Package:LISP
How many levels deep the GCL printer should print.  Unlimited if NIL.


@end defvar

@defvar *PRINT-RADIX* 
Package:LISP
Whether the GCL printer should print the radix indicator when printing
integers and rationals.


@end defvar

@defun Y-OR-N-P (&optional (format-string nil) &rest args)
Package:LISP

Asks the user a question whose answer is either 'Y' or 'N'.  If FORMAT-STRING
is non-NIL, then FRESH-LINE operation is performed, a message is printed as
if FORMAT-STRING and ARGs were given to FORMAT, and then a prompt
"(Y or N)" is printed.  Otherwise, no prompt will appear.


@end defun

@defun MAKE-BROADCAST-STREAM (&rest streams)
Package:LISP

Returns an output stream which sends its output to all of the given streams.


@end defun

@defun READ-CHAR (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
Package:LISP

Reads a character from STREAM.


@end defun

@defun PEEK-CHAR (&optional (peek-type nil) (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
Package:LISP

Peeks at the next character in the input stream STREAM.


@end defun

@defun OUTPUT-STREAM-P (stream)
Package:LISP

Returns non-nil if STREAM can handle output operations; NIL otherwise.


@end defun

@defvar *QUERY-IO* 
Package:LISP
The query I/O stream.


@end defvar

@defvar *READ-BASE* 
Package:LISP
The radix that the GCL reader reads numbers in.


@end defvar

@deffn {Macro} WITH-OPEN-STREAM 
Package:LISP

Syntax:
@example
(with-open-stream (var stream) @{decl@}* @{form@}*)
@end example

Evaluates FORMs as a PROGN with VAR bound to the value of STREAM.  The stream
is automatically closed on exit.


@end deffn

@deffn {Macro} WITH-INPUT-FROM-STRING 
Package:LISP

Syntax:
@example
(with-input-from-string (var string @{keyword value@}*) @{decl@}*
@{form@}*)
@end example

Binds VAR to an input stream that returns characters from STRING and evaluates
the FORMs.  The stream is automatically closed on exit.  Allowed keywords are
:INDEX, :START, and :END.


@end deffn

@defun CLEAR-INPUT  (&optional (stream *standard-input*))
Package:LISP
 Clears the input
stream STREAM.


@end defun

@defvar *TERMINAL-IO* 
Package:LISP
The terminal I/O stream.


@end defvar

@defun LISTEN (&optional (stream *standard-input*))
Package:LISP

Returns T if a character is available on STREAM; NIL otherwise.  This function
does not correctly work in some versions of GCL because of the lack of such
mechanism in the underlying operating system.


@end defun

@defun MAKE-PATHNAME (&key (defaults (parse-namestring "" (pathname-host *default-pathname-defaults*))) (host (pathname-host defaults)) (device (pathname-device defaults)) (directory (pathname-directory defaults)) (name (pathname-name defaults)) (type (pathname-type defaults)) (version (pathname-version defaults)))
Package:LISP

Create a pathname from HOST, DEVICE, DIRECTORY, NAME, TYPE and VERSION.


@end defun

@defun PATHNAME-TYPE (pathname)
Package:LISP

Returns the type slot of PATHNAME.


@end defun

@defvar *PRINT-GENSYM* 
Package:LISP
Whether the GCL printer should prefix symbols with no home package
with "#:".


@end defvar

@defun READ-LINE (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
Package:LISP

Returns a line of text read from STREAM as a string, discarding the newline
character.

Note that when using line at a time input under unix,
input forms will always be followed by a #\newline.   Thus if you
do

>(read-line)
""
nil

the empty string will be returned.  After lisp reads the (read-line)
it then invokes (read-line).  This happens before it does anything
else and so happens before the newline character immediately following
(read-line) has been read.  Thus read-line immediately encounters a
#\newline and so returns the empty string.  If there had been other
characters before the #\newline it would have been different:

>(read-line) how are you
" how are you"
nil

If you want to throw away "" input, you can do that with
the following:

(sloop::sloop while (equal (setq input (read-line)) ""))

You may also want to use character at a time input, but that
makes input editing harder.
nicolas% stty cbreak
nicolas% gcl
GCL (GNU Common Lisp)  Version(1.1.2) Mon Jan  9 12:58:22 MET 1995
Licensed under GNU Public Library License
Contains Enhancements by W. Schelter

>(let ((ifilename nil))
    (format t "~%Input file name: ")
    (setq ifilename (read-line)))
Input file name: /tmp/myfile
"/tmp/myfile"

>(bye)Bye.




@end defun

@defun WRITE-TO-STRING (object &key (escape *print-escape*) (radix *print-radix*) (base *print-base*) (circle *print-circle*) (pretty *print-pretty*) (level *print-level*) (length *print-length*) (case *print-case*) (array *print-array*) (gensym *print-gensym*))
Package:LISP

Returns as a string the printed representation of OBJECT in the specified
mode.  See the variable docs of *PRINT-...* for the mode.


@end defun

@defun PATHNAMEP (x)
Package:LISP

Returns T if X is a pathname object; NIL otherwise.


@end defun

@defun READTABLEP (x)
Package:LISP

Returns T if X is a readtable object; NIL otherwise.


@end defun

@defun READ (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursivep nil))
Package:LISP

Reads in the next object from STREAM.


@end defun

@defun NAMESTRING (pathname)
Package:LISP

Returns the full form of PATHNAME as a string.


@end defun

@defun UNREAD-CHAR (character &optional (stream *standard-input*))
Package:LISP

Puts CHARACTER back on the front of the input stream STREAM.


@end defun

@defun CLOSE (stream &key (abort nil))
Package:LISP

Closes STREAM.  A non-NIL value of :ABORT indicates an abnormal termination.


@end defun

@defvar *PRINT-LENGTH* 
Package:LISP
How many elements the GCL printer should print at each level of nested data
object.  Unlimited if NIL.


@end defvar

@defun SET-SYNTAX-FROM-CHAR (to-char from-char &optional (to-readtable *readtable*) (from-readtable nil))
Package:LISP

Makes the syntax of TO-CHAR in TO-READTABLE be the same as the syntax of
FROM-CHAR in FROM-READTABLE.


@end defun

@defun INPUT-STREAM-P (stream)
Package:LISP

Returns non-NIL if STREAM can handle input operations; NIL otherwise.


@end defun

@defun PATHNAME (x)
Package:LISP

Turns X into a pathname.  X may be a string, symbol, stream, or pathname.


@end defun

@defun FILE-NAMESTRING (pathname)
Package:LISP

Returns the written representation of PATHNAME as a string.


@end defun

@defun MAKE-DISPATCH-MACRO-CHARACTER (char &optional (non-terminating-p nil) (readtable *readtable*))
Package:LISP

Causes the character CHAR to be a dispatching macro character in READTABLE.


@end defun

@defvar *STANDARD-OUTPUT* 
Package:LISP
The default output stream used by the GCL printer.


@end defvar

@defun MAKE-TWO-WAY-STREAM (input-stream output-stream)
Package:LISP

Returns a bidirectional stream which gets its input from INPUT-STREAM and
sends its output to OUTPUT-STREAM.


@end defun

@defvar *PRINT-ESCAPE* 
Package:LISP
Whether the GCL printer should put escape characters whenever appropriate.


@end defvar

@defun COPY-READTABLE (&optional (from-readtable *readtable*) (to-readtable nil))
Package:LISP

Returns a copy of the readtable FROM-READTABLE.  If TO-READTABLE is non-NIL,
then copies into TO-READTABLE.  Otherwise, creates a new readtable.


@end defun

@defun DIRECTORY-NAMESTRING (pathname)
Package:LISP

Returns the directory part of PATHNAME as a string.


@end defun

@defun TRUENAME (pathname)
Package:LISP

Returns the pathname for the actual file described by PATHNAME.


@end defun

@defvar *READ-SUPPRESS* 
Package:LISP
When the value of this variable is NIL, the GCL reader operates normally.
When it is non-NIL, then the reader parses input characters but much of what
is read is not interpreted.


@end defvar

@defun GET-DISPATCH-MACRO-CHARACTER (disp-char sub-char &optional (readtable *readtable*))
Package:LISP

Returns the macro-character function for SUB-CHAR under DISP-CHAR.


@end defun

@defun PATHNAME-DEVICE (pathname)
Package:LISP

Returns the device slot of PATHNAME.


@end defun

@defun READ-CHAR-NO-HANG (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))
Package:LISP

Returns the next character from STREAM if one is available; NIL otherwise.


@end defun

@defun FRESH-LINE (&optional (stream *standard-output*))
Package:LISP

Outputs a newline if it is not positioned at the beginning of a line.  Returns
T if it output a newline; NIL otherwise.


@end defun

@defun WRITE-CHAR (char &optional (stream *standard-output*))
Package:LISP

Outputs CHAR and returns it.


@end defun

@defun PARSE-NAMESTRING (thing &optional host (defaults *default-pathname-defaults*) &key (start 0) (end (length thing)) (junk-allowed nil))
Package:LISP

Parses a string representation of a pathname into a pathname.  HOST
is ignored.


@end defun

@defun PATHNAME-DIRECTORY (pathname)
Package:LISP

Returns the directory slot of PATHNAME.


@end defun

@defun GET-MACRO-CHARACTER (char &optional (readtable *readtable*))
Package:LISP

Returns the function associated with CHAR and, as a second value, returns
the non-terminating-p flag.


@end defun

@defun FORMAT (destination control-string &rest arguments)
Package:LISP

Provides various facilities for formatting output.
DESTINATION controls where the result will go.  If DESTINATION is T, then
the output is sent to the standard output stream.  If it is NIL, then the
output is returned in a string as the value of the call.  Otherwise,
DESTINATION must be a stream to which the output will be sent.

CONTROL-STRING is a string to be output, possibly with embedded
formatting directives, which are flagged with the escape character
"~".  Directives generally expand into additional text to be output,
usually consuming one or more of ARGUMENTs in the process.



A few useful directives are:
@example

~A, ~nA, ~n@@A	Prints one argument as if by PRINC
~S, ~nS, ~n@@S	Prints one argument as if by PRIN1
~D, ~B, ~O, ~X	Prints one integer in decimal, binary, octal, and hexa
~%		Does TERPRI
~&		Does FRESH-LINE
@end example

where n is the minimal width of the field in which the object is printed.
~nA and ~nS put padding spaces on the right; ~n@@A and ~n@@S put on the left.

@example
~R  is for printing numbers in various formats.

  ~nR   prints arg in radix n.
  ~R    prints arg as a cardinal english number: two
  ~:R   prints arg as an ordinal english number: third
  ~@@R   prints arg as an a Roman Numeral: VII
  ~:@@R   prints arg as an old Roman Numeral: IIII

~C prints a character.
  ~:C represents non printing characters by their pretty names,eg Space
  ~@@C uses the #\ syntax to allow the reader to read it.

~F prints a floating point number arg.
  The full form is ~w,d,k,overflowchar,padcharF
  w represents the total width of the printed representation (variable if
    not present)
  d the number of fractional digits to display
    (format nil "~,2f" 10010.0314) --> "10010.03"
  k arg is multiplied by 10^k before printing it as a decimal number.
  overflowchar width w characters copies of the overflow character will
    be printed.   eg(format t "X>~5,2,,'?F<X" 100.034) --> X>?????<X
  padchar is the character to pad with
    (format t "X>~10,2,1,'?,'bF<X" 100.03417) -->X>bbb1000.34<X
  @@ makes + sign print if the arg is positive

~@@[print-if-true~]
@end example
   if arg is not nil, then it is retained as an arg for further printing,
   otherwise it is used up

@example
   (format nil "~@@[x = ~d~]~a" nil 'bil) --> "BIL"
   (format nil "~@@[x = ~d ~]~a" 8) --> "x = 8 BIL"
@end example


@end defun

@defun PATHNAME-NAME (pathname)
Package:LISP

Returns the name slot of PATHNAME.


@end defun

@defun MAKE-STRING-OUTPUT-STREAM ()
Package:LISP

Returns an output stream which will accumulate all output given it for
the benefit of the function GET-OUTPUT-STREAM-STRING.


@end defun

@defun MAKE-SYNONYM-STREAM (symbol)
Package:LISP

Returns a stream which performs its operations on the stream which is the
value of the dynamic variable named by SYMBOL.


@end defun

@defvar *LOAD-VERBOSE* 
Package:LISP
The default for the VERBOSE argument to LOAD.


@end defvar

@defvar *PRINT-CIRCLE* 
Package:LISP
Whether the GCL printer should take care of circular lists.


@end defvar

@defvar *PRINT-PRETTY* 
Package:LISP
Whether the GCL printer should pretty-print.  See the function doc of PPRINT
for more information about pretty-printing.


@end defvar

@defun FILE-WRITE-DATE (file)
Package:LISP

Returns the time at which the specified file is written, as an integer in
universal time format.  FILE may be a string or a stream.


@end defun

@defun PRIN1-TO-STRING (object)
Package:LISP

Returns as a string the printed representation of OBJECT in the mostly
readable representation.
Equivalent to (WRITE-TO-STRING OBJECT :ESCAPE T).


@end defun

@defun MERGE-PATHNAMES (pathname &optional (defaults *default-pathname-defaults*) default-version)
Package:LISP

Fills in unspecified slots of PATHNAME from DEFAULTS.  DEFAULT-VERSION
is ignored in GCL.


@end defun

@defun READ-BYTE (stream &optional (eof-error-p t) (eof-value nil))
Package:LISP

Reads the next byte from STREAM.


@end defun

@defun PRINC-TO-STRING (object)
Package:LISP

Returns as a string the printed representation of OBJECT without escape
characters.  Equivalent to
	(WRITE-TO-STRING OBJECT :ESCAPE NIL).


@end defun

@defvar *STANDARD-INPUT* 
Package:LISP
The default input stream used by the GCL reader.


@end defvar

@defun PROBE-FILE (file)
Package:LISP

Returns the truename of file if the file exists.
Returns NIL otherwise.


@end defun

@defun PATHNAME-VERSION (pathname)
Package:LISP

Returns the version slot of PATHNAME.


@end defun

@defun WRITE-LINE (string &optional (stream *standard-output*) &key (start 0) (end (length string)))
Package:LISP

Outputs STRING and then outputs a newline character.  Returns STRING.


@end defun

@defun WRITE (object &key (stream *standard-output*) (escape *print-escape*) (radix *print-radix*) (base *print-base*) (circle *print-circle*) (pretty *print-pretty*) (level *print-level*) (length *print-length*) (case *print-case*) (array *print-array*) (gensym *print-gensym*))
Package:LISP

Prints OBJECT in the specified mode.  See the variable docs of *PRINT-...*
for the mode.


@end defun

@defun GET-OUTPUT-STREAM-STRING (stream)
Package:LISP

Returns a string of all the characters sent to STREAM made by
MAKE-STRING-OUTPUT-STREAM since the last call to this function.


@end defun

@defun READ-DELIMITED-LIST (char &optional (stream *standard-input*) (recursive-p nil))
Package:LISP

Reads objects from STREAM until the next character after an object's
representation is CHAR.  Returns a list of the objects read.


@end defun

@defun READLINE-ON ()
Package:SI

Begins readline command editing mode when possible.  In addition to
the basic readline editing features, command word completion is
implemented according to the following scheme:

[[pkg]:[:]]txt

pkg -- an optional package specifier.  Defaults to the current
package.  The symbols in this package and those in the packages in
this package's use list will be searched.

:[:] -- an optional internal/external specifier.  Defaults to
external.  The keyword package is denoted by a single colon at the
beginning of the token.  Only symbols of this type will be searched
for completion.

txt -- a string.  Symbol names beginning with this string are
completed.  The comparison is case insensitive.


@end defun 

@defun READLINE-OFF ()
Package:SI

Disables readline command editing mode.

@end defun 

@defvar *READLINE-PREFIX* 
Package:SI

A string implicitly prepended to input text for use in readline
command completion.  If this string contains one or more colons, it is
used to specify the default package and internal/external setting for
searched symbols in the case that the supplied text itself contains no
explicit package specification.  If this string contains characters
after the colon(s), or contains no colons at all, it is treated as a
symbol name prefix.  In this case, the prefix is matched first, then
the supplied text, and the completion returned is relative to the
supplied text itself, i.e. contains no prefix.  For example, the
setting ``maxima::$'' will complete input text ``int'' according to
the internal symbols in the maxima package of the form
``maxima::$int...'', and return suggestions to the user of the form
``int...''.

@end defvar