ns-load {base} | R Documentation

## Loading and Unloading Name Spaces

### Description

Functions to load and unload name spaces.

### Usage

    attachNamespace(ns, pos = 2L, depends = NULL)
    loadNamespace(package, lib.loc = NULL,
                  keep.source = getOption("keep.source.pkgs"),
                  partial = FALSE, versionCheck = NULL)
    requireNamespace(package, ..., quietly = FALSE)
    loadedNamespaces()
    unloadNamespace(ns)
    isNamespaceLoaded(name)

### Arguments

`ns` | string or name space object.
`pos` | integer specifying position to attach.
`depends` | `NULL` or a character vector of dependencies to be recorded in object `.Depends` in the package.
`package` | string naming the package/name space to load.
`lib.loc` | character vector specifying library search path.
`keep.source` | Now ignored except during package installation. For more details see this argument to `library`.
`partial` | logical; if true, stop just after loading code.
`versionCheck` | `NULL` or a version specification (a list with components `op` and `version`).
`quietly` | logical: should progress and error messages be suppressed?
`name` | string or ‘name’, see `as.symbol`, of a package, e.g., `"stats"`.
`...` | further arguments to be passed to `loadNamespace`.

### Details

The functions `loadNamespace` and `attachNamespace` are usually called implicitly when `library` is used to load a name space and any imports needed. However it may be useful at times to call these functions directly.

`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 `library`, whose help page explains the details of how a particular installed package comes to be chosen. After loading, `loadNamespace` looks for a hook function named `.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 ‘Licenses’ in the help for `library`.

`loadNamespace` does not attach the name space it loads to the search path. `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 via `library`). The hook function `.onAttach` is run after the name space exports are attached.

`requireNamespace` is a wrapper for `loadNamespace` analogous to `require` that returns a logical value.

`loadedNamespaces` returns a character vector of the names of the loaded name spaces.

`isNamespaceLoaded(pkg)` is equivalent to but more efficient than `pkg %in% loadedNamespaces()`.

`unloadNamespace` can be used to attempt to force a name space to be unloaded. If the name space is attached, it is first `detach`ed, thereby running a `.onDetach` or `.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 `.onUnload` is run before removing the name space from the internal registry.

See the comments in the help for `detach` about some issues with unloading and reloading name spaces.

### Value

`attachNamespace` returns invisibly the package environment it adds to the search path.

`loadNamespace` returns the name space environment, either one already loaded or the one the function causes to be loaded.

`requireNamespace` returns `TRUE` if it succeeds or `FALSE`.

`loadedNamespaces` returns a `character` vector.

`unloadNamespace` returns `NULL`, invisibly.

### Author(s)

Luke Tierney and R-core

### References

The ‘Writing R Extensions’ manual, section “Package namespaces”.

### See Also

`getNamespace`, `asNamespace`, `topenv`, `.onLoad` (etc); further `environment`.

### Examples

     (lns <- loadedNamespaces())
     statL <- isNamespaceLoaded("stats")
     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)

[Package base version 3.5.1 Index]