98 lines
8.7 KiB
HTML
98 lines
8.7 KiB
HTML
<!-- Common Lisp HyperSpec (TM), version 7.0 generated by Kent M. Pitman on Mon, 11-Apr-2005 2:31am EDT -->
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>CLHS: macro WITH-OPEN-FILE</TITLE>
|
|
<LINK HREF="../Data/clhs.css" REL="stylesheet" TYPE="text/css" />
|
|
<META HTTP-EQUIV="Author" CONTENT="Kent M. Pitman">
|
|
<META HTTP-EQUIV="Organization" CONTENT="LispWorks Ltd.">
|
|
<LINK REL=TOP HREF="../Front/index.htm">
|
|
<LINK REL=COPYRIGHT HREF="../Front/Help.htm#Legal">
|
|
<LINK REL=DISCLAIMER HREF="../Front/Help.htm#Disclaimer">
|
|
<LINK REL=PREV HREF="f_stm_ex.htm">
|
|
<LINK REL=UP HREF="c_stream.htm">
|
|
<LINK REL=NEXT HREF="f_close.htm">
|
|
</HEAD>
|
|
<BODY>
|
|
<H1><A REV=MADE HREF="http://www.lispworks.com/"><IMG WIDTH=80 HEIGHT=65 ALT="[LISPWORKS]" SRC="../Graphics/LWSmall.gif" ALIGN=Bottom></A><A REL=TOP HREF="../Front/index.htm"><IMG WIDTH=237 HEIGHT=65 ALT="[Common Lisp HyperSpec (TM)]" SRC="../Graphics/CLHS_Sm.gif" ALIGN=Bottom></A> <A REL=PREV HREF="f_stm_ex.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Previous]" SRC="../Graphics/Prev.gif" ALIGN=Bottom></A><A REL=UP HREF="c_stream.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Up]" SRC="../Graphics/Up.gif" ALIGN=Bottom></A><A REL=NEXT HREF="f_close.htm"><IMG WIDTH=40 HEIGHT=40 ALT="[Next]" SRC="../Graphics/Next.gif" ALIGN=Bottom></A></H1>
|
|
|
|
<HR>
|
|
|
|
<A NAME="with-open-file"><I>macro</I> <B>WITH-OPEN-FILE</B></A> <P>
|
|
<P>
|
|
<P><B>Syntax:</B><P>
|
|
<P>
|
|
|
|
<B>with-open-file</B> <I>(stream filespec <I>options</I><B>*</B>) <I>declaration</I><B>*</B> <I>form</I><B>*</B></I><P> => <I>results</I><P>
|
|
<P>
|
|
<P><B>Arguments and Values:</B><P>
|
|
<P>
|
|
<I>stream</I> -- a variable. <P>
|
|
<I>filespec</I>---a <A REL=DEFINITION HREF="26_glo_p.htm#pathname_designator"><I>pathname designator</I></A>. <P>
|
|
<I>options</I> -- <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>forms</I></A>; evaluated. <P>
|
|
<I>declaration</I>---a <A REL=DEFINITION HREF="s_declar.htm#declare"><B>declare</B></A> <A REL=DEFINITION HREF="26_glo_e.htm#expression"><I>expression</I></A>; not evaluated. <P>
|
|
<I>forms</I>---an <A REL=DEFINITION HREF="26_glo_i.htm#implicit_progn"><I>implicit progn</I></A>. <P>
|
|
<I>results</I>---the <A REL=DEFINITION HREF="26_glo_v.htm#value"><I>values</I></A> returned by the <I>forms</I>. <P>
|
|
<P><B>Description:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="#with-open-file"><B>with-open-file</B></A> uses <A REL=DEFINITION HREF="f_open.htm#open"><B>open</B></A> to create a <A REL=DEFINITION HREF="26_glo_f.htm#file_stream"><I>file stream</I></A> to <A REL=DEFINITION HREF="26_glo_f.htm#file"><I>file</I></A> named by <I>filespec</I>. <I>Filespec</I> is the name of the file to be opened. <I>Options</I> are used as keyword arguments to <A REL=DEFINITION HREF="f_open.htm#open"><B>open</B></A>. <P>
|
|
The <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A> <A REL=DEFINITION HREF="26_glo_o.htm#object"><I>object</I></A> to which the <I>stream</I> <A REL=DEFINITION HREF="26_glo_v.htm#variable"><I>variable</I></A> is <A REL=DEFINITION HREF="26_glo_b.htm#bound"><I>bound</I></A> has <A REL=DEFINITION HREF="26_glo_d.htm#dynamic_extent"><I>dynamic extent</I></A>; its <A REL=DEFINITION HREF="26_glo_e.htm#extent"><I>extent</I></A> ends when the <A REL=DEFINITION HREF="26_glo_f.htm#form"><I>form</I></A> is exited. <P>
|
|
<A REL=DEFINITION HREF="#with-open-file"><B>with-open-file</B></A> evaluates the <I>forms</I> as an <A REL=DEFINITION HREF="26_glo_i.htm#implicit_progn"><I>implicit progn</I></A> with <I>stream</I> bound to the value returned by <A REL=DEFINITION HREF="f_open.htm#open"><B>open</B></A>. <P>
|
|
When control leaves the body, either normally or abnormally (such as by use of <A REL=DEFINITION HREF="s_throw.htm#throw"><B>throw</B></A>), 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. <P>
|
|
It is possible by the use of <TT>:if-exists nil</TT> or <TT>:if-does-not-exist nil</TT> for <I>stream</I> to be bound to <A REL=DEFINITION HREF="a_nil.htm#nil"><B>nil</B></A>. Users of <TT>:if-does-not-exist nil</TT> should check for a valid <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A>. <P>
|
|
The consequences are undefined if an attempt is made to <A REL=DEFINITION HREF="26_glo_a.htm#assign"><I>assign</I></A> the <I>stream</I> <A REL=DEFINITION HREF="26_glo_v.htm#variable"><I>variable</I></A>. The compiler may choose to issue a warning if such an attempt is detected. <P>
|
|
<P><B>Examples:</B><P>
|
|
<P>
|
|
<PRE>
|
|
(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."
|
|
</PRE>
|
|
</TT> <P>
|
|
|
|
<PRE>
|
|
;; 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!
|
|
</PRE>
|
|
</TT> <P>
|
|
<P><B>Side Effects:</B><P>
|
|
<P>
|
|
Creates a <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A> to the <A REL=DEFINITION HREF="26_glo_f.htm#file"><I>file</I></A> named by <I>filename</I> (upon entry), and closes the <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A> (upon exit). In some <A REL=DEFINITION HREF="26_glo_i.htm#implementation"><I>implementations</I></A>, the <A REL=DEFINITION HREF="26_glo_f.htm#file"><I>file</I></A> might be locked in some way while it is open. If the <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A> is an <A REL=DEFINITION HREF="26_glo_o.htm#output"><I>output</I></A> <A REL=DEFINITION HREF="26_glo_s.htm#stream"><I>stream</I></A>, a <A REL=DEFINITION HREF="26_glo_f.htm#file"><I>file</I></A> might be created. <P>
|
|
<P><B>Affected By:</B><P>
|
|
<P>
|
|
The host computer's file system. <P>
|
|
<P><B>Exceptional Situations:</B><P>
|
|
<P>
|
|
See the <A REL=DEFINITION HREF="26_glo_f.htm#function"><I>function</I></A> <A REL=DEFINITION HREF="f_open.htm#open"><B>open</B></A>. <P>
|
|
<P><B>See Also:</B><P>
|
|
<P>
|
|
<A REL=DEFINITION HREF="f_open.htm#open"><B>open</B></A>, <A REL=DEFINITION HREF="f_close.htm#close"><B>close</B></A>, <A REL=DEFINITION HREF="t_pn.htm#pathname"><B>pathname</B></A>, <A REL=DEFINITION HREF="t_logica.htm#logical-pathname"><B>logical-pathname</B></A>, <A REL=CHILD HREF="19_ab.htm">Section 19.1.2 (Pathnames as Filenames)</A> <P>
|
|
<P><B>Notes:</B> None.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P><HR>The following <A REL=META HREF="../Front/X3J13Iss.htm">X3J13 cleanup issues</A>, <I>not part of the specification</I>, apply to this section:<P><UL><LI> <A REL=CHILD HREF="../Issues/iss258.htm">PATHNAME-HOST-PARSING:RECOGNIZE-LOGICAL-HOST-NAMES</A><LI> <A REL=CHILD HREF="../Issues/iss259.htm">PATHNAME-LOGICAL:ADD</A><LI> <A REL=CHILD HREF="../Issues/iss157.htm">FILE-OPEN-ERROR:SIGNAL-FILE-ERROR</A><LI> <A REL=CHILD HREF="../Issues/iss362.htm">WITH-OPEN-FILE-SETQ:EXPLICITLY-VAGUE</A><LI> <A REL=CHILD HREF="../Issues/iss361.htm">WITH-OPEN-FILE-DOES-NOT-EXIST:STREAM-IS-NIL</A><LI> <A REL=CHILD HREF="../Issues/iss363.htm">WITH-OPEN-FILE-STREAM-EXTENT:DYNAMIC-EXTENT</A><LI> <A REL=CHILD HREF="../Issues/iss327.htm">STREAM-ACCESS:ADD-TYPES-ACCESSORS</A><LI> <A REL=CHILD HREF="../Issues/iss097.htm">DECLS-AND-DOC</A><P></UL><HR>
|
|
|
|
<A REL=NAVIGATOR HREF="../Front/StartPts.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Starting Points]" SRC="../Graphics/StartPts.gif" ALIGN=Bottom></A><A REL=TOC HREF="../Front/Contents.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Contents]" SRC="../Graphics/Contents.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Master.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Index]" SRC="../Graphics/Index.gif" ALIGN=Bottom></A><A REL=INDEX HREF="../Front/X_Symbol.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Symbols]" SRC="../Graphics/Symbols.gif" ALIGN=Bottom></A><A REL=GLOSSARY HREF="../Body/26_a.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Glossary]" SRC="../Graphics/Glossary.gif" ALIGN=Bottom></A><A HREF="../Front/X3J13Iss.htm"><IMG WIDTH=80 HEIGHT=40 ALT="[Issues]" SRC="../Graphics/Issues.gif" ALIGN=Bottom></A><BR>
|
|
|
|
<A REL=COPYRIGHT HREF="../Front/Help.htm#Legal"><I>Copyright 1996-2005, LispWorks Ltd. All rights reserved.</I></A><P>
|
|
</BODY>
|
|
</HTML>
|