Manage report modules

Security: Modules can execute arbitrary R code with the permissions of your R process during testing or report generation. Add and run only modules from sources you trust, and inspect their code, package declarations, network requests and file operations first. Modules are not sandboxed.

Usage

add_Module(x, before, after, test, object, formats, dir)

move_Module(name, before, after, parent, level0, formats, dir)

remove_Module(name, recursive, dir)

restore_Module(name, batch_id, test, dir)

empty_trash(name, id, dir)

list_Modules(tree, brief, include_trash, validate, dir)

Arguments

x

A character string giving the path to a module YAML file to add to the package.

before

An optional character string naming the module before which the new or moved module should be placed. The default is NULL.

after

An optional character string naming the module after which the new or moved module should be placed. The default is NULL.

test

A logical value specifying whether a module is tested before being added or restored. For add_Module(), the default is FALSE when object is not supplied and TRUE when a camReport object is supplied. For restore_Module(), the default is TRUE.

object

An optional camReport object used when testing a module that requires access to report data. The default is NULL.

formats

Output compatibility for the module: "html", "pdf", or "both". For add_Module(), an omitted value is read from an optional formats field in the YAML file and otherwise defaults to "both". For move_Module(), an omitted value retains the current setting.

dir

Path to a writable module registry containing __modulesList.csv. This argument is required for modifying modules. The registry bundled with the package is read-only and cannot be modified directly.

name

A character string naming the module to move, remove, restore, or permanently delete from the trash. For empty_trash(), the default is NULL.

parent

An optional character string naming the parent module. If omitted, the current parent is retained when moving a module.

level0

An optional character vector specifying the top-level module order. The default is c("introduction", "methods", "results", "acknowledgements", "appendix").

recursive

A logical value (default TRUE) specifying whether child modules are removed together with the selected parent module.

batch_id

An optional character string identifying a deleted-module batch to restore. The default is NULL.

id

An optional character string identifying a deleted-module batch to remove permanently from the trash. The default is NULL.

tree

A logical value (default TRUE). If TRUE, modules are returned as a hierarchical tree.

brief

A logical value (default TRUE). If TRUE, a shortened module summary is returned when tree = FALSE.

include_trash

A logical value (default FALSE) specifying whether deleted modules in the trash are also listed.

validate

A logical value (default FALSE) specifying whether module YAML files are checked for validity when listing modules.

Value

list_Modules() returns a data frame, a hierarchical module tree, or a list containing active and trashed modules. The other functions return information about the performed operation invisibly.

Details

Manage report modules in camtrapReport. These functions can be used to list existing modules, add new modules, move modules within the report structure, remove modules, restore deleted modules, and empty the module trash.

camtrapReport uses a modular report architecture in which each report section is stored as a module. A module can contain section metadata, text, executable R code, required packages, and rendering settings.

add_Module() adds a new YAML-defined module to a module registry. The module can optionally be inserted before or after an existing module.

move_Module() changes the position or parent of an existing module within the hierarchical report structure.

remove_Module() moves a module to the module trash. If recursive = TRUE, child modules are also moved to the trash.

restore_Module() restores a previously removed module from the trash.

empty_trash() permanently removes modules from the trash.

list_Modules() lists active modules and can optionally include deleted modules stored in the trash.

Supply dir when changing modules. If it is omitted, the bundled registry is available for reading only. Copy reportSections to a writable project directory first, then pass that copied directory to add_Module() and the other management functions. See the module guide.

YAML modules contain executable R code. Add and run only modules from trusted sources; inspect their code, package declarations, network requests, and file operations before running them. A profile selects modules but does not sandbox their execution.

See also

reportSection(), updateReportSection(), testSection(), report()

Examples

# List modules as a hierarchical tree
module_tree <- list_Modules()
head(module_tree)
#>              ID         name  parent formats level            label
#> introduction  1 introduction   .root    both     0   - introduction
#> methods       2      methods   .root    both     0        - methods
#> study_area    3   study_area methods    both     1     - study_area
#> sampling      4     sampling methods    both     1       - sampling
#> location      5     location methods    both     1       - location
#> location_eow  6 location_eow methods    both     1   - location_eow

# List modules in table form
module_table <- list_Modules(tree = FALSE)
head(module_table)
#>   ID         name  parent formats valid status
#> 1  1 introduction   .root    both  TRUE     ok
#> 2  2      methods   .root    both  TRUE     ok
#> 3  3   study_area methods    both  TRUE     ok
#> 4  4     sampling methods    both  TRUE     ok
#> 5  5     location methods    both  TRUE     ok
#> 6  6 location_eow methods    both  TRUE     ok