library
Load and List Packages

Description

Attaches a package or lists packages. A package is a way of packaging a collection of functions, data sets, documentation, and compiled code.

Usage

library(package, help, pos = 2, lib.loc = NULL,
    character.only = FALSE, logical.return = FALSE,
    warn.conflicts = TRUE, quietly = FALSE,
    keep.source = getOption("keep.source.pkgs"),
    verbose = getOption("verbose"))

require(package, lib.loc = NULL, quietly = FALSE,
    warn.conflicts = TRUE,
    keep.source = getOption("keep.source.pkgs"),
    character.only = FALSE)

# the following are for package writers only
.onLoad(lib.loc, package)
.onAttach(lib.loc, package)
.onUnload(packagePath)

Arguments

package a character string or name giving the name of the package. The package must be a valid package. If omitted, The engine returns a help message describing the libraries in lib.loc. (See Value for more information.)
help a character string or name of a package for which help is sought. In most cases, this string gives a list of objects in the package, along with brief descriptions. After you attach a package, you can use thehelp function directly to see documentation on particular objects.
pos an integer or a string. The position in the search list the package should occupy. The packages originally in position pos or above are moved down the list. Alternatively, the position can be given as the name in the search list, such as "package:base". The new package is inserted at the position of the specified package, and the package is moved down the list.
lib.loc a character vector containing the names of library directories in which to search for package. If lib.loc is NULL, .libPaths() is used. It is not used when searching for packages listed in the "Depends:" section of packageDescription(package) but it is temporary added to the front of the list returned by .libPaths() while searching for packages listed in the "Imports:" section.
character.only a logical value. If FALSE (the default), library(package) (without quotes) is equivalent to library("package"). If TRUE, package is expected to be the name of a variable containing a character string. (This also applies to the help argument.)
logical.return a logical value.
  • If TRUE, and if package is specified or no argument is specified, it returns a logical value indicating whether the package was successfully attached. No error messages are displayed (if any).
  • If FALSE (the default), and if the package loading was successful, it returns the list of loaded packages. Any resulting error messages are displayed.
  • If help is specified and package is not specified, this argument is not used.
warn.conflicts a logical value. If TRUE (the default), it displays a warning if the objects or functions in the package mask any of the packages already loaded. If FALSE, no check is performed.
quietly a logical value. If TRUE, no message is displayed to say a required package is being loaded. The default is FALSE: such a message will be printed.
keep.source a logical value indicating if source code including comments are kept. Used by loadNamespace and sys.source functions.
verbose a logical value. If it is TRUE, it displays warnings under the following conditions:
  • If the package is already exists.
  • If package does not contain R code.

Details

Value
libraryreturns the following:
  • If package is specified, it returns (invisibly) a character vector containing loaded packages.
  • If help is specified, it returns (invisibly) the information for the specified package of class packageInfo.
  • If no argument is specified, it returns the information about the list of available packages (in a list of class libraryIQR, which is printed nicely by print.libraryIQR).
  • If logical.return is TRUE, it returns TRUE or FALSE.
requirereturns (invisibly) a logical value to indicate whether the required package is available.
Side Effects
The package is loaded and attached to the search list.
Loading a package also loads (and attaches) the packages listed as required by the package in the Depends section of the DESCRIPTION file. Packages listed in the import and importFrom clauses in the NAMESPACE file are loaded using loadNamepace, and are not attached to the search list.
If a package is loaded, its .onLoad function is called (if it exists) when the namespace is loaded, and its .onAttach function is called (if it exists) when the package is attached to the search list. Both of those functions are passed two character arguments, the path of the of package library and the name of the package.
When a package's namespace is unloaded with detach("package:PackageName", unload=TRUE), its .onUnload function is called (if it exists). Its one argument is the path to the package's directory.
See Also
attach, detach, system.file, .libPaths
Examples
## Not run: 
if(require(somePackage, quietly=TRUE)) {
   somePackage::functionInSomePackage()
} else {
   message("'somePackage' is not available, will work around it absence")
}
library()

## End(Not run)
Package base version 6.1.1-7
Package Index