box (version 1.0.0)

use: Import a module or package

Description

box::use imports one or more modules and/or packages, and makes them available in the calling environment.

Usage

use(...)

Arguments

...

one or more module import declarations, see ‘Details’ for a description of the format.

Value

box::use has no return value. It is called for its side-effect.

Import semantics

Modules and packages are loaded into dedicated namespace environments. Names from a module or package can be selectively attached to the current scope as shown above.

Unlike with library, attaching happens locally, i.e. in the caller<U+2019>s environment: if box::use is executed in the global environment, the effect is the same. Otherwise, the effect of importing and attaching a module or package is limited to the caller<U+2019>s local scope (its environment()). When used inside a module at module scope, the newly imported module is only available inside the module<U+2019>s scope, not outside it (nor in other modules which might be loaded).

Member access of (non-attached) exported names of modules and packages happens via the $ operator. This operator does not perform partial argument matching, in contrast with the behavior of the $ operator in base R, which matches partial names.

Search path

Modules are searched in the module search path, given by getOption('box.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/b.r exists both in the current directory and in a module search path, the local file ./a/b.r will not be loaded, unless the import is explicitly declared as box::use(./a/b).

The current directory is context-dependent: inside a module, the directory corresponds to the module<U+2019>s directory. Inside an R code file invoked from the command line, it corresponds to the directory containing that file. If the code is running inside a Shiny application or a knitr document, the directory of the execution is used. Otherwise (e.g. in an interactive R session), the current working directory as given by getwd() is used.

Local import declarations (that is, module prefixes that start with . or ..) never use the search path to find the module. Instead, only the current directory is searched.

S3 support

Modules can contain S3 generics and methods. To override known generics (= those defined outside the module), methods inside a module need to be registered using register_S3_method. See the documentation there for details.

Encoding

All module source code files are assumed to be UTF-8 encoded.

Details

box::use(...) specifies a list of one or more import declarations, given as individual arguments to box::use, separated by comma. Each import declaration takes one of the following forms:

prefix/mod:

Import a module given the qualified module name prefix/mod and make it available locally using the name mod. The prefix itself can be a nested name to allow importing specific submodules. Local imports can be specified via the prefixes starting with . and .., to override the search path and use the local path instead. See the ‘Search path’ below for details.

pkg:

Import a package pkg and make it available locally using its own package name.

alias = prefix/mod or alias = pkg:

Import a module or package, and make it available locally using the name alias instead of its regular module or package name.

prefix/mod[attach_list] or pkg[attach_list]:

Import a module or package and attach the exported symbols listed in attach_list locally. This declaration does not make the module/package itself available locally. To override this, provide an alias, that is, use alias = prefix/mod[attach_list] or alias = pkg[attach_list].

The attach_list is a comma-separated list of names, optionally with aliases assigned via alias = name. The list can also contain the special symbol ..., which causes all exported names of the module/package to be imported.

See the vignette in vignette('box', 'box') for detailed examples of usage of the different types of use declarations listed above.

See Also

name and file give information about loaded modules. help displays help for a module<U+2019>s exported names. unload and reload aid during module development by performing dynamic unloading and reloading of modules in a running R session.

Examples

# NOT RUN {
local({
    # Set the module search path for the example module.
    old_opts = options(box.path = system.file(package = 'box'))
    on.exit(options(old_opts))

    # Basic usage
    # The file `box/hello_world.r` exports the functions `world` and `bye`.
    box::use(box/hello_world)
    hello_world$hello('Robert')
    hello_world$bye('Robert')

    # Using an alias
    box::use(world = box/hello_world)
    world$hello('John')

    # Attaching exported names
    box::use(box/hello_world[hello])
    hello('Jenny')
    # Exported but not attached, thus access fails:
    try(bye('Jenny'))

    # Attach everything, give 'world' an alias:
    box::use(box/hello_world[hi = hello, ...])
    hi('Eve')
    bye('Eve')
})
# }