
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



The \spadtype{File(S)} domain provides a basic interface to read and
write values of type \spad{S} in files.
\xtc{
Before working with a file, it must be made accessible to \Language{} with
the \spadfunFrom{open}{File} operation.
}{
\spadcommand{ifile:File List Integer:=open("/tmp/jazz1","output")  \bound{ifile}}
}
The \spadfunFrom{open}{File} function arguments are a \spadtype{FileName}
and a \spadtype{String} specifying the mode.
If a full pathname is not specified, the current default directory is
assumed.
The mode must be one of \spad{"input"} or \spad{"output"}.
If it is not specified, \spad{"input"} is assumed.
Once the file has been opened, you can read or write data.
\xtc{
The operations \spadfunFromX{read}{File} and \spadfunFromX{write}{File} are
provided.
}{
\spadcommand{write!(ifile, [-1,2,3])        \free{ifile}\bound{ifile1}}
}
\xtc{
}{
\spadcommand{write!(ifile, [10,-10,0,111])  \free{ifile1}\bound{ifile2}}
}
\xtc{
}{
\spadcommand{write!(ifile, [7])             \free{ifile2}\bound{ifile3}}
}
\xtc{
You can change from writing to reading (or vice versa)
by reopening a file.
}{
\spadcommand{reopen!(ifile, "input")        \free{ifile3}\bound{ifile4}}
}
\xtc{
}{
\spadcommand{read! ifile                    \free{ifile4}\bound{ifile5}}
}
\xtc{
}{
\spadcommand{read! ifile                    \free{ifile5}\bound{ifile6}}
}
\xtc{
The \spadfunFromX{read}{File} operation can cause an error if one tries to
read more data than is in the file.
To guard against this possibility the \spadfunFromX{readIfCan}{File}
operation should be used.
}{
\spadcommand{readIfCan! ifile  \free{ifile6}\bound{ifile7}}
}
\xtc{
}{
\spadcommand{readIfCan! ifile  \free{ifile7}\bound{ifile8}}
}
\xtc{
You can find the current mode of the file, and the file's name.
}{
\spadcommand{iomode ifile           \free{ifile}}
}
\xtc{
}{
\spadcommand{name ifile             \free{ifile}}
}
\xtc{
When you are finished with a file, you should close it.
}{
\spadcommand{close! ifile           \free{ifile}\bound{ifileA}}
}
\noOutputXtc{
}{
\spadcommand{)system rm /tmp/jazz1  \free{ifileA}}
}
%\xtc{
%}{
%\spadcommand{)clear all  \free{}\bound{}}
%}

A limitation of the underlying LISP system is that not all values can be
represented in a file.
In particular, delayed values containing compiled functions cannot be
saved.

For more information on related topics, see
\xmpref{TextFile},
\xmpref{KeyedAccessFile},
\xmpref{Library}, and
\xmpref{FileName}.
\showBlurb{File}
