FILE I/O FUNCTIONS

File streams are printed using the #< format that cannot be read by the reader. Console, standard input, standard output, and closed streams are explicitly indicated. Other file streams will typically indicate the name of the attached file.

When the transcript is active (either -t on the command line or the DRIBBLE function), all characters that would be sent to the display via *TERMINAL-IO* are also placed in the transcript file.

*TERMINAL-IO* should not be changed. Any other system streams that are changed by an application should be restored to their original values.

READ A CHARACTER FROM A STREAM

NOTE: New eof arguments are incompatible with older XLISP versions.

• <stream> the input stream (default, or NIL, is *standard-input*, T is *terminal-io*)
• <eofp> When T, signal an error on end of file, when NIL return <eof> (default is T)
• <eof> the value to return on end of file (default is NIL)
• returns the character or <eof> at end of file

• <flag> flag for skipping white space (default is NIL)
• <stream> the input stream (default, or NIL, is *standard-input*, T is *terminal-io*)
• returns the character or NIL at end of file

• <ch> the character to write
• <stream> the output stream (default, or NIL, is *standard-output*, T is *terminal-io*)
• returns the character

NOTE: New eof arguments are incompatible with older XLISP versions.

• <stream> the input stream (default, or NIL, is *standard-input*, T is *terminal-io*)
• <eofp> When T, signal an error on end of file, when NIL return <eof> (default is T)
• <eof> the value to return on end of file (default is NIL)
• returns the string excluding the #\newline, or <eof> at end of file

The function OPEN has been significantly enhanced over original XLISP. The original function only had the :direction keyword argument, which could only have the values :input or :output. When used with the :output keyword, it was equivalent to (open <fname> :direction :output :if-exists :supersede). A maximum of ten files can be open at any one time, including any files open via the LOAD, DRIBBLE, SAVE and RESTORE commands. The open command may force a garbage collection to reclaim file slots used by unbound file streams.

• <fname> the file name string, symbol, or file stream created via OPEN. In the last case, the name is used to open a second stream on the same file -- this can cause problems if one or more streams is used for writing.
• :direction Read and write permission for stream (default is :input).
  • :input Open file for read operations only.
  • :probe Open file for reading, then close it (use to test for file existance)
  • :output Open file for write operations only.
  • :io Like :output, but reading also allowed.
• :element-type FIXNUM or CHARACTER (default is CHARACTER), as returned by type-of function (on page 88). Files opened with type FIXNUM are binary files instead of ascii, which means no crlf to/from lf conversion takes place, and control-Z will not terminate an input file. It is the intent of Common Lisp that binary files only be accessed with read-byte and write-byte while ascii files be accessed with any function but read-byte and write-byte. XLISP does not enforce that distinction.
• :if-exists action to take if file exists. Argument ignored for :input (file is positioned at start) or :probe (file is closed)
  • :error give error message
  • :rename rename file to generated backup name, then open a new file of the original name. This is the default action
  • :new-version same as :rename
  • :overwrite file is positioned to start, original data intact
  • :append file is positioned to end
  • :supersede delete original file and open new file of the same name
  • :rename-and-delete same as :supersede
  • NIL close file and return NIL
• :if-does-not-exist
  action to take if file does not exist.
  • :error give error message (default for :input, or :overwrite or :append)
  • :create create a new file (default for :output or :io when not :overwrite or :append)
  • NIL return NIL (default for :probe)
• returns a file stream, or sometimes NIL

The stream becomes a "closed stream." Note that unbound file streams are closed automatically during a garbage collection.

• <stream> the stream, which may be a string stream
• returns t if stream closed, NIL if terminal (cannot be closed) or already closed.

• <fname> file name string, symbol or a stream opened with OPEN
• returns t if file does not exist or is deleted. If <fname> is a stream, the stream is closed before the file is deleted. An error occurs if the file cannot be deleted.

• <fname> file name string, symbol, or a stream opened with OPEN
• returns string representing the true file name (absolute path to file).

Defined in common.lsp as a macro. File will always be closed upon completion

• <var> symbol name to bind stream to while evaluating expresssions (quoted)
• <fname> file name string or symbol
• <karg> keyword arguments for the implicit open command
• <expr> expressions to evaluate while file is open (implicit progn)
• returns value of last <expr>.

NOTE: New eof arguments are incompatible with older XLISP versions.

• <stream> the input stream (default, or NIL, is *standard-input*, T is *terminal-io*)
• <eofp> When T, signal an error on end of file, when NIL return <eof> (default is T)
• <eof> the value to return on end of file (default is NIL)
• returns the byte (integer) or <eof> at end of file

• <byte> the byte to write (integer)
• <stream> the output stream (default, or NIL, is *standard-output*, T is *terminal-io*)
• returns the byte (integer)

For an ascii file, the length reported may be larger than the number of characters read or written because of CR conversion.

• <stream> the file stream (should be disk file)
• returns length of file, or NIL if cannot be determined.

For an ascii file, the file position may not be the same as the number of characters read or written because of CR conversion. It will be correct when using file-position to position a file at a location earlier reported by file-position.

• <stream> the file stream (should be a disk file)
• <expr> desired file position, if setting position. Can also be :start for start of file or :end for end of file.
• returns if setting position, and successful, then T; if getting position and successful then the position; otherwise NIL