reduce-historical/r38/doc/help/io.tex

\section{Input and Output}

\begin{Command}{IN}
\index{input}
The \name{in} command takes a list of file names and inputs each file into
the system.
\begin{Syntax}
\name{in} \meta{filename}\{,\meta{filename}\}\optional
\end{Syntax}

\meta{filename} must be in the current directory, or be a valid pathname.
If the file name is not an identifier, double quote marks (\name{"}) are
needed around the file name.

\begin{Comments}
A message is given if the file cannot be found, or has a mistake
in it.

Ending the command with a semicolon causes the file to be echoed to the
screen; ending it with a dollar sign does not echo the file.  If you want
some but not all of a file echoed, turn the switch \nameref{echo} on or off
in the file.

An efficient way to develop procedures in REDUCE is to write them into a file 
using a system editor of your choice, and then input the
files into an active REDUCE session.  REDUCE reparses the procedure as
it takes information from the file, overwriting the previous procedure
definition.  When it accepts the procedure, it echoes its name to the screen.
Data can also be input to the system from files.

Files to be read in should always end in \nameref{end}\name{;} to avoid
end-of-file problems.  Note that this is an additional \name{end;} to any
ending procedures in the file.
\end{Comments}
\end{Command}


\begin{Command}{INPUT}
\index{interactive}
The \name{input} command returns the input expression to the REDUCE numbered
prompt that is its argument.
\begin{Syntax}
\name{input}\(\meta{number}\) or \name{input} \meta{number}

\end{Syntax}

\meta{number} must be between 1 and the current REDUCE prompt number.

%%%\begin{Examples}
%%%\explanation{(In the following examples, unlike most others, the numbered
%%%prompt is shown.)}
%%%\end{Examples}
\begin{Comments}
An expression brought back by \name{input} can be reexecuted with new
values or switch settings, or used as an argument in another expression.
The command \nameref{ws} brings back the results of a numbered REDUCE
statement.  Two lists contain every input and every output statement since
the beginning of the session.  If your session is very long, storage space
begins to fill up with these expressions, so it is a good idea to end the
session once in a while, saving needed expressions to files with the
\nameref{saveas} and \nameref{out} commands.
%%% You can also clear the history lists with the \name{forget} command.

Switch settings and \nameref{let} statements can also be reexecuted by using
\name{input}.

An error message is given if a number is called for that has not yet been used.
\end{Comments}
\end{Command}


\begin{Command}{OUT}
\index{output}\index{open}
The \name{out} command directs output to the filename that is its argument,
until another \name{out} changes the output file, or \nameref{shut} closes it.
\begin{Syntax}
\name{out} \meta{filename} or \name{out "}\meta{pathname} \name{"} or \name{out t}
\end{Syntax}

\meta{filename} must be in the current directory, or be a valid complete
file description for your system.  If the file name is not
in the current directory, quote marks are needed around the file name.
If the file already exists, a message is printed allowing you to decide
whether to supersede the contents of the file with new material.

\begin{Comments}
To restore output to the terminal, type \name{out t}, or \nameref{shut} the
file.  When you use \name{out t}, the file remains available, and if you
open it again (with another \name{out}), new material is appended rather
than overwriting.

To write a file using \name{out} that can be input at a later time, the
switch \nameref{nat} must be turned off, so that the standard linear form
is saved that can be read in by \nameref{in}.  If \name{nat} is on, exponents
are printed on the line above the expression, which causes trouble
when REDUCE tries to read the file.

There is a slight complication if you are using the \name{out} command from
inside a file to create another file.  The \nameref{echo} switch is normally
off at the top-level and on while reading files (so you can see what is
being read in).  If you create a file using \name{out} at the top-level,
the result lines are printed into the file as you want them.  But if you
create such a file from inside a file, the \name{echo} switch is on, and
every line is echoed, first as you typed it, then as REDUCE parsed it, and
then once more for the file.  Therefore, when you create a file {\it from}
a file, you need to turn \name{echo} off explicitly before the \name{out}
command, and turn it back on when you \name{shut} the created file, so your
executing file echoes as it should.  This behavior also means that as you
watch the file execute, you cannot see the lines that are being put into
the \name{out} file.  As soon as you turn \name{echo} on, you can see
output again.
\end{Comments}
\end{Command}


\begin{Command}{SHUT}
\index{output}\index{close}
The \name{shut} command closes output files.
\begin{Syntax}
\name{shut} \meta{filename}\{,\meta{filename}\}\optional
\end{Syntax}

\meta{filename} must have been a file opened by \nameref{out}.

\begin{Comments}
A file that has been opened by \nameref{out} must be \name{shut} before it is
brought in by \nameref{in}.  Files that have been opened by \name{out} should
always be \name{shut} before the end of the REDUCE session, to avoid either
loss of information or the printing of extraneous information into the file.  
In most systems, terminating a session by \nameref{bye} closes all open
output files.
\end{Comments}
\end{Command}