Merge branch 'release/0.5.0'

Author: HenrikBengtsson

.Rbuildignore

@@ -3,6 +3,7 @@
 #----------------------------
 ^.svn
 ^.git
+^.github
 ^.make
 ^INSTALL[.]md$
 ^OVERVIEW[.]md$

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

@@ -0,0 +1,77 @@
+on: [push, pull_request]
+
+name: R-CMD-check
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+    name: ${{ matrix.config.os }} (${{ matrix.config.r }})
+    if: "! contains(github.event.head_commit.message, '[ci skip]')"    
+    
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+        - { os: windows-latest, r: '3.5'}
+        - { os: windows-latest, r: '3.6'}
+        - { os: windows-latest, r: 'devel'}
+        - { os: macOS-latest, r: '3.5'}
+        - { os: macOS-latest, r: '3.6'}
+        - { os: macOS-latest, r: 'devel'}
+        - { os: ubuntu-16.04, r: '3.4', cran: "https://demo.rstudiopm.com/all/__linux__/xenial/latest"}
+        - { os: ubuntu-16.04, r: '3.5', cran: "https://demo.rstudiopm.com/all/__linux__/xenial/latest"}
+        - { os: ubuntu-16.04, r: '3.6', cran: "https://demo.rstudiopm.com/all/__linux__/xenial/latest"}
+
+    env:
+      R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
+      CRAN: ${{ matrix.config.cran }}
+
+
+    steps:
+      - uses: actions/checkout@v1
+
+      - uses: r-lib/actions/setup-r@master
+        with:
+          r-version: ${{ matrix.config.r }}
+
+      - uses: r-lib/actions/setup-pandoc@master
+
+      - name: Query dependencies
+        run: Rscript -e "install.packages('remotes')" -e "saveRDS(remotes::dev_package_deps(dependencies = TRUE), 'depends.Rds', version = 2)"
+
+      - name: Cache R packages
+        if: runner.os != 'Windows'
+        uses: actions/cache@v1
+        with:
+          path: ${{ env.R_LIBS_USER }}
+          key: ${{ runner.os }}-r-${{ matrix.config.r }}-${{ hashFiles('depends.Rds') }}
+          restore-keys: ${{ runner.os }}-r-${{ matrix.config.r }}-
+
+      - name: Install system dependencies
+        if: runner.os == 'Linux'
+        env:
+          RHUB_PLATFORM: linux-x86_64-ubuntu-gcc
+        run: |
+          Rscript -e "remotes::install_github('r-hub/sysreqs')"
+          sysreqs=$(Rscript -e "cat(sysreqs::sysreq_commands('DESCRIPTION'))")
+          sudo -s eval "$sysreqs"
+
+      - name: Install dependencies
+        run: |
+          Rscript -e "library(remotes)" -e "update(readRDS('depends.Rds'))" -e "remotes::install_cran('rcmdcheck')"
+          Rscript -e "install.packages('progressr')"  ## 'self' vignette engine
+
+      - name: Check
+        run: Rscript -e "rcmdcheck::rcmdcheck(args = '--no-manual', error_on = 'warning', check_dir = 'check')"
+
+      - name: Upload check results
+        if: failure()
+        uses: actions/upload-artifact@master
+        with:
+          name: ${{ runner.os }}-r${{ matrix.config.r }}-results
+          path: check
+
+      - name: Test coverage
+        if: matrix.config.os == 'ubuntu-16.04' && matrix.config.r == '3.6-9000'
+        run: |
+          Rscript  -e "install.packages('covr')" -e 'covr::codecov(token = "${{secrets.CODECOV_TOKEN}}")'

.gitignore

@@ -4,4 +4,4 @@
 .local
 inst/doc
 .make/README.md.rsp
-
+revdep/

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: progressr
-Version: 0.4.0
-Title: A 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()' or 'progress::progress_bar()', in a graphical user interface using 'utils::winProgressBar()', 'tcltk::tkProgressBar()' or 'shiny::withProgress()', via the speakers using 'beep::beepr()', 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 APIs 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::map()', and 'foreach' with 'doFuture'. The package is compatible with Shiny applications.
+Version: 0.5.0
+Title: A 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() or progress::progress_bar(), in a graphical user interface using utils::winProgressBar(), tcltk::tkProgressBar() or shiny::withProgress(), via the speakers using beep::beepr(), 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 APIs 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(
   person("Henrik", "Bengtsson", role=c("aut", "cre", "cph"),
          email = "[email protected]"))
@@ -24,9 +24,10 @@ Suggests:
     furrr,
     shiny,
     commonmark,
+    base64enc,
     tools
 VignetteBuilder: progressr
 URL: https://github.com/HenrikBengtsson/progressr
 BugReports: https://github.com/HenrikBengtsson/progressr/issues
