\HeaderA{gzcon}{(De)compress I/O Through Connections}{gzcon}
\keyword{file}{gzcon}
\keyword{connection}{gzcon}
\begin{Description}\relax
\code{gzcon} provides a modified connection that wraps an existing
connection, and decompresses reads or compresses writes through that
connection.  Standard \code{gzip} headers are assumed.
\end{Description}
\begin{Usage}
\begin{verbatim}
gzcon(con, level = 6, allowNonCompressed = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{con}] a connection.
\item[\code{level}] integer between 0 and 9, the compression level when writing.
\item[\code{allowNonCompressed}] logical.  When reading, should
non-compressed input be allowed?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If \code{con} is open then the modified connection is opened.  Closing
the wrapper connection will also close the underlying connection.

Reading from a connection which does not supply a \code{gzip} magic
header is equivalent to reading from the original connection if
\code{allowNonCompressed} is true, otherwise an error.

The original connection becomes unusable: any object pointing to it will
now refer to the modified connection.

When the connection is opened for reading, the input is expected to
start with the \code{gzip} magic header.  If it does not and if
\code{allowNonCompressed = TRUE} (the default) the input is read as-is.
\end{Details}
\begin{Value}
An object inheriting from class \code{"connection"}.  This is the same
connection \emph{number} as supplied, but with a modified internal
structure. It has binary mode.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{gzfile}{gzfile}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
## Uncompress a data file from a URL
z <- gzcon(url("http://www.stats.ox.ac.uk/pub/datasets/csb/ch12.dat.gz"))
# read.table can only read from a text-mode connection.
raw <- textConnection(readLines(z))
close(z)
dat <- read.table(raw)
close(raw)
## End(Not run)

## gzfile and gzcon can inter-work.
## Of course here one would used gzfile, but file() can be replaced by
## any other connection generator.
zz <- gzfile("ex.gz", "w")
cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n")
close(zz)
readLines(zz <- gzcon(file("ex.gz", "rb")))
close(zz)
unlink("ex.gz")

zz <- gzcon(file("ex.gz", "wb"))
cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n")
close(zz)
readLines(zz <- gzfile("ex.gz"))
close(zz)
unlink("ex.gz")
\end{ExampleCode}
\end{Examples}

