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