src/library/base/man/ns-load.Rd

% File src/library/base/man/ns-load.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2019 R Core Team
% Distributed under GPL 2 or later

\name{ns-load}
\title{Loading and Unloading Name Spaces}
%% Currently considered "main" help page on namespaces
%%                       --------------- -> \references{}, \seealso{}
\alias{attachNamespace}
\alias{loadNamespace}
\alias{requireNamespace}
\alias{loadedNamespaces}
\alias{unloadNamespace}
\alias{isNamespaceLoaded}

\description{
  Functions to load and unload name spaces.
}
\usage{
attachNamespace(ns, pos = 2L, depends = NULL, exclude, include.only)
loadNamespace(package, lib.loc = NULL,
              keep.source = getOption("keep.source.pkgs"),
              partial = FALSE, versionCheck = NULL,
              keep.parse.data = getOption("keep.parse.data.pkgs"))
requireNamespace(package, ..., quietly = FALSE)
loadedNamespaces()
unloadNamespace(ns)
isNamespaceLoaded(name)
}
\arguments{
  \item{ns}{string or name space object.}
  \item{pos}{integer specifying position to attach.}
  \item{depends}{\code{NULL} or a character vector of dependencies to be
    recorded in object \code{.Depends} in the package.}
  \item{package}{string naming the package/name space to load.}
  \item{lib.loc}{character vector specifying library search path.}
  \item{keep.source}{Now ignored except during package installation.}
  \item{keep.parse.data}{Ignored except during package installation.}
  \item{partial}{logical; if true, stop just after loading code.}
  \item{versionCheck}{\code{NULL} or a version specification (a list
    with components \code{op} and \code{version}).}
  \item{quietly}{logical: should progress and error messages be suppressed?}
  \item{name}{string or \sQuote{name}, see \code{\link{as.symbol}},
    of a package, e.g., \code{"stats"}.}
  \item{exclude, include.only}{character vectors; see \code{\link{library}}.}
  \item{\dots}{further arguments to be passed to \code{loadNamespace}.}
}
\details{
  The functions \code{loadNamespace} and \code{attachNamespace} are
  usually called implicitly when \code{\link{library}} is used to load a name
  space and any imports needed.  However it may be useful at times to
  call these functions directly.

  \code{loadNamespace} loads the specified name space and registers it in
  an internal data base.  A request to load a name space when one of that
  name is already loaded has no effect.  The arguments have the same
  meaning as the corresponding arguments to \code{\link{library}}, whose
  help page explains the details of how a particular installed package
  comes to be chosen.  After loading, \code{loadNamespace} looks for a
  hook function named \code{\link{.onLoad}} as an internal variable in
  the name space (it should not be exported).  Partial loading is used
  to support installation with lazy-loading.

  Optionally the package licence is checked during loading: see section
  \sQuote{Licenses} in the help for \code{\link{library}}.

  \code{loadNamespace} does not attach the name space it loads to the
  search path.  \code{attachNamespace} can be used to attach a frame
  containing the exported values of a name space to the search path (but
  this is almost always done \emph{via} \code{\link{library}}).  The
  hook function \code{\link{.onAttach}} is run after the name space
  exports are attached.

  \code{requireNamespace} is a wrapper for \code{loadNamespace}
  analogous to \code{\link{require}} that returns a logical value.

  \code{loadedNamespaces} returns a character vector of the names of
  the loaded name spaces.

  \code{isNamespaceLoaded(pkg)} is equivalent to but more efficient than
  \code{pkg \%in\% loadedNamespaces()}.

  \code{unloadNamespace} can be used to attempt to force a name space to
  be unloaded.  If the name space is attached, it is first
  \code{\link{detach}}ed, thereby running a \code{\link{.onDetach}} or
  \code{.Last.lib} function in the name space if one is exported.  An
  error is signaled and the name space is not unloaded if the name space
  is imported by other loaded name spaces.  If defined, a hook function
  \code{\link{.onUnload}} is run before removing the name space from the
  internal registry.

  See the comments in the help for \code{\link{detach}} about some
  issues with unloading and reloading name spaces.
}
\value{
  \code{attachNamespace} returns invisibly the package environment it
  adds to the search path.

  \code{loadNamespace} returns the name space environment, either one
  already loaded or the one the function causes to be loaded.

  \code{requireNamespace} returns \code{TRUE} if it succeeds or
  \code{FALSE}.

  \code{loadedNamespaces} returns a \code{\link{character}} vector.

  \code{unloadNamespace} returns \code{NULL}, invisibly.
}
\seealso{
  \code{\link{getNamespace}}, \code{\link{asNamespace}},
  \code{\link{topenv}}, \code{\link{.onLoad}} (etc);
  further \code{\link{environment}}.
}
\references{
  The \sQuote{Writing R Extensions} manual, section \dQuote{Package namespaces}.
}
\author{Luke Tierney and R-core}
\examples{
 (lns <- loadedNamespaces())
 statL <- isNamespaceLoaded("stats")% checks work also when it is *not* loaded
 stopifnot( identical(statL, "stats" \%in\% lns) )

 ## The string "foo" and the symbol 'foo' can be used interchangably here:
 stopifnot( identical(isNamespaceLoaded(  "foo"   ), FALSE),
            identical(isNamespaceLoaded(quote(foo)), FALSE),
            identical(isNamespaceLoaded(quote(stats)), statL))

hasS <- isNamespaceLoaded("splines") # (to restore if needed)
Sns <- asNamespace("splines") # loads it if not already
stopifnot(   isNamespaceLoaded("splines"))
unloadNamespace(Sns) # unloading the NS 'object'
stopifnot( ! isNamespaceLoaded("splines"))
if (hasS) loadNamespace("splines") # (restoring previous state)
}
\keyword{data}
\keyword{utilities}