The R Project SVN R

% File src/library/base/man/detach.Rd
% Part of the R package, http://www.R-project.org
% Copyright 1995-2009 R Core Development Team
% Distributed under GPL 2 or later

\name{detach}
\alias{detach}
\title{Detach Objects from the Search Path}
\usage{
detach(name, pos = 2, unload = FALSE, character.only = FALSE, force = FALSE)
}
\arguments{
  \item{name}{
    The object to detach.  Defaults to \code{search()[pos]}.
    This can be an unquoted name or a character string but \emph{not} a
    character vector.  If a number is supplied this is taken as \code{pos}.
  }
  \item{pos}{
    Index position in \code{\link{search}()} of the database to
    detach.  When \code{name} is a number, \code{pos = name}
    is used.
  }
  \item{unload}{A logical value indicating whether or not to attempt to
    unload the namespace when a package is being detached.  If the
    package has a namespace and \code{unload} is \code{TRUE}, then
    \code{detach} will attempt to unload the namespace \emph{via}
    \code{\link{unloadNamespace}}: if the namespace is imported by
    another namespace or \code{unload} is \code{FALSE}, no unloading
    will occur.
  }
  \item{character.only}{a logical indicating whether \code{name}
    can be assumed to be character strings.}
  \item{force}{logical: should a package be detached even though other
    loaded packages depend on it?}
}
\description{
  Detach a database, i.e., remove it from the \code{\link{search}()}
  path of available \R objects.  Usually this is either a
  \code{\link{data.frame}} which has been \code{\link{attach}}ed or a
  package which was attached by \code{\link{library}}.
}
\details{
  This is most commonly used with a single number argument referring to a
  position on the search list, and can also be used with a unquoted or
  quoted name of an item on the search list such as \code{package:tools}.

  If a package has a namespace, detaching it does not by default unload
  the namespace (and may not even with \code{unload=TRUE}), and
  detaching will not in general unload any dynamically loaded compiled
  code (DLLs).  Further, registered S3 methods from the namespace will
  not be removed.  If you use \code{\link{library}} on a package whose
  name space is loaded, it attaches the exports of the already loaded
  name space.  So detaching and re-attaching a package may not refresh
  some or all components of the package, and is inadvisable.
}
\note{
  You cannot detach either the workspace (position 1) nor the \pkg{base}
  package (the last item in the search list), and attempting to do so
  will throw an error.
  
  Unloading some name spaces has undesirable side effects:
  e.g. unloading \pkg{grid} closes all graphics devices, and on most
  systems \pkg{tcltk} cannot be reloaded once it has been unloaded and
  may crash \R if this is attempted.
}
\value{
  The return value is \link{invisible}.  It is \code{NULL} when a
  package is detached, otherwise the environment which was returned by
  \code{\link{attach}} when the object was attached (incorporating any
  changes since it was attached).
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{attach}}, \code{\link{library}}, \code{\link{search}},
  \code{\link{objects}}, \code{\link{unloadNamespace}},
  \code{\link{library.dynam.unload}} .
}
\examples{
require(splines) # package
detach(package:splines)
## or also
library(splines)
pkg <- "package:splines"
\dontshow{
stopifnot(inherits(tryCatch(detach(pkg), error=function(.).),  "error"))
}
detach(pkg, character.only = TRUE)

## careful: do not do this unless 'splines' is not already loaded.
library(splines)
detach(2) # 'pos' used for 'name'

## an example of the name argument to attach
## and of detaching a database named by a character vector
attach_and_detach <- function(db, pos=2)
{
   name <- deparse(substitute(db))
   attach(db, pos=pos, name=name)
   print(search()[pos])
   detach(name, character.only = TRUE)
}
attach_and_detach(women, pos=3)
}
\keyword{data}