library {base}R Documentation

パッケージの読み込みと一覧

説明

library と require はアドオンパッケージをロードする。 .First.lib はパッケージがロードされる時呼び出される。 .Last.lib はパッケージが切り離されるとき呼び出される。 .packages はパッケージの利用可能性に関する情報を返す。 .path.package はパッケージがどこからロードされたか関する情報を返す。 .find.package はインストールされたパッケージのディレクトリパスを返す。

用法

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

.First.lib(libname, pkgname)
.Last.lib(libpath)

.packages(all.available = FALSE, lib.loc = NULL)
.path.package(package = .packages(), quiet = FALSE)
.find.package(package, lib.loc = NULL, use.attached, quiet = FALSE,
              verbose = getOption("verbose"))
.libPaths(new)

.Library
.Autoloaded

引数

package, help name または文字列でパッケージの名前を与える。
lib.loc 探索すべき R のライブラリツリーの位置を記述する文字ベクトル、もしくは NULL。規定値 NULL は現在知られているすべてのライブラリ。
character.only package もしくは help が文字列であると仮定して良いかどうかを指示する論理値。
logical.return 論理値。もしこれが TRUE なら FALSE または TRUE が成功を指示するために返される。
warn.conflicts 論理値。もし TRUE なら、新しく加えられたパッケージから、それが .conflicts.OK のオブジェクトを含まない限り、 conflicts に関する警告がでる。
keep.source 論理値。もし TRUE なら関数は``ソースを保存''し注釈を含む、 options に対する引数 keep.source を見よ。
verbose 論理値。もし TRUE なら、追加の診断が出力される。
quietly 論理値。もし TRUE なら、パッケージが見つからないと警告が出力される。
libname パッケージが見つかったライブラリディレクトリを与える文字列。
pkgname パッケージの名前を与える文字列。
libpath パッケージの完全なパスを与える文字列。
all.available 論理値；もし TRUE ならば lib.loc 中のすべての利用可能なパッケージの文字ベクトル。
quiet 論理値。 .path.package に対しては、もしパッケージがロードされなかった時これが警告またはエラーを出さないか？ .find.package に対しては、もしパッケージが見つからなかった時これが警告またはエラーを出さないか？
use.attached 論理値で、追加パッケージが与えられたライブラリ中のものに対する追加と考えるべきかどうかを指示する。
new R ライブラリツリーの位置を持つ文字ベクトル。

詳細

library(package) と require(package) はともに package という名前のパッケージをロードする。 require は関数の内部から使うようにデザインされている；もしパッケージが存在しなければ FALSE とオプションでエラーではなくむしろ警告を与える。両関数は現在ロードされているパッケージを検査・更新し、既にロードされているコードはロードしない。

大きなパッケージに対しては、keep.source = FALSE をセットするとメモリーを著しく節約するかもしれない。

もし library が package もしくは help 引数無しで呼び出されると、lib.loc で指定されるライブラリ中のすべての利用可能ライブラリの一覧を与え、クラス "libraryIQR" のオブジェクト中の対応する情報を返す。 このクラスの構造は将来変更されるかもしれない。R のこれまでのバージョンではすべての利用可能なパッケージの名前だけが返される；これらを得るためには .packages(all = TRUE) を使う。

library(help = somename) はパッケージ somename に関する基本的な情報を計算し、これをクラス "packageInfo" のオブジェクトとして返す。 このクラスの構造は将来変更されるかもしれない。

.First.lib はパッケージが library でロードされた時に呼び出される。 これは二つの引数、パッケージが見つかったライブラリディレクトリの名前(つまり対応する lib.loc の要素)とパッケージの名前(この順で)、で呼び出される。 パッケージをこの関数にロードする際必要になる library.dynam に呼び出しを置くために良い場所である。 .First.lib は search() により調べられた検索パスが更新された後に起動され、従って as.environment(match("package:name"), search()) はパッケージが保管されている環境を返す。 もし .First.lib の呼び出しがエラーを与えると、パッケージのロードは中止され、パッケージは利用不可能になる。 同様に、もしオプション ".First.lib" がパッケージの名前をもつリスト要素を持てば、この要素はパッケージがロードされ時の .First.lib と同じ流儀で呼び出される。 この機構はユーザーがパッケージに、パッケージ保守者が提供する起動コードに加えてパッケージの``ロードフック''を設定する事を可能にする。

