| Title: | Lightweight and Self-Contained Modules for Code Organization |
|---|---|
| Description: | Creates modules inline or from a file. Modules can contain any R object and be nested. Each module have their own scope and package "search path" that does not interfere with one another or the user's working environment. |
| Authors: | Siqi Zhang [aut, cre] |
| Maintainer: | Siqi Zhang <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.4.9000 |
| Built: | 2024-11-01 11:17:06 UTC |
| Source: | https://github.com/iqis/mod |
Use a Package as if a Module
as_module(package)as_module(package)
package |
name of a package; character |
a module that contains a package's exported objects
tcltk <- as_module("tcltk") ls(tcltk) tcltk$is.tclObj(NULL)tcltk <- as_module("tcltk") ls(tcltk) tcltk$is.tclObj(NULL)
If no argument is supplied, detach the most recently attached module.
drop(name)drop(name)
name |
name of the module to exit from; character |
TRUE if successful; invisible
use(mod::ule({ a <- 1 }), as = "my_module") use(mod::ule({ b <- 2 }), as = "my_other_module") search() # by name drop("my_module") # and at the head position drop() search()use(mod::ule({ a <- 1 }), as = "my_module") use(mod::ule({ b <- 2 }), as = "my_other_module") search() # by name drop("my_module") # and at the head position drop() search()
Test if an Object is a Module
is_module(x)is_module(x)
x |
An object |
TRUE if the object is a module, FALSE otherwise
Institute a module object inline or from a file. mod::ule() is a useful shorthand for module() when this package is not attached.
module(expr, parent = parent.frame(), lock = TRUE) ule(expr, parent = parent.frame(), lock = TRUE) acquire(path, parent = baseenv(), lock = TRUE)module(expr, parent = parent.frame(), lock = TRUE) ule(expr, parent = parent.frame(), lock = TRUE) acquire(path, parent = baseenv(), lock = TRUE)
expr |
module expression |
parent |
the enclosing environment |
lock |
lock the environment; logical |
path |
path to a module file |
Only use lock = FALSE for runtime debugging. It is otherwise necessary to keep the module locked.
an environment of class module containing defined objects
# from file module_path <- system.file("misc", "example_module.R", package = "mod") example_module <- acquire(module_path) example_module$e(123) # inline my_module <- mod::ule({ a <- 1 .a <- 2 f <- function(){.a} }) my_module$a my_module$f# from file module_path <- system.file("misc", "example_module.R", package = "mod") example_module <- acquire(module_path) example_module$e(123) # inline my_module <- mod::ule({ a <- 1 .a <- 2 f <- function(){.a} }) my_module$a my_module$f
Name a Module
name(name)name(name)
name |
the name of the module; character |
the input
Other declaratives: provide,
refer, require
mod::ule({ name("my") # ... })mod::ule({ name("my") # ... })
Print a Module
## S3 method for class 'module' print(x, ...)## S3 method for class 'module' print(x, ...)
x |
an object |
... |
dot-dot-dot, ignored |
the object itself; invisible
Extract the Private Environment of a Module
private(module)private(module)
module |
a module |
environment
m <- mod::ule({a <- 1}) pvt <- private(m) ls(pvt, all.names = TRUE)m <- mod::ule({a <- 1}) pvt <- private(m) ls(pvt, all.names = TRUE)
Can only be used inside a module expression. If this function is used, only the names included as argument are public. If not used, every name in the module will be public.
provide(...)provide(...)
... |
name of any object to be accessible by user; name or character |
NULL; invisible
Other declaratives: name,
refer, require
mod_a <- mod::ule({ # names included in provide() are public, however... mod:::provide(var,.var, ..var) # It is suggested to omit mod::: when using var <- 1 .var <- 2 ..var <- 3 # objects denoted by .. prefix are always private. another_var <- 4 # objects not included in provide() are also private. }) mod_b <- mod::ule({ # if no call to provide(), all objects are public, except... var <- 1 .var <- 2 ..var <- 3 # objects denoted by .. prefix are always private. }) ls(mod_a) ls(mod_b)mod_a <- mod::ule({ # names included in provide() are public, however... mod:::provide(var,.var, ..var) # It is suggested to omit mod::: when using var <- 1 .var <- 2 ..var <- 3 # objects denoted by .. prefix are always private. another_var <- 4 # objects not included in provide() are also private. }) mod_b <- mod::ule({ # if no call to provide(), all objects are public, except... var <- 1 .var <- 2 ..var <- 3 # objects denoted by .. prefix are always private. }) ls(mod_a) ls(mod_b)
Can only be used inside a module expression. Makes reference to objects from one module, with specified filters.
refer(..., include = c(), exclude = c(), prefix = "", sep = ".")refer(..., include = c(), exclude = c(), prefix = "", sep = ".")
... |
names of modules; dot-dot-dot |
include |
names to include; character |
exclude |
names to excludde; character |
prefix |
prefix to names; character |
sep |
separator between prefix and names; character |
NULL; invisible
Other declaratives: name,
provide, require
mod_a <- mod::ule(number <- 1) mod_b <- mod::ule(number <- 2) mod_c <- mod::ule({ mod:::refer(mod_a, mod_b, prefix = .) # It is suggested to omit mod::: when using number <- mod_a.number + mod_b.number }) mod_c$numbermod_a <- mod::ule(number <- 1) mod_b <- mod::ule(number <- 2) mod_c <- mod::ule({ mod:::refer(mod_a, mod_b, prefix = .) # It is suggested to omit mod::: when using number <- mod_a.number + mod_b.number }) mod_c$number
Can only be used in a module expression. Emulates the effect of base::require() in its containing module, making functions and their chain of environment available. Will not automatically attach dependencies of the package, and the user must do it separately. Masks base::require() inside a module context. Unlike base::require(), gives an error when package is not installed.
require(package)require(package)
package |
name of the package; name or character |
NULL; invisible
Other declaratives: name,
provide, refer
mod_tcl <- mod::ule({ mod:::require(tcltk) # It is suggested to omit mod::: when using f <- tcl }) identical(mod_tcl$f, tcltk::tcl)mod_tcl <- mod::ule({ mod:::require(tcltk) # It is suggested to omit mod::: when using f <- tcl }) identical(mod_tcl$f, tcltk::tcl)
If the module as a name, defined by name(), it will always be used for the search path.
use(module, as, parent = baseenv(), lock = TRUE)use(module, as, parent = baseenv(), lock = TRUE)
module |
a module object, or path to a module file |
as |
name when attached to search; character |
parent |
the enclosing environment |
lock |
lock the environment; logical |
TRUE if successful; invisible
module_path <- system.file("misc", "example_module.R", package = "mod") example_module <- acquire(module_path) # Attach module object to search path use(example_module) # or directly from file use(module_path, "example_module")module_path <- system.file("misc", "example_module.R", package = "mod") example_module <- acquire(module_path) # Attach module object to search path use(example_module) # or directly from file use(module_path, "example_module")