BBmisc (version 1.10)

makeProgressBar: Create a progress bar with estimated time.

Description

Create a progress bar function that displays the estimated time till completion and optional messages. Call the returned functions set or inc during a loop to change the display. Note that you are not allowed to decrease the value of the bar. If you call these function without setting any of the arguments the bar is simply redrawn with the current value. For errorhandling use error and have a look at the example below.

You can globally change the behavior of all bars by setting the option options(BBmisc.ProgressBar.style) either to “text” (the default) or “off”, which display no bars at all.

You can globally change the width of all bars by setting the option options(BBmisc.ProgressBar.width). By default this is getOption("width").

You can globally set the stream where the output of the bar is directed by setting the option options(BBmisc.ProgressBar.stream) either to “stderr” (the default) or “stdout”. Note that using the latter will result in the bar being shown in reports generated by Sweave or knitr, what you probably do not want.

Usage

makeProgressBar(min = 0, max = 100, label = "", char = "+", style = getOption("BBmisc.ProgressBar.style", "text"), width = getOption("BBmisc.ProgressBar.width", getOption("width")), stream = getOption("BBmisc.ProgressBar.stream", "stderr"))

Arguments

min

[numeric(1)] Minimum value, default is 0.

max

[numeric(1)] Maximum value, default is 100.

label

[character(1)] Label shown in front of the progress bar. Note that if you later set msg in the progress bar function, the message will be left-padded to the length of this label, therefore it should be at least as long as the longest message you want to display. Default is “”.

char

[character(1)] A single character used to display progress in the bar. Default is ‘+’.

style

[character(1)] Style of the progress bar. Default is set via options (see details).

width

[integer(1)] Width of the progress bar. Default is set via options (see details).

stream

[character(1)] Stream to use. Default is set via options (see details).

Value

[ProgressBar]. A list with following functions:

set [function(value, msg = label)]

Set the bar to a value and possibly display a message instead of the label.

inc [function(value, msg = label)]

Increase the bar and possibly display a message instead of the label.

kill [function(clear = FALSE)]

Kill the bar so it cannot be used anymore. Cursor is moved to new line. You can also erase its display.

error [function(e)]

Useful in tryCatch to properly display error messages below the bar. See the example.

Examples

bar = makeProgressBar(max = 5, label = "test-bar")
for (i in 0:5) {
  bar$set(i)
  Sys.sleep(0.2)
}
bar = makeProgressBar(max = 5, label = "test-bar")
for (i in 1:5) {
  bar$inc(1)
  Sys.sleep(0.2)
}
# display errors properly (in next line)
## Not run: 
# f = function(i) if (i>2) stop("foo")
# bar = makeProgressBar(max = 5, label = "test-bar")
# for (i in 1:5) {
#   tryCatch ({
#     f(i)
#     bar$set(i)
#   }, error = bar$error)
# }
# ## End(Not run)