export extractFromCache() + cleanup CacheHelpers docs

with #389

DESCRIPTION

@@ -20,7 +20,7 @@ URL:
     https://reproducible.predictiveecology.org,
     https://github.com/PredictiveEcology/reproducible
 Date: 2024-05-16
-Version: 2.0.12.9012
+Version: 2.0.12.9013
 Authors@R: 
     c(person(given = "Eliot J B",
              family = "McIntire",

NAMESPACE

@@ -73,6 +73,7 @@ export(cropInputs)
 export(cropTo)
 export(dataType2)
 export(downloadFile)
+export(extractFromCache)
 export(fastMask)
 export(fixErrors)
 export(fixErrorsIn)

R/DBI.R

@@ -1,21 +1,28 @@
-#' Functions to create and work with a cache
+#' Low-level functions to create and work with a cache
+#'
+#' **These are intended for advanced use only.**
 #'
 #' @param cachePath A path describing the directory in which to create
 #'   the database file(s)
+#'
 #' @inheritParams Cache
+#'
 #' @param drv A driver, passed to `dbConnect`
+#'
 #' @param force Logical. Should it create a cache in the `cachePath`,
 #'   even if it already exists, overwriting.
-#' @importFrom data.table data.table
-#' @rdname CacheHelpers
+#'
 #' @details
-#' `createCache` function will create a Cache folder structure and necessary files, based on
-#' the particular `drv` or `conn` provided.
+#' - `createCache()` will create a Cache folder structure and necessary files, based on
+#' the particular `drv` or `conn` provided;
 #'
 #' @return
-#' `createCache` does not return a value; it is called for side effects.
+#' - `createCache()` returns `NULL` (invisibly) and intended to be called for side effects;
 #'
 #' @export
+#' @importFrom data.table data.table
+#' @rdname CacheHelpers
+#'
 #' @examples
 #' data.table::setDTthreads(2)
 #' newCache <- tempdir2()
@@ -47,8 +54,11 @@ createCache <- function(cachePath = getOption("reproducible.cachePath"),
   if (useDBI()) {
     .createCache(cachePath = cachePath, drv = drv, conn = conn)
   }
+
+  invisible(NULL)
 }
 
+#' @keywords internal
 .createCache <- function(cachePath, drv, conn) {
   if (is.null(conn)) {
     conn <- dbConnectAll(drv, cachePath = cachePath)
@@ -77,16 +87,20 @@ createCache <- function(cachePath = getOption("reproducible.cachePath"),
 
 #' Save an object to Cache
 #'
-#' This is not expected to be used by a user as it requires that the `cacheId`
-#' be calculated in exactly the same as it calculated inside `Cache` (which requires
-#' `match.call` to match arguments with their names, among other things).
+#' This is not expected to be used by a user as it requires that the `cacheId` be
+#' calculated in exactly the same as it calculated inside `Cache`
+#' (which requires `match.call` to match arguments with their names, among other things).
 #'
 #' @inheritParams Cache
+#'
 #' @param cacheId The hash string representing the result of `.robustDigest`
+#'
 #' @param obj The R object to save to the cache
+#'
 #' @param linkToCacheId Optional. If a `cacheId` is provided here, then a `file.link`
 #'   will be made to the file with that `cacheId` name in the cache repo.
 #'   This is used when identical outputs exist in the cache. This will save disk space.
+#'
 #' @return
 #' This is used for its side effects, namely, it will add the object to the cache and
 #' cache database.
@@ -187,19 +201,25 @@ saveToCache <- function(cachePath = getOption("reproducible.cachePath"),
   return(obj)
 }
 
-#' @export
-#' @rdname CacheHelpers
 #' @inheritParams CacheStoredFile
+#'
 #' @param fullCacheTableForObj The result of `showCache`, but subsetted for only
 #'   the `cacheId` being loaded or selected
+#'
 #' @param .dotsFromCache Optional. Used internally.
+#'
 #' @param .functionName Optional. Used for messaging when this function is called from `Cache`
+#'
 #' @param preDigest The list of `preDigest` that comes from `CacheDigest` of an object
+#'
 #' @details
-#' `loadFromCache` is a function to get a single object from the cache, given its `cacheId`.
+#' - `loadFromCache()` retrieves a single object from the cache, given its `cacheId`;
+#'
 #' @return
-#' `loadFromCache` returns the object from the cache that has the particular `cacheId`.
+#' - `loadFromCache()` returns the object from the cache that has the particular `cacheId`;
 #'
+#' @export
+#' @rdname CacheHelpers
 loadFromCache <- function(cachePath = getOption("reproducible.cachePath"),
                           cacheId, preDigest,
                           fullCacheTableForObj = NULL,
@@ -317,6 +337,20 @@ loadFromCache <- function(cachePath = getOption("reproducible.cachePath"),
   obj
 }
 
+#' @param sc a cache tags `data.table` object
+#' @param elem character string specifying a `tagKey` value to match
+#' @param ifNot character (or NULL) specifying the return value to use if `elem` not matched
+#'
+#' @details
+#' - `extractFromCache()` retrieves a single `tagValue` from the cache based on
+#' the `tagKey` of `elem`;
+#'
+#' @return
+#' - `extractFromCache()` returns the `tagValue` from the cache corresponding to `elem` if found,
+#' otherwise the value of `ifNot`;
+#'
+#' @export
+#' @rdname CacheHelpers
 extractFromCache <- function(sc, elem, ifNot = NULL) {
   rowNum <- sc[["tagKey"]] %in% elem
   elemExtracted <- if (any(rowNum)) {
@@ -327,16 +361,15 @@ extractFromCache <- function(sc, elem, ifNot = NULL) {
   elemExtracted
 }
 
-#' Low level tools to work with Cache
-#'
-#' @export
-#' @rdname CacheHelpers
 #' @details
-#' `rmFromCache` removes one or more items from the cache, and updates the cache
+#' - `rmFromCache()` removes one or more items from the cache, and updates the cache
 #' database files.
 #'
 #' @return
-#' `rmFromCache` has no return value; it is called for its side effects.
+#' - `rmFromCache()` returns `NULL` (invisibly) and is intended to be called for side effects;
+#'
+#' @export
+#' @rdname CacheHelpers
 rmFromCache <- function(cachePath = getOption("reproducible.cachePath"),
                         cacheId, drv = getDrv(getOption("reproducible.drv", NULL)),
                         conn = getOption("reproducible.conn", NULL),
@@ -523,21 +556,20 @@ dbConnectAll <- function(drv = getDrv(getOption("reproducible.drv", NULL)),
   "tagValue"
 }
 
-#' A collection of low level tools for Cache
-#'
-#' These are not intended for normal use.
-#'
 #' @inheritParams Cache
+#'
 #' @inheritParams createCache
-#' @rdname CacheHelpers
-#' @export
+#'
 #' @return
-#' `CacheDBFile` returns the name of the database file for a given Cache,
-#' when `useDBI() == FALSE`, or `NULL` if `TRUE`.
-#' `CacheDBFiles` (i.e,. plural) returns the name of all the database files for
-#' a given Cache when `useDBI() == TRUE`, or `NULL` if `FALSE`
-#' @details
-#' `CacheStoredFile` returns the file path to the file with the specified hash value.
+#' - `CacheDBFile()` returns the name of the database file for a given Cache,
+#' when `useDBI() == FALSE`, or `NULL` if `TRUE`;
+#' - `CacheDBFiles()` (i.e,. plural) returns the name of all the database files for
+#' a given Cache when `useDBI() == TRUE`, or `NULL` if `FALSE`;
+#' - `CacheStoredFile()` returns the file path to the file with the specified hash value,
+#' This can be loaded to memory with e.g., `loadFile()`.;
+#'
+#' @export
+#' @rdname CacheHelpers
 #'
 #' @examples
 #' data.table::setDTthreads(2)
@@ -581,29 +613,29 @@ CacheDBFile <- function(cachePath = getOption("reproducible.cachePath"),
   }
 }
 
-#' @rdname CacheHelpers
-#' @export
 #' @return
-#' `CacheStorageDir` returns the name of the directory where cached objects are
-#' stored.
+#' - `CacheStorageDir()` returns the name of the directory where cached objects are stored;
+#'
+#' @export
+#' @rdname CacheHelpers
 CacheStorageDir <- function(cachePath = getOption("reproducible.cachePath")) {
   file.path(cachePath, "cacheOutputs")
 }
 
-#' @details
-#' `CacheStoredFile` returns the file path to the file with the specified hash value.
-#'
-#' @rdname CacheHelpers
 #' @param obj The optional object that is of interest; it may have an attribute "saveRawFile"
 #'   that would be important.
-#' @export
+#'
 #' @param cacheId The cacheId or otherwise digested hash value, as character string.
+#'
 #' @param format The text string representing the file extension used normally by
 #'   different save formats; currently only `"rds"` or `"qs"`. Defaults
 #'   to `getOption("reproducible.cacheSaveFormat", "rds")`
+#'
 #' @return
-#' `CacheStoredFile` returns the name of the file in which the cacheId object is stored.
-#' This can be loaded to memory with e.g., `loadFile`.
+#' - `CacheStoredFile` returns the file path to the file with the specified hash value;
+#'
+#' @export
+#' @rdname CacheHelpers
 CacheStoredFile <- function(cachePath = getOption("reproducible.cachePath"), cacheId,
                             format = NULL, obj = NULL) {
   if (is.null(format)) format <- getOption("reproducible.cacheSaveFormat", "rds")
@@ -636,11 +668,12 @@ CacheStoredFile <- function(cachePath = getOption("reproducible.cachePath"), cac
   file.path(CacheStorageDir(cachePath), c(filename, fns))
 }
 
-#' @rdname CacheHelpers
-#' @export
 #' @return
-#' `CacheDBTableName` returns the name of the table inside the SQL database, if that
-#' is being used.
+#' - `CacheDBTableName()` returns the name of the table inside the SQL database, if that
+#' is being used;
+#'
+#' @export
+#' @rdname CacheHelpers
 CacheDBTableName <- function(cachePath = getOption("reproducible.cachePath"),
                              drv = getDrv(getOption("reproducible.drv", NULL))) {
   if (!is(cachePath, "Path")) {
@@ -665,16 +698,15 @@ CacheDBTableName <- function(cachePath = getOption("reproducible.cachePath"),
   return(newPath)
 }
 
-#' @rdname CacheHelpers
-#' @param create Logical. Currently only affects non RQSLite default drivers. If this
-#'   is `TRUE` and there is no Cache database, the function will create one.
-#' @export
+#' @param create Logical. Currently only affects non \pkg{RSQLite} default drivers.
+#'        If `TRUE` and there is no Cache database, the function will create one.
+#'
 #' @return
-#' `CacheIsACache` returns a logical indicating whether the `cachePath` is currently
-#' a `reproducible` cache database.
-#' @details
-#' `CacheIsACache` returns a logical of whether the specified `cachePath`
-#'   is actually a functioning cache.
+#' - `CacheIsACache()` returns a logical indicating whether the `cachePath` is currently
+#' a `reproducible` cache database;
+#'
+#' @export
+#' @rdname CacheHelpers
 CacheIsACache <- function(cachePath = getOption("reproducible.cachePath"), create = FALSE,
                           drv = getDrv(getOption("reproducible.drv", NULL)),
                           conn = getOption("reproducible.conn", NULL)) {
@@ -690,7 +722,7 @@ CacheIsACache <- function(cachePath = getOption("reproducible.cachePath"), creat
   ret <- all(basename2(c(CacheDBFile(cachePath, drv, conn), CacheStorageDir(cachePath))) %in%
     list.files(cachePath))
 
-  # Need to check even if ret is TRUE because we may be in the process of changing
+  ## Need to check even if ret is TRUE because we may be in the process of changing
   convertDBbackendIfIncorrect(cachePath, drv, conn)
 
   needCreate <- FALSE

R/exportedMethods.R

@@ -647,7 +647,7 @@ setMethod(
 #' Remap file names
 #'
 #' Update file path metadata for file-backed objects (e.g., `SpatRasters`).
-#' Useful when moving saved objects between porjects or machines.
+#' Useful when moving saved objects between projects or machines.
 #'
 #' @param obj (optional) object whose file path metadata will be remapped
 #' @param tags cache tags `data.table` object