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

Usage pattern

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

withr functions

• with_collate(): collation order

• with_dir(): working directory

• with_envvar(): environment variables

• with_libpaths(): library paths, replacing current libpaths

• with_locale(): any locale setting

• with_makevars(): Makevars variables

• with_options(): options

• with_par(): graphics parameters

• with_path(): PATH environment variable

• with_sink(): output redirection

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: Lionel Henry lionel@posit.co

Authors:

• Jim Hester

• Kirill Müller krlmlr+r@mailbox.org

• Kevin Ushey kevinushey@gmail.com

• Hadley Wickham hadley@posit.co

• Winston Chang

Other contributors:

• Jennifer Bryan [contributor]

• Richard Cotton [contributor]

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://withr.r-lib.org

• https://github.com/r-lib/withr#readme

• Report bugs at https://github.com/r-lib/withr/issues

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

Defer Evaluation of an Expression

Description

Similar to on.exit(), but allows one to attach an expression to be evaluated when exiting any frame currently on the stack. This provides a nice mechanism for scoping side effects for the duration of a function's execution.

Usage

defer(expr, envir = parent.frame(), priority = c("first", "last"))

defer_parent(expr, priority = c("first", "last"))

deferred_run(envir = parent.frame())

deferred_clear(envir = parent.frame())

Arguments

Details

defer() works by attaching handlers to the requested environment (as an attribute called "handlers"), and registering an exit handler that executes the registered handler when the function associated with the requested environment finishes execution.

Deferred events can be set on the global environment, primarily to facilitate the interactive development of code that is intended to be executed inside a function or test. A message alerts the user to the fact that an explicit deferred_run() is the only way to trigger these deferred events. Use deferred_clear() to clear them without evaluation. The global environment scenario is the main motivation for these functions.

Running handlers within source()

withr handlers run within source() are run when source() exits rather than line by line.

This is only the case when the script is sourced in globalenv(). For a local environment, the caller needs to set options(withr.hook_source = TRUE). This is to avoid paying the penalty of detecting source() in the normal usage of defer().

Examples

# define a 'local' function that creates a file, and
# removes it when the parent function has finished executing
local_file <- function(path) {
  file.create(path)
  defer_parent(unlink(path))
}

# create tempfile path
path <- tempfile()

# use 'local_file' in a function
local({
  local_file(path)
  stopifnot(file.exists(path))
})

# file is deleted as we leave 'local' local
stopifnot(!file.exists(path))

# investigate how 'defer' modifies the
# executing function's environment
local({
  local_file(path)
  print(attributes(environment()))
})

# Note that examples lack function scoping so deferred calls are
# generally executed immediately
defer(print("one"))
defer(print("two"))

Graphics devices

Description

Temporarily use a graphics device.

Usage

with_bmp(new, code, ...)

local_bmp(new, ..., .local_envir = parent.frame())

with_cairo_pdf(new, code, ...)

local_cairo_pdf(new, ..., .local_envir = parent.frame())

with_cairo_ps(new, code, ...)

local_cairo_ps(new, ..., .local_envir = parent.frame())

with_pdf(new, code, ...)

local_pdf(new, ..., .local_envir = parent.frame())

with_postscript(new, code, ...)

local_postscript(new, ..., .local_envir = parent.frame())

with_svg(new, code, ...)

local_svg(new, ..., .local_envir = parent.frame())

with_tiff(new, code, ...)

local_tiff(new, ..., .local_envir = parent.frame())

with_xfig(new, code, ...)

local_xfig(new, ..., .local_envir = parent.frame())

with_png(new, code, ...)

local_png(new, ..., .local_envir = parent.frame())

with_jpeg(new, code, ...)

local_jpeg(new, ..., .local_envir = parent.frame())

Arguments

Details

• with_bmp() and local_bmp() wrap around grDevices::bmp().

• with_cairo_pdf() and local_cairo_pdf() wrap around grDevices::cairo_pdf().

• with_cairo_ps() and local_cairo_ps() wrap around grDevices::cairo_ps().

