Inspecting Option Values

Usage

opt(x, default, env = parent.frame(), ...)

opt_set(x, value, env = parent.frame(), ...)

opt(x, ...) <- value

opt_source(x, env = parent.frame())

opts(xs = NULL, env = parent.frame())

opt_set_local(
  x,
  value,
  env = parent.frame(),
  ...,
  add = TRUE,
  after = FALSE,
  scope = parent.frame()
)

Arguments

x, xs: An option name, vector of option names, or a named list of new option values
default: A default value if the option is not set
env: An environment, namespace or package name to pull options from
...: Additional arguments unused
value: A new value to update the associated global option
add, after, scope: Passed to on.exit, with alternative defaults. scope is passed to the on.exit envir parameter to disambiguate it from env.

Value

For opt() and opts(); the result of the option (or a list of results), either the value from a global option, the result of processing the environment variable or the default value, depending on which of the alternative sources are defined.

For modifying functions (opt_set and opt<-: the value of the option prior to modification

For opt_source; the source that is used for a specific option, one of "option", "envir" or "default".

Functions

opt(): Retrieve an option
opt_set(): Set an option's value
opt(x, ...) <- value: An alias for opt_set
opt_source(): Determine source of option value. Primarily used for diagnosing options behaviors.
opts(): Retrieve multiple options. When no names are provided, return a list containing all options from a given environment. Accepts a character vector of option names or a named list of new values to modify global option values.
opt_set_local(): Set an option only in the local frame

Note

Local options are set with on.exit, which can be prone to error if subsequent calls are not called with add = TRUE (masking existing on.exit callbacks). A more rigorous alternative might make use of withr::defer.

old <- opt_set("option", value)
withr::defer(opt_set("option", old))

Examples

define_options("Whether execution should emit console output", quiet = FALSE)
#> 
#> quiet = FALSE
#> 
#>   Whether execution should emit console output
#> 
#>   option  : globalenv.quiet
#>   envvar  : R_GLOBALENV_QUIET (evaluated if possible, raw string otherwise)
#>  *default : FALSE
#> 
opt("quiet")
#> [1] FALSE

define_options("Whether execution should emit console output", quiet = FALSE)
#> 
#> quiet = FALSE
#> 
#>   Whether execution should emit console output
#> 
#>   option  : globalenv.quiet
#>   envvar  : R_GLOBALENV_QUIET (evaluated if possible, raw string otherwise)
#>  *default : FALSE
#> 
opt_source("quiet")
#> [1] "default"

Sys.setenv(R_GLOBALENV_QUIET = TRUE)
opt_source("quiet")
#> [1] "envir"

options(globalenv.quiet = FALSE)
opt_source("quiet")
#> [1] "option"

define_options("Quietly", quiet = TRUE, "Verbosity", verbose = FALSE)
#> 
#> quiet = TRUE
#> 
#>   Quietly
#> 
#>  *option  : globalenv.quiet
#>   envvar  : R_GLOBALENV_QUIET (evaluated if possible, raw string otherwise)
#>   default : TRUE
#> 
#> verbose = FALSE
#> 
#>   Verbosity
#> 
#>   option  : globalenv.verbose
#>   envvar  : R_GLOBALENV_VERBOSE (evaluated if possible, raw string otherwise)
#>  *default : FALSE
#> 

# retrieve multiple options
opts(c("quiet", "verbose"))
#> $quiet
#> [1] FALSE
#> 
#> $verbose
#> [1] FALSE
#> 

# update multiple options, returns unmodified values
opts(list(quiet = 42, verbose = TRUE))
#> $quiet
#> [1] TRUE
#> 
#> $verbose
#> [1] FALSE
#> 

# next time we check their values we'll see the modified values
opts(c("quiet", "verbose"))
#> $quiet
#> [1] 42
#> 
#> $verbose
#> [1] TRUE
#>