Contents|Symbol Index|Up: Chapter 21 Dictionary|Prev: stream-external-format|Next: close

Macro `with-open-file`

Syntax:

with-open-file (stream filespec {options}^*) {declaration}^* {form}^* → results

Arguments and Values:

stream—a variable.

filespec—a pathname designator.

!!! I doubt this can be right. -kmp 22-Apr-91options—forms; evaluated.

declaration—a declare expression; not evaluated.

forms—an implicit progn.

results—the values returned by the forms.

Description:

with-open-file uses open to create a file stream to file named by filespec. 23.2.0 41Filespec is the name of the file to be opened. Options are used as keyword arguments to open. Moon thought this was "drivel". -kmp 11-Feb-92 Then \macref{with-open-file} performs a specified series of actions on the open file. This is implied by "pathname designator". -kmp 16-Feb-92 \issue{PATHNAME-STREAM} If \param{filespec} is a \term{file stream}, that \term{file stream} can only have been originally opened by \funref{open} or \macref{with-open-file}, or is a \term{synonym stream} whose \term{symbol} is bound to a \term{file stream} originally opened by \funref{open} or \macref{with-open-file}. If \param{filespec} is a \term{pathname} (as returned by \funref{pathname} it represents the name used to open the file. This may be, but is not required to be, the actual name of the file. \endissue{PATHNAME-STREAM} \issue{PATHNAME-LOGICAL:ADD} If \param{filespec} is a \term{logical pathname}, it is translated into a physical pathname as if by calling \funref{translate-logical-pathname}. \endissue{PATHNAME-LOGICAL:ADD}

The stream object to which the stream variable is bound has dynamic extent; its extent ends when the form is exited.

23.2.0 39with-open-file evaluates the forms as an implicit progn with stream bound to the value returned by open.

23.2.0 40When control leaves the body, either normally or abnormally (such as by use of throw), the file is automatically closed. If a new output file is being written, and control leaves abnormally, the file is aborted and the file system is left, so far as possible, as if the file had never been opened.

It is possible by the use of :if-exists nil or :if-does-not-exist nil for stream to be bound to nil. Users of :if-does-not-exist nil should check for a valid stream.

23.2.0 42 This looks suspect to me. -kmp 22-Apr-91 Moon: Yes, this is drivel. \macref{with-open-file} opens, modifies, and tries to close the \param{file stream}.

The consequences are undefined if an attempt is made to assign the stream variable. The compiler may choose to issue a warning if such an attempt is detected.

Examples:

 (setq p (merge-pathnames "test"))
→ #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY directory-name
    :NAME "test" :TYPE NIL :VERSION :NEWEST>
 (with-open-file (s p :direction :output :if-exists :supersede)
    (format s "Here are a couple~%of test data lines~%")) → NIL
 (with-open-file (s p)
    (do ((l (read-line s) (read-line s nil 'eof)))
        ((eq l 'eof) "Reached end of file.")
     (format t "~&*** ~A~%" l)))
⊳ *** Here are a couple
⊳ *** of test data lines
→ "Reached end of file."

\code (with-open-file (ifile name :direction :input) (with-open-file (ofile (merge-pathname-defaults ifile nil "out") :direction :output :if-exists :supersede) (transduce-file ifile ofile))) \endcode

!!! This example is -way- too weird to be included without more commentary.

;; Normally one would not do this intentionally because it is
;; not perspicuous, but beware when using :IF-DOES-NOT-EXIST NIL
;; that this doesn't happen to you accidentally...
 (with-open-file (foo "no-such-file" :if-does-not-exist nil)
   (read foo))
⊳ hello?
→ HELLO? ;This value was read from the terminal, not a file!

;; Here's another bug to avoid...
 (with-open-file (foo "no-such-file" :direction :output :if-does-not-exist nil)
   (format foo "Hello"))
→ "Hello" ;FORMAT got an argument of NIL!

Side Effects:

Creates a stream to the file named by filename (upon entry), and closes the stream (upon exit). In some implementations, the file might be locked in some way while it is open. If the stream is an output stream, a file might be created.

Affected By:

The host computer's file system.

Exceptional Situations:

This restriction (and more) is already manifest in OPEN, so just omit it here. \issue{PATHNAME-WILD:NEW-FUNCTIONS} !!! Moon: I would have assumed type-error rather than file-error for this one. I have no strong opinion, though. An error \oftype{file-error} is signaled if \f{(wild-pathname-p \param{filespec})} returns true. \endissue{PATHNAME-WILD:NEW-FUNCTIONS}See the function open.

Notes:

None.