• with_pdf() and local_pdf() wrap around grDevices::pdf().

• with_postscript() and local_postscript() wrap around grDevices::postscript().

• with_svg() and local_svg() wrap around grDevices::svg().

• with_tiff() and local_tiff() wrap around grDevices::tiff().

• with_xfig() and local_xfig() wrap around grDevices::xfig().

• with_png() and local_png() wrap around grDevices::png().

• with_jpeg() and local_jpeg() wrap around grDevices::jpeg().

Value

[any]
The results of the evaluation of the code argument.

Functions

• with_bmp(): BMP device

• with_cairo_pdf(): CAIRO_PDF device

• with_cairo_ps(): CAIRO_PS device

• with_pdf(): PDF device

• with_postscript(): POSTSCRIPT device

• with_svg(): SVG device

• with_tiff(): TIFF device

• with_xfig(): XFIG device

• with_png(): PNG device

• with_jpeg(): JPEG device

See Also

withr for examples

Devices

Examples

# dimensions are in inches
with_pdf(file.path(tempdir(), "test.pdf"), width = 7, height = 5,
  plot(runif(5))
)

# dimensions are in pixels
with_png(file.path(tempdir(), "test.png"), width = 800, height = 600,
  plot(runif(5))
)

Defer expression globally

Description

This function is mostly internal. It is exported to be called in standalone defer() implementations to defer expressions from the global environment.

Usage

global_defer(expr, priority = c("first", "last"))

Arguments

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,
  get = NULL,
  ...,
  envir = parent.frame(),
  new = TRUE,
  dots = FALSE
)

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

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)

Shim for tools::makevars_user()

Description

Shim for tools::makevars_user()

Usage

makevars_user()

Create a new Makevars file, by adding new variables

Description

You probably want with_makevars() instead of this function.

Usage

set_makevars(
  variables,
  old_path = makevars_user(),
  new_path = tempfile(),
  assignment = c("=", ":=", "?=", "+=")
)

Arguments

Details

Unlike with_makevars(), it does not activate the new Makevars file, i.e. it does not set the R_MAKEVARS_USER environment variable.

Collation Order

Description

Temporarily change collation order by changing the value of the LC_COLLATE locale.

Usage

with_collate(new, code)

