Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

withr

Execute code in temporarily altered environment


Description

All functions prefixed by with_ work as follows. First, a particular aspect of the global environment is modified (see below for a list). Then, custom code (passed via the code argument) is executed. Upon completion or error, the global environment is restored to the previous state. Each with_ function has a local_ variant, which instead resets the state when the current evaluation context ends (such as the end of a function).

Arguments pattern

new [various] Values for setting
code [any] Code to execute in the temporary environment
... Further arguments

Usage pattern

with_...(new, code, ...)

withr functions

Creating new "with" functions

All with_ functions are created by a helper function, with_(). This functions accepts two arguments: a setter function and an optional resetter function. The setter function is expected to change the global state and return an "undo instruction". This undo instruction is then passed to the resetter function, which changes back the global state. In many cases, the setter function can be used naturally as resetter.

Author(s)

Maintainer: Jim Hester jim.hester@rstudio.com

Authors:

Other contributors:

  • Jennifer Bryan [contributor]

  • Richard Cotton [contributor]

  • RStudio [copyright holder]

See Also

Useful links:

Examples

getwd()
with_dir(tempdir(), getwd())
getwd()

Sys.getenv("WITHR")
with_envvar(c("WITHR" = 2), Sys.getenv("WITHR"))
Sys.getenv("WITHR")

with_envvar(c("A" = 1),
  with_envvar(c("A" = 2), action = "suffix", Sys.getenv("A"))
)

# local variants are best used within other functions
f <- function(x) {
  local_envvar(c("WITHR" = 2))
  Sys.getenv("WITHR")
}
Sys.getenv("WITHR")

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

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.