Data

Tools

Indexes

Applications

Experiments

Open Source Science

withr

Methods For Temporarily Modifying Global State

https://github.com/r-lib/withr

Science Score: 23.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ○
    .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    2 of 33 committers (6.1%) from academic institutions
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (19.1%) to scientific vocabulary

Keywords

r

Keywords from Contributors

tidy-data data-manipulation documentation-tool visualisation grammar setup unit-testing parsing csv fwf
Last synced: 10 months ago · JSON representation

Repository

Methods For Temporarily Modifying Global State

Basic Info
  • Host: GitHub
  • Owner: r-lib
  • License: other
  • Language: R
  • Default Branch: main
  • Homepage: http://withr.r-lib.org
  • Size: 8.46 MB
Statistics
  • Stars: 178
  • Watchers: 6
  • Forks: 40
  • Open Issues: 24
  • Releases: 16
Topics
r
Created about 11 years ago · Last pushed over 1 year ago
Metadata Files
Readme Changelog License

README.Rmd 

---
output:
  github_document
---



```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
knitr::opts_knit$set(root.dir = tempdir())
library(withr)
```

# withr - run code 'with' modified state 


[![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)
[![CRAN Version](https://www.r-pkg.org/badges/version/withr)](https://www.r-pkg.org/pkg/withr)
[![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)


## Overview

A 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. 

Pure 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. 

The 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.

The 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. 

The 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.

## Installation

```{r, eval = FALSE}
#Install the latest version with:
install.packages("withr")
```

Many of these functions were originally a part of the [devtools][] package,
this provides a simple package with limited dependencies to provide access to
these functions.

- `with_collate()` / `local_collate()` - collation order
- `with_dir()` / `local_dir()` - working directory
- `with_envvar()` / `local_envvar()` - environment variables
- `with_libpaths()` / `local_libpaths()` - library paths
- `with_locale()` / `local_locale()` - any locale setting
- `with_makevars()` / `local_makevars()` / `set_makevars()` - makevars variables
- `with_options()` / `local_options()` - options
- `with_par()` / `local_par()` - graphics parameters
- `with_path()` / `local_path()` - PATH environment variable
- `with_*()` and `local_*()` functions for the built in R devices, `bmp`,
  `cairo_pdf`, `cairo_ps`, `pdf`, `postscript`, `svg`, `tiff`, `xfig`, `png`,
  `jpeg`.
- `with_connection()` / `local_connection()` - R file connections
- `with_db_connection()` / `local_db_connection()` - DB connections
- `with_package()` / `local_package()`, `with_namespace()` / `local_namespace()` and `with_environment()` / `local_environment()` - to run code
  with modified object search paths.
- `with_tempfile()` / `local_tempfile()` - create and clean up a temp file.
- `with_file()` / `local_file()` - create and clean up a normal file.
- `with_message_sink()` / `local_message_sink()` - divert message
- `with_output_sink()` / `local_output_sink()` - divert output
- `with_preserve_seed()` / `with_seed()`- specify seeds 
- `with_temp_libpaths()` / `local_temp_libpaths()` - library paths
- `defer()` / `defer_parent()` - defer
- `with_timezone()` / `local_timezone()` - timezones
- `with_rng_version()` / `local_rng_version()` - random number generation version


## Usage

There are two sets of functions, those prefixed with `with_` and those
with `local_`. The former reset their state as soon as the `code` argument has
been evaluated. The latter reset when they reach the end of their scope,
usually at the end of a function body.

```{r}
par("col" = "black")
my_plot <- function(new) {
  with_par(list(col = "red", pch = 19),
    plot(mtcars$hp, mtcars$wt)
  )
  par("col")
}
my_plot()
par("col")

f <- function(x) {
  local_envvar(c("WITHR" = 2))
  Sys.getenv("WITHR")
}

f()
Sys.getenv("WITHR")
```


There are also `with_()` and `local_()` functions to construct new `with_*`
and `local_*` functions if needed.
```{r}
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"))
)
```


# See Also #
- [Devtools][devtools]

[devtools]: https://github.com/r-lib/devtools

Owner

  • Name: R infrastructure
  • Login: r-lib
  • Kind: organization

GitHub Events

Total
  • Create event: 2
  • Release event: 1
  • Issues event: 11
  • Watch event: 5
  • Delete event: 1
  • Issue comment event: 11
  • Push event: 6
  • Pull request event: 4
  • Fork event: 1
Last Year
  • Create event: 2
  • Release event: 1
  • Issues event: 11
  • Watch event: 5
  • Delete event: 1
  • Issue comment event: 11
  • Push event: 6
  • Pull request event: 4
  • Fork event: 1

Committers

Last synced: 12 months ago

All Time
  • Total Commits: 547
  • Total Committers: 33
  • Avg Commits per committer: 16.576
  • Development Distribution Score (DDS): 0.574
Past Year
  • Commits: 26
  • Committers: 3
  • Avg Commits per committer: 8.667
  • Development Distribution Score (DDS): 0.5
Top Committers
Name Email Commits
Jim Hester j****r@g****m 233
Lionel Henry l****y@g****m 135
Kirill Müller k****r@i****h 72
Hadley Wickham h****m@g****m 40
Kirill Müller k****r@m****g 14
Jenny Bryan j****n@g****m 11
Richard Cotton r****3@q****u 7
Gábor Csárdi c****r@g****m 5
Michael Chirico c****m@g****m 4
Alessandro Gasparini l****n@g****m 2
Ciprian Alexandru a****o@y****m 2
Siddhartha Bagaria s****a@g****m 1
Angeline Protacio g****b@a****m 1
AshesITR r****t@y****e 1
Davis Vaughan d****s@p****o 1
Derrick Kearney 8****d 1
Dragoș Moldovan-Grünfeld d****d@g****m 1
Ho Bich Hai h****i@g****m 1
Ildiko Czeller c****i@g****m 1
Javier Luraschi j****i@h****m 1
Jonathan Keane j****e@g****m 1
Kathleen Wendt 4****e 1
Kyle Meyer k****e@k****m 1
Laura Acion 1****n 1
Manuel López-Ibáñez 2****z 1
Mara Averick m****k@g****m 1
Marcela Alfaro Córdoba m****a@u****r 1
Maria Paula Caldas 3****s 1
Martin Morgan m****n@r****g 1
Michael Milton t****t@g****m 1
and 3 more...
Committer Domains (Top 20 + Academic)
purrple.cat: 1 roswellpark.org: 1 ucr.ac.cr: 1 kyleam.com: 1 posit.co: 1 yahoo.de: 1 angelineprotacio.com: 1 grailbio.com: 1 google.com: 1 qatar-med.cornell.edu: 1 mailbox.org: 1 ivt.baug.ethz.ch: 1

Issues and Pull Requests

Last synced: 10 months ago

All Time
  • Total issues: 98
  • Total pull requests: 60
  • Average time to close issues: 6 months
  • Average time to close pull requests: about 1 month
  • Total issue authors: 51
  • Total pull request authors: 15
  • Average comments per issue: 2.21
  • Average comments per pull request: 1.43
  • Merged pull requests: 54
  • Bot issues: 0
  • Bot pull requests: 0
Past Year
  • Issues: 8
  • Pull requests: 3
  • Average time to close issues: 3 days
  • Average time to close pull requests: about 8 hours
  • Issue authors: 8
  • Pull request authors: 2
  • Average comments per issue: 0.5
  • Average comments per pull request: 0.33
  • Merged pull requests: 3
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • hadley (21)
  • jimhester (10)
  • MichaelChirico (7)
  • gaborcsardi (5)
  • jennybc (4)
  • lionel- (2)
  • moodymudskipper (2)
  • cderv (2)
  • scanisius (1)
  • tillea (1)
  • jakejh (1)
  • shaman-yellow (1)
  • jmbarbone (1)
  • jfunction (1)
  • venpopov (1)
Pull Request Authors
  • lionel- (31)
  • hadley (26)
  • MichaelChirico (7)
  • jennybc (2)
  • jimhester (2)
  • DavisVaughan (2)
  • MLopez-Ibanez (2)
  • jonkeane (1)
  • batpigandme (1)
  • orichters (1)
  • multimeric (1)
  • kyleam (1)
  • AshesITR (1)
  • pfuehrlich-pik (1)
Top Labels
Issue Labels
feature (5) documentation (4) tidy-dev-day :nerd_face: (3) upkeep (1) bug (1)
Pull Request Labels

Packages

  • Total packages: 2
  • Total downloads:
    • cran 993,316 last-month
  • Total docker downloads: 208,682,480
  • Total dependent packages: 616
    (may contain duplicates)
  • Total dependent repositories: 2,008
    (may contain duplicates)
  • Total versions: 35
  • Total maintainers: 1
cran.r-project.org: withr

Run Code 'With' Temporarily Modified Global State

  • Versions: 19
  • Dependent Packages: 616
  • Dependent Repositories: 2,008
  • Downloads: 993,316 Last month
  • Docker Downloads: 208,682,480
Rankings
Downloads: 0.1%
Dependent packages count: 0.2%
Dependent repos count: 0.2%
Forks count: 1.9%
Stargazers count: 2.6%
Average: 3.7%
Docker downloads count: 17.3%
Maintainers (1)
lionel@posit.co
Last synced: 11 months ago
proxy.golang.org: github.com/r-lib/withr
  • Versions: 16
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.5%
Average: 5.6%
Dependent repos count: 5.8%
Last synced: 11 months ago

Dependencies

DESCRIPTION cran
  • R >= 3.2.0 depends
  • grDevices * imports
  • graphics * imports
  • stats * imports
  • DBI * suggests
  • RSQLite * suggests
  • callr * suggests
  • covr * suggests
  • knitr * suggests
  • lattice * suggests
  • methods * suggests
  • rlang * suggests
  • rmarkdown >= 2.12 suggests
  • testthat >= 3.0.0 suggests