local_collate(new = list(), .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

Examples

# Modify collation order:
x <- c("bernard", "bérénice", "béatrice", "boris")

with_collate("fr_FR", sort(x))
#> [1] "béatrice" "bérénice" "bernard"  "boris"   

with_collate("C", sort(x))
#> [1] "bernard"  "boris"    "béatrice" "bérénice"

See Also

withr for examples

Connections which close themselves

Description

R file connections which are automatically closed.

Usage

with_connection(con, code)

local_connection(con, .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Examples

with_connection(list(con = file("foo", "w")), {
  writeLines(c("foo", "bar"), con)
})

read_foo <- function() {
  readLines(local_connection(file("foo", "r")))
}
read_foo()

unlink("foo")

DBMS Connections which disconnect themselves.

Description

Connections to Database Management Systems which automatically disconnect. In particular connections which are created with DBI::dbConnect() and closed with DBI::dbDisconnect().

Usage

with_db_connection(con, code)

local_db_connection(con, .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Examples

db <- tempfile()
with_db_connection(
  list(con = DBI::dbConnect(RSQLite::SQLite(), db)), {
    DBI::dbWriteTable(con, "mtcars", mtcars)
})

head_db_table <- function(...) {
  con <- local_db_connection(DBI::dbConnect(RSQLite::SQLite(), db))
  head(DBI::dbReadTable(con, "mtcars"), ...)
}
head_db_table()
unlink(db)

Working directory

Description

Temporarily change the current working directory.

Usage

with_dir(new, code)

local_dir(new = list(), .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

setwd()

Examples

getwd()

with_dir(tempdir(), getwd())

Environment variables

Description

Temporarily change system environment variables.

Usage

with_envvar(new, code, action = "replace")

local_envvar(
  .new = list(),
  ...,
  action = "replace",
  .local_envir = parent.frame()
)

Arguments

Details

if NA is used those environment variables will be unset. If there are any duplicated variable names only the last one is used.

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Sys.setenv()

Examples

with_envvar(new = c("GITHUB_PAT" = "abcdef"), Sys.getenv("GITHUB_PAT"))

# with_envvar unsets variables after usage
Sys.getenv("TEMP_SECRET")
with_envvar(new = c("TEMP_SECRET" = "secret"), Sys.getenv("TEMP_SECRET"))
Sys.getenv("TEMP_SECRET")

Files which delete themselves

Description

Create files, which are then automatically removed afterwards.

Usage

with_file(file, code)

local_file(.file, ..., .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Examples

with_file("file1", {
  writeLines("foo", "file1")
  readLines("file1")
})

with_file(list("file1" = writeLines("foo", "file1")), {
  readLines("file1")
})

Torture Garbage Collector

Description

Temporarily turn gctorture2 on.

Usage

with_gctorture2(new, code, wait = new, inhibit_release = FALSE)

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Language

Description

Temporarily change the language used for translations.

Usage

with_language(lang, code)

local_language(lang, .local_envir = parent.frame())

Arguments

Examples

with_language("en", try(mean[[1]]))
with_language("fr", try(mean[[1]]))
with_language("es", try(mean[[1]]))

Library paths

Description

Temporarily change library paths.

Usage

with_libpaths(new, code, action = "replace")

local_libpaths(new = list(), action = "replace", .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

.libPaths()

Other libpaths: with_temp_libpaths()

Examples

.libPaths()
new_lib <- tempfile()
dir.create(new_lib)
with_libpaths(new_lib, print(.libPaths()))
unlink(new_lib, recursive = TRUE)

Locale settings

Description

Temporarily change locale settings.

Usage

with_locale(new, code)

local_locale(.new = list(), ..., .local_envir = parent.frame())

Arguments

Details

Setting the LC_ALL category is currently not implemented.

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Sys.setlocale()

Examples

## Change locale for time:
df <- data.frame(
  stringsAsFactors = FALSE,
  date = as.Date(c("2019-01-01", "2019-02-01")),
  value = c(1, 2)
)
with_locale(new = c("LC_TIME" = "es_ES"), code = plot(df$date, df$value))
## Compare with:
#  plot(df$date, df$value)

## Month names:
with_locale(new = c("LC_TIME" = "en_GB"), format(ISOdate(2000, 1:12, 1), "%B"))
with_locale(new = c("LC_TIME" = "es_ES"), format(ISOdate(2000, 1:12, 1), "%B"))

## Change locale for currencies:
with_locale(new = c("LC_MONETARY" = "it_IT"), Sys.localeconv())
with_locale(new = c("LC_MONETARY" = "en_US"), Sys.localeconv())

## Ordering:
x <- c("bernard", "bérénice", "béatrice", "boris")
with_locale(c(LC_COLLATE = "fr_FR"), sort(x))
with_locale(c(LC_COLLATE = "C"), sort(x))

Makevars variables

Description

Temporarily change contents of an existing Makevars file.

Usage

with_makevars(
  new,
  code,
  path = makevars_user(),
  assignment = c("=", ":=", "?=", "+=")
)

local_makevars(
  .new = list(),
  ...,
  .path = makevars_user(),
  .assignment = c("=", ":=", "?=", "+="),
  .local_envir = parent.frame()
)

Arguments

Details

If no Makevars file exists or the fields in new do not exist in the existing Makevars file then the fields are added to the new file. Existing fields which are not included in new are appended unchanged. Fields which exist in Makevars and in new are modified to use the value in new.

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Examples

writeLines("void foo(int* bar) { *bar = 1; }\n", "foo.c")
system("R CMD SHLIB --preclean -c foo.c")
with_makevars(c(CFLAGS = "-O3"), system("R CMD SHLIB --preclean -c foo.c"))
unlink(c("foo.c", "foo.so"))

Options

Description

Temporarily change global options.

Usage

with_options(new, code)

local_options(.new = list(), ..., .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

options()

Examples

# number of significant digits to print
getOption("digits")
# modify temporarily the number of significant digits to print
with_options(list(digits = 3), getOption("digits"))
with_options(list(digits = 3), print(pi))

# modify temporarily the character to be used as the decimal point
getOption("digits")
with_options(list(OutDec = ","), print(pi))

# modify temporarily multiple options
with_options(list(OutDec = ",", digits = 3), print(pi))

# modify, within the scope of the function, the number of
# significant digits to print
print_3_digits <- function(x) {
  # assign 3 to the option "digits" for the rest of this function
  # after the function exits, the option will return to its previous
  # value
  local_options(list(digits = 3))
  print(x)
}

print_3_digits(pi)  # returns 3.14
print(pi)           # returns 3.141593

Execute code with a modified search path

Description

with_package() attaches a package to the search path, executes the code, then removes the package from the search path. The package namespace is not unloaded however. with_namespace() does the same thing, but attaches the package namespace to the search path, so all objects (even unexported ones) are also available on the search path.

Usage

with_package(
  package,
  code,
  pos = 2,
  lib.loc = NULL,
  character.only = TRUE,
  logical.return = FALSE,
  warn.conflicts = FALSE,
  quietly = TRUE,
  verbose = getOption("verbose")
)

local_package(
  package,
  pos = 2,
  lib.loc = NULL,
  character.only = TRUE,
  logical.return = FALSE,
  warn.conflicts = FALSE,
  quietly = TRUE,
  verbose = getOption("verbose"),
  .local_envir = parent.frame()
)

with_namespace(package, code, warn.conflicts = FALSE)

local_namespace(package, .local_envir = parent.frame(), warn.conflicts = FALSE)

with_environment(
  env,
  code,
  pos = 2L,
  name = format(env),
  warn.conflicts = FALSE
)

local_environment(
  env,
  pos = 2L,
  name = format(env),
  warn.conflicts = FALSE,
  .local_envir = parent.frame()
)

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Examples

## Not run: 
with_package("ggplot2", {
  ggplot(mtcars) + geom_point(aes(wt, hp))
})

## End(Not run)

Graphics parameters

Description

Temporarily change graphics parameters.

Usage

with_par(new, code, no.readonly = FALSE)

local_par(
  .new = list(),
  ...,
  no.readonly = FALSE,
  .local_envir = parent.frame()
)

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

par()

Examples

old <- par("col" = "black")

# This will be in red
with_par(list(col = "red", pch = 19),
  plot(mtcars$hp, mtcars$wt)
)

# This will still be in black
plot(mtcars$hp, mtcars$wt)

par(old)

PATH environment variable

Description

Temporarily change the system search path.

Usage

with_path(new, code, action = c("prefix", "suffix", "replace"))

local_path(
  new = list(),
  action = c("prefix", "suffix", "replace"),
  .local_envir = parent.frame()
)

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Sys.setenv()

Examples

# temporarily modify the system PATH, *prefixing* the current path
with_path(getwd(), Sys.getenv("PATH"))
# temporarily modify the system PATH, *appending* to the current path
with_path(getwd(), Sys.getenv("PATH"), "suffix")

RNG version

Description

Change the RNG version and restore it afterwards.

Usage

with_rng_version(version, code)

local_rng_version(version, .local_envir = parent.frame())

Arguments

Details

with_rng_version() runs the code with the specified RNG version and resets it afterwards.

local_rng_version() changes the RNG version for the caller execution environment.

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

RNGversion(), RNGkind(), with_seed().

Examples

RNGkind()
with_rng_version("3.0.0", RNGkind())
with_rng_version("1.6.0", RNGkind())

with_rng_version("3.0.0",
  with_seed(42, sample(1:100, 3)))

with_rng_version("1.6.0",
  with_seed(42, sample(1:100, 3)))

RNGkind()

fun1 <- function() {
  local_rng_version("3.0.0")
  with_seed(42, sample(1:100, 3))
}

fun2 <- function() {
  local_rng_version("1.6.0")
  with_seed(42, sample(1:100, 3))
}

RNGkind()
fun1()
fun2()
RNGkind()

Random seed

Description

with_seed() runs code with a specific random seed and resets it afterwards.

with_preserve_seed() runs code with the current random seed and resets it afterwards.

Usage

with_seed(
  seed,
  code,
  .rng_kind = NULL,
  .rng_normal_kind = NULL,
  .rng_sample_kind = NULL
)

local_seed(
  seed,
  .local_envir = parent.frame(),
  .rng_kind = NULL,
  .rng_normal_kind = NULL,
  .rng_sample_kind = NULL
)

with_preserve_seed(code)

local_preserve_seed(.local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Examples

# Same random values:
with_preserve_seed(runif(5))
with_preserve_seed(runif(5))

# Use a pseudorandom value as seed to advance the RNG and pick a different
# value for the next call:
with_seed(seed <- sample.int(.Machine$integer.max, 1L), runif(5))
with_seed(seed, runif(5))
with_seed(seed <- sample.int(.Machine$integer.max, 1L), runif(5))

Output redirection

Description

Temporarily divert output to a file via sink(). For sinks of type message, an error is raised if such a sink is already active.

Usage

with_output_sink(new, code, append = FALSE, split = FALSE)

local_output_sink(
  new = list(),
  append = FALSE,
  split = FALSE,
  .local_envir = parent.frame()
)

with_message_sink(new, code, append = FALSE)

local_message_sink(new = list(), append = FALSE, .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

sink()

Library paths

Description

Temporarily prepend a new temporary directory to the library paths.

Usage

with_temp_libpaths(code, action = "prefix")

local_temp_libpaths(action = "prefix", .local_envir = parent.frame())

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

.libPaths()

Other libpaths: with_libpaths()

Temporary files and directories

Description

Temporarily create a file or directory, which will automatically deleted once you're finished with it.

Usage

with_tempfile(
  new,
  code,
  envir = parent.frame(),
  .local_envir = parent.frame(),
  pattern = "file",
  tmpdir = tempdir(),
  fileext = ""
)

local_tempfile(
  new = NULL,
  lines = NULL,
  envir = parent.frame(),
  .local_envir = parent.frame(),
  pattern = "file",
  tmpdir = tempdir(),
  fileext = ""
)

with_tempdir(
  code,
  clean = TRUE,
  pattern = "file",
  tmpdir = tempdir(),
  fileext = ""
)

local_tempdir(
  pattern = "file",
  tmpdir = tempdir(),
  fileext = "",
  .local_envir = parent.frame(),
  clean = TRUE
)

Arguments

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Examples

# local_tempfile() is the easiest to use because it returns a path
local({
  path1 <<- local_tempfile(lines = c("x,y", "1,2"))
  readLines(path1)
})
# the file is deleted automatically
file.exists(path1)

# with_tempfile() is a bit trickier; the first argument gives the name
# of a variable that will contain the path:
with_tempfile("path2", {
  print(path2)
  write.csv(iris, path2)
  file.size(path2)
})

# Note that this variable is only available in the scope of with_tempfile
try(path2)

Time zone

Description

Change the time zone, and restore it afterwards.

Usage

with_timezone(tz, code)

local_timezone(tz, .local_envir = parent.frame())

Arguments

Details

with_timezone() runs the code with the specified time zone and resets it afterwards.

local_timezone() changes the time zone for the caller execution environment.

Value

[any]
The results of the evaluation of the code argument.

See Also

withr for examples

Sys.timezone().

Examples

Sys.time()
with_timezone("Europe/Paris", print(Sys.time()))
with_timezone("America/Los_Angeles", print(Sys.time()))

fun1 <- function() {
  local_timezone("CET")
  print(Sys.time())
}

fun2 <- function() {
  local_timezone("America/Los_Angeles")
  print(Sys.time())
}
Sys.time()
fun1()
fun2()
Sys.time()