R_PROGRESSR_* environment variables are now only read when the 'progressr' package is loaded

Author: HenrikBengtsson

NEWS

@@ -8,6 +8,14 @@ SIGNIFICANT CHANGES:
  * Creating a new progressor() will now automatically finish an existing
    progressor in the same environment.  The previous behavior was to give an
    error (see below bug fix).
+
+ * R_PROGRESSR_* environment variables are now only read when the 'progressr'
+   package is loaded, where they set the corresponding progressr.* option.
+   Previously, some of these environment variables were queried by different
+   functions as a fallback to when an option was not set.  By only parsing
+   them when the package is loaded, it decrease the overhead in functions,
+   and it clarifies that options can be changed at runtime whereas environment
+   variables should only be set at startup.
 
 NEW FEATURES:
 

R/make_progression_handler.R

@@ -50,7 +50,7 @@
 #'
 #' @keywords internal
 #' @export
-make_progression_handler <- function(name, reporter = list(), handler = NULL, enable = getOption("progressr.enable", Sys.getenv("R_PROGRESSR_ENABLE", interactive())), enable_after = getOption("progressr.enable_after", Sys.getenv("R_PROGRESSR_ENABLE_AFTER", 0.0)), times = getOption("progressr.times", Sys.getenv("R_PROGRESSR_TIMES", +Inf)), interval = getOption("progressr.interval", Sys.getenv("R_PROGRESSR_INTERVAL", 0.0)), intrusiveness = 1.0, clear = getOption("progressr.clear",  Sys.getenv("R_PROGRESSR_CLEAR", TRUE)), target = "terminal", ...) {
+make_progression_handler <- function(name, reporter = list(), handler = NULL, enable = getOption("progressr.enable", interactive()), enable_after = getOption("progressr.enable_after", 0.0), times = getOption("progressr.times", +Inf), interval = getOption("progressr.interval", 0.0), intrusiveness = 1.0, clear = getOption("progressr.clear", TRUE), target = "terminal", ...) {
   enable <- as.logical(enable)
   stop_if_not(is.logical(enable), length(enable) == 1L, !is.na(enable))
   if (!enable) times <- 0

R/options.R

@@ -21,30 +21,30 @@
 #' @section Options for controlling progression handlers:
 #'
 #' \describe{
-#'   \item{\option{progressr.clear} / \env{R_PROGRESSR_CLEAR}:}{
+#'   \item{\option{progressr.clear}:}{
 #'     (logical)
 #'     If TRUE, any output, typically visual, produced by a reporter will be cleared/removed upon completion, if possible. (Default: TRUE)
 #'   }
 #'
-#'   \item{\option{progressr.enable} / \env{R_PROGRESSR_ENABLE}:}{
+#'   \item{\option{progressr.enable}:}{
 #'     (logical)
 #'     If FALSE, then progress is not reported.
 #'     (Default: TRUE)
 #'   }
 #'
-#'   \item{\option{progressr.enable_after} / \env{R_PROGRESSR_ENABLE_AFTER}:}{
+#'   \item{\option{progressr.enable_after}:}{
 #'     (numeric)
 #'     Delay (in seconds) before progression updates are reported.
 #'     (Default: `0.0`)
 #'   }
 #'
-#'   \item{\option{progressr.times} / \env{R_PROGRESSR_TIMES}:}{
+#'   \item{\option{progressr.times}:}{
 #'     (numeric)
 #'     The maximum number of times a handler should report progression updates. If zero, then progress is not reported.
 #'     (Default: `+Inf`)
 #'   }
 #'
-#'   \item{\option{progressr.interval} / \env{R_PROGRESSR_INTERVAL}:}{
+#'   \item{\option{progressr.interval}:}{
 #'     (numeric)
 #'     The minimum time (in seconds) between successive progression updates from this handler.
 #'     (Default: `0.0`)
@@ -93,6 +93,14 @@
 #'  \item{\option{progressr.demo.delay}:}{(numeric) Delay (in seconds) between each iteration of [slow_sum()]. (Default: `1.0`)}
 #' }
 #'
+#' @section Environment variables that set R options:
+#' Some of the above \R \option{progressr.*} options can be set by corresponding
+#' environment variable \env{R_PROGRESSR_*} _when the \pkg{progressr} package
+#' is loaded_.
+#' For example, if `R_PROGRESSR_ENABLE = "true"`, then option
+#' \option{progressr.enable} is set to `TRUE` (logical).
+#' For example, if `R_PROGRESSR_ENABLE_AFTER = "2.0"`, then option
+#' \option{progressr.enable_after} is set to `2.0` (numeric).
 #'
 #' @seealso
 #' To set \R options when \R starts (even before the \pkg{progressr} package is loaded), see the \link[base]{Startup} help page.  The \href{https://cran.r-project.org/package=startup}{\pkg{startup}} package provides a friendly mechanism for configuring \R at startup.
@@ -218,6 +226,16 @@ update_package_option <- function(name, mode = "character", default = NULL, pack
 update_package_options <- function(debug = FALSE) {
   update_package_option("demo.delay", mode = "numeric", debug = debug)
 
+  ## make_progression_handler() arguments
+  update_package_option("clear", mode = "logical", default = TRUE, debug = debug)
+  update_package_option("enable", mode = "logical", default = interactive(), debug = debug)
+  update_package_option("enable_after", mode = "numeric", default = 0.0, debug = debug)
+  update_package_option("interval", mode = "numeric", default = 0.0, debug = debug)
+  update_package_option("times", mode = "numeric", default = +Inf, debug = debug)
+
+  ## Life-cycle, e.g. deprecation an defunct
+  update_package_option("lifecycle.progress", mode = "character", default = "deprecated", debug = debug)
+
   ## However, not used
   update_package_option("global.handler", mode = "logical", debug = debug)
 }

R/progress.R

@@ -15,7 +15,7 @@
 #' @keywords internal
 #' @export
 progress <- function(..., call = sys.call()) {
-  action <- getOption("progressr.progress", "deprecated")
+  action <- getOption("progressr.lifecycle.progress", "deprecated")
   signal <- switch(action, deprecated = .Deprecated, defunct = .Defunct)
   signal(msg = sprintf("progress() is %s", action), package = .packageName)
 

R/utils.R

@@ -73,6 +73,8 @@ comma <- function(x, sep = ", ") paste(x, collapse = sep)
 
 commaq <- function(x, sep = ", ") paste(sQuote(x), collapse = sep)
 
+trim <- function(s) sub("[\t\n\f\r ]+$", "", sub("^[\t\n\f\r ]+", "", s))
+
 stop_if_not <- function(..., calls = sys.calls()) {
   res <- list(...)
   n <- length(res)