From f7c5f4a9e3885b0ee5e32d468416a7707e3da68d Mon Sep 17 00:00:00 2001
From: Alex Chubaty <achubaty@for-cast.ca>
Date: Tue, 20 Aug 2024 19:35:55 -0600
Subject: [PATCH] set cache path using env var (#274)

---
 R/cache.R      | 42 +++++++++++++++++++++++++++++++++++++++---
 man/Caching.Rd | 32 ++++++++++++++++++++++++++++++--
 2 files changed, 69 insertions(+), 5 deletions(-)

diff --git a/R/cache.R b/R/cache.R
index 79e7c5d4..ebad5176 100644
--- a/R/cache.R
+++ b/R/cache.R
@@ -2,16 +2,52 @@
 
 #' Return package local cache path
 #'
-#' @details By default, it uses [tools::R_user_dir()]. The cache location can be
-#' set using the `climr.cache.path` option with `options("climr.cache.path" = "your_path")`.
+#' @details By default, it uses [tools::R_user_dir()].
+#' The cache location can be set using the `CLIMR_CACHE_PATH` environment variable,
+#' or using the `climr.cache.path` option. The value set via the option takes precedence.
 #'
 #' @return character. The full path of the package local cache.
+#' 
+#' @examples
+#' \dontshow{
+#'   ## record previous settings for post-example cleanup
+#'   prev_envvar <- Sys.getenv("CLIMR_CACHE_PATH")
+#'   prev_opts <- getOption("climr.cache.path")
+#' }
+#' cache_path() ## the current cache path
+#' 
+#' ## set via environment variable
+#' Sys.setenv(CLIMR_CACHE_PATH = file.path(tempdir(), "climr-cache"))
+#' cache_path() ## e.g., /tmp/Rtmpbo9VC7/climr-cache
+#' 
+#' ## set via option (takes precedence over envvar)
+#' options(climr.cache.path = file.path(tempdir(), "climr-cache-2"))
+#' cache_path() ## e.g., /tmp/Rtmpbo9VC7/climr-cache-2
+#' 
+#' \dontshow{
+#'   ## unset/cleanup
+#'   if (nzchar(prev_envvar)) {
+#'     Sys.unsetenv("CLIMR_CACHE_PATH")
+#'   } else {
+#'     Sys.setenv(CLIMR_CACHE_PATH = prev_envvar)
+#'   }
+#'   options(prev_opts)
+#' }
 #'
 #' @export
 #' @rdname Caching
 #' @importFrom tools R_user_dir
 cache_path <- function() {
-  getOption("climr.cache.path", default = R_user_dir("climr", "cache"))
+  opt_name <- "climr.cache.path"
+  envvar_name <- toupper(opt_name) %>% gsub("[.]", "_", x = .)
+  envvar_val <- Sys.getenv(envvar_name, unset = "")
+  
+  if (nzchar(envvar_val)) {
+    opt_val <- envvar_val
+  } else {
+    opt_val <- R_user_dir("climr", "cache") ## default
+  }
+  getOption(opt_name, default = opt_val)
 }
 
 #' Check if package local cache exists
diff --git a/man/Caching.Rd b/man/Caching.Rd
index 2a94d552..48a6a054 100644
--- a/man/Caching.Rd
+++ b/man/Caching.Rd
@@ -26,11 +26,39 @@ Clear the package's local cache path
 Attempts to delete all folder/files in \code{cache_path()}.
 }
 \details{
-By default, it uses \code{\link[tools:userdir]{tools::R_user_dir()}}. The cache location can be
-set using the \code{climr.cache.path} option with \code{options("climr.cache.path" = "your_path")}.
+By default, it uses \code{\link[tools:userdir]{tools::R_user_dir()}}.
+The cache location can be set using the \code{CLIMR_CACHE_PATH} environment variable,
+or using the \code{climr.cache.path} option. The value set via the option takes precedence.
 
 It may fail if R has no permission to delete files/folders
 in the \code{cache_path()} directory
+}
+\examples{
+\dontshow{
+  ## record previous settings for post-example cleanup
+  prev_envvar <- Sys.getenv("CLIMR_CACHE_PATH")
+  prev_opts <- getOption("climr.cache.path")
+}
+cache_path() ## the current cache path
+
+## set via environment variable
+Sys.setenv(CLIMR_CACHE_PATH = file.path(tempdir(), "climr-cache"))
+cache_path() ## e.g., /tmp/Rtmpbo9VC7/climr-cache
+
+## set via option (takes precedence over envvar)
+options(climr.cache.path = file.path(tempdir(), "climr-cache-2"))
+cache_path() ## e.g., /tmp/Rtmpbo9VC7/climr-cache-2
+
+\dontshow{
+  ## unset/cleanup
+  if (nzchar(prev_envvar)) {
+    Sys.unsetenv("CLIMR_CACHE_PATH")
+  } else {
+    Sys.setenv(CLIMR_CACHE_PATH = prev_envvar)
+  }
+  options(prev_opts)
+}
+
 }
 \seealso{
 \code{\link[=cache_path]{cache_path()}}