.Last.lib はパッケージが切り離されるときに呼び出される。 これは .First.lib が失敗したときも呼び出され、従ってそれは注意深く書かれるべきであることを注意しよう。 (これは try の内部から呼び出され、従ってエラーは切り離されたパッケージを停止しない。)

.packages() は現在付加されているパッケージの``基本名''を目に見えないように返し、一方 .packages(all.available = TRUE) はライブラリ位置パス lib.loc で得られるすべてのパッケージを(目に見えるように)与える。

.path.package は指名されたパッケージ、もしどれも指名されていなければすべての現在ロード中のパッケージ、がそこからロードされたパスを返す。 quiet = TRUE でない限り、もし一部の指名パッケージ名がロードされていなければ警告が出され、もしどれも指名されていなければエラーを与える。 この関数はユーザーから呼び出されることを想定しておらず、そのインタフェイスは将来変更される可能性がある。

.find.package は与えられたパッケージを見つけることができる位置へのパスを返す。 もし lib.loc が NULL なら、付加されるパッケージがライブラリよりも先に探索される。 もしパッケージが二回以上見つかれば、最初に見つかった物が使われる。 quiet = TRUE でないかぎり、見つからない指名パッケージについて警告が与えられる。 もし verbose が真なら、複数見つかったパッケージに関する警告が与えられる。 引数 use.attached は廃止された。 この関数はユーザーから呼び出されることを想定しておらず、そのインタフェイスは将来変更される可能性がある。 versions.

.Autoloaded は自動的にロードされることが約束されたパッケージの``基本名''を含む。

.Library は既定のライブラリの位置、R_HOME の `library' サブディレクトリ、を与える文字列である。 .libPaths は R がそれについて知っている(従ってパッケージを探すときに使う)ライブラリツリーを獲得したり、設定したりするのに使われる。 もし引数 new とともに与えると、ライブラリ検索パスは unique(new, .Library) にセットされ、そしてこれが返される。 もし引数がないと、現在知られているライブラリツリーを示す文字ベクトルが返される。 ライブラリ検索パスは起動時に環境変数 R_LIBS 環境変数 R_LIBS (R のライブラリツリーのルートがあるディレクトリのコンマで区切られたリストである必要)から、R_LIBS で指定されたディレクトリとともに .libPaths を呼び出すことにより初期化される。 現在のところ大域的変数 .lib.loc が既知のライブラリツリーへのパスを保管するために使われており、 この変数は直接アクセスすべきではない。

返り値

library はロードされた(または利用可能な)パッケージのリストを返す (または logical.return が TRUE　なら TRUE を返す)。 require は要求されたパッケージが利用可能かどうかを指示する論理値を返す。

著者

R core; .packages　の all.available=TRUE　部分は Guido Masarotto

関連事項

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

例

(.packages())               # 恐らく単に "base"
.packages(all = TRUE)       # 利用可能なすべてを文字列として返す
library()                   # 利用可能なすべてのパッケージを一覧
library(lib = .Library)     # 既定ライブラリ中のすべてのパッケージを一覧
library(help = eda)         # パッケージ `eda'　に関するドキュメント
library(eda)                # パッケージ `eda' をロード
require(eda)                # 同じ事
(.packages())               # "eda"　も
detach("package:eda")

# もしパッケージ名が文字ベクトルにあるなら次を使う
pkg <- "eda"
library(pkg, character.only = TRUE)
detach(pos = match(paste("package", pkg, sep=":"), search()))

.path.package()
.Autoloaded                 # 恐らく "ctest"

.libPaths()                 # R が知っているすべてのライブラリツリー

require(nonexistent)        # FALSE
## もしパッケージが `fooEXT' という名前の共有ライブラリ(ここで `EXT' 
## はシステム固有の拡張子)を使用するなら、次のようにする
.First.lib <- function(lib, pkg) {
  library.dynam("foo", pkg, lib)
}
[Package Contents]
R: Loading and Listing of Packages
library {base}R Documentation

Loading and Listing of Packages

Description

library and require load add-on packages. .First.lib is called when a package is loaded; .Last.lib is called when a package is detached. .packages returns information about package availability. .path.package returns information about where a package was loaded from. .find.package returns the directory paths of installed packages.

Usage

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

.First.lib(libname, pkgname)
.Last.lib(libpath)

