mod::ule
The mod
package is a lightweight module system; It provides a simple
way to structure program and data into modules for programming and
interactive use, without the formalities of R packages.
Why?
This is a good question.
As units for code organization in R, packages are very robust. However, they are formal and compliated; they require additional knowledge to R and must be installed in the local library. Scripts, as widely understood, are simplistic and brittle, unsuitable for building tools and may conflict with each other.
Situated between packages and scripts, modules feature characteristics that are somewhat similar to those from other languages. They can be defined either inline with other codes or in a standalone file, and can be used in the user’s working environment, packages, or other modules.
Let’s see.
Installation
Install the development version from GitHub with:
devtools::install_github("iqis/mod")
Use
The mod
package is designed to be used either attached or unattached
to your working environment.
If you wish to attach the package:
require(mod)
#> Loading required package: mod
#>
#> Attaching package: 'mod'
#> The following object is masked from 'package:base':
#>
#> drop
Vocabulary
- Make a module:
- Inline:
module()
/mod::ule()
- From a file:
acquire()
- Inline:
- The search path:
- Attach a module to:
use()
- Detach a module from:
drop()
- Attach a module to:
- Inside a module:
- Declare public variables within the module:
provide()
- Attach a package locally:
require()
- Import variables from another module:
refer()
- Declare public variables within the module:
Examples
Define an inline module:
my <- module({
a <- 1
b <- 2
f <- function(x, y) x + y
})
The resulting module contains the variables defined within.
ls(my)
#> [1] "a" "b" "f"
Subset the module.
my$a
#> [1] 1
my$b
#> [1] 2
my$f(my$a, my$b)
#> [1] 3
Use the with()
to spare qualification.
with(my,
f(a,b))
#> [1] 3
Attach a Module to the Search Path
Just like a package, a module can be attached to the search path.
use(my)
The my
module is attached to the search path as “module:my”, before
other attached packages.
search()
#> [1] ".GlobalEnv" "module:my" "package:mod"
#> [4] "package:stats" "package:graphics" "package:grDevices"
#> [7] "package:utils" "package:datasets" "package:methods"
#> [10] "Autoloads" "package:base"
And you can use the variables inside directly, just like those from a package.
f(a,b)
#> [1] 3
Detach the module from the search path when done, if desired.
drop("my")
Make Variables Available to another Module
Use refer()
to “import” variables from another module.
ls(my)
#> [1] "a" "b" "f"
my_other<- module({
refer(my)
c <- 4
d <- 5
})
ls(my_other)
#> [1] "a" "b" "c" "d" "f"
Use a package
The mod::require()
makes packages available for use in a module.
mpg_analysis <- module({
require(ggplot2)
plot <- qplot(mtcars$mpg)
})
#> Registered S3 methods overwritten by 'ggplot2':
#> method from
#> [.quosures rlang
#> c.quosures rlang
#> print.quosures rlang
mpg_analysis$plot
#> `stat_bin()` using `bins = 30`. Pick better value with `binwidth`.
Meanwhile, your working environment’s search path remain unaffected:
search()
#> [1] ".GlobalEnv" "package:mod" "package:stats"
#> [4] "package:graphics" "package:grDevices" "package:utils"
#> [7] "package:datasets" "package:methods" "Autoloads"
#> [10] "package:base"
"package:ggplot2" %in% search()
#> [1] FALSE
Private Variables
A variable is private if its name starts with ..
.
room_101 <- module({
..diary <- "Dear Diary: I used SPSS today..."
get_diary <- function(){
..diary
}
})
A private variable cannot be seen or touched. There is no way to access
the ..diary
from the outside, except by a function defined within the
module. This can be useful if you want to shield some information from
the user or other programs.
ls(room_101)
#> [1] "get_diary"
room_101$..diary
#> NULL
room_101$get_diary()
#> [1] "Dear Diary: I used SPSS today..."
Another way is using provide()
function to declair public variables,
while all others become private.
room_102 <- module({
provide(open_info, get_classified)
open_info <- "I am a data scientist."
classified_info <- "I can't get the database driver to work."
get_classified <- function(){
classified_info
}
})
ls(room_102)
#> [1] "get_classified" "open_info"
room_102$open_info
#> [1] "I am a data scientist."
room_102$classified_info
#> NULL
room_102$get_classified()
#> [1] "I can't get the database driver to work."
Simlate OOP
The below example simulates one essential behavior of an object in
Object-oriented Programming by manipulating the state of ..count
.
counter <- module({
..count <- 0
add_one <- function(){
#Its necessary to use `<<-` operator, as ..count lives in the parent frame.
..count <<- ..count + 1
}
reset <- function(){
..count <<- 0
}
get_count <- function(){
..count
}
})
A variable must be private to be mutable like ..count
.
The following demonstration should be self-explanatory:
counter$get_count()
#> [1] 0
counter$add_one()
counter$add_one()
counter$get_count()
#> [1] 2
counter$reset()
counter$get_count()
#> [1] 0
It is imperative that mod
be only adopted in the simplest cases. If
full-featured OOP is desired, use
R6
.
Notes
Environment
A module is an environment. This means that every rule that applies to environments, such as copy-by-reference, applies to modules as well.
mode(my)
#> [1] "environment"
is.environment(my)
#> [1] TRUE
Terms
Some may wonder the choice of terms. Why refer()
and provide()
?
Further, why not import()
and export()
? This is because we feel
import()
and export()
are used too commonly, in both R, and other
popular languages with varying meanings. The reticulate
package also
uses import()
. To avoid confusion, we decided to introduce some
synonyms. With analogous semantics,
refer()
is borrowed from
Clojure, while
provide()
from Racket; Both languages are R’s close relatives.
Locked
If a module is locked, it is impossible to either change the value of a variable or add a new variable to a module. A private variable’s value can only be changed by a function defined within the module, as shown previously.
my$a <- 1
#> Error in my$a <- 1: cannot change value of locked binding for 'a'
my$new_var <- 1
#> Error in my$new_var <- 1: cannot add bindings to a locked environment
Hidden Variables
As a general R rule, names that start with .
define hidden variables.
my_yet_another <- module({
.var <- "I'm hidden!"
})
Hidden variables are not returned by ls()
, unless specified.
ls(my_yet_another)
#> character(0)
ls(my_yet_another, all.names = TRUE)
#> [1] ".var"
Nonetheless, in a module, they are treated the same as public variables.
my_yet_another$.var
#> [1] "I'm hidden!"
Load/Attach from File
module_path <- system.file("misc/example_module.R", package = "mod")
To load and assign to variable:
example_module <- acquire(module_path)
ls(example_module)
#> [1] "a" "d" "e"
example_module$a
#> [1] 1
example_module$d()
#> [1] 6
example_module$e(100)
#> [1] 106
To load and attach to search path:
use(module_path)
ls("module:example_module")
#> [1] "a" "d" "e"
a
#> [1] 1
d()
#> [1] 6
e(100)
#> [1] 106
Modules and Packages
It could be confusing how modules and packages live together. To clarify:
- Attach a Package
- Everywhere:
require()
- Everywhere:
- Attach a Module
- To another module: not available
- To the global search path:
use()
- Copy Variables from a Module
- To another module:
refer()
- To the working directory: not available
- To another module:
- Use Modules inside a Package
- Yes, the package must
Depends
onmod
package
- Yes, the package must
Unattached
As aforementioned, the package is designed to be usable both attached and unattached.
If you use the package unattached, you must always qualify the variable
name with ::
, such as mod::ule()
, a shorthand for mod::module()
.
However, while inside a module, the mod
package is always available,
so you do not need to use ::
. Note that in the following example,
provide()
inside the module expression is unqualified.
See:
detach("package:mod")
my_mind <- mod::ule({
provide(good_thought)
good_thought <- "I love working on this package!"
bad_thought <- "I worry that no one will appreciate it."
})
mod::use(my_mind)
good_thought
#> [1] "I love working on this package!"