from {import} | R Documentation |
Import Objects From a Package.
Description
The import::from
and import::into
functions provide an
alternative way to import objects (e.g. functions) from packages. It is
sometimes preferred over using library
(or require
) which will
import all objects exported by the package. The benefit over obj <-
pkg::obj
is that the imported objects will (by default) be placed in a
separate entry in the search path (which can be specified), rather in the
global/current environment. Also, it is a more succinct way of importing
several objects. Note that the two functions are symmetric, and usage is a
matter of preference and whether specifying the .into
argument is
desired. The function import::here
imports into the current environment.
Usage
from(
.from,
...,
.into = "imports",
.library = .libPaths()[1L],
.directory = ".",
.all = (length(.except) > 0),
.except = character(),
.chdir = TRUE,
.character_only = FALSE,
.S3 = FALSE
)
here(
.from,
...,
.library = .libPaths()[1L],
.directory = ".",
.all = (length(.except) > 0),
.except = character(),
.chdir = TRUE,
.character_only = FALSE,
.S3 = FALSE
)
into(
.into,
...,
.from,
.library = .libPaths()[1L],
.directory = ".",
.all = (length(.except) > 0),
.except = character(),
.chdir = TRUE,
.character_only = FALSE,
.S3 = FALSE
)
Arguments
Details
The function arguments can be quoted or unquoted as with e.g. library
.
In any case, the character representation is used when unquoted arguments are
provided (and not the value of objects with matching names). The period in
the argument names .into
and .from
are there to avoid name
clash with package objects. However, while importing of hidden objects (those with
names prefixed by a period) is supported, care should be taken not to conflict
with the argument names. The double-colon syntax import::from
allows for imports of exported objects (and lazy data) only. To import
objects that are not exported, use triple-colon syntax, e.g.
import:::from
. The two ways of calling the import
functions
analogue the ::
and :::
operators themselves.
Note that the import
functions usually have the (intended) side-effect
of altering the search path, as they (by default) import objects into the
"imports" search path entry rather than the global environment.
The import
package is not meant to be loaded with library
(and
will output a message about this if attached), but rather it is named to make
the function calls expressive without the need to loading before use, i.e. it is
designed to be used explicitly with the ::
syntax, e.g.
import::from(pkg, x, y)
.
Value
a reference to the environment containing the imported objects.
Packages vs. modules
import
can either be used to import objects either from R packages or
from R
source files. If the .from
parameter ends with '.R' or
'.r', import
will look for a source file to import from. A source file
in this context is referred to as a module
in the documentation.
Package Versions
With import
you can specify package version requirements. To do this
add a requirement in parentheses to the package name (which then needs to
be quoted), e.g import::from("parallel (>= 3.2.0)", ...)
.
You can use the operators <
, >
, <=
, >=
,
==
, !=
. Whitespace in the specification is irrelevant.
See Also
Helpful links:
Examples
import::from(parallel, makeCluster, parLapply)
import::into("imports:parallel", makeCluster, parLapply, .from = parallel)