R: Load an Rcpp Module into a Package

loadModule {Rcpp} | R Documentation

## Load an Rcpp Module into a Package

### Description

One or more calls to `loadModule` will be included in the source code for a package to load modules and optionally expose objects from them. The actual extraction of the module takes place at load time.

### Usage

    loadModule(module, what = , loadNow, env =)

### Arguments

`module` | The name of the C++ module to load. The code for the module should be in the same package as the R call to `loadModule`.
`what` | The objects to expose in the package's namespace corresponding to objects in the module. By default, nothing is exposed. The special value `TRUE` says to load all the objects in the module that have syntactically standard R names (which all objects in a module will normally have). Otherwise, if supplied this should be a character vector, the elements being objects defined in the module. The vector can have a names attribute, in which case the non-empty names will be used to rename the objects; otherwise, the name of the object in the package namespace will be the same as the name in the C++ module.
`loadNow, env` | A logical flag to say whether the load actions should happen now, and the environment into which the objects should be inserted. When called from the source of a package, both of these arguments should usually be omitted. The value of `loadNow` will be set by checking the module's status. At package installation time, the module cannot be started, in which case a load action (see `setLoadAction`) is scheduled to do the actual module load. The value of `env` will default to the package's namespace.

### Details

If the purpose of loading the module is to define classes based on C++ classes, see `setRcppClass()`, which does the necessary module loading for you.

When the module can be started (at namespace load time), the function `Module()` returns an environment with a description of the module's contents. Function `loadModule()` saves this as a metadata object in the package namespace. Therefore multiple calls to `loadModule()` are an efficient way to extract different objects from the module.

Requesting an object that does not exist in the module produces a warning.

Since assignments from the call cannot take place until namespace loading time, any computations using the objects must also be postponed until this time. Use load actions (`setLoadAction`) and make sure that the load action is specified after the call to `loadModule()`.

### Value

If the load takes place, the module environment is returned. Usually however the function is called for its side effects.

### Note

This function requires version 2.15.0 of R or later, in order to use load actions, introduced in that version. See the note in the help page for `setRcppClass()` for details.

### Author(s)

John Chambers

### See Also

`setRcppClass()` to avoid the explicit call.

`loadRcppModules()` for a (deprecated) shotgun procedure to load all modules.

### Examples

    ## Not run:
    loadModule("yada", TRUE) # load all the objects from module "yada"

    ## End(Not run)

[Package Rcpp version 1.0.2 Index]