Merge branch 'release/0.1.3'

Author: HenrikBengtsson

.Rbuildignore

@@ -58,3 +58,5 @@ Rplots.pdf$
 ^.ghi
 ^.issues
 ^last.dump*
+
+vignettes/

DESCRIPTION

@@ -1,15 +1,15 @@
 Package: progressr
-Version: 0.1.2
+Version: 0.1.3
 Title: A Unifying API for Progress Updates
 Description: A minimal API for reporting progress updates upstream.  The design is to separate the representation of progress updates from how they are presented.  What type of progress to signal is controlled by the developer.  How these progress updates are rendered is controlled by the end user.  For instance, some users may prefer visual feedback such as a horizontal progress bar in the terminal, whereas others may prefer auditory feedback.
 Authors@R: c(
   person("Henrik", "Bengtsson", role=c("aut", "cre", "cph"),
          email = "[email protected]"))
 License: GPL (>= 3)
 Imports:
-    digest
+    digest,
+    utils
 Suggests:
-    utils,
     tcltk,
     beepr,
     notifier,

NAMESPACE

@@ -7,6 +7,8 @@ export(ascii_alert_handler)
 export(beepr_handler)
 export(debug_handler)
 export(filesize_handler)
+export(handlers)
+export(make_progression_handler)
 export(newline_handler)
 export(notifier_handler)
 export(pbmcapply_handler)
@@ -15,7 +17,6 @@ export(progress_aggregator)
 export(progress_handler)
 export(progress_progressr)
 export(progression)
-export(progression_handler)
 export(progressor)
 export(slow_sum)
 export(tkprogressbar_handler)
@@ -27,4 +28,6 @@ importFrom(digest,digest)
 importFrom(utils,capture.output)
 importFrom(utils,file_test)
 importFrom(utils,flush.console)
+importFrom(utils,setTxtProgressBar)
 importFrom(utils,str)
+importFrom(utils,txtProgressBar)

NEWS

@@ -1,6 +1,20 @@
 Package: progressr
 ==================
 
+Version: 0.1.3 [2019-07-01]
+
+NEW FEATURES:
+
+ * Now it is possible to send "I'm still here" progression updates by setting
+   the progress step to zero, e.g. progress(amount = 0).  This type of
+   information can for instance be used to updated a progress bar spinner.
+
+ * Add utility function handlers() for controlling option 'progressr.handlers'.
+ 
+ * Progression handlers' internal state now has a sticky 'message' field,
+   which hold the most recent, non-empty progression 'message' received.
+
+
 Version: 0.1.2 [2019-06-14]
 
 NEW FEATURES:

OVERVIEW.md

