## 5 Streams and Reading

Function: 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.

Variable: *READTABLE*

  Package:LISP The current readtable.

Function: LOAD (filename &key (verbose *load-verbose*) (print nil) (if-does-not-exist :error))

  Package:LISP

  Loads the file named by FILENAME into GCL.

Function: 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.

      (setq pipe (open "| wc < /tmp/jim"))
      (format t "File has ~%d lines" (read pipe))
      (close pipe)

Variable: *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.

Function: 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.

Function: 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.

Variable: *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.

Function: 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.

Function: STREAMP (x)

  Package:LISP

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

Function: 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.

Macro: WITH-OUTPUT-TO-STRING

  Package:LISP

  Syntax:

      (with-output-to-string (var [string]) {decl}* {form}*)

  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.

Function: FILE-LENGTH (file-stream)

  Package:LISP

  Returns the length of the specified file stream.

Variable: *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.

Function: 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)).

Function: 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.

Function: FORCE-OUTPUT (&optional (stream *standard-output*))

  Package:LISP

  Attempts to force any buffered output to be sent.

Variable: *PRINT-ARRAY*

  Package:LISP Whether the GCL printer should print array elements.

Function: STREAM-ELEMENT-TYPE (stream)

  Package:LISP

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

Function: WRITE-BYTE (integer stream)

  Package:LISP

  Outputs INTEGER to the binary stream STREAM. Returns INTEGER.

Function: 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.

Function: 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).

Function: PRINC (object &optional (stream *standard-output*))

  Package:LISP

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

Function: CLEAR-OUTPUT (&optional (stream *standard-output*))

  Package:LISP

  Clears the output stream STREAM.

Function: TERPRI (&optional (stream *standard-output*))

  Package:LISP

  Outputs a newline character.

Function: 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.

Macro: WITH-OPEN-FILE

  Package:LISP

  Syntax:

      (with-open-file (stream filename {options}*) {decl}* {form}*)

  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.

Special Form: DO

  Package:LISP

  Syntax:

      (do ({(var [init [step]])}*) (endtest {result}*)
                {decl}* {tag | statement}*)

  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.

Function: 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.

Function: WRITE-STRING (string &optional (stream *standard-output*) &key (start 0) (end (length string)))

  Package:LISP

  Outputs STRING and returns it.

Variable: *PRINT-LEVEL*

  Package:LISP How many levels deep the GCL printer should print. Unlimited if NIL.

Variable: *PRINT-RADIX*

  Package:LISP Whether the GCL printer should print the radix indicator when printing integers and rationals.

Function: 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.

Function: MAKE-BROADCAST-STREAM (&rest streams)

  Package:LISP

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

Function: READ-CHAR (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursive-p nil))

  Package:LISP

  Reads a character from STREAM.

Function: 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.

Function: OUTPUT-STREAM-P (stream)

  Package:LISP

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

Variable: *QUERY-IO*

  Package:LISP The query I/O stream.

Variable: *READ-BASE*

  Package:LISP The radix that the GCL reader reads numbers in.

Macro: WITH-OPEN-STREAM

  Package:LISP

  Syntax:

      (with-open-stream (var stream) {decl}* {form}*)

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

Macro: WITH-INPUT-FROM-STRING

  Package:LISP

  Syntax:

      (with-input-from-string (var string {keyword value}*) {decl}*
      {form}*)

  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.

Function: CLEAR-INPUT (&optional (stream *standard-input*))

  Package:LISP Clears the input stream STREAM.

Variable: *TERMINAL-IO*

  Package:LISP The terminal I/O stream.

Function: 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.

Function: 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.

Function: PATHNAME-TYPE (pathname)

  Package:LISP

  Returns the type slot of PATHNAME.

Variable: *PRINT-GENSYM*

  Package:LISP Whether the GCL printer should prefix symbols with no home package with "#:".

Function: 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.

Function: 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.

Function: PATHNAMEP (x)

  Package:LISP

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

Function: READTABLEP (x)

  Package:LISP

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

Function: READ (&optional (stream *standard-input*) (eof-error-p t) (eof-value nil) (recursivep nil))

  Package:LISP

  Reads in the next object from STREAM.

Function: NAMESTRING (pathname)

  Package:LISP

  Returns the full form of PATHNAME as a string.

Function: UNREAD-CHAR (character &optional (stream *standard-input*))

  Package:LISP

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

Function: CLOSE (stream &key (abort nil))

  Package:LISP

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

Variable: *PRINT-LENGTH*

  Package:LISP How many elements the GCL printer should print at each level of nested data object. Unlimited if NIL.

Function: 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.

Function: INPUT-STREAM-P (stream)

  Package:LISP

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

Function: PATHNAME (x)

  Package:LISP

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

Function: FILE-NAMESTRING (pathname)

  Package:LISP

  Returns the written representation of PATHNAME as a string.

Function: 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.

Variable: *STANDARD-OUTPUT*

  Package:LISP The default output stream used by the GCL printer.

Function: 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.

Variable: *PRINT-ESCAPE*

  Package:LISP Whether the GCL printer should put escape characters whenever appropriate.

Function: 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.

Function: DIRECTORY-NAMESTRING (pathname)

  Package:LISP

  Returns the directory part of PATHNAME as a string.

Function: TRUENAME (pathname)

  Package:LISP

  Returns the pathname for the actual file described by PATHNAME.

Variable: *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.

Function: GET-DISPATCH-MACRO-CHARACTER (disp-char sub-char &optional (readtable *readtable*))

  Package:LISP

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

Function: PATHNAME-DEVICE (pathname)

  Package:LISP

  Returns the device slot of PATHNAME.

Function: 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.

Function: 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.

Function: WRITE-CHAR (char &optional (stream *standard-output*))

  Package:LISP

  Outputs CHAR and returns it.

Function: 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.

Function: PATHNAME-DIRECTORY (pathname)

  Package:LISP

  Returns the directory slot of PATHNAME.

Function: 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.

Function: 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:

      ~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

  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.

      ~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~]

  if arg is not nil, then it is retained as an arg for further printing, otherwise it is used up

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

Function: PATHNAME-NAME (pathname)

  Package:LISP

  Returns the name slot of PATHNAME.

Function: 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.

Function: 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.

Variable: *LOAD-VERBOSE*

  Package:LISP The default for the VERBOSE argument to LOAD.

Variable: *PRINT-CIRCLE*

  Package:LISP Whether the GCL printer should take care of circular lists.

Variable: *PRINT-PRETTY*

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

Function: 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.

Function: 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).

Function: 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.

Function: READ-BYTE (stream &optional (eof-error-p t) (eof-value nil))

  Package:LISP

  Reads the next byte from STREAM.

Function: 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).

Variable: *STANDARD-INPUT*

  Package:LISP The default input stream used by the GCL reader.

Function: PROBE-FILE (file)

  Package:LISP

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

Function: PATHNAME-VERSION (pathname)

  Package:LISP

  Returns the version slot of PATHNAME.

Function: 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.

Function: 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.

Function: 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.

Function: 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.

Function: 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.

Function: READLINE-OFF ()

  Package:SI

  Disables readline command editing mode.

Variable: *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...”.