\HeaderA{attach}{Attach Set of R Objects to Search Path}{attach}
\keyword{data}{attach}
\begin{Description}\relax
The database is attached to the \R{} search path.  This means that the
database is searched by \R{} when evaluating a variable, so objects in
the database can be accessed by simply giving their names.
\end{Description}
\begin{Usage}
\begin{verbatim}
attach(what, pos = 2, name = deparse(substitute(what)), warn.conflicts=TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{what}] \dQuote{database}.  This may currently be a
\code{data.frame} or \code{list} or a \R{} data file created with
\code{\LinkA{save}{save}}.
\item[\code{pos}] integer specifying position in \code{\LinkA{search}{search}()} where
to attach.
\item[\code{name}] alternative way to specify the database to be attached.
\item[\code{warn.conflicts}] logical.  If \code{TRUE}, warnings are
printed about \code{\LinkA{conflicts}{conflicts}} from attaching the database,
unless that database contains an object \code{.conflicts.OK}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
When evaluating a variable or function name \R{} searches for
that name in the databases listed by \code{\LinkA{search}{search}}.  The first
name of the appropriate type is used.

By attaching a data frame to the search path it is possible to refer
to the variables in the data frame by their names alone, rather than
as components of the data frame (eg in the example below,
\code{height} rather than \code{women\$height}).

By default the database is attached in position 2 in the search path,
immediately after the user's workspace and before all previously
loaded packages and previously attached databases. This can be altered
to attach later in the search path with the \code{pos} option, but you
cannot attach at \code{pos=1}.

The database is not actually attached.  Rather, a new environment is
created on the search path and the elements of a list (including columns
of a dataframe) or objects in a save file are \emph{copied} into the
new environment.  If you use \code{\LinkA{<{}<\Rdash}{<.Rlbrace..Rrbrace.<.Rdash.}} or \code{\LinkA{assign}{assign}}
to assign to an attached database, you only alter the attached copy,
not the original object.  (Normal assignment will place a modified
version in the user's workspace: see the examples.)
For this reason \code{attach} can lead to confusion.

One useful \sQuote{trick} is to use \code{what = NULL} (or equivalently a
length-zero list) to create a new environment on the search path into
which objects can be assigned by \code{\LinkA{assign}{assign}} or
\code{\LinkA{sys.source}{sys.source}}.
\end{Details}
\begin{Value}
The \code{\LinkA{environment}{environment}} is returned invisibly with a
\code{"name"} attribute.
\end{Value}
\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{library}{library}}, \code{\LinkA{detach}{detach}}, \code{\LinkA{search}{search}},
\code{\LinkA{objects}{objects}}, \code{\LinkA{environment}{environment}}, \code{\LinkA{with}{with}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
summary(women$height)   # refers to variable 'height' in the data frame
attach(women)
summary(height)         # The same variable now available by name
height <- height*2.54   # Don't do this. It creates a new variable
                        # in the user's workspace
find("height")
summary(height)         # The new variable in the workspace
rm(height)
summary(height)         # The original variable.
height <<- height*25.4  # Change the copy in the attached environment
find("height")
summary(height)         # The changed copy
detach("women")
summary(women$height)   # unchanged

## Not run: 
## create an environment on the search path and populate it
sys.source("myfuns.R", envir=attach(NULL, name="myfuns"))
## End(Not run)\end{ExampleCode}
\end{Examples}