-RoxygenNote: 7.0.2
+RoxygenNote: 7.1.0
 Roxygen: list(markdown = TRUE)

Makefile

@@ -4,5 +4,6 @@ vignettes/progressr-intro.md: OVERVIEW.md vignettes/incl/clean.css
 	sed -i '/%\\Vignette/!d' $@
 	echo "<!-- DO NOT EDIT THIS FILE! Edit 'OVERVIEW.md' instead and then rebuild this file with 'make vigs' -->" >> $@
 	cat $< >> $@
+	sed -i 's/vignettes\///g' $@
 
 vigs: vignettes/progressr-intro.md

NAMESPACE

@@ -14,6 +14,7 @@ export(handler_progress)
 export(handler_shiny)
 export(handler_tkprogressbar)
 export(handler_txtprogressbar)
+export(handler_void)
 export(handler_winprogressbar)
 export(handlers)
 export(make_progression_handler)

NEWS

@@ -1,6 +1,17 @@
 Package: progressr
 ==================
 
+Version: 0.5.0 [2020-04-16]
+
+NEW FEATURES:
+
+ * Add 'void' progression handler.
+
+BUG FIXES:
+
+ * Only the last of multiple progression handlers registered was used.
+
+
 Version: 0.4.0 [2020-01-22]
 
 SIGNIFICANT CHANGES:

OVERVIEW.md

@@ -1,9 +1,9 @@
-![Life cycle: experimental](imgs/lifecycle-experimental-orange.svg)
+![Life cycle: experimental](vignettes/imgs/lifecycle-experimental-orange.svg)
 
 The **[progressr]** package provides a minimal API for reporting progress updates in [R](https://www.r-project.org/).  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.
 
 
-<img src="imgs/three_in_chinese.gif" alt="Three strokes writing three in Chinese" style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
+<img src="vignettes/imgs/three_in_chinese.gif" alt="Three strokes writing three in Chinese" style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
 
 Design motto:
 
@@ -103,6 +103,16 @@ handlers("txtprogressbar", "beepr")
 ```
 
 
+### Silence all progress
+
+To silence all progress updates, use:
+
+```r
+handlers("void")
+```
+
+
+
 ## Support for progressr elsewhere
 
 Note that progression updates by **progressr** is designed to work out of the box for any _sequential_ iterator framework in R.  Below is an set of examples for the most common ones.
@@ -291,7 +301,7 @@ When using the **progressr** package, progression updates are communicated via R
 
 
 
-![](imgs/slow_sum.svg)
+![](vignettes/imgs/slow_sum.svg)
 
 _Figure: Sequence diagram illustrating how signaled progression conditions are captured by `with_progress()` and relayed to the two progression handlers 'progress' (a progress bar in the terminal) and 'beepr' (auditory) that the end user has chosen._
 
@@ -319,7 +329,7 @@ To debug progress updates, use:
 
 
 
-[progressr]: https://github.com/HenrikBengtsson/progressr/
+[progressr]: https://cran.r-project.org/package=progressr
 [beepr]: https://cran.r-project.org/package=beepr
 [progress]: https://cran.r-project.org/package=progress
 [purrr]: https://cran.r-project.org/package=purrr

R/handler_void.R

@@ -0,0 +1,28 @@
+#' Progression Handler: No Progress Report
+#'
+#' @inheritParams make_progression_handler
+#'
+#' @param \ldots Additional arguments passed to [make_progression_handler()].
+#'
+#' @examples
+#' \donttest{\dontrun{
+#' handlers(handler_void())
+#' with_progress(y <- slow_sum(1:100))
+#' print(y)
+#' }}
+#'
+#' @details
+#' This progression handler gives not output - it is invisible and silent.
+#'
+#' @export
+handler_void <- function(intrusiveness = 0, ...) {
+  reporter <- local({
+    list(
+      initiate = function(config, state, progression, ...) NULL,
+      update = function(config, state, progression, ...) NULL,
+      finish = function(config, state, progression, ...) NULL
+    )
+  })
+  
+  make_progression_handler("void", reporter, intrusiveness = intrusiveness, ...)
+}

R/handlers.R

@@ -24,7 +24,7 @@
 #' This function provides a convenient alternative for getting and setting
 #' option \option{progressr.handlers}.
 #'
-#' _IMPORTANT: Setting progression handlers is a privileges that should be
+#' _IMPORTANT: Setting progression handlers is a privilege that should be
 #' left to the end user. It should not be used by R packages, which only task
 #' is to _signal_ progress updates, not to decide if, when, and how progress
 #' should be reported._
@@ -96,4 +96,4 @@ handlers <- function(..., append = FALSE, on_missing = c("error", "warning", "ig
   }
 
   options(progressr.handlers = handlers)[[1]]
-}
+}