Environment
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. Meaningful error messages are thrown to guide the user to troubleshoot any mistakes.
Note: This package is Standard compliant package.
Installation
At the time of writing this README, this Environment
R-Package is not available on CRAN.
Use devtools
to either install from GitHub or Build and Install Locally:
Install via GitHub
- Use Devtools
devtools::install_github("https://github.com/FlippieCoetser/Environment")
Build and Install Locally
- Generate
.tar.gz
file
devtools::build()
- Install
.tar.gz
file
install.packages("path_to_file/tar_gz_file", repos = NULL, type="source")
Loading the Package
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
Use Global 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)
Use Package Namespace
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]]()
Usage
Define an environment
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
Get an environment variable's value
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']]()
Cache an environment variable's value
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)
Clear an environment variable's 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']]()
Contribute
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.
Running Unit Tests
Note: Some unit tests are not executed during the continuous integration process.
- Running Unit Tests:
devtools::test()