save R object to a central location

Usage

save_object(
  object_list,
  save_date = jamba::getDate(),
  objects_path = jamsession_paths()$objects,
  object_notes_list = "",
  do_file_info = FALSE,
  object_suffix = ".RData",
  envir = globalenv(),
  verbose = TRUE,
  ...
)

Arguments

object_list: character vector with one or more R object names to save. The typical workflow stores only one object per file. We recommend storing multiple objects into one file only when those objects are only useful together, and using only one object would be insufficient or lack enough context for full re-use.
save_date: character date string to use when naming the file. By default, the current date is used via the function jamba::getDate(), however to use a custom date format any text string can be used here.
objects_path: character vector of one or more file paths to search for saved R objects. When objects_path=NULL, it uses the output from jamsession_paths()$objects. The process will try to save the .RData file in each path in objects_path in order, and will use the first successful attempt. For example if two paths are supplied, and the first path is not accessible or not user-writeable, the second path will be attempted. If no paths are user-writeable, this function will stop().
object_notes_list: character vector or list of character vectors that contain optional notes associated with the R object(s). This mechanism is intended as a crude way to store text information associated with the stored R objects. For example, one could store a short text description of how to R objects were created, or some other useful information. This process is currently experimental, and may be refactored in future to have a more consistent workflow.
do_file_info: logical indicating whether to print information about the saved .RData file, which includes the stored file size and path.
object_suffix: character string used as the file extension, by default ".RData". This value should probably never change, but it is possible to change here.
envir: the environment from which to obtain the R object.
verbose: logical indicating whether to print verbose output.
...: additional arguments are ignored.

Value

character string with the file path where the R object data is stored.

Details

This function saves a single R object to an .RData file, versioned by date using jamba::getDate(), so it can be discovered and re-used by other R sessions.

When multiple objects should be saved together, the recommended method:

create a list object that includes these objects
save this list object using save_object()

However, when multiple objects are supplied in object_list, the object names are concatenated with "-" and this string is used to define the saved R object file. For example save_object(c("df1", "df2")) will save an R object file using the string "df1-df2". When this file is loaded, two R objects are loaded into the environment: "df1" and "df2". While not always ideal, this mechanism may be more convenient, and it is left for the user to decide which is best.

Note that objects_path may contain multiple directories, and when this occurs, the directories are attempted in order. The R object is saved to the first directory that allows the file to be saved successfully.

Examples

if (FALSE) { # interactive()
withr::with_options(list(jam.objects_path=tempdir()), {

example_df <- data.frame(name=LETTERS[1:5], values=letters[1:5])
save_object("example_df")
grep_objects("example")

list_objects()

})
}