progressor() gained argument 'enable'

This is a very efficient (near-zero overhead) way to disable the progress framework
(fixes #102)

Author: HenrikBengtsson

NEWS

@@ -1,7 +1,7 @@
 Package: progressr
 ==================
 
-Version: 0.6.0-9000 [2020-12-07]
+Version: 0.6.0-9000 [2020-12-10]
 
 SIGNIFICANT CHANGES:
 
@@ -20,6 +20,16 @@ SIGNIFICANT CHANGES:
 
 NEW FEATURES:
 
+ * progressor() gained argument 'enable' to control whether or not the
+   progressor signals 'progression' conditions.  It defaults to option
+   'progressr.enable' so that progress updates can be disabled globally.
+   The 'enable' argument makes it easy for package developers who already
+   provide a 'progress = TRUE/FALSE' argument in their functions to migrate
+   to the 'progressr' package without having to change their existing API,
+   e.g. the setup becomes 'p <- progressor(along = x, enabled = progress)'.
+   The p() function created by p <- progressor(..., enable = FALSE) is an
+   empty function with near-zero overhead.
+
  * Now with_progress() and without_progress() returns the value of the
    evaluated expression.
 

R/progressor.R

@@ -22,6 +22,11 @@
 #' @param auto_finish (logical) If TRUE, then the progressor will signal a
 #' [progression] 'finish' condition as soon as the last step has been reached.
 #'
+#' @param enable (logical) If TRUE, [progression] conditions are signaled when
+#' calling the progressor function created by this function.
+#' If FALSE, no [progression] conditions is signaled because the progressor
+#' function is an empty function that does nothing.
+#'
 #' @param on_exit,envir (logical) If TRUE, then the created progressor will
 #' signal a [progression] 'finish' condition when the calling frame exits.
 #' This is ignored if the calling frame (`envir`) is the global environment.
@@ -31,8 +36,17 @@
 #' @export
 progressor <- local({
   progressor_count <- 0L
-  
-  function(steps = length(along), along = NULL, offset = 0L, scale = 1L, transform = function(steps) scale * steps + offset, message = character(0L), label = NA_character_, initiate = TRUE, auto_finish = TRUE, on_exit = !identical(envir, globalenv()), envir = parent.frame()) {
+
+  void_progressor <- function(...) NULL
+  environment(void_progressor)$enable <- FALSE
+  class(void_progressor) <- c("progressor", class(void_progressor))
+
+  function(steps = length(along), along = NULL, offset = 0L, scale = 1L, transform = function(steps) scale * steps + offset, message = character(0L), label = NA_character_, initiate = TRUE, auto_finish = TRUE, on_exit = !identical(envir, globalenv()), enable = getOption("progressr.enable", TRUE), envir = parent.frame()) {
+    stop_if_not(is.logical(enable), length(enable) == 1L, !is.na(enable))
+
+    ## Quickly return a moot progressor function?
+    if (!enable) return(void_progressor)
+    
     stop_if_not(!is.null(steps) || !is.null(along))
     stop_if_not(length(steps) == 1L, is.numeric(steps), !is.na(steps),
                 steps >= 0)
@@ -123,6 +137,8 @@ print.progressor <- function(x, ...) {
   s <- c(s, paste("- progression_index:", e$progression_index))
   owner_session_uuid <- e$owner_session_uuid
   s <- c(s, paste("- owner_session_uuid:", owner_session_uuid))
+  
+  s <- c(s, paste("- enable:", e$enable))
 
   s <- paste(s, collapse = "\n")
   cat(s, "\n", sep = "")