There are a number of generics that are exported for other packages to use. These are listed below. They are not intended for use by normal users; rather, they are made available for package developers to build specific methods.
.sortDotsUnderscoreFirst(obj)
.orderDotsUnderscoreFirst(obj)
.tagsByClass(object)
# S4 method for ANY
.tagsByClass(object)
.cacheMessage(
object,
functionName,
fromMemoise = getOption("reproducible.useMemoise", TRUE),
verbose = getOption("reproducible.verbose", 1)
)
# S4 method for ANY
.cacheMessage(
object,
functionName,
fromMemoise = getOption("reproducible.useMemoise", TRUE),
verbose = getOption("reproducible.verbose", 1)
)
.addTagsToOutput(object, outputObjects, FUN, preDigestByClass)
# S4 method for ANY
.addTagsToOutput(object, outputObjects, FUN, preDigestByClass)
.preDigestByClass(object)
# S4 method for ANY
.preDigestByClass(object)
.checkCacheRepo(
object,
create = FALSE,
verbose = getOption("reproducible.verbose", 1)
)
# S4 method for ANY
.checkCacheRepo(
object,
create = FALSE,
verbose = getOption("reproducible.verbose", 1)
)
.prepareOutput(object, cachePath, ...)
# S4 method for ANY
.prepareOutput(object, cachePath, ...)
.addChangedAttr(object, preDigest, origArguments, ...)
# S4 method for ANY
.addChangedAttr(object, preDigest, origArguments, ...)
updateFilenameSlots(obj, curFilenames, newFilenames, isStack = NULL)
# S3 method for default
updateFilenameSlots(obj, curFilenames, newFilenames, isStack = NULL, ...)
# S3 method for list
updateFilenameSlots(obj, ...)
# S3 method for environment
updateFilenameSlots(obj, ...)
makeMemoisable(x)
# S3 method for default
makeMemoisable(x)
# S3 method for data.table
makeMemoisable(x)
unmakeMemoisable(x)
# S3 method for default
unmakeMemoisable(x)An object. This function only has useful methods for Raster*,
with all other classes being simply a pass-through
Any R object returned from a function
A character string indicating the function name
Logical. If TRUE, the message will be about
recovery from memoised copy
Numeric, -1 silent (where possible), 0 being very quiet,
1 showing more messaging, 2 being more messaging, etc.
Default is 1. Above 3 will output much more information about the internals of
Caching, which may help diagnose Caching challenges. Can set globally with an
option, e.g., options('reproducible.verbose' = 0) to reduce to minimal
Optional character vector indicating which objects to return. This is only relevant for list, environment (or similar) objects
A function
A list, usually from .preDigestByClass
Logical. If TRUE, then it will create the path for cache.
A repository used for storing cached objects.
This is optional if Cache is used inside a SpaDES module.
Anything passed to methods.
The full, element by element hash of the input arguments to that same function,
e.g., from .robustDigest
These are the actual arguments (i.e., the values, not the names) that
were the source for preDigest
An optional character vector of filenames currently existing
and that are pointed to in the obj. If omitted, will take from the obj
using Filenames(obj)
An optional character vector of filenames to use instead of
the curFilenames. This can also be a single directory, in which case the
renaming will be given:
file.path(newFilenames, basename(Filenames(obj, allowMultiple = FALSE)))
An object to make memoisable. See individual methods in other packages.
.sortDotsUnderscoreFirst: the same object as obj,
but sorted with dots and underscores first,
lower case before upper case.
.tagsByClass default method returns NULL.
.cacheMessage: nothing; called for its messaging side effect, which,
by default, just edits the name of the function into a generic "loaded cached result"
message.
.addTagsToOutput: The inputted object but with tags attached.
.preDigestByClass: A list with elements that have a difficult time
being digested correctly, e.g., an S4 object with some elements removed and
handled for digesting purposes. The default method for preDigestByClass and
simply returns NULL.
.checkCacheRepo: A character string with a path to a cache repository.
.prepareOutput: The object, modified
.addChangedAttr: the object, with an attribute ".Cache" and sub-element, "changed",
added set to either TRUE or FALSE
updateFilenameSlots: The original object, but with its internal file pointer
updated to the newFilenames
The same object, but with any modifications, especially dealing with saving of environments, which memoising doesn't handle correctly in some cases.
.sortDotsUnderscoreFirst: This exists so Windows, Linux, and Mac machines can have
the same order after a sort. It will put dots and underscores first
(with the sort key based on their second character, see examples.
It also sorts lower case before upper case.
The methods should do as described below.
.tagsByClass should return a character vector, with a single colon (":") dividing
two parts: the tag type and tag value, for the specific class.
.cacheMessage should make a call to message that gives information about
the loaded cached object being returned.
.addTagsToOutput should add one or more attributes to an object, named either
"tags", "call" or "function". It may be wise to do a "deep" copy within this
method, but it may not be necessary.
.addChangedAttr should return the same object, with this a very specific
attribute added: it must be named ".Cache", and have a sub-list element named
"changed", which must be a logical, TRUE or FALSE, to describe whether the object
has changed or not since last attempt to cache it. This is mostly useful when there
are only one or a few sub-elements of e.g., a large list, that are changed. Cache
will be able to only recover the changed parts, to reduce time required to
complete a call to Cache.
updateFilenameSlots: this exists because when copying file-backed rasters, the
usual mechanism of writeRaster can be very slow. This function allows
for a user to optionally create a hard link to the old file, give it a new
name, then update the filename slot(s) in the Raster* class object. This
can be 100s of times faster for large rasters.
makeMemoiseable and unmakeMemoisable methods are run during Cache. The
methods should address any parts that will not successfully work for memoising,
most notably, data.table or other pass-by-reference objects likely need to
be deep copied, so that the memoised version doesn't get changed after being
stashed in the RAM cache (i.e., memoised)
makeMemoiseable and unmakeMemoisable are, by default, just a pass through
for most class. reproducible only has a method for data.table class objects.
items <- c(A = "a", Z = "z", `.D` = ".d", `_C` = "_C")
.sortDotsUnderscoreFirst(items)
#> A Z _C .D
#> "a" "z" "_C" ".d"
# dots & underscore (using 2nd character), then all lower then all upper
items <- c(B = "Upper", b = "lower", A = "a", `.D` = ".d", `_C` = "_C")
.sortDotsUnderscoreFirst(items)
#> A B _C .D b
#> "a" "Upper" "_C" ".d" "lower"
# with a vector
.sortDotsUnderscoreFirst(c(".C", "_B", "A")) # _B is first
#> [1] "A" "_B" ".C"
.tagsByClass(character())
#> NULL
a <- 1
.cacheMessage(a, "mean")
#> loaded cached result from previous mean call (and added a memoised copy)
a <- 1
.preDigestByClass(a) # returns NULL in the simple case here.
#> NULL
a <- normalizePath(file.path(tempdir(), "test"), mustWork = FALSE)
.checkCacheRepo(a, create = TRUE)
a <- 1
.prepareOutput(a) # does nothing
#> [1] 1
b <- "NULL"
.prepareOutput(b) # converts to NULL
#> NULL
if (requireNamespace("terra", quietly = TRUE)) {
r <- terra::rast(terra::ext(0, 10, 0, 10), vals = 1:100)
# write to disk manually -- will be in tempdir()
r <- terra::writeRaster(r, file = tempfile(fileext = ".tif"))
# copy it to the cache repository
r <- .prepareOutput(r, tempdir())
}
a <- 1
.addChangedAttr(a) # does nothing because default method is just a pass through
#> [1] 1