Utilities to write, load and access the R environment used by saveObject for any given object.
getSaveEnvironment()
formatSaveEnvironment()
useSaveEnvironment(use)
registerSaveEnvironment(info = NULL)
loadSaveEnvironment(path)Logical scalar specifying whether to use a save environment during reading/saving of objects.
Named list containing information about the environment used to save each object.
If NULL, this is created by calling formatSaveEnvironment.
String containing the path to a directory representing an object,
same as that used by saveObject and readObject.
getSaveEnvironment returns a named list describing the environment used to save the “current” object (see Details).
The list should have a type field specifying the type of environment, e.g., "R".
For objects created by saveObject, this will typically have the same format as the list returned by formatSaveEnvironment.
Alternatively, NULL is returned if useSaveEnvironment is set to FALSE or no environment information was recorded for the current object.
formatSaveEnvironment returns a named list containing the current R environment, derived from the sessionInfo.
This records the R version, the platform in which R is running, and the versions of all packages as a named list.
If use is not supplied, useSaveEnvironment returns a logical scalar indicating whether to use the save environment information.
If use is supplied, it is used to define the save environment usage policy, and the previous setting of this value is invisibly returned.
registerSaveEnvironment registers the current environment information in memory so that it can be returned by getSaveEnvironment.
It returns a list containing a restore function that should be called on.exit to (i) restore the previous environment information;
and a write function that accepts a path to a directory in which to create an _environment.json file with the environment information.
Both functions are no-ops if useSaveEnvironment is set to FALSE or if a save environment has already been registered.
loadSaveEnvironment loads the environment information from a _environment.json file in path.
It also registers the environment information in memory so that it is returned when getSaveEnvironment is called.
It returns a function that should be called on.exit to restore the previous environment information.
This function is a no-op if useSaveEnvironment is set to FALSE, or if the environment information is not parsable (in which case a warning will be emitted).
When saving an object, saveObject will automatically record some details about the current R environment.
This facilitates trouble-shooting and provides some opportunities for corrective measures if any bugs are found in older saveObject methods.
Information about the save environment is stored in an _environment.json file inside the directory containing the object.
Subdirectories for child objects may also have separate _environment.json files (e.g., if they were created in a different environment),
otherwise it is assumed that they inherit the save environment from the parent object.
Application or extension developers are expected to call getSaveEnvironment from inside a loading function used by readObject or altReadObject.
This wil return the save environment that was used for the “current” object, i.e., the object that was previously saved at path.
By accessing the historical save environment, developers can check if buggy versions of the corresponding saveObject or altSaveObject methods were used.
Appropriate corrective measures can then be applied to recover the correct object, warn users, etc.
getSaveEnvironment can also be called inside saveObject or altSaveObject methods, in which case the current object is the one being saved.
In most cases, registerSaveEnvironment does not need to be explicitly called by end-users or developers.
It is automatically executed by the top-level calls to the saveObject or altSaveObject generics.
Methods can simply call getSaveEnvironment to access the save environment information.
Similarly, loadSaveEnvironment does not usually need to be explicitly called by end-users or developers,
as it is automatically executed by each readObject or altReadObject call.
Individual reader functions can simply call getSaveEnvironment to access the save environment information.
Tracking of the save environment can be disabled by setting useSaveEnvironment(FALSE).
str(formatSaveEnvironment())
#> List of 4
#> $ type : chr "R"
#> $ version : chr "4.5.0"
#> $ platform: chr "x86_64-pc-linux-gnu"
#> $ packages:List of 49
#> ..$ S4Vectors : chr "0.45.4"
#> ..$ BiocGenerics : chr "0.53.6"
#> ..$ generics : chr "0.1.3"
#> ..$ alabaster.base : chr "1.7.7"
#> ..$ jsonlite : chr "1.9.0"
#> ..$ compiler : chr "4.5.0"
#> ..$ BiocManager : chr "1.30.25"
#> ..$ Rcpp : chr "1.0.14"
#> ..$ xml2 : chr "1.3.6"
#> ..$ rhdf5filters : chr "1.19.1"
#> ..$ yaml : chr "2.3.10"
#> ..$ fastmap : chr "1.2.0"
#> ..$ jsonvalidate : chr "1.5.0"
#> ..$ R6 : chr "2.6.0"
#> ..$ curl : chr "6.2.0"
#> ..$ httr2 : chr "1.1.0"
#> ..$ knitr : chr "1.49"
#> ..$ htmlwidgets : chr "1.6.4"
#> ..$ tibble : chr "3.2.1"
#> ..$ desc : chr "1.4.3"
#> ..$ pillar : chr "1.10.1"
#> ..$ rlang : chr "1.1.5"
#> ..$ V8 : chr "6.0.1"
#> ..$ cachem : chr "1.1.0"
#> ..$ xfun : chr "0.50"
#> ..$ fs : chr "1.6.5"
#> ..$ memoise : chr "2.0.1"
#> ..$ cli : chr "3.6.4"
#> ..$ pkgdown : chr "2.1.1"
#> ..$ withr : chr "3.0.2"
#> ..$ magrittr : chr "2.0.3"
#> ..$ Rhdf5lib : chr "1.29.0"
#> ..$ digest : chr "0.6.37"
#> ..$ rstudioapi : chr "0.17.1"
#> ..$ alabaster.schemas: chr "1.7.0"
#> ..$ rappdirs : chr "0.3.3"
#> ..$ rhdf5 : chr "2.51.2"
#> ..$ lifecycle : chr "1.0.4"
#> ..$ vctrs : chr "0.6.5"
#> ..$ downlit : chr "0.4.4"
#> ..$ evaluate : chr "1.0.3"
#> ..$ glue : chr "1.8.0"
#> ..$ whisker : chr "0.4.1"
#> ..$ fansi : chr "1.0.6"
#> ..$ rmarkdown : chr "2.29"
#> ..$ purrr : chr "1.0.4"
#> ..$ tools : chr "4.5.0"
#> ..$ pkgconfig : chr "2.0.3"
#> ..$ htmltools : chr "0.5.8.1"
prev <- useSaveEnvironment(TRUE)
tmp <- tempfile()
dir.create(tmp)
wfun <- registerSaveEnvironment(tmp)
getSaveEnvironment()
#> [1] "/tmp/Rtmp6XG2G9/file2214691acdf"
wfun$restore()
useSaveEnvironment(prev)