opt {options}

Inspecting Option Values

Description

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 passed to an optional option_fn. See option_spec() for details.

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", "envvar" 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)
opt("quiet")

define_options("Whether execution should emit console output", quiet = FALSE)
opt_source("quiet")

Sys.setenv(R_GLOBALENV_QUIET = TRUE)
opt_source("quiet")

options(globalenv.quiet = FALSE)
opt_source("quiet")

define_options("Quietly", quiet = TRUE, "Verbosity", verbose = FALSE)

# retrieve multiple options
opts(c("quiet", "verbose"))

# update multiple options, returns unmodified values
opts(list(quiet = 42, verbose = TRUE))

# next time we check their values we'll see the modified values
opts(c("quiet", "verbose"))