detach                 package:base                 R Documentation

Detach Objects from the Search Path

Description:

     Detach a database, i.e., remove it from the 'search()' path of
     available R objects.  Usually, this is either a 'data.frame' which
     has been 'attach'ed or a package which was required previously.

Usage:

     detach(name, pos = 2, version, unload = FALSE)

Arguments:

    name: The object to detach.  Defaults to 'search()[pos]'. This can
          be an unquoted name or a character string but _not_ a
          character vector.  If a number is supplied this is taken as
          'pos'. 

     pos: Index position in 'search()' of database to detach.  When
          'name' is a number, 'pos = name' is used. 

 version: A character string denoting a version number of the package
          to be removed.  This should be used only with a versioned
          installation of the package: see 'library'. 

  unload: A logical value indicating whether or not to attempt to
          unload the namespace and S4 methods when a package is being
          detached.  If the package has a namespace and 'unload' is
          'TRUE', then 'detach' will attempt to unload the namespace
          and remove any S4 methods defined by the package.  If the
          namespace is in use or 'unload' is 'FALSE', no unloading will
          occur. 

Details:

     This 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
     'package:tools'.

     When a package have been loaded with an explicit version number it
     can be detached using the name shown by 'search' or by supplying
     'name' and 'version': see the examples.

     If a package has a namespace, detaching it does not by default
     unload the namespace (and may not even with '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 'library' on a package
     whose name space is loaded, it attaches the exports of the loaded
     name space. So detaching and re-attaching a package may not
     refresh some or all components of the package, and is inadvisable.

Value:

     The attached database is returned invisibly, either as
     'data.frame' or as 'list'.

Note:

     You cannot detach either the workspace (position 1) or the 'base'
     package (the last item in the search list).

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'attach', 'library', 'search', 'objects', 'unloadNamespace',
     'library.dynam.unload' .

Examples:

     require(splines) # package
     detach(package:splines)
     ## could equally well use detach("package:splines")
     ## but NOT  pkg <- "package:splines"; detach(pkg)
     ## Instead, use
     library(splines)
     pkg <- "package:splines"
     detach(pos = match(pkg, search()))

     ## 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])
        eval(substitute(detach(n), list(n=name)))
     }
     attach_and_detach(women, pos=3)

     ## Not run: 
     ## Using a versioned install
     library(ash, version="1.0-9")  # or perhaps just library(ash)
     # then one of
     detach("package:ash", version="1.0-9")
     # or
     detach("package:ash_1.0-9")
     ## End(Not run)

