withr: with_ – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

with_

Create a new "with" or "local" function

Description

These are constructors for with_... or local_... functions. They are only needed if you want to alter some global state which is not covered by the existing with_... functions, see withr for an overview.

Usage

local_(set, reset = set, envir = parent.frame(), new = TRUE, dots = FALSE)

with_(set, reset = set, envir = parent.frame(), new = TRUE)

Arguments

`set`	`[function(...)]` Function used to set the state. The function can have arbitrarily many arguments, they will be replicated in the formals of the returned function.
`reset`	`[function(x)]` Function used to reset the state. The first argument can be named arbitrarily, further arguments with default values, or a "dots" argument, are supported but not used: The function will be called as `reset(old)`.
`envir`	`[environment]` Environment of the returned function.
`new`	`[logical(1)]` Replace the first argument of the `set` function by `new`? Set to `FALSE` if the `set` function only has optional arguments.

Details

The with_... functions reset the state immediately after the code argument has been evaluated. The local_... functions reset their arguments after they go out of scope, usually at the end of the function body.

Value

[function(new, code, ...)] A function with at least two arguments,

new: New state to use
code: Code to run in that state.

If there are more arguments to the function passed in set they are added to the returned function. If set does not have arguments, or new is FALSE, the returned function does not have a code argument.

Examples

with_(setwd)

global_stack <- list()
set_global_state <- function(state, msg = "Changing global state.") {
  global_stack <- c(list(state), global_stack)
  message(msg)
  state
}
reset_global_state <- function(state) {
  old_state <- global_stack[[1]]
  global_stack <- global_stack[-1]
  stopifnot(identical(state, old_state))
}
with_(set_global_state, reset_global_state)

withr

Run Code 'With' Temporarily Modified Global State

v2.4.2

MIT + file LICENSE

Authors

Jim Hester [aut, cre], Kirill Müller [aut], Kevin Ushey [aut], Hadley Wickham [aut], Winston Chang [aut], Jennifer Bryan [ctb], Richard Cotton [ctb], RStudio [cph]

Initial release