Import R-package, its Re-exports, Dependencies, and/or Extensions, Under a Single Alias
Source:R/import_as.R
import_as.Rd
The import_as()
function
imports the namespace of an R-package,
and optionally also its re-exports, dependencies, and extensions,
all under the same alias.
The specified alias,
containing the exported functions from the specified packages,
will be placed in the current environment.
Arguments
- alias
a syntactically valid non-hidden name giving the alias object where the package(s) are to be imported into.
This name can be given either as a single string (i.e."alias."
), or as a one-sided formula with a single term (i.e.~ alias.
).- main_package
a single string, giving the name of the main package to import under the given alias.
Core R (i.e. "base", "stats", etc.) is not allowed.- re_exports
TRUE
orFALSE
.If
re_exports = TRUE
the re-exports from themain_package
(including those exported from Core R) are added to the alias together with the main package.
This is the default, as it is analogous to the behaviour of base R's :: operator.If
re_exports = FALSE
, these re-exports are not added together with the main package.
The user can still import the packages under the alias from which the re-exported functions came from, by specifying them in thedependencies
argument.
- dependencies
an optional character vector, giving the names of the dependencies of the
main_package
to be imported also under the alias.
Defaults toNULL
, which means no dependencies are imported under the alias.
See pkg_get_deps to quickly get dependencies from a package.
Core R (i.e. "base", "stats", etc.) is not allowed.- extensions
an optional character vector, giving the names of the extensions of the
main_package
to be imported also under the alias.
Defaults toNULL
, which means no extensions are imported under the alias.
Core R (i.e. "base", "stats", etc.) is not allowed.- lib.loc
character vector specifying library search path (the location of R library trees to search through).
Thelib.loc
argument would usually be.libPaths()
.
See also loadNamespace.- import_order
the character vector
c("dependencies", "main_package", "extensions")
,
or some re-ordering of this character vector, giving the relative import order of the groups of packages.
See Details section for more information.
Value
A locked environment object, similar to the output of loadNamespace,
with the name as specified in the alias
argument,
will be created.
This object, referred to as the "(package) alias object",
will contain the exported functions from the specified package(s).
The alias object will be placed in the current environment.
To use, for example, function "some_function()" from alias "alias.", use:
alias.$some_function()
To see the special attributes of this alias object, use attr.import.
To "unimport" the package alias object, simply remove it
(i.e. rm(list = "alias.")
).
Details
Expanded Definitions of Some Arguments
"Re-exports" are functions that are defined in the dependencies of the
main_package
, but are re-exported in the namespace of themain_package
.
Unlike theDependencies
argument, functions from core R are included in re-exports."Dependencies" are here defined as any R-package appearing in the "Depends", "Imports", or "LinkingTo" fields of the Description file of the
main_package
. So no recursive dependencies."Extensions" are reverse-dependencies that actually extend the functionality of the
main_package
.
Programmatically, some package "E" is considered an extension of some "main_package", if the following isTRUE
:"main_package" %in%
pkg_get_deps_minimal("E")
Why Aliasing Multiple Packages is Useful
To use an R-package with its extension packages or dependencies,
whilst avoiding the disadvantages of attaching a package (see tinycodet_import),
one would traditionally use the :: operator like so:
main_package::some_function1()
dependency1::some_function2()
extension1::some_function3()
This becomes cumbersome as more packages are needed and/or
as the package name(s) become longer.
The import_as()
function avoids this issue
by allowing multiple related packages to be imported under a single alias,
allowing one to code like this:
import_as(
~ alias., "main_package",
dependencies = "dependency1", extensions = "extension1",
lib.loc = .libPaths()
)
alias.$some_function1()
alias.$some_function2()
alias.$some_function3()
Thus importing a package, or multiple directly related packages, under a single alias,
which import_as()
provides, avoids the above issues.
Importing a package under an alias is referred to as "aliasing" a package.
Alias Naming Recommendation
To keep package alias object names easily distinguishable from other objects
that can also be subset with the $ operator,
I recommend ending (not starting!) all alias names
with a dot (.
) or underscore (_
).
Regarding import_order
The order of the character vector given in
the dependencies
and extensions
arguments matters.
If multiple packages share objects with the same name,
the objects of the package named last will overwrite those of the earlier named packages.
The import_order
argument defaults to the character vector c("dependencies", "main_package", "extensions")
,
which is the recommended setting.
This setting results in the following importing order:
The dependencies, in the order specified by the
depenencies
argument.The main_package (see argument
main_package
), including re-exports (ifre_exports = TRUE
).The extensions, in the order specified by the
extensions
argument.
Other Details
Packages that appear in the "Suggests" or "Enhances" fields of packages
are not considered dependencies or extensions.
No more than 10 packages
(ignoring re-exports)
are allowed to be imported under a single alias.
Examples
all(c("data.table", "tidytable") %installed in% .libPaths())
#> [1] TRUE
import_as( # this creates the 'tdt.' object
"tdt.", "tidytable", dependencies = "data.table"
)
#> Importing packages and registering methods...
#> Done
#> You can now access the functions using `tdt.$`
#> For conflicts report, packages order, and other attributes, run `attr.import(tdt.)`
# same as:
import_as(
~ tdt., "tidytable", dependencies = "data.table"
)
#> Importing packages and registering methods...
#> Done
#> You can now access the functions using `tdt.$`
#> For conflicts report, packages order, and other attributes, run `attr.import(tdt.)`