| library | R Documentation |
library andrequire load and attach add-on packages.
library(package, help, pos = 2, lib.loc = NULL, character.only = FALSE, logical.return = FALSE, warn.conflicts, quietly = FALSE, verbose = getOption("verbose"), mask.ok, exclude, include.only, attach.required = missing(include.only))require(package, lib.loc = NULL, quietly = FALSE, warn.conflicts, character.only = FALSE, mask.ok, exclude, include.only, attach.required = missing(include.only))conflictRules(pkg, mask.ok = NULL, exclude = NULL)package, help | the name of a package, given as a name orliteral character string, or a character string, depending onwhether |
pos | the position on the search list at which to attach theloaded namespace. Can also be the name of a position on the currentsearch list as given by |
lib.loc | a character vector describing the location ofRlibrary trees to search through, or |
character.only | a logical indicating whether |
logical.return | logical. If it is |
warn.conflicts | logical. If |
verbose | a logical. If |
quietly | a logical. If |
pkg | character string naming a package. |
mask.ok | character vector of names of objects that can maskobjects on the search path without signaling an error when strictconflict checking is enabled |
exclude,include.only | character vector of names of objects toexclude or include in the attached frame. Only one of these argumentsmay be used in a call to |
attach.required | logical specifying whether required packageslisted in the |
library(package) andrequire(package) both load thenamespace of the package with namepackage and attach it on thesearch list.require is designed for use inside otherfunctions; it returnsFALSE and gives a warning (rather than anerror aslibrary() does by default) if the package does notexist. Both functions check and update the list of currently attachedpackages and do not reload a namespace which is already loaded. (Ifyou want to reload such a package, calldetach(unload = TRUE) orunloadNamespace first.) If you want to load apackage without attaching it on the search list, seerequireNamespace.
To suppress messages during the loading of packages usesuppressPackageStartupMessages: this will suppress allmessages fromR itself but not necessarily all those from packageauthors.
Iflibrary is called with nopackage orhelpargument, it lists all available packages in the libraries specifiedbylib.loc, and returns the corresponding information in anobject of class"libraryIQR". (The structure of this class maychange in future versions.) Use.packages(all = TRUE) toobtain just the names of all available packages, andinstalled.packages() for even more information.
library(help = somename) computes basic information about thepackagesomename, and returns this in an object of class"packageInfo". (The structure of this class may change infuture versions.) When used with the default value (NULL) forlib.loc, the attached packages are searched before the libraries.
Normallylibrary returns (invisibly) the list of attachedpackages, butTRUE orFALSE iflogical.return isTRUE. When called aslibrary() it returns an object ofclass"libraryIQR", and forlibrary(help=), one ofclass"packageInfo".
require returns (invisibly) a logical indicating whether the requiredpackage is available.
Handling of conflicts depends on the setting of theconflicts.policy option. If this option is not set, thenconflicts result in warning messages if the argumentwarn.conflicts isTRUE. If the option is set to thecharacter string"strict", then all unresolved conflicts signalerrors. Conflicts can be resolved using themask.ok,exclude, andinclude.only arguments tolibrary andrequire. Defaults formask.ok andexclude can bespecified usingconflictRules.
If theconflicts.policy option is set to the string"depends.ok" then conflicts resulting from attaching declareddependencies will not produce errors, but other conflicts will.This is likely to be the best setting for most users wanting someadditional protection against unexpected conflicts.
The policy can be tuned further by specifying theconflicts.policy option as a named list with the followingfields:
error:logical; ifTRUE treat unresolvedconflicts as errors.
warn:logical; unlessFALSE issue a warningmessage when conflicts are found.
generics.ok:logical; ifTRUE ignore conflictscreated by defining S4 generics for functions on the search path.
depends.ok:logical; ifTRUE do not treatconflicts with required packages as errors.
can.mask:character vector of names of packages thatare allowed to be masked. These would typically be base packagesattached by default.
Some packages have restrictive licenses, and there is a mechanism toallow users to be aware of such licenses. IfgetOption("checkPackageLicense") == TRUE, then at firstuse of a package with a not-known-to-be-FOSS (see below) license theuser is asked to view and accept the license: a list of acceptedlicenses is stored in file ‘~/.R/licensed’. In a non-interactivesession it is an error to use such a package whose license has notalready been recorded as accepted.
As fromR 3.4.0 the license check is done when the namespace is loaded.
Free or Open Source Software (FOSS,e.g.https://en.wikipedia.org/wiki/FOSS) packages aredetermined by the same filters used byavailable.packages but applied to just the currentpackage, not its dependencies.
There can also be a site-wide file ‘R_HOME/etc/licensed.site’ ofpackages (one per line).
library takes some further actions when packagemethodsis attached (as it is by default). Packages may define formal genericfunctions as well as re-defining functions in other packages (notablybase) to be generic, and this information is cached wheneversuch a namespace is loaded aftermethods and re-defined functions(implicit generics) are excluded from the list of conflicts.The caching and check for conflicts require looking for a pattern ofobjects; the search may be avoided by defining an object.noGenerics (with any value) in the namespace. Naturally, if thepackagedoes have any such methods, this will prevent them frombeing used.
library andrequire can only load/attach aninstalled package, and this is detected by having a‘DESCRIPTION’ file containing aBuilt: field.
Under Unix-alikes, the code checks that the package was installedunder a similar operating system as given byR.version$platform(the canonical name of the platform under which R was compiled),provided it contains compiled code. Packages which do not containcompiled code can be shared between Unix-alikes, but not to other OSesbecause of potential problems with line endings and OS-specific helpfiles. If sub-architectures are used, the OS similarity is notchecked since the OS used to build may differ(e.g.i386-pc-linux-gnu code can be built on anx86_64-unknown-linux-gnu OS).
The package name given tolibrary andrequire must matchthe name given in the package's ‘DESCRIPTION’ file exactly, evenon case-insensitive file systems such as are common on Windows andmacOS.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)The New S Language.Wadsworth & Brooks/Cole.
.libPaths,.packages.
attach,detach,search,objects,autoload,requireNamespace,library.dynam,data,install.packages andinstalled.packages;INSTALL,REMOVE.
The initial set of packages attached is set byoptions(defaultPackages=): see alsoStartup.
library() # list all available packageslibrary(lib.loc = .Library) # list all packages in the default librarylibrary(help = splines) # documentation on package 'splines'library(splines) # attach package 'splines'require(splines) # the samesearch() # "splines", toodetach("package:splines")# if the package name is in a character vector, usepkg <- "splines"library(pkg, character.only = TRUE)detach(pos = match(paste("package", pkg, sep = ":"), search()))require(pkg, character.only = TRUE)detach(pos = match(paste("package", pkg, sep = ":"), search()))require(nonexistent) # FALSE## Not run: ## if you want to mask as little as possible, uselibrary(mypkg, pos = "package:base")## End(Not run)Add the following code to your website.
For more information on customizing the embed code, readEmbedding Snippets.
