cordon: Evaluate Function inside an Environment and Extract and Save...

In priscian/plinth: Provide "Keystone" Functions for Most Scripts or Packages

Evaluate Function inside an Environment and Extract and Save Any Useful Variables from Its Body

Description

Puts a function's body and its arguments into an environment for evaluation, and afterwards allows extraction of any variables from the body, not just a return value.

Usage

cordon(
  fun,
  ...,
  arguments = list(),
  envir = environment(),
  file_path = NULL,
  variables = NULL,
  version = NA,
  version_fmt = "_v%03d",
  copy_args = FALSE,
  timestamp = TRUE,
  timestamp... = list(),
  action = c("run", "save", "load", "skip", "archive"),
  evaluate_dots = TRUE,
  create_path_dir = TRUE,
  verbose = TRUE
)

Arguments

fun	The function to be evaluated.
...	Arguments to be passed into fun.
arguments	A list of additional arguments for passing into fun; can be used e.g. when the formal arguments of fun conflict with those of the current function.
envir	Environment where variables will be copied after fun has been evaluated. For action = "save", also names what variables in the evaluation environment will be save()d to an external file.
file_path	For action = c("save", "load"), the path to the file to which the variables in envir will be written, or from which objects will be extracted to envir. If timestamp = TRUE, the file name provides a base name to which a timestamp is appended.
variables	A character string naming variables among the arguments to, or in the body of, fun that will be extracted from the evaluation environment. If any of the strings are named, those names with carry the variables' values in envir.
copy_args	Logical: Should all named arguments to fun also be extracted from the evaluation environment (and for action = "save", saved)?
timestamp	A logical value deciding whether a current timestamp (default format %Y-%m-%d+[seconds after midnight]) should be appended to the base file name given as part of file_path.
action	A character string denoting the purpose of calling cordon() in the first place: run Evaluate fun and extract variables, but don't load or save them. save Evaluate fun, extract variables, and save them to an external file. load Load saved data from file_path. If timestamp = TRUE, load the most recent version according to the timestamped file name. skip Do nothing, i.e. prevent fun from being evaluated at all. archive Not implemented.

Value

The environment in which the body of fun was evaluated.

Examples

## Not run: 
f <- function(x = "frog", ...) { args <- get_dots(...)$arguments; nines <- args$beast + 333; bite <- args$bite; return (nop()) }
e <- cordon(f, bite = "me", 3.14, beast = 666, TRUE, envir = globalenv(), variables = "nines")
get("nines", envir = globalenv())
e$bite
ls(e, all = TRUE)

## End(Not run)

priscian/plinth documentation built on June 13, 2022, 9:57 a.m.