497 lines
No EOL
10 KiB
HTML
497 lines
No EOL
10 KiB
HTML
<!DOCTYPE HTML>
|
|
<HTML LANG="en-us"
|
|
><HEAD
|
|
><TITLE
|
|
>with-open-file | Common Lisp Nova Spec</TITLE
|
|
><META CHARSET="US-ASCII"
|
|
><LINK REL="canonical" HREF="f_with-open-file.html"
|
|
><LINK REL="next" HREF="f_close.html" TYPE="text/html" TITLE="close"
|
|
><LINK REL="prev" HREF="f_stream-external-format.html" TYPE="text/html" TITLE="stream-external-format"
|
|
><LINK REL="up" HREF="21_2_Streams_Dictionary.html" TYPE="text/html" TITLE="21.2 Streams Dictionary"
|
|
><LINK REL="start" HREF="index.html" TYPE="text/html" TITLE="Common Lisp Nova Spec"
|
|
><META NAME="VIEWPORT" CONTENT="width=device-width, initial-scale=1.0"
|
|
><LINK REL="STYLESHEET" HREF="dpans.css%3F3909942064.css"
|
|
><SCRIPT SRC="dpans.js%3F3909942064"
|
|
></SCRIPT
|
|
><SCRIPT SRC="apropos.js%3F3909942064"
|
|
></SCRIPT
|
|
></HEAD
|
|
><BODY
|
|
><DIV
|
|
><DIV CLASS="topnav"
|
|
><DIV CLASS="breadcrumb"
|
|
><SPAN CLASS="breadcrumb-item"
|
|
><A HREF="index.html"
|
|
>Common Lisp Nova Spec</A
|
|
></SPAN
|
|
> <SPAN CLASS="breadcrumb-item"
|
|
>→ <A HREF="21_Streams.html"
|
|
>21. Streams</A
|
|
></SPAN
|
|
> <SPAN CLASS="breadcrumb-item"
|
|
>→ <A HREF="21_2_Streams_Dictionary.html"
|
|
>21.2 Streams Dictionary</A
|
|
></SPAN
|
|
> <SPAN CLASS="breadcrumb-item"
|
|
>→ <A HREF="f_with-open-file.html"
|
|
>with-open-file</A
|
|
></SPAN
|
|
></DIV
|
|
><DIV CLASS="apropos"
|
|
><DIV CLASS="apropos-io"
|
|
><A HREF="f_stream-external-format.html" CLASS="prev"
|
|
>←</A
|
|
><SPAN ID="apropos-label"
|
|
>Apropos </SPAN
|
|
><INPUT ID="apropos" AUTOFOCUS="AUTOFOCUS" PLACEHOLDER="Type here to search" ONINPUT="aproposInput(this);" ONKEYUP="aproposKeyup(event);" ONCHANGE="aproposChange(this);" ONFOCUS="aproposFocus(this);" ONFOCUSOUT="aproposFocusout(this);"
|
|
><A HREF="f_close.html" CLASS="next"
|
|
>→</A
|
|
></DIV
|
|
><DIV ID="apropos-res"
|
|
></DIV
|
|
></DIV
|
|
></DIV
|
|
><DIV CLASS="matter"
|
|
><DIV CLASS="com"
|
|
><DIV CLASS="begincom"
|
|
><HR
|
|
><TABLE WIDTH="100%" CELLSPACING="0" CELLPADDING="0"
|
|
><TR
|
|
><TD ALIGN="LEFT" VALIGN="BASELINE" WIDTH="100%" CLASS="name"
|
|
><SPAN CLASS="idx" DATA-KIND="idxref" DATA-TERM="with-open-file"
|
|
></SPAN
|
|
><B
|
|
>with-open-file</B
|
|
></TD
|
|
><TD ALIGN="RIGHT" VALIGN="BASELINE" WIDTH="0" NOWRAP="NOWRAP" CLASS="ftype"
|
|
><I
|
|
>Macro</I
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
></DIV
|
|
><UL CLASS="subtoc"
|
|
></UL
|
|
><DL
|
|
><DT
|
|
><B
|
|
>Syntax</B
|
|
></DT
|
|
><DD
|
|
><DIV CLASS="DefmacWithValuesNewline"
|
|
><DIV
|
|
><B
|
|
>with-open-file</B
|
|
> <SPAN CLASS="cmr"
|
|
>(</SPAN
|
|
><SPAN CLASS="cmssi"
|
|
>stream</SPAN
|
|
> <SPAN CLASS="cmssi"
|
|
>filespec</SPAN
|
|
> <SPAN CLASS="cmsy"
|
|
>{</SPAN
|
|
><VAR CLASS="param"
|
|
>options</VAR
|
|
><SPAN CLASS="cmsy"
|
|
>}</SPAN
|
|
><SPAN CLASS="cmr"
|
|
>*)</SPAN
|
|
> <SPAN CLASS="cmsy"
|
|
>{</SPAN
|
|
><VAR CLASS="param"
|
|
>declaration</VAR
|
|
><SPAN CLASS="cmsy"
|
|
>}</SPAN
|
|
><SPAN CLASS="cmr"
|
|
>*</SPAN
|
|
> <SPAN CLASS="cmsy"
|
|
>{</SPAN
|
|
><VAR CLASS="param"
|
|
>form</VAR
|
|
><SPAN CLASS="cmsy"
|
|
>}</SPAN
|
|
><SPAN CLASS="cmr"
|
|
>*</SPAN
|
|
> </DIV
|
|
><DIV
|
|
><SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> <SPAN CLASS="cmssi"
|
|
>results</SPAN
|
|
></DIV
|
|
></DIV
|
|
></DD
|
|
><DT
|
|
><B
|
|
>Arguments and Values</B
|
|
></DT
|
|
><DD
|
|
><P CLASS="j"
|
|
><VAR CLASS="param"
|
|
>stream</VAR
|
|
> – a variable. </P
|
|
><P CLASS="j"
|
|
><VAR CLASS="param"
|
|
>filespec</VAR
|
|
> — a <A HREF="26_1_Glossary.html#pathname_designator"
|
|
><EM CLASS="term"
|
|
>pathname designator</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
><VAR CLASS="param"
|
|
>options</VAR
|
|
> – <A HREF="26_1_Glossary.html#form"
|
|
><EM CLASS="term"
|
|
>forms</EM
|
|
></A
|
|
>; evaluated. </P
|
|
><P CLASS="j"
|
|
><VAR CLASS="param"
|
|
>declaration</VAR
|
|
> — a <A HREF="m_declare.html" CLASS="misc"
|
|
><B
|
|
>declare</B
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#expression"
|
|
><EM CLASS="term"
|
|
>expression</EM
|
|
></A
|
|
>; not evaluated. </P
|
|
><P CLASS="j"
|
|
><VAR CLASS="param"
|
|
>forms</VAR
|
|
> — an <A HREF="26_1_Glossary.html#implicit_progn"
|
|
><EM CLASS="term"
|
|
>implicit progn</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
><VAR CLASS="param"
|
|
>results</VAR
|
|
> — the <A HREF="26_1_Glossary.html#value"
|
|
><EM CLASS="term"
|
|
>values</EM
|
|
></A
|
|
> returned by the <VAR CLASS="param"
|
|
>forms</VAR
|
|
>.</P
|
|
></DD
|
|
><DT
|
|
><B
|
|
>Description</B
|
|
></DT
|
|
><DD
|
|
><P CLASS="j"
|
|
><A HREF="f_with-open-file.html" CLASS="macref"
|
|
><B
|
|
>with-open-file</B
|
|
></A
|
|
> uses <A HREF="f_open.html" CLASS="funref"
|
|
><B
|
|
>open</B
|
|
></A
|
|
> to create a <A HREF="26_1_Glossary.html#file_stream"
|
|
><EM CLASS="term"
|
|
>file stream</EM
|
|
></A
|
|
> to <A HREF="26_1_Glossary.html#file"
|
|
><EM CLASS="term"
|
|
>file</EM
|
|
></A
|
|
> named by <VAR CLASS="param"
|
|
>filespec</VAR
|
|
>. <VAR CLASS="param"
|
|
>Filespec</VAR
|
|
> is the name of the file to be opened. <VAR CLASS="param"
|
|
>Options</VAR
|
|
> are used as keyword arguments to <A HREF="f_open.html" CLASS="funref"
|
|
><B
|
|
>open</B
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>The <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#object"
|
|
><EM CLASS="term"
|
|
>object</EM
|
|
></A
|
|
> to which the <VAR CLASS="param"
|
|
>stream</VAR
|
|
> <A HREF="26_1_Glossary.html#variable"
|
|
><EM CLASS="term"
|
|
>variable</EM
|
|
></A
|
|
> is <A HREF="26_1_Glossary.html#bound"
|
|
><EM CLASS="term"
|
|
>bound</EM
|
|
></A
|
|
> has <A HREF="26_1_Glossary.html#dynamic_extent"
|
|
><EM CLASS="term"
|
|
>dynamic extent</EM
|
|
></A
|
|
>; its <A HREF="26_1_Glossary.html#extent"
|
|
><EM CLASS="term"
|
|
>extent</EM
|
|
></A
|
|
> ends when the <A HREF="26_1_Glossary.html#form"
|
|
><EM CLASS="term"
|
|
>form</EM
|
|
></A
|
|
> is exited. </P
|
|
><P CLASS="j"
|
|
><A HREF="f_with-open-file.html" CLASS="macref"
|
|
><B
|
|
>with-open-file</B
|
|
></A
|
|
> evaluates the <VAR CLASS="param"
|
|
>forms</VAR
|
|
> as an <A HREF="26_1_Glossary.html#implicit_progn"
|
|
><EM CLASS="term"
|
|
>implicit progn</EM
|
|
></A
|
|
> with <VAR CLASS="param"
|
|
>stream</VAR
|
|
> bound to the value returned by <A HREF="f_open.html" CLASS="funref"
|
|
><B
|
|
>open</B
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>When control leaves the body, either normally or abnormally (such as by use of <A HREF="f_throw.html" CLASS="specref"
|
|
><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
|
|
><P CLASS="j"
|
|
>It is possible by the use of <CODE CLASS="f"
|
|
>:if-exists nil</CODE
|
|
> or <CODE CLASS="f"
|
|
>:if-does-not-exist nil</CODE
|
|
> for <VAR CLASS="param"
|
|
>stream</VAR
|
|
> to be bound to <SPAN CLASS="misc"
|
|
><B
|
|
>nil</B
|
|
></SPAN
|
|
>. Users of <CODE CLASS="f"
|
|
>:if-does-not-exist nil</CODE
|
|
> should check for a valid <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
>. </P
|
|
><P CLASS="j"
|
|
>The consequences are undefined if an attempt is made to <A HREF="26_1_Glossary.html#assign"
|
|
><EM CLASS="term"
|
|
>assign</EM
|
|
></A
|
|
> the <VAR CLASS="param"
|
|
>stream</VAR
|
|
> <A HREF="26_1_Glossary.html#variable"
|
|
><EM CLASS="term"
|
|
>variable</EM
|
|
></A
|
|
>. The compiler may choose to issue a warning if such an attempt is detected.</P
|
|
></DD
|
|
><DT
|
|
><B
|
|
>Examples</B
|
|
></DT
|
|
><DD
|
|
><PRE CLASS="screen"
|
|
> (setq p (merge-pathnames "test"))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> #<PATHNAME :HOST NIL :DEVICE <I CLASS="i"
|
|
><I
|
|
>device-name</I
|
|
></I
|
|
> :DIRECTORY <I CLASS="i"
|
|
><I
|
|
>directory-name</I
|
|
></I
|
|
>
|
|
: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~%")) <SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> 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)))
|
|
<SPAN CLASS="cmr"
|
|
>⊳</SPAN
|
|
> *** Here are a couple
|
|
<SPAN CLASS="cmr"
|
|
>⊳</SPAN
|
|
> *** of test data lines
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Reached end of file."</PRE
|
|
><PRE CLASS="screen"
|
|
>;; 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))
|
|
<SPAN CLASS="cmr"
|
|
>⊳</SPAN
|
|
> <U CLASS="underline"
|
|
><SPAN CLASS="cmtt"
|
|
>hello?</SPAN
|
|
></U
|
|
>
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> 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"))
|
|
<SPAN CLASS="cmsy"
|
|
><SPAN CLASS="arrow"
|
|
>→</SPAN
|
|
></SPAN
|
|
> "Hello" ;FORMAT got an argument of NIL!</PRE
|
|
></DD
|
|
><DT
|
|
><B
|
|
>Side Effects</B
|
|
></DT
|
|
><DD
|
|
><P CLASS="j"
|
|
>Creates a <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
> to the <A HREF="26_1_Glossary.html#file"
|
|
><EM CLASS="term"
|
|
>file</EM
|
|
></A
|
|
> named by <VAR CLASS="param"
|
|
>filename</VAR
|
|
> (upon entry), and closes the <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
> (upon exit). In some <A HREF="26_1_Glossary.html#implementation"
|
|
><EM CLASS="term"
|
|
>implementations</EM
|
|
></A
|
|
>, the <A HREF="26_1_Glossary.html#file"
|
|
><EM CLASS="term"
|
|
>file</EM
|
|
></A
|
|
> might be locked in some way while it is open. If the <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
> is an <A HREF="26_1_Glossary.html#output"
|
|
><EM CLASS="term"
|
|
>output</EM
|
|
></A
|
|
> <A HREF="26_1_Glossary.html#stream"
|
|
><EM CLASS="term"
|
|
>stream</EM
|
|
></A
|
|
>, a <A HREF="26_1_Glossary.html#file"
|
|
><EM CLASS="term"
|
|
>file</EM
|
|
></A
|
|
> might be created.</P
|
|
></DD
|
|
><DT
|
|
><B
|
|
>Affected By</B
|
|
></DT
|
|
><DD
|
|
><P CLASS="j"
|
|
>The host computer’s file system.</P
|
|
></DD
|
|
><DT
|
|
><B
|
|
>Exceptional Situations</B
|
|
></DT
|
|
><DD
|
|
><P CLASS="j"
|
|
>See the <A HREF="26_1_Glossary.html#function"
|
|
><EM CLASS="term"
|
|
>function</EM
|
|
></A
|
|
> <A HREF="f_open.html" CLASS="funref"
|
|
><B
|
|
>open</B
|
|
></A
|
|
>.</P
|
|
></DD
|
|
><DT
|
|
><B
|
|
>See Also</B
|
|
></DT
|
|
><DD
|
|
><P CLASS="j"
|
|
><A HREF="f_open.html" CLASS="funref"
|
|
><B
|
|
>open</B
|
|
></A
|
|
>, <A HREF="f_close.html" CLASS="funref"
|
|
><B
|
|
>close</B
|
|
></A
|
|
>, <A HREF="t_pathname.html" CLASS="typeref"
|
|
><B
|
|
>pathname</B
|
|
></A
|
|
>, <A HREF="t_logical-pathname.html" CLASS="typeref"
|
|
><B
|
|
>logical-pathname</B
|
|
></A
|
|
>, <A HREF="19_1_Overview_of_Filenames.html#sec_19_1_2" CLASS="secref"
|
|
><SPAN CLASS="cmr"
|
|
>Section</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>19.1.2</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>(Pathnames</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>as</SPAN
|
|
> <SPAN CLASS="cmr"
|
|
>Filenames)</SPAN
|
|
></A
|
|
></P
|
|
></DD
|
|
></DL
|
|
></DIV
|
|
></DIV
|
|
><DIV CLASS="footer"
|
|
><DIV CLASS="btmnav"
|
|
><A HREF="f_stream-external-format.html" CLASS="prev"
|
|
>←</A
|
|
><A HREF="f_close.html" CLASS="next"
|
|
>→</A
|
|
></DIV
|
|
><DIV CLASS="trail"
|
|
>Conversion to HTML copyright 2023 by Gilbert Baumann</DIV
|
|
></DIV
|
|
></DIV
|
|
><SCRIPT
|
|
>domReady();</SCRIPT
|
|
></BODY
|
|
></HTML
|
|
> |