
% 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 domain \spadtype{TextFile} allows \Language{} to read and write
character data and exchange text with other programs.
This type behaves in \Language{} much like a \spadtype{File} of strings,
with additional operations to cause new lines.
We give an example of how to produce an upper case copy of a file.
\xtc{
This is the file from which we read the text.
}{
\spadcommand{f1: TextFile := open("/etc/group", "input")   \bound{f1}}
}
\xtc{
This is the file to which we read the text.
}{
\spadcommand{f2: TextFile := open("/tmp/MOTD", "output")  \bound{f2}}
}
\xtc{
Entire lines are handled using the \spadfunFromX{readLine}{TextFile} and
\spadfunFromX{writeLine}{TextFile} operations.
}{
\spadcommand{l := readLine! f1 \free{f1}\bound{l}}
}
\xtc{
}{
\spadcommand{writeLine!(f2, upperCase l) \free{f2 l}}
}
\xtc{
Use the
\spadfunFrom{endOfFile?}{TextFile} operation to check if you have
reached the end of the file.
}{
\begin{spadsrc}[\free{f1 f2}\bound{Copied}]
while not endOfFile? f1 repeat
    s := readLine! f1
    writeLine!(f2, upperCase s)
\end{spadsrc}
}
\xtc{
The file \spad{f1} is exhausted and should be closed.
}{
\spadcommand{close! f1  \free{Copied}\bound{closed1}}
}

\xtc{
It is sometimes useful to write lines a bit at a time.
The \spadfunFromX{write}{TextFile} operation allows this.
}{
\spadcommand{write!(f2, "-The-")  \free{Copied}\bound{tthhee}}
}
\xtc{
}{
\spadcommand{write!(f2, "-End-")  \free{tthhee}\bound{eenndd}}
}
\xtc{
This ends the line.
This is done in a machine-dependent manner.
}{
\spadcommand{writeLine! f2        \free{eenndd}\bound{LastLine}}
}
\xtc{
}{
\spadcommand{close! f2              \free{LastLine}\bound{closed2}}
}
% \xtc{
% Now that the file has been translated to upper case, let's compare it with
% the original.
% }{
% \spadcommand{)system cat /etc/motd  \free{closed2}\bound{showlow}}
% }
% \xtc{
% }{
% \spadcommand{)system cat /tmp/MOTD  \bound{showHI}\free{closed2}}
% }
\noOutputXtc{
Finally, clean up.
}{
\spadcommand{)system rm /tmp/MOTD   \free{closed2}}
}

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