\Header{pushBack}{Push Text Back on to a Connection}
\alias{pushBackLength}{pushBack}
\keyword{connection}{pushBack}
\begin{Description}\relax
Functions to push back text lines onto a connection, and to enquire
how many lines are currently pushed back.
\end{Description}
\begin{Usage}
\begin{verbatim}
pushBack(data, connection, newLine = TRUE)
pushBackLength(connection)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{data}] a character vector.
\item[\code{connection}] A connection.
\item[\code{newLine}] logical. If true, a newline is appended to each string
pushed back.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Several character strings can be pushed back on one or more occasions.
The occasions form a stack, so the first line to be retrieved will be
the first string from the last call to \code{pushBack}.  Lines which
are pushed back are read prior to the normal input from the
connection, by the normal text-reading functions such as
\code{\Link{readLines}} and \code{\Link{scan}}.

Pushback is only allowed for readable connections.

Not all uses of connections respect pushbacks, in particular the input
connection is still wired directly, so for example parsing
commands from the console and \code{\Link{scan}("")} ignore pushbacks on
\code{\Link{stdin}}.
\end{Details}
\begin{Value}
\code{pushBack} returns nothing.

\code{pushBackLength} returns number of lines currently pushed back.
\end{Value}
\begin{SeeAlso}\relax
\code{\Link{connections}}, \code{\Link{readLines}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
zz <- textConnection(LETTERS)
readLines(zz, 2)
pushBack(c("aa", "bb"), zz)
pushBackLength(zz)
readLines(zz, 1)
pushBackLength(zz)
readLines(zz, 1)
readLines(zz, 1)
close(zz)
\end{ExampleCode}
\end{Examples}

