import_as {tinycodet}

Import R-package, its Re-exports, Dependencies, and/or Extensions, Under a Single Alias

Description

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.

Usage

import_as(
  alias,
  main_package,
  re_exports = TRUE,
  dependencies = NULL,
  extensions = NULL,
  lib.loc = .libPaths(),
  import_order = c("dependencies", "main_package", "extensions")
)

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 or FALSE.

• If re_exports = TRUE the re-exports from the main_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 the dependencies argument.

dependencies

an optional character vector, giving the names of the dependencies of the main_package to be imported also under the alias.
Defaults to NULL, 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 to NULL, 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).
The lib.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.

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 the main_package.
  Unlike the Dependencies 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 is TRUE:
  "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:

1. The dependencies, in the order specified by the depenencies argument.

2. The main_package (see argument main_package), including re-exports (if re_exports = TRUE).

3. 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.

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.")).

See Also

tinycodet_import

Examples

all(c("data.table", "tidytable") %installed in% .libPaths())

import_as( # this creates the 'tdt.' object
  "tdt.", "tidytable", dependencies = "data.table"
)
# same as:
import_as(
  ~ tdt., "tidytable", dependencies = "data.table"
)