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.
from(
.from,
...,
.into = "imports",
.library = .libPaths(),
.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
)
a reference to the environment containing the imported objects.
The package from which to import.
Names or name-value pairs specifying objects to import. If arguments are named, then the imported object will have this new name.
The environment into which the imported objects should be
assigned. If the value is of mode character
, it is treated as referring
to a named environment on the search path. If it is of mode environment
,
the objects are assigned directly to that environment. Using
.into=environment()
causes imports to be made into the current
environment; .into=""
is an equivalent shorthand value.
character specifying the library to use when importing from
packages. Defaults to the current set of library paths (note that the
default value was different in versions up to and including 1.3.0
).
character specifying the directory to use when importing
from modules. Defaults to the current working directory. If .from is a
module specified using an absolute path (i.e. starting with /
), this
parameter is ignored.
logical specifying whether all available objects in a package or module should be imported. It defaults to FALSE unless .exclude is being used to omit particular functions.
character vector specifying any objects that should not be
imported. Any values specified here override both values provided in ...
and objects included because of the .all
parameter
logical specifying whether to change directories before sourcing a module (this parameter is ignored for libraries)
A logical indicating whether .from
and ...
can be
assumed to be character strings. (Note that this parameter does not apply
to how the .into
parameter is handled).
A logical indicating whether an
automatic detection and registration of S3 methods should be performed. The
S3 methods are assumed to be in the standard form generic.class
. Methods
can also be registered manually instead using be registered manually
instead using the .S3method(generic, class, method)
call. This is an
experimental feature. We think it should work well and you are encouraged
to use it and report back – but the syntax and semantics may change in the
future to improve the feature.
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.
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.
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)
.
import::from(parallel, makeCluster, parLapply)
import::into("imports:parallel", makeCluster, parLapply, .from = parallel)
Run the code above in your browser using DataLab