.packages(all.available = FALSE, lib.loc = NULL)
.path.package(package = .packages(), quiet = FALSE)
.find.package(package, lib.loc = NULL, use.attached, quiet = FALSE,
              verbose = getOption("verbose"))
.libPaths(new)

.Library
.Autoloaded

Arguments

package, 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, or NULL. The default value of NULL corresponds to all libraries currently known.
character.only a logical indicating whether package 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 .conflicts.OK.
keep.source logical. If TRUE, functions ``keep their source'' including comments, see argument keep.source to options.
verbose a logical. If TRUE, additional diagnostics are printed.
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.
libpath a character string giving the complete path to the package.
all.available logical; if TRUE return a character vector of all available packages in lib.loc.
quiet logical. For .path.package, should this not give warnings or an error if the package(s) are not loaded? For .find.package, should this not give warnings or an error if the package(s) are not found?
use.attached a logical indicating whether attached packages should be considered in addition to the ones installed in the given libraries.
new a character vector with the locations of R library trees.

Details

library(package) and require(package) both load the package with name package. require is designed for use inside other functions; it returns FALSE and optionally 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.

For large packages, setting keep.source = FALSE may save quite a bit of memory.

If library is called with no package or help argument, it lists all available packages in the libraries specified by lib.loc, and returns the corresponding information in an object of class "libraryIQR". The structure of this class may change in future versions. In earlier versions of R, only the names of all available packages were returned; use .packages(all = TRUE) for obtaining these.

library(help = somename) computes basic information about the package somename, and returns this in an object of class "packageInfo". The structure of this class may change in future versions.

.First.lib is called when a package is loaded by library. It is called with two arguments, the name of the library directory 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'' location). .First.lib is invoked after the search path interrogated by search() has been updated, so as.environment(match("package:name"), search()) will return the environment in which the package is stored. If calling .First.lib gives an error the loading of the package is abandoned, and the package will be unavailable. Similarly, if the option ".First.lib" has a list element with the package's name, this element is called in the same manner as .First.lib when the package is loaded. This mechanism allows the user to set package ``load hooks'' in addition to startup code as provided by the package maintainers.

.Last.lib is called when a package is detached. Beware that it might be called if .First.lib has failed, so it should be written defensively. (It is called within try, so errors will not stop the package being detached.)

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

.path.package returns the paths from which the named packages were loaded, or if none were named, for all currently loaded packages. Unless quiet = TRUE it will warn if some of the packages named are not loaded, and given an error if none are. This function is not meant to be called by users, and its interface might change in future versions.

.find.package returns the paths to the locations where the given packages can be found. If lib.loc is NULL, then then attached packages are searched before the libraries. If a package is found more than once, the first match is used. Unless quiet = TRUE a warning will be given about the named packages which are not found, and an error if none are. If verbose is true, warnings about packages found more than once are given. Argument use.attached is deprecated. This function is not meant to be called by users, and its interface might change in future versions.

.Autoloaded contains the ``base names'' of the packages for which autoloading has been promised.

.Library is a character string giving the location of the default library, the `library' subdirectory of R_HOME. .libPaths is used for getting or setting the library trees that R knows about (and hence uses when looking for packages). If called with argument new, the library search path is set to unique(new, .Library) and this is returned. If given no argument, a character vector with the currently known library trees is returned. The library search path is initialized at startup from the environment variable R_LIBS (which should be a colon-separated list of directories at which R library trees are rooted) by calling .libPaths with the directories specified in R_LIBS. Currently, the global variable .lib.loc is used for storing the paths to the known library trees; however, this variable should not be accessed directly.

Value

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.

Author(s)

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

See Also

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

Examples

(.packages())               # maybe just "base"
.packages(all = TRUE)       # return all available as character 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
detach("package:eda")

# if the package name is in a character vector, use
pkg <- "eda"
library(pkg, character.only = TRUE)
detach(pos = match(paste("package", pkg, sep=":"), search()))

.path.package()
.Autoloaded                 # maybe "ctest"

.libPaths()                 # all library trees R knows about

require(nonexistent)        # FALSE
## Suppose a package needs to call a shared library named `fooEXT',
## where `EXT' is the system-specific extension.  Then you should use
.First.lib <- function(lib, pkg) {
  library.dynam("foo", pkg, lib)
}
[Package Contents]