\Header{textConnection}{Text Connections}
\keyword{file}{textConnection}
\keyword{connection}{textConnection}
\begin{Description}\relax
Input and output text connections.\end{Description}
\begin{Usage}
\begin{verbatim}
textConnection(object, open = "r")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] character.  A description of the connection. 
For an input is an \R{} character vector object, and for an output
connection the name for the \R{} character vector to receive the
output.

\item[\code{open}] character.  Either \code{"r"} (or equivalently \code{""})
for an input connection or \code{"w"} or \code{"a"}for an output
connection.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
An input text connection is opened and the character vector is copied
at time the connection object is created, and \code{close}
destroys the copy.

An output text connection is opened and creates an \R{} character vector
of the given name in the user's workspace.  This object will at all
times hold the completed lines of output to the connection, and
\code{\Link{isIncomplete}} will indicate if there is an incomplete
final line.  Closing the connection will output the final line,
complete or not.

Opening a text connection with \code{mode = "a"} will attempt to
append to an existing character vector with the given name in the
user's workspace.  If none is found (even if an object exists of the
right name but the wrong type) a new character vector wil be created,
with a warning.

You cannot \code{seek} on a text connection, and \code{seek} will
always return zero as the position.\end{Details}
\begin{Value}
A connection object of class \code{"textConnection"} which inherits
from class \code{"connection"}.\end{Value}
\begin{SeeAlso}\relax
\code{\Link{connections}}, \code{\Link{showConnections}},
\code{\Link{pushBack}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
zz <- textConnection(LETTERS)
readLines(zz, 2)
scan(zz, "", 4)
pushBack(c("aa", "bb"), zz)
scan(zz, "", 4)
close(zz)

zz <- textConnection("foo", "w")
writeLines(c("testit1", "testit2"), zz)
cat("testit3 ", file=zz)
isIncomplete(zz)
cat("testit4\n", file=zz)
isIncomplete(zz)
close(zz)
foo

# capture R output: use part of example from help(lm)
zz <- textConnection("foo", "w")
ctl <- c(4.17, 5.58, 5.18, 6.11, 4.5, 4.61, 5.17, 4.53, 5.33, 5.14)
trt <- c(4.81, 4.17, 4.41, 3.59, 5.87, 3.83, 6.03, 4.89, 4.32, 4.69)
group <- gl(2, 10, 20, labels = c("Ctl", "Trt"))
weight <- c(ctl, trt)
sink(zz)
anova(lm.D9 <- lm(weight ~ group))
cat("\nSummary of Residuals:\n\n")
summary(resid(lm.D9))
sink()
close(zz)
cat(foo, sep = "\n")

\end{ExampleCode}
\end{Examples}

