spell and grammar corrections [ci skip]

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: progressr
-Version: 0.18.0-9003
+Version: 0.18.0-9004
 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(person("Henrik", "Bengtsson",

NEWS.md

@@ -184,7 +184,7 @@
 
 ## Significant Changes
 
- * Now `with_progress()` and `without_progress()` disables the global
+ * Now `with_progress()` and `without_progress()` disable the global
    progress handler temporarily while running to avoid progress
    updates being handled twice.  Previously, it was, technically,
    possible to have two different progress handlers intertwined.
@@ -230,7 +230,7 @@
 
 ## New Features
 
- * When the using a 'winprogressbar' or a 'tkprogressbar' handler,
+ * When using a 'winprogressbar' or a 'tkprogressbar' handler,
    progression messages updates the `label` component of the progress
    panel.  Now, it is also possible to update the `title` component
    based on progression messages.  How the `title` and `label`
@@ -241,7 +241,7 @@
    ones to update both.  For backward compatible reasons, the default
    is `inputs = list(title = NULL, label = "message")`.
 
- * Now the demo function `slow_sum()` outputs also "sticky" messages.
+ * Now the demo function `slow_sum()` also outputs "sticky" messages.
 
 ## Miscellaneous
 
@@ -252,7 +252,7 @@
 
 ## New Features
 
- * Now **plyr** (>= 1.8.7) supports **progressr** for also parallel
+ * Now **plyr** (>= 1.8.7) supports **progressr** also for parallel
    processing, e.g. `y <- plyr::llply(X, slow_sum, .parallel = TRUE,
    .progress = "progressr")`.
 
@@ -276,7 +276,7 @@
 ## Bug Fixes
 
  * A progressor that signaled progress beyond 100% prevented any
-   further progressors in the same environment to report on progress.
+   further progressors in the same environment reporting on progress.
 
  * It was not possible to reuse handlers of type 'progress' more than
    once, because they did not fully reset themselves when finished.
@@ -298,7 +298,7 @@
 ## Performance
 
  * The progressor function created by `progressor()` no longer
-   "inherit" objects from the calling environment, which would, for
+   inherits objects from the calling environment, which would, for
    instance, result in those objects to be exported to parallel
    workers together with the progressor function, which in turn would
    come with large time and memory costs.
@@ -322,14 +322,14 @@
    the call stack should be recorded in each `progression` condition.
 
  * Now `print()` for `progressor` functions and `progression`
-   conditions report also on the size of the object, i.e. the number
+   conditions reports also on the size of the object, i.e. the number
    of bytes it requires when serialized, for instance, to and from a
    parallel worker.
 
 ## Bug Fixes
 
  * Registered progression handlers would report on progress also when
-   in a _forked_ parallel child processes, e.g. when using
+   in a _forked_ parallel child process, e.g. when using
    `parallel::mclapply()`.  This would give a false impression that
    **progressr** updates would work when using `parallel::mclapply()`,
    which is not true. Note however, that it does indeed work when
@@ -350,11 +350,11 @@
    `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
+   loaded, it decreases the overhead in functions, and it clarifies
    that options can be changed at runtime whereas environment
    variables should only be set at startup.
 
- * When using `withProgressShiny()`, progression messages now updates
+ * When using `withProgressShiny()`, progression messages now update
    the `detail` component of the Shiny progress panel.  Previously, it
    updated the `message` component. This can be configured via new
    `inputs` argument.
@@ -379,7 +379,7 @@
  * As an alternative to specifying the relative amount of progress,
    say, `p(amount = 2)`, it is now possible to also specify the
    absolute amount of progress made this far, e.g. `p(step = 42)`.
-   Argument `amount` has not effect when argument `step` is specified.
+   Argument `amount` has no effect when argument `step` is specified.
    WARNING: Argument `step` should only be used when in full control
    of the order when this `progression` condition is signaled.  For
    example, it must not be signaled as one of many parallel progress
@@ -521,7 +521,7 @@
 
  * Argument `interval` was ignored for `handler_debug()`.
 
- * The class of `handler_<nnn>()` functions where all
+ * The class of `handler_<nnn>()` functions were all
    `reset_progression_handler` rather than
    `<nnn>_progression_handler`.  The same bug caused the reported
    `name` field to be `"reset"` rather than `"<nnn>"`.
@@ -542,7 +542,7 @@
 
 ## Significant Changes
 
- * All progression handler function have been renamed from
+ * All progression handler functions have been renamed from
    `<name>_handler()` to `handler_<name>()` to make it easier to use
    autocompletion on them.
 
@@ -603,7 +603,7 @@
  * Package could set `.Random.seed` to NULL, instead of removing it,
    which in turn would produce a warning on "'.Random.seed' is not an
    integer vector but of type 'NULL', so ignored" when the next random
-   number generated.
+   number was generated.
 
 
 # Version 0.1.4 [2019-07-02]
@@ -619,14 +619,14 @@
 
  * 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
+   This type of information can for instance be used to update 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`
+   field, which holds the most recent, non-empty progression `message`
    received.
 
 
@@ -739,7 +739,7 @@
 
  * Now `with_progress(..., cleanup = TRUE)` will signal a generic
    "shutdown" progression at the end that will trigger all progression
-   handlers to finish up regardless of all steps have been take or
+   handlers to finish up regardless of whether all steps have been taken or
    not.
 
  * Now progressions originating from an unknown source are ignored.
@@ -822,7 +822,7 @@
    also signal "done" as soon as the last step has been reached.
 
  * Made `amount` the first argument of progressors to avoid having to
-   specify it by name if progressing with an amount than the default
+   specify it by name if progressing with an amount other than the default
    `amount = 1.0`.
 
  * Add argument `clear` to control whether progress reporter should
@@ -882,4 +882,4 @@
 
  * Add `progress()` to create and signal `progression` condition.
 
- * Add `progression()` to create `progression` condition.
+ * Add `progression()` to create `progression` condition.

R/handler_cli.R

@@ -73,7 +73,7 @@ handler_cli <- function(show_after = 0.0, intrusiveness = getOption("progressr.i
     }
 
     cli_progress_bar <- function(total, ...) {
-      ## WORKAROUND: Do no not involve 'cli' when total = 0
+      ## WORKAROUND: Do not involve 'cli' when total = 0
       if (total == 0) return(NA_character_)
 
       ## Make sure to always use the built-in 'cli' handler, no matter
@@ -85,13 +85,13 @@ handler_cli <- function(show_after = 0.0, intrusiveness = getOption("progressr.i
     }
 
     cli_progress_update <- function(id, ..., force = TRUE, .envir) {
-      ## WORKAROUND: Do no not involve 'cli' when total = 0
+      ## WORKAROUND: Do not involve 'cli' when total = 0
       if (.envir$total == 0) return(id)
       cli_progress_call(cli::cli_progress_update, id = id, ..., force = force, .envir = .envir)
     }
 
     cli_progress_done <- function(id, ..., .envir) {
-      ## WORKAROUND: Do no not involve 'cli' when total = 0
+      ## WORKAROUND: Do not involve 'cli' when total = 0
       if (.envir$total == 0) return(id)
       cli_progress_call(cli::cli_progress_done, id = id, ..., .envir = .envir)
     }

R/handlers.R

@@ -1,45 +1,45 @@
 #' Control How Progress is Reported
 #'
 #' @param \ldots One or more progression handlers.  Alternatively, this
-#' functions accepts also a single vector of progression handlers as input.
+#' function also accepts a single vector of progression handlers as input.
 #' If this vector is empty, then an empty set of progression handlers will
 #' be set.
 #'
 #' @param append (logical) If FALSE, the specified progression handlers
-#' replace the current ones, otherwise appended to them.
+#' replace the current ones, otherwise they are appended to them.
 #'
 #' @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.
+#' the progression handlers does not exist.  If `"warning"`, a warning
+#' is produced and the missing handler is ignored.  If `"ignore"`, the
+#' missing handler is ignored.
 #'
 #' @param default The default progression calling handler to use if none
 #' are set.
 #'
 #' @param global If TRUE, then the global progression handler is enabled.
 #' If FALSE, it is disabled.  If NA, then TRUE is returned if it is enabled,
-#' otherwise FALSE.  Argument `global` must not used with other arguments.
+#' otherwise FALSE.  Argument `global` must not be used with other arguments.
 #'
 #' @return (invisibly) the previous list of progression handlers set.
 #' If no arguments are specified, then the current set of progression
 #' handlers is returned.
 #' If `global` is specified, then TRUE is returned if the global progression
-#' handlers is enabled, otherwise false.
+#' handler is enabled, otherwise FALSE.
 #'
 #' @details
 #' This function provides a convenient alternative for getting and setting
 #' option \option{progressr.handlers}.
 #'
 #' @section For package developers:
 #' **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
+#' left to the end user. It should not be used by R packages, whose only task
 #' is to _signal_ progress updates, not to decide if, when, and how progress
 #' should be reported.**
 #'
 #' If you have to set or modify the progression handlers inside a function,
 #' please make sure to undo the settings afterward.  If not, you will break
 #' whatever progression settings the user already has for other purposes
-#' used elsewhere.  To undo you settings, you can do:
+#' used elsewhere.  To undo your settings, you can do:
 #'
 #' ```r
 #' old_handlers <- handlers(c("beepr", "progress"))
@@ -53,8 +53,7 @@
 #' R session to use global progression handler by default, and (ii) report
 #' progress via the \pkg{progress} package when in the terminal and via the
 #' RStudio Jobs progress bar when in the RStudio Console.
-#' [handler_txtprogressbar], 
-#' other whenever using the RStudio Console, add
+#' To configure this, add
 #' the following to your \file{~/.Rprofile} startup file:
 #'
 #' ```r

R/progressor.R

@@ -7,7 +7,7 @@
 #' @param along (vector; alternative) Alternative that sets
 #' `steps = length(along)`.
 #'
-#' @param offset,scale (integer; optional) scale and offset applying transform
+#' @param offset,scale (integer; optional) scale and offset applying the transform
 #' `steps <- scale * steps + offset`.
 #'
 #' @param transform (function; optional) A function that takes the effective
@@ -42,7 +42,7 @@
 #' @details
 #' A `progressor` function can only be created inside a local environment,
 #' e.g. inside a function, within a `local()` call, or within a
-#' `with_progress()` call.  Notably, it _cannot_ be create at the top level,
+#' `with_progress()` call.  Notably, it _cannot_ be created at the top level,
 #' e.g. immediately at the R prompt or outside a local environment in an
 #' R script.  If attempted, an informative error message is produced, e.g.
 #'
@@ -120,7 +120,7 @@ progressor <- local({
     formals(fcn)$message <- message
     class(fcn) <- c("progressor", class(fcn))
 
-    ## WORKAROUND: Use teeny, custom enviroment for the progressor function.
+    ## WORKAROUND: Use teeny, custom environment for the progressor function.
     ## The default would otherwise be to inherit the parent frame, which
     ## might contain very large objects.
     progressor_envir <- new.env(parent = getNamespace(.packageName))
@@ -132,7 +132,7 @@ progressor <- local({
     }
     environment(fcn) <- progressor_envir
 
-    ## Is there already be an active '...progressr'?
+    ## Is there already an active '...progressr'?
     ## If so, make sure it is finished and then remove it
     if (exists("...progressor", mode = "function", envir = envir)) {
       ...progressor <- get("...progressor", mode = "function", envir = envir)

R/with_progress.R

@@ -6,10 +6,10 @@
 #' If NULL or an empty list, progress updates are ignored.
 #'
 #' @param cleanup If TRUE, all progression handlers will be shutdown
-#' at the end regardless of the progression is complete or not.
+#' at the end regardless of whether the progression is complete or not.
 #'
 #' @param delay_terminal If TRUE, output and conditions that may end up in
-#' the terminal will delayed.
+#' the terminal will be delayed.
 #'
 #' @param delay_stdout If TRUE, standard output is captured and relayed
 #' at the end just before any captured conditions are relayed.
@@ -19,8 +19,8 @@
 #' standard output is relayed.
 #'
 #' @param interrupts Controls whether interrupts should be detected or not.
-#' If TRUE and a interrupt is signaled, progress handlers are asked to
-#' report on the current amount progress when the evaluation was terminated
+#' If TRUE and an interrupt is signaled, progress handlers are asked to
+#' report on the current amount of progress when the evaluation was terminated
 #' by the interrupt, e.g. when a user pressed Ctrl-C in an interactive session,
 #' or a batch process was interrupted because it ran out of time.
 #' Note that it's optional for a progress handler to support this and only
@@ -50,19 +50,19 @@
 #' handlers.
 #'
 #' **IMPORTANT: This function is meant for end users only.  It should not
-#' be used by R packages, which only task is to _signal_ progress updates,
+#' be used by R packages, whose only task is to _signal_ progress updates,
 #' not to decide if, when, and how progress should be reported.**
 #'
 #' @section Progression handler functions:
 #' Formally, progression handlers are calling handlers that are called
 #' when a [progression] condition is signaled.  These handlers are functions
-#' that takes one argument which is the [progression] condition.
+#' that take one argument which is the [progression] condition.
 #'
 #' @section Progress updates in batch mode:
 #' When running R from the command line, R runs in a non-interactive mode
 #' (`interactive()` returns `FALSE`).  The default behavior of
 #' `with_progress()` is to _not_ report on progress in non-interactive mode.
-#' To have progress being reported on also then, set R options
+#' To have progress being reported also then, set R options
 #' \option{progressr.enable} or environment variable \env{R_PROGRESSR_ENABLE}
 #' to `TRUE`.  Alternatively, one can set argument `enable=TRUE` when calling
 #' `with_progress()`.  For example,

README.md

@@ -14,7 +14,7 @@ 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.  The **[progressr]** framework is designed
-to work out-of-the-box also with parallel and distributed processing,
+to work out-of-the-box also for parallel and distributed processing,
 especially with the **[futureverse]** ecosystem.
 
 <img src="vignettes/imgs/three_in_chinese.gif" alt="Three strokes writing three in Chinese" style="float: right; margin-right: 1ex; margin-left: 1ex;"/>
@@ -147,7 +147,7 @@ by:
 > progressr::handlers(global = TRUE)
 ```
 
-After this, progress will be reported;
+After this, progress will be reported:
 
 ```r
 > y <- slow_sum(1:10)
@@ -177,18 +177,18 @@ notification systems. You can also use a mix of these, e.g.
 handlers(c("cli", "beepr", "ntfy"))
 ```
 
-See the 'Customizing How Progress is Reported' vignette for for examples.
+See the 'Customizing How Progress is Reported' vignette for examples.
 
 
 ## Additional Features
 
 ### Support for progressr elsewhere
 
-Note that progression updates by **progressr** is designed to work out
+Note that progression updates by **progressr** are designed to work out
 of the box for any iterator framework in R. See the different package
 vignettes for details. Prominent examples are:
 
- * `lapply()` etc. of base R
+ * `lapply()` etc. in base R
  * `map()` etc. by the **[purrr]** package
  * `llply()` etc. by the **[plyr]** package
  * `foreach()` iterations by the **[foreach]** package
@@ -212,7 +212,7 @@ Other uses of **progressr** are:
 ### Use regular output as usual alongside progress updates
 
 In contrast to other progress-bar frameworks, output from `message()`,
-`cat()`, `print()` and so on, will _not_ interfere with progress
+`cat()`, `print()` and so on will _not_ interfere with progress
 reported via **progressr**.  For example, say we have:
 
 ```r
@@ -320,7 +320,6 @@ Step 10
 [pbmcapply]: https://cran.r-project.org/package=pbmcapply
 [plyr]: https://cran.r-project.org/package=plyr
 [BiocParallel]: https://www.bioconductor.org/packages/BiocParallel/
-
 ## Installation
 R package progressr is available on [CRAN](https://cran.r-project.org/package=progressr) and can be installed in R as:
 ```r