load R object by name

Usage

load_object(
  object,
  save_date = NULL,
  objects_path = jamsession_paths()$objects,
  envir = globalenv(),
  verbose = TRUE,
  ...
)

Arguments

object: character string indicating the name of the R object to load, or data.frame output from grep_objects() which contains colnames ("object", "object_path", "object_file").
save_date: optional character string with a specific date to use when loading an object. This string is matched with the "save_date" returned by list_objects(). When save_date is NULL, the most recent object is loaded, which is the default behavior.
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.
envir: optional R environment inside which to load the R object. Note that if an R object already exists in this environment, it will overwritten without warning. This behavior is intended by load_object().
verbose: logical whether to print verbose output
...: additional arguments are ignored.

Value

invisible name of the R object loaded. It also loads the R object into the environment specified, by default the active global environment .GlobalEnv.

Details

This function loads the most recently saved R object by name, from a given file path. This mechanism is intended to help share useful R objects across R sessions, especially where it may be helpful to discover R objects by name, and where R objects may continue to be useful over time.

Typically this function is called with the name of one or more saved objects, and loads the most recent version of each. However, the argument save_date can be supplied as a vector, which is recycled for each saved object, as a method to load a specific version of an object. This behavior is not intended for routine use, but is available in rare cases that you may want to inspect previous versions of an object.

Note that envir can be used to load the object into a separate environment, if needed.

Examples

if (FALSE) { # interactive()

withr::with_options(list(jam.objects_path=tempdir()), {

my_df <- data.frame(col1=LETTERS[1:5], col2=letters[1:5]);
print(my_df);

save_object("my_df", verbose=FALSE);

print(grep_objects("my_df"))

rm(my_df);

load_object("my_df", verbose=FALSE);
print(my_df);

load_object(grep_objects("my_df"), verbose=FALSE)
print(my_df);
})

######################################
# Load into a separate environment
rm(my_df);
sep_env <- new.env();

withr::with_options(list(jam.objects_path=tempdir()), {

load_object("my_df", envir=sep_env, verbose=FALSE)

# this object is not in the current workspace
print(find("sep_env"))

# you can use get() to see this object
print(get("my_df", envir=sep_env));

})

######################################
# example showing two objects stored together
withr::with_options(list(jam.objects_path=tempdir()), {
my_df2 <- data.frame(B=LETTERS[11:15], b=letters[11:15]);

load_object("my_df", verbose=FALSE);
save_object(c("my_df", "my_df2"), verbose=FALSE);

print(grep_objects("my_df2"))
loaded <- load_object(grep_objects("my_df2"), verbose=FALSE);

# note that it loads two objects
print(loaded);
})
}