Use module
to define self contained organisational units. Modules have
their own search path. import can be used to import packages.
use can be used to import other modules. Use export to define
which objects to export. expose can be used to reuse function
definitions from another module.
module(expr = {
}, topEncl = autoTopEncl(envir), envir = parent.frame())autoTopEncl(where)
an expression
(environment) the root of the local search path. It is tried to find a good default via autoTopEncl.
(environment) the environment from where module
is
called. Used to determine the top level environment and should not be
supplied by the use.
topEncl
is the environment where the search of the module ends.
autoTopEncl
handles the different situations. In general it defaults
to the base environment or the environment from which module
has
been called. If you are using use
or expose
referring to a
module in a file, it will always be the base environment. When
identical(topenv(parent.frame()), globalenv())
is false it (most
likely) means that the module is part of a package. In that case the module
defines a sub unit within a package but has access to the packages
namespace. This is relevant when you use the function module explicitly.
When you define a nested module the search path connects to the environment
of the enclosing module.
The use of library, attach, and source are discouraged
within modules. They change the global state of an R session, the
.GlobalEnv, and may not have the intended effect within modules.
import and use can replace calls to library and
attach. Both will work when called in the .GlobalEnv
but here they should only be used for development and debugging of modules.
source often is used to load additional user code into a session.
This is what use is designed to do within modules. use will
except files and folders to be used.
export will never export a function with a leading "." in its name.
expose is similar to use but instead of attaching a module it will copy all elements into the calling environment. This means that exposed functions can be (re-)exported.
extend can be used to extend an existing module definition. This feature is meant to be used by the module author. This can be very useful to write unit tests when they need to have access to private member functions of the module. It is not safe as a user of a module to use this feature: it breaks encapsulation. When you are looking for mechanisms for reuse expose and use should be favoured.
if (FALSE) {
vignette("modulesInR", "modules")
}
m <- module({
fun <- function(x) x
})
m$fun(1)
m <- module({
import("stats", "median")
export("fun")
fun <- function(x) {
## This is an identity function
## x (ANY)
x
}
})
m$fun
m
Run the code above in your browser using DataLab