Class for Package Options

This class holds public fields that represent the package options used to configure the default behavior of the functionality parabar provides.

Details

An instance of this class is automatically created and stored in the session base::.Options at load time. This instance can be accessed and changed via getOption("parabar"). Specific package options can be retrieved using the helper function get_option().

See also

get_option(), set_option(), and set_default_options().

Public fields

progress_track

A logical value indicating whether progress tracking should be enabled (i.e., TRUE) or disabled (i.e., FALSE) globally for compatible backends. The default value is TRUE.

progress_timeout

A numeric value indicating the timeout (i.e., in seconds) between subsequent checks of the log file for new progress records. The default value is 0.001.

progress_wait

A numeric value indicating the approximate duration (i.e., in seconds) to wait between progress bar updates before checking if the task has finished (i.e., possibly with an error). The default value is 0.1.

progress_bar_type

A character string indicating the default bar type to use with compatible backends. Possible values are "modern" (the default) or "basic".

progress_bar_config

A list of lists containing the default bar configuration for each supported bar engine. Elements of these lists represent arguments for the corresponding bar engines. Currently, the supported bar engines are:

• modern: The progress::progress_bar engine, with the following default configuration:

  • show_after = 0

  • format = "> completed :current out of :total tasks [:percent] [:elapsed]"

• basic: The utils::txtProgressBar engine, with no default configuration.

stop_forceful

A logical value indicating whether to allow stopping an asynchronous backend forcefully (i.e., TRUE), or not (i.e., FALSE). When stopping forcefully, the backend is terminated without waiting for a running tasks to finish or for the results to be read into the main R session. The default value is FALSE.

Active bindings

progress_log_path

A character string indicating the path to the log file where to track the execution progress of a running task. The default value is a temporary file generated by base::tempfile(). Calling this active binding repeatedly will yield different temporary file paths. Fixing the path to a specific value is possible by setting this active binding to a character string representing the desired path. Setting this active binding to NULL will reset it to the default value (i.e., yielding different temporary file paths).

Examples

# Set the default package options (i.e., automatically set at load time).
set_default_options()

# First, get the options instance from the session options.
parabar <- getOption("parabar")

# Then, disable progress tracking.
parabar$progress_track <- FALSE

# Check that the change was applied (i.e., `progress_track: FALSE`).
getOption("parabar")
#> <Options>
#>   Public:
#>     progress_bar_config: list
#>     progress_bar_type: modern
#>     progress_log_path: active binding
#>     progress_timeout: 0.001
#>     progress_track: FALSE
#>     progress_wait: 0.1
#>     stop_forceful: FALSE
#>   Private:
#>     .progress_log_path: NULL

# To restore defaults, set the default options again.
set_default_options()

# Check that the change was applied (i.e., `progress_track: TRUE`).
getOption("parabar")
#> <Options>
#>   Public:
#>     progress_bar_config: list
#>     progress_bar_type: modern
#>     progress_log_path: active binding
#>     progress_timeout: 0.001
#>     progress_track: TRUE
#>     progress_wait: 0.1
#>     stop_forceful: FALSE
#>   Private:
#>     .progress_log_path: NULL

# We can also use the built-in helpers to get and set options more conveniently.

# Get the progress tracking option.
get_option("progress_track")
#> [1] TRUE

# Set the progress tracking option to `FALSE`.
set_option("progress_track", FALSE)

# Check that the change was applied (i.e., `progress_track: FALSE`).
get_option("progress_track")
#> [1] FALSE

# Get a temporary file for logging the progress.
get_option("progress_log_path")
#> [1] "/tmp/RtmpdtNXoh/parabar1686257d3f3"

# Fix the logging file path.
set_option("progress_log_path", "./progress.log")

# Check that the logging path change was applied.
get_option("progress_log_path")
#> [1] "./progress.log"

# Restore the logging path to the default behavior.
set_option("progress_log_path", NULL)

# Check that the logging path change was applied.
get_option("progress_log_path")
#> [1] "/tmp/RtmpdtNXoh/parabar16863df6ec95"

# Restore the defaults.
set_default_options()