AppConfig v0.3.0 AppConfig View Source
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.
Link to this section Summary
Functions
Returns a tuple with the value for key
in an application’s environment,
in a keyword list or in the OS environment. The first argument can either be
an atom with the name of the application or a keyword list with the different
configuration values
Returns the value for key
in an application’s environment, in a keyword list
or in the OS environment. The first argument can either be an atom with the
name of the application or a keyword list with the different configuration
values
Retrieves a value from an application’s configuration, form a keyword list 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
Retrieves the value from and OS environment variable when it receives a tuple like the following as argument
Link to this section Types
Link to this section Functions
Returns a tuple with the value for key
in an application’s environment,
in a keyword list or in the OS environment. The first argument can either be
an atom with the name of the application or a keyword list with the different
configuration values.
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)
Returns the value for key
in an application’s environment, in a keyword list
or in the OS environment. The first argument can either be an atom with the
name of the application or a keyword list with the different configuration
values.
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)
Retrieves a value from an application’s configuration, form a keyword list or
from the OS environment. If the value is not present, the default
value is
returned.
The first argument can either be an atom with the name of the application or a keyword list with the different configuration values.
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
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)
Retrieves the value from and OS environment variable when it receives a tuple like the following as argument:
{: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"}
If any other value is passed, that’s what the function will return.
Returns
A tuple with the :ok
atom as the first element and the value of the
OS environment variable or the value that was passed if successful. It
returns :error
if the OS environment variable was not set.
Example
iex> System.put_env("MY_VAR", "MY_VALUE")
...> AppConfig.get_env_value({:system, "MY_VAR"})
{:ok, "MY_VALUE"}
iex> AppConfig.get_env_value({:system, "MY_UNSET_VAR"})
:error
iex> AppConfig.get_env_value({:system, "MY_UNSET_VAR", "DEFAULT"})
{:ok, "DEFAULT"}
iex> AppConfig.get_env_value("VALUE")
{:ok, "VALUE"}