README.md

In configulaR: Manage Application Settings via '.env' or '.ini' Files

configulaR

Strict separation of settings from code.

configulaR is a port of the excellent python-decouple library for R.

Table of Contents

• Overview
• Installation
• How It Works
• Priority Rules
• Config File Search
• Usage
• On-the-fly Parameter Evaluation
• Preloading Config Files
• Handling Undefined Parameters
• Type Casting
• Configuration File Formats
• INI Files
• ENV Files

Overview

As stated by its original author, configulaR makes it easy to:

• Store configuration parameters in ini or .env files
• Define comprehensive default values
• Properly convert values to the correct data type
• Have only one configuration module to rule all your application instances

configulaR's behavior mimics python-decouple as closely as possible and is tested against python-decouple's unit tests.

Installation

# Install from CRAN
install.packages("configulaR")

# Or install the development version from GitHub
# install.packages("devtools")
devtools::install_github("dataupsurge/configulaR")

How It Works

Priority Rules

configulaR always searches for configuration values in this order:

1. Environment variables
2. Repository config files: .ini or .env files
3. Default argument passed to config

Environment variables have precedence over config files to maintain Unix consistency.

Config File Search

By default, config files are searched for in: 1. The current working directory 2. Any other directory provided via the path argument 3. Parent directories (if no config files are found in the current directory)

configulaR looks for either settings.ini or .env files.

Usage

On-the-fly Parameter Evaluation

Parameter values can be retrieved anytime by invoking the configulaR::get_var function:

library(configulaR)

# Retrieve a value from environment or config file
api_key <- get_var('API_KEY', default='my-default-key')

# With type casting
debug_mode <- get_var('DEBUG', default=FALSE, cast='logical')
port_number <- get_var('PORT', default=3000, cast='integer')

If the config parameter is not provided, a config file search will be performed at each function call.

Preloading Config Files

To avoid repeated config file searches, preload the configuration once:

# Load config once
config <- get_config()

# Then use it for all subsequent calls
api_key <- get_var('API_KEY', config=config, default='my-default-key')
debug_mode <- get_var('DEBUG', config=config, default=FALSE, cast='logical')

Undefined Parameters

If a parameter has no default value and doesn't exist in the environment or config files, configulaR will raise an error:

# This will fail if SECRET_KEY is not defined anywhere
secret_key <- get_var('SECRET_KEY')

# This will use the default if SECRET_KEY is not defined
secret_key <- get_var('SECRET_KEY', default='fallback-secret-key')

This fail-fast policy helps you avoid subtle bugs when parameters are missing.

Casting Argument

By default, all values returned by configulaR are strings.

To specify a different return type, use the cast argument:

# Return as integer
max_connections <- get_var('MAX_CONNECTIONS', default='10', cast='integer')

# Return as logical
debug_enabled <- get_var('DEBUG', default='True', cast='logical')

# Return as float
timeout_seconds <- get_var('TIMEOUT', default='5.5', cast='float')

# Custom casting function
get_var('NUMBERS', default='1,2,3', cast=function(x) as.numeric(strsplit(x, ',')[[1]]))

Predefined casting types include:

• Integer: 'int', 'integer'
• Boolean: 'bool', 'boolean', 'logical'
• Float: 'float'

Implementated Parsers

configulaR supports both .ini and .env files.

Ini File

configulaR can read ini files and provide simple interpolation.

Simply create a settings.ini in your working directory or in its parent directories:

[settings]
DEBUG=True
TEMPLATE_DEBUG=%(DEBUG)s
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase
PERCENTILE=90%%
#COMMENTED=42

Env File

Create a .env text file in your repository's root directory:

DEBUG=True
TEMPLATE_DEBUG=True
SECRET_KEY=ARANDOMSECRETKEY
DATABASE_URL=mysql://myuser:mypassword@myhost/mydatabase
PERCENTILE=90%
#COMMENTED=42

configulaR documentation built on June 8, 2025, 10:52 a.m.