

library {base}                               R Documentation

_L_o_a_d_i_n_g _a_n_d _L_i_s_t_i_n_g _o_f _P_a_c_k_a_g_e_s

_D_e_s_c_r_i_p_t_i_o_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_s_a_g_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_r_g_u_m_e_n_t_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_e_t_a_i_l_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_a_l_u_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_u_t_h_o_r_(_s_)_:

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

_S_e_e _A_l_s_o_:

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

_E_x_a_m_p_l_e_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)
     }

