envvar

Make working with environment variables easier and more consistent

https://github.com/briandconnelly/envvar

Keywords

Repository

Make working with environment variables easier and more consistent

README.Rmd

---
output: github_document
---



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

# envvar


[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/envvar)](https://CRAN.R-project.org/package=envvar)
[![R-CMD-check](https://github.com/briandconnelly/envvar/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/briandconnelly/envvar/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/briandconnelly/envvar/branch/main/graph/badge.svg)](https://app.codecov.io/gh/briandconnelly/envvar?branch=main)


Environment variables are a powerful tool that enable your code to react to its environment.
However, two common design choices are a frequent source of friction.
First, unlike most other "getter"-type functions, those functions that retrieve values from environment variable typically fail silently.
Second, while programmers often use environment variables to store a wide variety of data types from numbers to timestamps to URLs, values are almost always returned as strings.
These choices necessitate additional code that checks whether an environment variable was actually set and to coerce its value into the intended format.
For frequent users of environment variables, writing all this extra code is unpleasant and time consuming.


## Failing Loudly

envvar takes a slightly opinionated perspective to make working with environment variables easier and more consistent.
Unless a default value is explicitly given, `envvar_get()` raises an error if an environment variable is not defined.

For example, let's say our code depends on an environment variable called `NUM_CPUS`.
In base R, we have to first get the value using `Sys.getenv()` and then see whether the result is the empty string (not `NA` like you might expect):

```{r base notset,error=TRUE}
num_cpus <- Sys.getenv("NUM_CPUS")

if (identical(num_cpus, "")) {
  stop("I need `NUM_CPUS` to be set!")
}
```

envvar's `envvar_get()` will just fail if `NUM_CPUS` isn't set:

```{r envvar notset,error=TRUE}
library(envvar)

envvar_get("NUM_CPUS")
```

If a reasonable default is known, it can be supplied via the `default` argument.
envvar prints a message, though, so you know that it's using a default rather than a value specified in the environment.

```{r envvar notset default}
envvar_get("NUM_CPUS", default = 12)
```

Warnings can be disabled with the `warn_default` argument.


## Speaking Native Types

```{r include=FALSE}
Sys.setenv("NUM_CPUS" = 8)
```

Let's say our `NUM_CPUS` environment variable is set to 8.
Because `Sys.getenv()` returns strings, we can't immediately treat it like the integer that it is.

```{r base nocoerce,error=TRUE}
Sys.getenv("NUM_CPUS") / 2
```

envvar includes several helper functions that return commonly-used data types as their proper type.
Here, we'll use `envvar_get_integer()` to get `NUM_CPUS` and return it as an integer.

```{r envvar nocoerce,error=TRUE}
envvar_get_integer("NUM_CPUS") / 2
```

Returning to the theme of failing loudly, envvar's type-specific functions will also fail if a value cannot be coerced to the expected type.
For example, using `Sys.getenv()` and `as.integer` to load what _should be_ an integer value might not produce what you'd expect.

```{r base int conversion}
Sys.setenv("NUM_CPUS" = 12.345)

num_cpus <- as.integer(Sys.getenv("NUM_CPUS"))
num_cpus
```

Using `envvar_get_integer()`:

```{r envvar int conversion, error=TRUE}
envvar_get_integer("NUM_CPUS")
```

This extends to default values:

```{r envvar int conversion default, error=TRUE}
envvar_get_integer("SOME_UNSET_INTEGER", default = 12.345)
```

envvar can handle numbers, logical values, version numbers, URLs, timestamps, UUIDs, IP addresses, and more.
We'll work with dates in the next example.


## Validation

Sometimes being the right type isn't enough.
envvar's `envvar_get` functions can also apply validation logic.
For this example, let's set an environment variable called `LAUNCH_DATE` that stores a date that absolutely, positively must be in the future.
Let's first set it to a date in the past.

```{r set launch date past}
envvar_set("LAUNCH_DATE" = "1969-07-16")
```

To read `LAUNCH_DATE` and ensure that it is in the future, we can supply a `validate` function to `envvar_get_date()` that checks the value.
If this function returns `FALSE`, an error is raised.

```{r get launch date,error=TRUE}
envvar_get_date("LAUNCH_DATE", validate = \(x) x > Sys.Date())
```

Let's try that again:
```{r get good launch date,error=TRUE}
envvar_set("LAUNCH_DATE" = "2028-08-28")

envvar_get_date("LAUNCH_DATE", validate = \(x) x > Sys.Date())
```

Note that the `validate` argument supports one function.
If you're in need of complex validation, just use a function that encapsulates all of that fanciness.


## Installation

You can install the latest released version of envvar by running:

``` r
install.packages("envvar")
```

If you’d like to try out the development version, you can install directly from GitHub:

``` r
# install.packages("remotes")
remotes::install_github("briandconnelly/envvar")
```


## Related Packages

- [dotenv](https://github.com/gaborcsardi/dotenv) package for loading environment variables from `.env` files
- [config](https://rstudio.github.io/config/) package for defining and using multiple environments
- [options](https://dgkf.github.io/options/) package for defining and using R package options, another way of adding flexibility to your code

Owner

GitHub Events

Committers

Last synced: about 2 years ago

Issues and Pull Requests

Last synced: 7 months ago

Packages