Scoping of modules

We can create a module using the modules::module function. A module is similar to a function definition; it comprises:

• the body of the module
• the environment in which it is created (defined implicitly)
• the environment used for the search path, in most cases baseenv() (defined implicitly)

Similar to a function you may supply arguments to a module; see the vignette on modules as objects on this topic.

To illustrate the very basic functionality of a module, consider the following example:

library("modules")
m <- module({
  foo <- function() "foo"
})
m$foo()

## [1] "foo"

Here m is the collection of objects created inside the module. This is a list with the function foo as only element. We can do the same thing and define a module in a separate file:

module.R

foo <- function() "foo"

main.R

m <- modules::use("module.R")
m$foo()

## [1] "foo"

The two examples illustrate the two ways in which modules can be constructed. Since modules are isolated from the .GlobalEnv the following object x can not be found:

x <- "hey"
m <- module({
  someFunction <- function() x
})
m$someFunction()

## Error in m$someFunction(): object 'x' not found

getSearchPathContent(m)

## List of 4
##  $ modules:root     : chr "someFunction"
##  $ modules:internals: chr [1:10] "attach" "depend" "export" "expose" ...
##  $ base             : chr [1:1268] "!" "!.hexmode" "!.octmode" "!=" ...
##  $ R_EmptyEnv       : chr(0) 
##  - attr(*, "class")= chr [1:2] "SearchPathContent" "list"

Two features of modules are important at this point:

• We can keep the global workspace clean, by introducing a local scope
• We have no direct access to the global environment from modules by default, enforcing discipline when using any form of dependency (objects and packages).

The following subsections explain how to work with these two features.

Imports

If you rely on exported objects of a package you can refer to them explicitly using :::

m <- module({
  functionWithDep <- function(x) stats::median(x)
})
m$functionWithDep(1:10)

## [1] 5.5

Or you can use import for attaching single objects or packages. Import acts as a substitute for library with an important difference: library has the side effect of changing the search path of the complete R session. import only changes the search path of the calling environment, i.e. the side effect is local to the module and does not affect the global state of the R session.

m <- module({
  import("stats", "median") # make median from package stats available

  functionWithDep <- function(x) median(x)
})
m$functionWithDep(1:10)

## [1] 5.5

getSearchPathContent(m)

## List of 5
##  $ modules:root     : chr "functionWithDep"
##  $ modules:stats    : chr "median"
##  $ modules:internals: chr [1:10] "attach" "depend" "export" "expose" ...
##  $ base             : chr [1:1268] "!" "!.hexmode" "!.octmode" "!=" ...
##  $ R_EmptyEnv       : chr(0) 
##  - attr(*, "class")= chr [1:2] "SearchPathContent" "list"

m <- module({
  import("stats")

  functionWithDep <- function(x) median(x)
})
m$functionWithDep(1:10)

## [1] 5.5

Importing modules

To import other modules, the function use can be called. use really just means import module. With use we can load modules:

• defined in the calling environment of the module definition
• or defined in files or folders (see the corresponding vignette on this topic)

Consider the following example:

mm <- module({
  m <- use(m)
  anotherFunction <- function(x) m$functionWithDep(x)
})
mm$anotherFunction(1:10)

## [1] 5.5

To load modules from a file we can refer to the file directly:

module({
  m <- use("someFile.R")
  # ...
})

Exports

Modules can help to isolate code from the state of the global environment. Now we may have reduced the complexity in our global environment and moved it into a module. However, to make it very obvious which parts of a module should be used we can also define exports. Every non-exported object will not be accessible.

Properties of exports are:

• You can list the names of objects in a call to export.
• Exports stack up: you can have multiple calls to export in a module definition, i.e. directly in front of each function you want to export.
• Exports can be defined as regular expressions which is indicated by a leading ‘^’. In this case only one export declaration should be used.

m <- module({
  export("fun")

  fun <- identity # public
  privateFunction <- identity

  # .named are always private
  .privateFunction <- identity
})

m

## fun:
## function(x)