

   library {base}                               R Documentation

   LLooaaddiinngg aanndd LLiissttiinngg ooff PPaacckkaaggeess

   DDeessccrriippttiioonn::

        `library(name)' and `require(name)' both load the pack-
        age named `name'.  `provide' allows code to register
        services that it provides.

        `.First.lib()' is called when a package is loaded by
        `library()'.  `.packages()' and the `.xxx' variables
        return information about package availability.

   UUssaaggee::

        library(name, help = NULL, lib.loc = .lib.loc,
             character.only = FALSE, logical.return = FALSE,
             warn.conflicts = TRUE)
        require(name, quietly = FALSE, warn.conflicts = TRUE)
        provide(name)

        .First.lib(libname, pkgname)

        .packages(all.available = FALSE, lib.loc = .lib.loc)
        .lib.loc
        .Library
        .Provided
        .Autoloaded

   AArrgguummeennttss::

   name, help: `name' or character string giving the name of a
             package.

    lib.loc: a character vector describing the location of R
             library trees to search through.

   character.only: a logical indicating whether `name' or
             `help' can be assumed to be character strings.

   logical.return: logical.  If it is `TRUE',  `FALSE' or
             `TRUE' is returned to indicate success.

   warn.conflicts: logical.  If `TRUE', warnings are printed
             about `conflicts' from attaching the new package,
             unless that package contains an object `.con-
             flicts.OK'.

    quietly: a logical.  If `TRUE', a warning will not be
             printed if the package cannot be found.

    libname: a character string giving the library directory
             where the package was found.

    pkgname: a character string giving the name of the package.

   all.available: logical; if `TRUE' return `character' vector
             of all available packages in `lib.loc'.

   DDeettaaiillss::

        `library(name)' and `require(name)' both load the pack-
        age with name `name'.  `require' is designed for use
        inside other functions; it returns `FALSE' and option-
        ally gives a warning, rather than giving an error, if
        the package does not exist.  Both functions check and
        update the list of currently loaded packages and do not
        reload code that is already loaded.  `require' also
        checks the list `.Provided'.

        `provide' allows code to register services that it pro-
        vides.  The argument is stored in the list `.Provided'.
        `provide' returns `FALSE' if the name was already pre-
        sent in `.Provided' or among the packages in
        `search()'.  The main use for `provide' is when multi-
        ple packages share code. This is most likely when the
        code implements features present in S(-PLUS) but not in
        R. For example, the spline functions `ns', `bs' and so
        on are not included in the R distribution.  A package
        containing these functions can use `provide(splines)'
        to register this fact.  Another package that needs the
        functions can execute `require(splines)' rather than
        `library(splines)' to load the spline package only if
        their functionality is not already available.

        If `library' is called with no `name' or `help' argu-
        ment, it gives a list of all available packages in
        `lib.loc' and invisibly returns their names (same as
        `.packages(all=T)').

        `library(help = name)' prints information on the pack-
        age `name', typically by listing the most important
        user level objects it contains.

        `.First.lib()' is called when a package is loaded by
        `library(.)'.  It is called with two arguments, the
        name of the library tree where the package was found
        (i.e., the corresponding element of `lib.loc'), and the
        name of the package (in that order).  It is a good
        place to put calls to `library.dynam()' which are
        needed when loading a package into this function (don't
        call `library.dynam()' directly, as this will not work
        if the package is not installed in a ``standard'' loca-
        tion).  `.First.lib()' is invoked after `search()' has
        been updated, so `pos.to.env(match("package:name"),
        search())' will return the environment in which the
        package is stored.

        `.packages()' returns the ``base names'' of the cur-
        rently attached packages invisibly whereas `.pack-
        ages(all.available =TRUE)' gives (visibly) all packages
        available in the library location path `lib.loc'.

        `.Autoloaded' contains the ``base names'' of the pack-
        ages for which autoloading has been promised.

        `.Library' is a character string giving the location of
        the default library, the ``library'' subdirectory of
        `R_HOME'.  `.lib.loc' is a character vector with the
        locations of all library trees that R should use.  It
        is initialized at startup from the environment variable
        `R_LIBS' (`RLIBS' as used by older versions of R is no
        longer accepted) (which should be a colon-separated
        list of directories at which R library trees are
        rooted) followed by `.Library'.

   VVaalluuee::

        `library' returns the list of loaded (or available)
        packages (or `TRUE' if `logical.return' is `TRUE').
        `require' returns a logical indicating whether the
        required package is available.

   AAuutthhoorr((ss))::

        R core;  Guido Masarotto for the `all.available=TRUE'
        part of `.packages'.

   SSeeee AAllssoo::

        `attach', `detach', `search', `objects', `autoload',
        `library.dynam', `data', `install.packages'.
        `INSTALL', `REMOVE'

   EExxaammpplleess::

        .packages()             # maybe just "base"
        .packages(all = TRUE)       # return all available as char.vector
        library()          # list all available packages
        library(lib = .Library)      # list all packages in the default library
        library(help = eda)     # documentation on package "eda"
        library(eda)            # load package "eda"
        require(eda)            # the same
        .packages()                 # "eda", too
        require(nonexistent)         # FALSE
        ## Suppose the a package needs to call a shared library named "foo.EXT",
        ## where "EXT" is the system-specific extension.  Then you should use
        .First.lib <- function(lib, pkg) {
          library.dynam("foo", pkg, lib)
        }

