{"id":13857432,"url":"https://github.com/r-lib/withr","last_synced_at":"2026-01-12T00:42:36.263Z","repository":{"id":30790321,"uuid":"34347294","full_name":"r-lib/withr","owner":"r-lib","description":"Methods For Temporarily Modifying Global State","archived":false,"fork":false,"pushed_at":"2025-02-25T09:45:15.000Z","size":8875,"stargazers_count":176,"open_issues_count":23,"forks_count":39,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-30T20:00:40.610Z","etag":null,"topics":["r"],"latest_commit_sha":null,"homepage":"http://withr.r-lib.org","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-lib.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-21T19:18:28.000Z","updated_at":"2025-03-22T08:13:10.000Z","dependencies_parsed_at":"2022-08-07T15:47:31.252Z","dependency_job_id":"57f988f2-6d80-422e-9645-f7f977c8d51e","html_url":"https://github.com/r-lib/withr","commit_stats":{"total_commits":521,"total_committers":36,"mean_commits":"14.472222222222221","dds":0.5527831094049904,"last_synced_commit":"334415234c4b049d125c1a0b47a20d682daef9ad"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fwithr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fwithr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fwithr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fwithr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-lib","download_url":"https://codeload.github.com/r-lib/withr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247550667,"owners_count":20956985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["r"],"created_at":"2024-08-05T03:01:36.858Z","updated_at":"2025-04-06T21:00:29.233Z","avatar_url":"https://github.com/r-lib.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput:\n  github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, echo = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\nknitr::opts_knit$set(root.dir = tempdir())\nlibrary(withr)\n```\n\n# withr - run code 'with' modified state \u003cimg src=\"man/figures/logo.png\" align=\"right\" /\u003e\n\n\u003c!-- badges: start --\u003e\n[![Codecov test coverage](https://codecov.io/gh/r-lib/withr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/withr?branch=main)\n[![CRAN Version](https://www.r-pkg.org/badges/version/withr)](https://www.r-pkg.org/pkg/withr)\n[![R-CMD-check](https://github.com/r-lib/withr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/withr/actions/workflows/R-CMD-check.yaml)\n\u003c!-- badges: end --\u003e\n\n## Overview\n\nA set of functions to run code with safely and temporarily modified global state, withr makes working with the global state, i.e. side effects, less error-prone. \n\nPure functions, such as the `sum()` function, are easy to understand and reason about: they always map the same input to the same output and have no other impact on the workspace. In other words, pure functions have no *side effects*: they are not affected by, nor do they affect, the global state in any way apart from the value they return. \n\nThe behavior of some functions *is* affected by the global state. Consider the `read.csv()` function: it takes a filename as an input and returns the contents as an output. In this case, the output depends on the contents of the file; i.e. the output is affected by the global state. Functions like this deal with side effects.\n\nThe purpose of the withr package is to help you manage side effects in your code. You may want to run code with secret information, such as an API key, that you store as an environment variable. You may also want to run code with certain options, with a given random-seed, or with a particular working-directory. \n\nThe withr package helps you manage these situations, and more, by providing functions to modify the global state temporarily, and safely. These functions modify one of the global settings for duration of a block of code, then automatically reset it after the block is completed.\n\n## Installation\n\n```{r, eval = FALSE}\n#Install the latest version with:\ninstall.packages(\"withr\")\n```\n\nMany of these functions were originally a part of the [devtools][] package,\nthis provides a simple package with limited dependencies to provide access to\nthese functions.\n\n- `with_collate()` / `local_collate()` - collation order\n- `with_dir()` / `local_dir()` - working directory\n- `with_envvar()` / `local_envvar()` - environment variables\n- `with_libpaths()` / `local_libpaths()` - library paths\n- `with_locale()` / `local_locale()` - any locale setting\n- `with_makevars()` / `local_makevars()` / `set_makevars()` - makevars variables\n- `with_options()` / `local_options()` - options\n- `with_par()` / `local_par()` - graphics parameters\n- `with_path()` / `local_path()` - PATH environment variable\n- `with_*()` and `local_*()` functions for the built in R devices, `bmp`,\n  `cairo_pdf`, `cairo_ps`, `pdf`, `postscript`, `svg`, `tiff`, `xfig`, `png`,\n  `jpeg`.\n- `with_connection()` / `local_connection()` - R file connections\n- `with_db_connection()` / `local_db_connection()` - DB connections\n- `with_package()` / `local_package()`, `with_namespace()` / `local_namespace()` and `with_environment()` / `local_environment()` - to run code\n  with modified object search paths.\n- `with_tempfile()` / `local_tempfile()` - create and clean up a temp file.\n- `with_file()` / `local_file()` - create and clean up a normal file.\n- `with_message_sink()` / `local_message_sink()` - divert message\n- `with_output_sink()` / `local_output_sink()` - divert output\n- `with_preserve_seed()` / `with_seed()`- specify seeds \n- `with_temp_libpaths()` / `local_temp_libpaths()` - library paths\n- `defer()` / `defer_parent()` - defer\n- `with_timezone()` / `local_timezone()` - timezones\n- `with_rng_version()` / `local_rng_version()` - random number generation version\n\n\n## Usage\n\nThere are two sets of functions, those prefixed with `with_` and those\nwith `local_`. The former reset their state as soon as the `code` argument has\nbeen evaluated. The latter reset when they reach the end of their scope,\nusually at the end of a function body.\n\n```{r}\npar(\"col\" = \"black\")\nmy_plot \u003c- function(new) {\n  with_par(list(col = \"red\", pch = 19),\n    plot(mtcars$hp, mtcars$wt)\n  )\n  par(\"col\")\n}\nmy_plot()\npar(\"col\")\n\nf \u003c- function(x) {\n  local_envvar(c(\"WITHR\" = 2))\n  Sys.getenv(\"WITHR\")\n}\n\nf()\nSys.getenv(\"WITHR\")\n```\n\n\nThere are also `with_()` and `local_()` functions to construct new `with_*`\nand `local_*` functions if needed.\n```{r}\nSys.getenv(\"WITHR\")\nwith_envvar(c(\"WITHR\" = 2), Sys.getenv(\"WITHR\"))\nSys.getenv(\"WITHR\")\n\nwith_envvar(c(\"A\" = 1),\n  with_envvar(c(\"A\" = 2), action = \"suffix\", Sys.getenv(\"A\"))\n)\n```\n\n\n# See Also #\n- [Devtools][devtools]\n\n[devtools]: https://github.com/r-lib/devtools\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fwithr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-lib%2Fwithr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fwithr/lists"}