Load or refresh R file functions as a temporary package

refresh_functions(
  session,
  pkg_name = NULL,
  functions_path = jamsession_paths()$functions,
  fn_pattern = "_functions.R$",
  define_defaults = FALSE,
  pkg_suffix = "",
  use_tempdir = base::tempdir(),
  verbose = TRUE,
  ...
)

Arguments

session	`character` vector of one or more function files to load. Note than when multiple functions are loaded, they are combined into the same temporary package.
pkg_name	`NULL` or `character` string indicating the name to use for the temporary package. By default it uses the first `session`, and if there are multiple `session` files then it appends the number of files as a suffix.
functions_path	character vector of one or more file paths to search for saved R functions. When `NULL`, it uses the output from `jamsession_paths()$functions`. When `session` matches multiple files, then the most recently modified file is used, as defined by `jamba::newestFile()`.
fn_pattern	`character` pattern appended to `session` to match compatible R files. The default format is `"session_functions.R"` and so default `fn_pattern="_functions.R"`.
define_defaults	`logical` indicating whether to define `options("usethis.description")` using jamsession default values. If `getOption("usethis.description")` is not defined, then default values are used regardless. Otherwise, the values from `getOption("usethis.description")` are only modified when `default_defaults=TRUE`. As the R package is only temporary, these defaults have little actual impact. Just be sure to edit the DESCRIPTION file if you intend to use the R package long term.
pkg_suffix	`NULL` or `character` string used as a suffix, appended to the end of the temporary package name. The `pkg_suffix` or `pkg_name` are useful to avoid name conflicts with proper R packages. For example `"igraph_functions.R"` should be not be loaded as `"igraph"` or else it will conflict with the actual `"igraph"` R package.
use_tempdir	`character` path, or function which returns a valid file path suitable to create a subdirectory for this temporary R package. By default `base::tempdir()` returns a single temporary directory for each R session, note that this directory may be deleted when the R session is ended.
verbose	`logical` indicating whether to print verbose output.
...	additional arguments are ignored.

Details

This function loads an R file that contains custom R functions, as if that R file were part of a temporary R package.

It assumes the R file or files contain only valid R functions, which are optionally documented using the roxygen2 style described in the roxygen2 package.

This mechanism of loading R functions is an improvement over using base::source() or base::sys.source() in these ways:

Help documents for each function will be prepared, if they were defined using roxygen2 format for each function.
R functions are loaded into a namespace, separate from the .GlobalEnv workspace. When saving the R session itself, the custom functions will not be included, because they are not part of the workspace.
When the custom R functions are updated, repeat the call to this function and it will replace the namespace with the newer namespace.
The package is included in sessionInfo() which helps indicate that custom functions were also included.

Aside: It really is fast and easy to create a new R package, however it makes sense that small one-off projects do not justify creating a whole new R package for only one or two custom R functions. However, the temporary R package created by this function can be used to create an actual R package, by copying the temporary folder, or by supplying a specific folder with the argument use_tempdir.

To find the temporary R package folder:

system.file(package=pkg_name)

Ideally you should also use version control like Git, subversion, CVS, or a similar system. But for one-off projects, this mechanism is a good start -- and we think it will become a gateway to creating proper R packages as needed.

Note that this function refresh_functions() does not validate the .R file, nor does it check whether the R file is valid to be part of an R package. However, because refresh_functions() also calls roxygen2::roxygenize(), it inherits a lot of validation from that process and will display error messages as relevant. At this point, those error messages are intended to be a good thing because they make syntax errors visible.

Note that this function does not itself remove the temporary R package directory, it assumes that when use_tempdir is defined by base::tempdir(), see that function help for more information. Note that on some linux systems, temporary files not accessed for more than 7 days may be deleted automatically.

Examples

# create two temporary functions
tempfn <- function(x){x}
another_tempfn <- function(x){length(x)}

# save these functions to a temporary file
# tempfns_functions.R
tempfn_file <- file.path(tempdir(), "tempfns_functions.R");
dump(c("tempfn", "another_tempfn"), file=tempfn_file);

# remove the functions from the environment
rm(tempfn);
rm(another_tempfn);

# load the functions
refresh_functions("tempfns", functions_path=tempdir())
#> ##  (11:51:45) 26Feb2021:  refresh_functions(): Loaded temporary package as 'tempfns' 

# the tempfn() function is now inside a package
find("tempfn")
#> [1] "package:tempfns"
#> package:tempfns

# the function can be called
tempfn(c("one", "two"))
#> [1] "one" "two"
#> [1] "one" "two"