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()
)

opts_list(
  ...,
  env = parent.frame(),
  check_names = c("asis", "warn", "error"),
  opts = list(...)
)

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
...: See specific functions to see behavior.
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.
check_names: (experimental) A behavior used when checking option names against specified options. Expects one of "asis", "warn" or "stop".
opts: A list of values, for use in functions that accept ... arguments. In rare cases where your argument names conflict with other named arguments to these functions, you can specify them directly using this parameter.

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. Additional ... arguments passed to an optional option_fn. See option_spec() for details.
opt_set(): Set an option's value. Additional ... arguments passed to get_option_spec().
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. Additional ... arguments passed to on.exit().
opts_list(): Produce a named list of namespaced option values, for use with options() and withr. Additional ... arguments used to provide named option values.

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))

If you'd prefer to use this style, see opts_list(), which is designed to work nicely with withr.

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] "envvar"

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
#> 

define_options("print quietly", quiet = TRUE)
#> 
#> quiet = TRUE
#> 
#>   print 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
#> 

print.example <- function(x, ...) if (!opt("quiet")) NextMethod()
example <- structure("Hello, World!", class = "example")
print(example)

# using base R options to manage temporary options
orig_opts <- options(opts_list(quiet = FALSE))
print(example)
#> [1] "Hello, World!"
#> attr(,"class")
#> [1] "example"
options(orig_opts)

# using `withr` to manage temporary options
withr::with_options(opts_list(quiet = FALSE), print(example))
#> [1] "Hello, World!"
#> attr(,"class")
#> [1] "example"