Manage report modules

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.

Usage

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

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

remove_Module(name, recursive)

restore_Module(name, batch_id, test)

empty_trash(name, id)

list_Modules(tree, brief, include_trash, validate)

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.

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

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.

Because modules can execute arbitrary R code with the permissions of the current R process, only install modules from trusted sources and inspect their contents before running them.

add_Module() adds a new YAML-defined module to the package module directory. 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.

See also

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

Examples

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

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