@@ -102,6 +102,19 @@ with_progress({
 ```
 
 
+## Roadmap
+
+Because this project is under active development, the progressr API is currently kept at a very minimum.  This will allow for the framework and the API to evolve while minimizing the risk for breaking code that depends on it.  The roadmap for developing the API is roughly:
+
+1. Provide minimal API for producing progress updates, i.e. `progressor()` and `with_progress()`
+   
+2. Add support for nested progress updates
+
+3. Add API to allow users and package developers to design additional progression handlers
+
+For a more up-to-date view on what features might be added, see <https://github.com/HenrikBengtsson/progressr/issues>.
+
+
 ## Appendix
 
 ### Debugging

R/handlers.R

@@ -0,0 +1,80 @@
+#' Get and Set the List of Progression Handlers
+#'
+#' @param \dots One or more progression handlers.  Alternatively, this
+#' functions accepts also a single vector of progression handlers as input.
+#' If this vector is empty, then an empty set of progression handlers will
+#' be set.
+#'
+#' @param on_missing (character) If `"error"`, an error is thrown if one of
+#' the progression handlers does not exists.  If `"warning"`, a warning
+#' is produces and the missing handlers is ignored.  If `"ignore"`, the
+#' missing handlers is ignored.
+#'
+#' @return (invisibly) the previous list of progression handlers set.
+#' If no arguments are specified, then the current set of progression
+#' handlers is returned.
+#'
+#' @details
+#' This function provides a convenient alternative for getting and setting
+#' option \option{progressr.handlers}.
+#'
+#' @example incl/handlers.R
+#'
+#' @export
+handlers <- function(..., on_missing = c("error", "warning", "ignore")) {
+  args <- list(...)
+
+  ## Get the current set of progression handlers?
+  if (length(args) == 0L) return(getOption("progressr.handlers"))
+
+  on_missing <- match.arg(on_missing)
+  
+  ## Was a list specified?
+  if (length(args) == 1L && is.vector(args[[1]])) {
+    args <- args[[1]]
+  }
+
+  handlers <- list()
+  names <- names(args)
+  for (kk in seq_along(args)) {
+    handler <- args[[kk]]
+    stop_if_not(length(handler) == 1L)
+    
+    if (is.character(handler)) {
+      name <- handler
+      name2 <- sprintf("%s_handler", name)
+      
+      handler <- NULL
+      if (exists(name2, mode = "function")) {
+        handler <- get(name2, mode = "function")
+      }
+      
+      if (is.null(handler)) {
+        if (exists(name, mode = "function")) {
+          handler <- get(name, mode = "function")
+        }
+      }
+      
+      if (is.null(handler)) {
+        if (on_missing == "error") {
+          stop("No such progression handler found: ", sQuote(name))
+	} else if (on_missing == "warning") {
+          warning("Ignoring non-existing progression handler: ", sQuote(name))
+	}
+        next
+      }
+
+      names[kk] <- name
+    }
+    stop_if_not(is.function(handler), length(formals(handler)) >= 1L)
+    handlers[[kk]] <- handler
+  }
+  stop_if_not(is.list(handlers))
+  names(handlers) <- names
+
+  ## Drop non-existing handlers
+  keep <- vapply(handlers, FUN = is.function, FUN.VALUE = FALSE)
+  handlers <- handlers[keep]
+
+  options(progressr.handlers = handlers)[[1]]
+}

R/options.R

@@ -0,0 +1,74 @@
+#' Options used for progressr
+#'
+#' Below are all \R options that are currently used by the \pkg{progressr} package.\cr
+#' \cr
+#' \emph{WARNING: Note that the names and the default values of these options may change in future versions of the package.  Please use with care until further notice.}
+#'
+#'
+#' @section Options for controlling progression reporting:
+#'
+#' \describe{
+#'  \item{\option{progressr.handlers}:}{(function or list of functions) Zero or more progression handlers that will report on any progression updates.  If NULL or an empty list, progress updates are ignored. (Default: `txtprogressbar_handler`)}
+#' }
+#'
+#'
+#' @section Options for controlling progression handlers:
+#'
+#' \describe{
+#'  \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}:}{(logical) If FALSE, then progress is not reported. (Default: TRUE)}
+#'
+#'  \item{\option{progressr.enable_after}:}{(numeric) Delay (in seconds) before progression updates are reported. (Default: `0.0`)}
+#'
+#'  \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}:}{(numeric) The minimum time (in seconds) between successive progression updates from this handler. (Default: `0.0`)}
+#'
+#'  \item{\option{progressr.intrusiveness}:}{(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.auditory}:}{(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`)}
+#'   }
+#'  }
+#' }
+#'
+#' @section Options for controlling how standard output and conditions are relayed:
+#'
+#' \describe{
+#'  \item{\option{progressr.delay_conditions}:}{(character vector) condition classes to be captured and relayed at the end after any captured standard output is relayed. (Default: `c("condition")`)}
+#'
+#'  \item{\option{progressr.delay_stdout}:}{(logical) If TRUE, standard output is captured and relayed at the end just before any captured conditions are relayed. (Default: TRUE)}
+#' }
+#'
+#'
+#' @section Options for debugging progression updates:
+#'
+#' \describe{
+#'  \item{\option{progressr.debug}:}{(logical) If TRUE, extensive debug messages are generated. (Default: FALSE)}
+#' }
+#'
+#'
+#' @section Options for progressr examples and demos:
+#'
+#' \describe{
+#'  \item{\option{progressr.delay}:}{(numeric) Delay (in seconds) between each iteration of [slow_sum()]. (Default: `1.0`)}
+#' }
+#'
+#'
+#' @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 configurating \R's startup process.
+#'
+#' @aliases
+#' progressr.debug
+#' progressr.handlers
+#' progressr.clear
+#'
+#' @keywords internal
+#' @name progressr.options
+NULL

R/progress_aggregator.R

@@ -39,7 +39,7 @@ progress_aggregator <- function(progress) {
     invokeRestart("muffleProgression")
   }
 
-  handler <- progression_handler("progress_aggregator", handler = handler)
+  handler <- make_progression_handler("progress_aggregator", handler = handler)
 
   fcn <- function(...) {
     with_progress(..., handlers = handler)

R/progression.R

@@ -1,9 +1,11 @@
 #' A Progression Condition
 #'
-#' @param amount (numeric) The total amount of progress made.
+#' A progression condition represents a progress in an \R program.
 #'
 #' @param message (character) A progress message.
 #'
+#' @param amount (numeric) The total amount of progress made.
+#'
 #' @param step (character or integer) The step completed.
 #'
 #' @param time (POSIXct) A timestamp.
@@ -35,7 +37,7 @@
 #' To create and signal a progression condition at once, use [progress()].
 #'
 #' @export
-progression <- function(amount = 1.0, message = character(0L), step = NULL, time = progression_time, ..., type = "update", class = NULL, progressor_uuid = NULL, progression_index = NULL, progression_time = Sys.time(), call = NULL, owner_session_uuid = NULL) {
+progression <- function(message = character(0L), amount = 1.0, step = NULL, time = progression_time, ..., type = "update", class = NULL, progressor_uuid = NULL, progression_index = NULL, progression_time = Sys.time(), call = NULL, owner_session_uuid = NULL) {
   message <- as.character(message)
   amount <- as.numeric(amount)
   time <- as.POSIXct(time)
@@ -78,8 +80,8 @@ progression <- function(amount = 1.0, message = character(0L), step = NULL, time
 print.progression <- function(x, ...) {
   s <- sprintf("%s:", class(x)[1])
   s <- c(s, paste("- call:", deparse(conditionCall(x))))
-  s <- c(s, paste("- message:", sQuote(conditionMessage(x))))
   s <- c(s, paste("- type:", x$type))
+  s <- c(s, paste("- message:", sQuote(conditionMessage(x))))
   s <- c(s, paste("- amount:", x$amount))
   s <- c(s, paste("- step:", x$step))
   s <- c(s, paste("- time:", x$time))