1#' Execute code in temporarily altered environment
2#'
3#' All functions prefixed by `with_` work as follows. First, a particular
4#' aspect of the global environment is modified (see below for a list).
5#' Then, custom code (passed via the `code` argument) is executed.
6#' Upon completion or error, the global environment is restored to the previous
7#' state. Each `with_` function has a `local_` variant, which instead resets
8#' the state when the current evaluation context ends (such as the end of a
9#' function).
10#'
11#' @section Arguments pattern:
12#' \tabular{lll}{
13#'   `new` \tab `[various]` \tab Values for setting \cr
14#'   `code` \tab `[any]` \tab Code to execute in the temporary environment \cr
15#'   `...` \tab \tab Further arguments \cr
16#' }
17#' @section Usage pattern:
18#' `with_...(new, code, ...)`
19#' @name withr
20#' @docType package
21#' @section withr functions:
22#' \itemize{
23#' \item [with_collate()]: collation order
24#' \item [with_dir()]: working directory
25#' \item [with_envvar()]: environment variables
26#' \item [with_libpaths()]: library paths, replacing current libpaths
27#' \item [with_locale()]: any locale setting
28#' \item [with_makevars()]: Makevars variables
29#' \item [with_options()]: options
30#' \item [with_par()]: graphics parameters
31#' \item [with_path()]: `PATH` environment variable
32#' \item [with_sink()]: output redirection
33#' }
34#' @section Creating new "with" functions:
35#' All `with_` functions are created by a helper function,
36#' [with_()].  This functions accepts two arguments:
37#' a setter function and an optional resetter function.  The setter function is
38#' expected to change the global state and return an "undo instruction".
39#' This undo instruction is then passed to the resetter function, which changes
40#' back the global state. In many cases, the setter function can be used
41#' naturally as resetter.
42#' @examples
43#' getwd()
44#' with_dir(tempdir(), getwd())
45#' getwd()
46#'
47#' Sys.getenv("WITHR")
48#' with_envvar(c("WITHR" = 2), Sys.getenv("WITHR"))
49#' Sys.getenv("WITHR")
50#'
51#' with_envvar(c("A" = 1),
52#'   with_envvar(c("A" = 2), action = "suffix", Sys.getenv("A"))
53#' )
54#'
55#' # local variants are best used within other functions
56#' f <- function(x) {
57#'   local_envvar(c("WITHR" = 2))
58#'   Sys.getenv("WITHR")
59#' }
60#' Sys.getenv("WITHR")
61"_PACKAGE"
62