AppConfig v0.1.4 AppConfig

Helper module with a macro that adds the following functions to the module where it is called:

def fetch_env(key) :: {:ok, value} | :error
def fetch_env!(key) :: value | no_return
def get_env(key, value | nil) :: value
def get_env_integer(key, integer | nil) :: integer

These functions fetch values from an application’s environment or from operating system (OS) environment variables. The values will be retrieved from OS environment variables when the following expression is assigned to a configuration parameter on the application’s configuration:

{:system, "VAR"}

An optional default value can be returned when the environment variable is not set to a specific value by using the following format:

{:system, "VAR", "default"}

The AppConfig module is normally used from within the module that implements the Application behaviour or from one used to access configuration values, and has to be defined in the following way:

defmodule MyConfig do
  use AppConfig, otp_app: :my_app
  # [...]
end

The otp_app argument contains the name of the application where the functions (added by the macro from the AppConfig module) will look for configuration parameters.

Examples

Given the following application configuration:

config :my_app,
  db_host: {:system, "DB_HOST", "localhost"},
  db_port: {:system, "DB_PORT", "5432"}
  db_user: {:system, "DB_USER"},
  db_password: {:system, "DB_PASSWORD"},
  db_name: "my_database"

And the following environment variables:

export DB_USER="my_user"
export DB_PASSWORD="guess_me"

And assuming that the MyConfig module is using the AppConfig macro, then the following expressions used to retrieve the values of the parameters would be valid:

"localhost" = MyConfig.get_env(:db_host)
5432 = MyConfig.get_env_integer(:db_port)
{:ok, "my_user"} = MyConfig.fetch_env(:db_user)
"guess_me" = MyConfig.fetch_env!(:db_password)
"my_database" = MyConfig.get_env(:db_name, "unknown")

Most functions from the AppConfig module can also be called without using its macro. To do so, just call the functions directly by passing the application’s name as the first argument. e.g.

AppConfig.get_env(:my_app, :db_host)

This module will come in handy especially when retrieving configuration values for applications running within Elixir/Erlang releases, as it simplifies the retrieval of values that were not defined when the release was built (i.e. at compile-time) from OS environment variables.

Summary

Functions

Returns a tuple with the value for key in the application’s configuration or in the OS environment

Returns the value for key in the application’s configuration or in the OS environment

Retrieves a value from an application’s configuration or from the OS environment. If the value is not present, the default value is returned

Same as get_env/3, but returns the result as an integer. If the value cannot be converted to an integer, the default value is returned instead

Types

app()
app() :: Application.app
key()
key() :: Application.key
value()
value() :: Application.value

Functions

fetch_env(app, key)
fetch_env(app, key) :: {:ok, value} | :error

Returns a tuple with the value for key in the application’s configuration or in the OS environment.

Returns

A tuple with the :ok atom as the first element and the value of the configuration or OS environment variable if successful. It returns :error if the configuration parameter does not exist or if the application was not loaded.

Example

{:ok, "VALUE"} = AppConfig.fetch_env(:my_app, :test_var)
fetch_env!(app, key)
fetch_env!(app, key) :: value | no_return

Returns the value for key in the application’s configuration or in the OS environment.

Returns

The value of the configuration parameter or OS environment variable if successful. It raises an ArgumentError exception if the configuration parameter does not exist or if the application was not loaded.

Example

"VALUE" = AppConfig.fetch_env!(:my_app, :test_var)
get_env(app, key, default \\ nil)
get_env(app, key, value | nil) :: value

Retrieves a value from an application’s configuration or from the OS environment. If the value is not present, the default value is returned.

If the application’s parameter was assigned an expression like the following one:

{:system, "VAR"}

An optional default value can be provided by using the following format:

{:system, "VAR", "default"}

If neither the application’s configuration nor the specified OS environment variable exist, then the default value will be returned.

Example

iex> {test_var, expected_value} = System.get_env() |> Enum.take(1) |> List.first()
...> Application.put_env(:myapp, :test_var, {:system, test_var})
...> ^expected_value = AppConfig.get_env(:myapp, :test_var)
...> :ok
:ok

iex> Application.put_env(:myapp, :test_var2, 1)
...> 1 = AppConfig.get_env(:myapp, :test_var2)
1

iex> :default = AppConfig.get_env(:myapp, :missing_var, :default)
:default
get_env_integer(app, key, default \\ nil)
get_env_integer(app, key, integer) :: integer

Same as get_env/3, but returns the result as an integer. If the value cannot be converted to an integer, the default value is returned instead.

Example

5432 = AppConfig.get_env_integer(:my_app, :db_port)