rlang (version 1.1.2)

local_options: Change global options

Description

• local_options() changes options for the duration of a stack frame (by default the current one). Options are set back to their old values when the frame returns.

• with_options() changes options while an expression is evaluated. Options are restored when the expression returns.

• push_options() adds or changes options permanently.

• peek_option() and peek_options() return option values. The former returns the option directly while the latter returns a list.

Usage

local_options(..., .frame = caller_env())
with_options(.expr, ...)
push_options(...)
peek_options(...)
peek_option(name)

Value

For local_options() and push_options(), the old option values. peek_option() returns the current value of an option while the plural peek_options() returns a list of current option values.

Arguments

...

For local_options() and push_options(), named values defining new option values. For peek_options(), strings or character vectors of option names.

.frame

The environment of a stack frame which defines the scope of the temporary options. When the frame returns, the options are set back to their original values.

.expr

An expression to evaluate with temporary options.

name

An option name as string.

Life cycle

These functions are experimental.

Examples

# Store and retrieve a global option:
push_options(my_option = 10)
peek_option("my_option")

# Change the option temporarily:
with_options(my_option = 100, peek_option("my_option"))
peek_option("my_option")

# The scoped variant is useful within functions:
fn <- function() {
  local_options(my_option = 100)
  peek_option("my_option")
}
fn()
peek_option("my_option")

# The plural peek returns a named list:
peek_options("my_option")
peek_options("my_option", "digits")