This R Package is used to Manage Environment Variables using the .Renviron
file. .Renviron
configuration file is part of the R ecosystem and well suited to manage sensitive information.
This Environment
package makes defining, reading and clearing environment variables straightforward.
Four utility functions are provided to manage environment variables. These functions are:
open.config.file
- Opens the.Renviron
configuration file in the IDE: RStudio or VSCode.get.env.variable
- Gets the value of an environment variable by name, as stored in.Renviron
cache.env.variable
- Caches the value of an environment variable by name, for current R session.clear.env.variable
- Clears the value of an environment variable by name, for current R session.
Structural Validation of inputs are performed with meaningful error messages thrown to guide the user to troubleshoot any mistakes.
Note: This package is Standard compliant package.
This Environment
R-Package is not available on CRAN.
Use devtools
to either install from GitHub or Build and Install Locally:
- Use Devtools
devtools::install_github("https://github.com/FlippieCoetser/Environment")
- Generate
.tar.gz
file
devtools::build()
- Install
.tar.gz
file
install.packages("path_to_file/tar_gz_file", repos = NULL, type="source")
There are two ways to access the four utility functions:
- Use the library function to load the four utility functions into the global namespace
- Create an instance of the Environment component using the package namespace
When using the library function to load the package the four utility functions are automatically loaded into the global namespace.
- Load Package
library(Environment)
When using the package namespace to create a new instance of the Environment component, the four utility functions will be available as member of the instance.
- Create new instance of Environment component
environment <- Environment::Environment()
- Access the three utility functions, by name, on the instance
environment[[name]]()
All environment variables are defined in a locally stored .Renviron
configuration file.
This package does not directly add environment variables into the .Renviron
configuration file.
To define new variable, simply use the provided utility function to open an existing or a new empty file directly in your IDE. This function requires either RStudio or VSCode.
- Open
.Renviron
configuration file
open.config.file()
or
environment[['open.config.file']]()
Note: Add new environment variables as key value pairs directly into the
.Renviron
configuration file. Example, adding this:Username='DefinedUsername'
on a new line, defines a new environment variable with nameUsername
and valueDefinedUsername
Reading environment variables is the most common use case of this package. Attempting to read an environment variable that is not defined will throw an exception with useful details.
- Get environment variable's value
name <- "Username"
value <- name |> get.env.variable()
or
name <- "Username"
value <- name |> environment[['get.env.variable']]()
This package provides a way to cache an environment variable with value for the current R session. This is useful when the value of an environment variable is used multiple times in the same R session.
- Cache the value of an environment variable
name <- "Username"
value <- "DefinedUsername"
name |> cache.env.variable(value)
or
name <- "Username"
value <- "DefinedUsername"
name |> environment[['cache.env.variable']](value)
This package provides a way to clear an environment variable for the current R session. This is useful when testing packages which relies on this package.
- Clear the value of an environment variable
name <- "Username"
name |> clear.env.variable()
or
name <- "Username"
name |> environment[['clear.env.variable']]()
Note: Developing R-Packages assumes you have devtools installed
Contributions is encouraged and very much welcome! Given this R-Package is Standard compliant, any contribution is expected to follow the same principles. This package is also developed using a TDD approach. It is therefore expected that commits happen in pairs: One commit with a failing test and one with a passing test. Lastly, R is flexible and allows for different syntax. Please stick to the naming and style convention used. For example dot.case
is used as naming convention, and [['']]
is preferred over $
as subset operator.
Note: Some unit tests are not executed during the continuous integration process.
- Running Unit Tests:
devtools::test()