Merge branch 'release/0.14.0'

.github/workflows/R-CMD-check.yaml

@@ -20,19 +20,19 @@ jobs:
           - {os: windows-latest, r: 'release'  }
           - {os: macOS-latest,   r: 'devel'    }
           - {os: macOS-latest,   r: 'release'  }
-          - {os: ubuntu-20.04,   r: 'devel'    }
-          - {os: ubuntu-20.04,   r: 'release'  }
-          - {os: ubuntu-20.04,   r: 'oldrel'   }
-          - {os: ubuntu-20.04,   r: 'oldrel-1' }
-          - {os: ubuntu-20.04,   r: 'oldrel-2' }
-          - {os: ubuntu-20.04,   r: '3.5'      }
-          - {os: ubuntu-20.04,   r: 'release'  , language: ko,    label: ko    }
-          - {os: ubuntu-20.04,   r: 'release'  , language: zh_CN, label: zh_CN }
-          - {os: ubuntu-20.04,   r: 'release'  , language: zh_TW, label: zh_TW }
+          - {os: ubuntu-22.04,   r: 'devel'    }
+          - {os: ubuntu-22.04,   r: 'release'  }
+          - {os: ubuntu-22.04,   r: 'oldrel'   }
+          - {os: ubuntu-22.04,   r: 'oldrel-1' }
+          - {os: ubuntu-22.04,   r: 'oldrel-2' }
+          - {os: ubuntu-22.04,   r: '3.5'      }
+          - {os: ubuntu-22.04,   r: 'release'  , language: ko,    label: ko    }
+          - {os: ubuntu-22.04,   r: 'release'  , language: zh_CN, label: zh_CN }
+          - {os: ubuntu-22.04,   r: 'release'  , language: zh_TW, label: zh_TW }
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      RSPM: https://packagemanager.rstudio.com/cran/__linux__/focal/latest
+      RSPM: https://packagemanager.rstudio.com/cran/__linux__/jammy/latest
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       ## R CMD check
       _R_CHECK_CRAN_INCOMING_: false
@@ -100,7 +100,7 @@ jobs:
         shell: Rscript {0}
 
       - name: Check
-        run: rcmdcheck::rcmdcheck(args = c("--no-manual", "--as-cran", if (.Platform$OS.type == "windows" && getRversion() >= "4.2.0") "--no-multiarch"), error_on = "note", check_dir = "check")
+        run: rcmdcheck::rcmdcheck(args = c("--no-manual", "--as-cran", if (.Platform$OS.type == "windows" && getRversion() >= "4.2.0") "--no-multiarch"), check_dir = "check")
         shell: Rscript {0}
 
       - name: Upload check results

.github/workflows/covr.yaml

@@ -8,7 +8,7 @@ jobs:
 
     timeout-minutes: 30
 
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     name: covr
 
@@ -17,7 +17,7 @@ jobs:
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      RSPM: https://packagemanager.rstudio.com/cran/__linux__/focal/latest
+      RSPM: https://packagemanager.rstudio.com/cran/__linux__/jammy/latest
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       ## R CMD check
       _R_CHECK_LENGTH_1_CONDITION_: true

.github/workflows/revdepcheck-top.yaml

@@ -8,7 +8,7 @@ jobs:
 
     timeout-minutes: 30
 
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
 
     name: ${{ matrix.config.pkg }} (${{ matrix.config.r }})
 
