opt {options} | R Documentation |
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()
)
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.
|
check_names |
(experimental) A behavior used when checking option
names against specified options. Expects one of |
opts |
A |
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 optionaloption_fn
. Seeoption_spec()
for details. -
opt_set()
: Set an option's value. Additional...
arguments passed toget_option_spec()
. -
opt(x, ...) <- value
: An alias foropt_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 toon.exit()
. -
opts_list()
: Produce a named list of namespaced option values, for use withoptions()
andwithr
. 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)
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"))
define_options("print quietly", quiet = TRUE)
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)
options(orig_opts)
# using `withr` to manage temporary options
withr::with_options(opts_list(quiet = FALSE), print(example))