modules (version 0.9.11)

import_: Import a module into the current scope

Description

module = import('module') imports a specified module and makes its code available via the environment-like object it returns.

Usage

import_(module, attach, attach_operators = TRUE, doc)
import(module, attach, attach_operators = TRUE, doc)
import_package_(package, attach, attach_operators = TRUE)
import_package(package, attach, attach_operators = TRUE)

Arguments

module

a character string specifying the full module path

attach

either a boolean or a character vector. If TRUE, attach the newly loaded module to the object search path (see Details). Alternatively, if a character vector is given, attach only the listed names.

attach_operators

if TRUE, attach operators of module to the object search path, even if attach is FALSE

doc

boolean specifying whether to load the module<U+2019>s documentation (see Details)

package

a character string specifying the package name

Value

the loaded module environment (invisible)

Details

Modules are loaded in an isolated environment which is returned, and optionally attached to the object search path of the current scope (if argument attach is TRUE). attach defaults to FALSE. However, in interactive code it is often helpful to attach packages by default. Therefore, in interactive code invoked directly from the terminal only (i.e. not within modules), attach defaults to the value of options('import.attach'), which can be set to TRUE or FALSE depending on the user<U+2019>s preference.

attach_operators causes operators to be attached by default, because operators can only be invoked in R if they re found in the search path. Not attaching them therefore drastically limits a module<U+2019>s usefulness.

doc loads the module<U+2019>s documentation, specified as roxygen comments. It defaults to TRUE in interactive mode and to FALSE otherwise.

Modules are searched in the module search path options('import.path'). This is a vector of paths to consider, from the highest to the lowest priority. The current directory is always considered last. That is, if a file a.r exists both in the current directory and in a module search path, the local file ./a.r will not be loaded, unless the import is explicitly specified as import('./a').

Module names can be fully qualified to refer to nested paths. See Examples.

Module source code files are assumed to be encoded in UTF-8 without BOM. Ensure that this is the case when using an extended character set.

pkg = import_package('pkg') imports a package and treats it much as if it were a module, making package contents available in the pkg variable.

See Also

unload

reload

module_name

module_help

Examples

# NOT RUN {
# `a.r` is a file in the local directory containing a function `f`.
a = import('a')
a$f()

# b/c.r is a file in path `b`, containing functions `f` and `g`.
import('b/c', attach = 'f')
# No module name qualification necessary
f()
g() # Error: could not find function "g"

import('b/c', attach = TRUE)
f()
g()
# }
# NOT RUN {
dplyr = import_package('dplyr')
# Not attached, so we cannot do:
#cars = tbl_df(cars)
# Instead, this works:
cars = dplyr$tbl_df(cars)
# But this invokes the correct `print` method for class `tbl_df`:
print(cars)
# }