@@ -23,7 +23,7 @@ jobs:
 #          - { r: "release", pkg: "gtfs2gps" }
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      RSPM: https://packagemanager.rstudio.com/cran/__linux__/focal/latest
+      RSPM: https://packagemanager.rstudio.com/cran/__linux__/jammy/latest
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       ## R CMD check
       _R_CHECK_LENGTH_1_CONDITION_: true

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: progressr
-Version: 0.13.0
+Version: 0.14.0
 Title: An Inclusive, Unifying API for Progress Updates
 Description: A minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing.  The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it.  The end user has full control of how, where, and when to render these progress updates, e.g. in the terminal using utils::txtProgressBar(), cli::cli_progress_bar(), in a graphical user interface using utils::winProgressBar(), tcltk::tkProgressBar() or shiny::withProgress(), via the speakers using beepr::beep(), or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce API:s like the lapply() family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. future.apply::future_lapply(), furrr::future_map(), and 'foreach' with 'doFuture'. The package is compatible with Shiny applications.
 Authors@R: c(

Makefile

@@ -10,4 +10,4 @@ vigns: vignettes/progressr-intro.md
 
 spelling:
 	$(R_SCRIPT) -e "spelling::spell_check_package()"
-	$(R_SCRIPT) -e "spelling::spell_check_files(c('NEWS', dir('vignettes', pattern='[.](md|rsp)$$', full.names=TRUE)), ignore=readLines('inst/WORDLIST', warn=FALSE))"
+	$(R_SCRIPT) -e "spelling::spell_check_files(dir('vignettes', pattern='[.](md|rsp)$$', full.names=TRUE), ignore=readLines('inst/WORDLIST', warn=FALSE))"

NEWS.md

@@ -1,3 +1,28 @@
+# Version 0.14.0 [2023-08-10]
+
+## New Features
+
+ * Progress reporting may be terminated by an interrupt (e.g. user
+   presses Ctrl-C, or the process is interrupted externally), or a
+   run-time error.  When this happens, the most recent progress update
+   is preserved (e.g. a progress bar in the terminal remains), and an
+   informative message is displayed (if the progress handler supported
+   it). In previous versions, the preservation of the progress and the
+   output of the message happened only for interrupts. In this version,
+   this happens also for errors.
+
+## Miscellaneous
+
+ * The `progressr.options` help page is now listed in the help index.
+
+## Bug Fixes
+
+ * The 'cli', 'pbcol', 'pbmclapply', 'progress', and 'txtprogressbar'
+   handlers did not redraw the progress bar if there was an interrupt,
+   which made it a hit or miss whether it was displayed after the
+   interruption.
+
+
 # Version 0.13.0 [2023-01-09]
 
 ## Significant Changes

R/global_progression_handler.R

@@ -54,7 +54,7 @@ register_global_progression_handler <- function(action = c("add", "remove", "que
 
 #' A Global Calling Handler For 'progression':s
 #'
-#' @param progression A [progression] conditions.
+#' @param condition A logical scalar or a condition object.
 #'
 #' @return Nothing.
 #'
@@ -90,7 +90,7 @@ global_progression_handler <- local({
     calling_handler <<- make_calling_handler(handlers)
   }
 
-  interrupt_calling_handler <- function(progression = control_progression("interrupt"), debug = FALSE) {
+  interrupt_calling_handler <- function(progression, debug = FALSE) {
     if (is.null(calling_handler)) return()
 
     ## Don't capture conditions that are produced by progression handlers
@@ -272,10 +272,12 @@ global_progression_handler <- local({
 
     ## Shut down progression handling?
     if (inherits(condition, c("interrupt", "error"))) {
-      if (inherits(condition, "interrupt") &&
-          isTRUE(getOption("progressr.interrupts", TRUE))) {
+      if (isTRUE(getOption("progressr.interrupts", TRUE))) {
+        ## Create progress message saying why the progress was interrupted
+        msg <- sprintf("Progress interrupted by %s condition", class(condition)[1])
+        msg <- paste(c(msg, conditionMessage(condition)), collapse = ": ")
         suspendInterrupts({
-          interrupt_calling_handler(debug = debug)
+          interrupt_calling_handler(control_progression("interrupt", message = msg), debug = debug)
         })
       }
 

R/handler_ascii_alert.R

@@ -20,7 +20,7 @@ handler_ascii_alert <- function(symbol = "\a", file = stderr(), intrusiveness =
       hide   = function(...) NULL,
       unhide = function(...) NULL,
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         msg <- paste(c("", msg, ""), collapse = "\n")
         cat(msg, file = file)
       },

R/handler_cli.R

@@ -199,7 +199,15 @@ handler_cli <- function(show_after = 0.0, intrusiveness = getOption("progressr.i
       interrupt = function(config, state, progression, ...) {
         if (is.null(pb)) return()
         stopifnot(is.character(pb$id), is.environment(pb$envir))
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+
+        ## WORKAROUND: At times, we might get 'Error in
+        ## del_from:length(app$styles) : NA/NaN argument'.
+        tryCatch({
+          erase_progress_bar(pb)
+          redraw_progress_bar(pb)
+        }, error = identity)
+
+        msg <- conditionMessage(progression)
         msg <- paste(c("", msg, ""), collapse = "\n")
         cat(msg, file = stderr())
       },

R/handler_filesize.R

@@ -58,7 +58,7 @@ handler_filesize <- function(file = "default.progress", intrusiveness = getOptio
       },
 
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         set_file_size(config = config, state = state, progression = progression, message = msg)
       },
 

R/handler_newline.R

@@ -17,7 +17,7 @@ handler_newline <- function(symbol = "\n", file = stderr(), intrusiveness = getO
       hide     = function(...) NULL,
       unhide   = function(...) NULL,
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         msg <- paste(c("", msg, ""), collapse = "\n")
         cat(msg, file = file)
       },

R/handler_notifier.R

@@ -45,7 +45,7 @@ handler_notifier <- function(intrusiveness = getOption("progressr.intrusiveness.
       },
 
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         notify(step = state$step, max_steps = config$max_steps, message = msg)
       },
 

R/handler_pbcol.R

@@ -113,7 +113,11 @@ handler_pbcol <- function(adjust = 0.0, pad = 1L, complete = function(s) cli::bg
       },
 
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        if (!state$enabled || config$times <= 2L) return()
+        erase_progress_bar()
+        ratio <- if (config$max_steps == 0) 1 else state$step / config$max_steps
+        redraw_progress_bar(ratio = ratio, message = state$message, spin = spinner[spin_state+1L])
+        msg <- conditionMessage(progression)
         msg <- paste(c("", msg, ""), collapse = "\n")
         cat_(msg)
       },

R/handler_pbmcapply.R

@@ -109,7 +109,9 @@ handler_pbmcapply <- function(char = "=", substyle = 3L, style = "ETA", file = s
       },
 
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        eraseTxtProgressBar(pb)
+        redrawTxtProgressBar(pb)
+        msg <- conditionMessage(progression)
         msg <- paste(c("", msg, ""), collapse = "\n")
         cat(msg, file = file)
       },

R/handler_progress.R

@@ -151,7 +151,11 @@ handler_progress <- function(format = ":spin [:bar] :percent :message", show_aft
 
       interrupt = function(config, state, progression, ...) {
         if (is.null(pb)) return()
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+
+        erase_progress_bar(pb)
+        redraw_progress_bar(pb)
+
+        msg <- conditionMessage(progression)
         msg <- paste(c("", msg, ""), collapse = "\n")
         cat(msg, file = stderr())
       },

R/handler_rpushbullet.R

@@ -67,7 +67,7 @@ handler_rpushbullet <- function(intrusiveness = getOption("progressr.intrusivene
       },
 
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         notify(step = state$step, max_steps = config$max_steps, message = msg)
       },
 

R/handler_shiny.R

@@ -54,7 +54,7 @@ handler_shiny <- function(intrusiveness = getOption("progressr.intrusiveness.gui
   reporter <- local({
     list(
       interrupt = function(config, state, progression, ...) {
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         amount <- if (config$max_steps == 0) 1 else progression$amount / config$max_steps
         args <- c(
           list(amount = amount),

R/handler_tkprogressbar.R

@@ -105,7 +105,7 @@ handler_tkprogressbar <- function(intrusiveness = getOption("progressr.intrusive
 
       interrupt = function(config, state, progression, ...) {
         if (!state$enabled) return()
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         update_pb(state, progression, message = msg)
       },
 

R/handler_txtprogressbar.R

@@ -102,7 +102,11 @@ handler_txtprogressbar <- function(char = "=", style = 3L, file = stderr(), intr
 
       interrupt = function(config, state, progression, ...) {
         if (is.null(pb)) return()
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+
+        eraseTxtProgressBar(pb)
+        redrawTxtProgressBar(pb)
+
+        msg <- conditionMessage(progression)
         msg <- paste(c("", msg, ""), collapse = "\n")
         cat(msg, file = file)
       },

R/handler_winprogressbar.R

@@ -122,7 +122,7 @@ handler_winprogressbar <- function(intrusiveness = getOption("progressr.intrusiv
 
       interrupt = function(config, state, progression, ...) {
         if (!state$enabled) return()
-        msg <- getOption("progressr.interrupt.message", "interrupt detected")
+        msg <- conditionMessage(progression)
         update_pb(state, progression, message = msg)
       },
 

R/options.R

@@ -54,14 +54,14 @@
 #'     (numeric)
 #'     A non-negative scalar on how intrusive (disruptive) the reporter to the user. This multiplicative scalar applies to the _interval_ and _times_ parameters. (Default: `1.0`)\cr
 #'   
-#'     \describe{
-#'       \item{\option{progressr.intrusiveness.audio}:}{(numeric) intrusiveness for auditory progress handlers (Default: `5.0`)}
-#'       \item{\option{progressr.intrusiveness.file}:}{(numeric) intrusiveness for file-based progress handlers (Default: `5.0`)}
-#'       \item{\option{progressr.intrusiveness.gui}:}{(numeric) intrusiveness for graphical-user-interface progress handlers (Default: `1.0`)}
-#'       \item{\option{progressr.intrusiveness.notifier}:}{(numeric) intrusiveness for progress handlers that creates notifications (Default: `10.0`)}
-#'       \item{\option{progressr.intrusiveness.terminal}:}{(numeric) intrusiveness for progress handlers that outputs to the terminal (Default: `1.0`)}
-#'       \item{\option{progressr.intrusiveness.debug}:}{(numeric) intrusiveness for "debug" progress handlers (Default: `0.0`)}
-#'     }
+#'    \describe{
+#'      \item{\option{progressr.intrusiveness.audio}:}{(numeric) intrusiveness for auditory progress handlers (Default: `5.0`)}
+#'      \item{\option{progressr.intrusiveness.file}:}{(numeric) intrusiveness for file-based progress handlers (Default: `5.0`)}
+#'      \item{\option{progressr.intrusiveness.gui}:}{(numeric) intrusiveness for graphical-user-interface progress handlers (Default: `1.0`)}
+#'      \item{\option{progressr.intrusiveness.notifier}:}{(numeric) intrusiveness for progress handlers that creates notifications (Default: `10.0`)}
+#'      \item{\option{progressr.intrusiveness.terminal}:}{(numeric) intrusiveness for progress handlers that outputs to the terminal (Default: `1.0`)}
+#'      \item{\option{progressr.intrusiveness.debug}:}{(numeric) intrusiveness for "debug" progress handlers (Default: `0.0`)}
+#'    }
 #'   }
 #' }
 #'
@@ -139,7 +139,6 @@
 #' progressr.handlers
 #' progressr.times
 #'
-#' @keywords internal
 #' @name progressr.options
 NULL
 
@@ -245,12 +244,19 @@ update_package_options <- function(debug = FALSE) {
 
   ## make_progression_handler() arguments
   update_package_option("clear", mode = "logical", default = TRUE, debug = debug)
-  update_package_option("enable", mode = "logical", default = interactive(), debug = debug)
+
+  ## Special case: Support R_PROGRESSR_ENABLE=interactive
+  value <- Sys.getenv("R_PROGRESSR_ENABLE", "")
+  if (value == "interactive") {
+    options(progressr.enable = interactive())
+  } else {
+    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)
   update_package_option("interrupts", mode = "logical", default = TRUE, debug = debug)
-  update_package_option("interrupt.message", mode = "character", default = "interrupt detected", debug = debug)
 
   ## Life-cycle, e.g. deprecation an defunct
   update_package_option("lifecycle.progress", mode = "character", default = "deprecated", debug = debug)

R/withProgressShiny.R

@@ -1,8 +1,10 @@
-#' Use Progressr in Shiny Apps: Plug-in Backward Compatibility Replacement for shiny::withProgress()
+#' Use Progressr in Shiny Apps: Plug-in Backward-Compatible Replacement for shiny::withProgress()
+#'
+#' A plug-in, backward-compatible replacement for [shiny::withProgress()].
 #'
 #' @inheritParams handler_shiny
 #'
-#' @param expr,\ldots,env,quoted Arguments passed to [shiny::withProgress] as is.
+#' @param expr,\ldots,env,quoted Arguments passed to [shiny::withProgress()] as is.
 #'
 #' @param message,detail (character string) The message and the detail message to be passed to [shiny::withProgress()].
 #'