\HeaderA{dump}{Text Representations of R Objects}{dump}
\keyword{file}{dump}
\keyword{connection}{dump}
\begin{Description}\relax
This function takes a vector of names of \R{} objects and produces
text representations of the objects on a file or connection.
A \code{dump} file can usually be \code{\LinkA{source}{source}}d into another
\R{} (or S) session.
\end{Description}
\begin{Usage}
\begin{verbatim}
dump(list, file = "dumpdata.R", append = FALSE, 
     control = "all", envir = parent.frame(), evaluate = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{list}] character. The names of one or more \R{} objects to be dumped.
\item[\code{file}] either a character string naming a file or a
connection.  \code{""} indicates output to the console.
\item[\code{append}] if \code{TRUE} and \code{file} is a character string,
output will be appended to \code{file}; otherwise, it will overwrite
the contents of \code{file}.
\item[\code{control}] character vector indicating deparsing options.
See \code{\LinkA{.deparseOpts}{.deparseOpts}} for their description.
\item[\code{envir}] the environment to search for objects.
\item[\code{evaluate}] logical.  Should promises be evaluated?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If some of the objects named do not exist (in scope), they are
omitted, with a warning.  If \code{file} is a file and no objects
exist then no file is created.

\code{source}ing may not produce an identical copy of
\code{dump}ed objects.  A warning is issued if it is likely that
problems will arise, for example when dumping exotic or complex
objects (see the Note).

\code{dump} will also warn if fewer characters were written to a file
than expected, which may indicate a full or corrupt file system.

A \code{dump} file can be \code{\LinkA{source}{source}}d into another \R{} (or
perhaps S) session, but the function \code{\LinkA{save}{save}} is designed to
be used for transporting \R{} data, and will work with \R{} objects that
\code{dump} does not handle.

To produce a more readable representation of an object, use
\code{control = NULL}.  This will skip attributes, and will make other
simplifications that make \code{source} less likely to produce an
identical copy.  See \code{\LinkA{deparse}{deparse}} for details.

To deparse the internal representation of a function rather than
displaying the saved source, use \code{control = c("keepInteger",
    "warnIncomplete", "keepNA")}.  This will lose all formatting and
comments, but may be useful in those cases where the saved source is
no longer correct.

Promises will normally only be encountered by users as a result of
lazy-loading (when the default \code{evaluate = TRUE} is essential)
and after the use of \code{\LinkA{delayedAssign}{delayedAssign}},
when \code{evaluate = FALSE} might be intended.
\end{Details}
\begin{Value}
An invisible character vector containing the names of the objects
which were dumped.
\end{Value}
\begin{Note}\relax
As \code{dump} is defined in the base name space, the \pkg{base}
package will be searched \emph{before} the global environment unless
\code{dump} is called from the top level prompt or the \code{envir}
argument is given explicitly.

To avoid the risk of a source attribute becoming out of sync with the
actual function definition, the source attribute of a function will
never be dumped as an attribute.

Currently environments, external pointers, weak references and objects
of type \code{S4} are not deparsed in a way that can be
\code{source}d.  In addition, language objects are deparsed in a
simple way whatever the value of \code{control}, and this includes not
dumping their attributes (which will result in a warning).
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{dput}{dput}}, \code{\LinkA{dget}{dget}}, \code{\LinkA{write}{write}}.\\
\code{\LinkA{save}{save}} for a more reliable way to save \R{} objects.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- 1; y <- 1:10
dump(ls(pattern = '^[xyz]'), "xyz.Rdmped")
print(.Last.value)
unlink("xyz.Rdmped")
\end{ExampleCode}
\end{Examples}

