View Source Bonfire.Common.EnvConfig (Bonfire v0.9.11-social-beta.6)

A Want type that reads environment variables and returns them as keyword lists or map(s).

Features

  • Collects environment variables with a specified prefix.
  • Allows key transformation via :transform_keys.
  • Supports type casting via :want_values using the Want library.
  • Supports both single (e.g. MYAPP_DB_HOST) and a list of configuration groups (e.g. MYAPP_DB_1_HOST, MYAPP_DB_2_HOST, etc).
  • Returns keyword lists if all keys are atoms, otherwise returns maps.

Summary

Functions

cast(input, opts)

Casts environment variables into keyword list(s) or map(s).

maybe_want(input, arg2, want_values)
parse(input \\ nil, opts)

Functions

cast(input, opts)

Casts environment variables into keyword list(s) or map(s).

Options

  • prefix (required): Prefix for environment variable matching.
  • transform_keys (optional): Function to transform keys (e.g., &String.to_existing_atom/1).
  • want_values (optional): Map of key type casts with optional defaults.
  • want_unknown_keys (optional): Whether to also include unknown keys when using want_values.
  • indexed_list (optional): Looks for an indexed list of env vars. Default: false.
  • max_index (optional): Maximum index for indexed configs. Default: 1000.
  • max_empty_streak (optional): Stops after this many consecutive missing indices. Default: 10.

Examples

Basic usage (usage as a Want custom type) 

iex> System.put_env("TESTA_DB_HOST", "localhost")
iex> EnvConfig.cast(System.get_env(), prefix: "TESTA_DB") 
{:ok, %{"host"=> "localhost"}}
# iex> Want.cast(System.get_env(), EnvConfig, prefix: "TESTA_DB") # FIXME: Want doesn't currently have a way to cast with a custom type at the top-level, only for data within a map or keyword list
# {:ok, %{"host"=> "localhost"}}

Basic usage with prefix only (direct usage) 

iex> System.put_env("TESTA_DB_HOST", "localhost")
iex> EnvConfig.parse(System.get_env(), prefix: "TESTA_DB") 
%{"host"=> "localhost"}

Basic usage with prefix only (direct usage, uses env from System.get_env() by default) 

iex> System.put_env("TESTA_DB_HOST", "localhost")
iex> EnvConfig.parse(prefix: "TESTA_DB") 
%{"host"=> "localhost"}

With key transformation 

iex> System.put_env("TESTB_DB_HOST", "localhost")
iex> System.put_env("TESTB_DB_PORT", "5432")
iex> EnvConfig.parse(
...>   prefix: "TESTB_DB",
...>   transform_keys: &String.to_existing_atom/1,
...> ) 
...> |> Enum.sort() # just to make the test assertion easier
[host: "localhost", port: "5432"]

With type casting for specific keys 

iex> System.put_env("TESTC_DB_PORT", "5432")
iex> System.put_env("TESTC_DB_MAX_CONNECTIONS", "100")
iex> System.put_env("TESTC_DB_SSL", "true")
iex> EnvConfig.parse(
...>   prefix: "TESTC_DB",
...>   want_values: %{
...>     port: :integer,
...>     max_connections: {:integer, default: 3},
...>     ssl: :boolean
...>   }
...> ) 
...> |> Enum.sort() # just to make the test assertion easier
[max_connections: 100, port: 5432, ssl: true]

With type casting for only some keys, including unknown keys as well (returns a map with mixed keys) 

iex> System.put_env("TESTU_DB_PORT", "5432")
iex> System.put_env("TESTU_DB_MAX_CONNECTIONS", "100")
iex> %{"max_connections"=> "100", port: 5432} = EnvConfig.parse(
...>   prefix: "TESTU_DB",
...>   want_unknown_keys: true,
...>   want_values: %{
...>     port: :integer
...>   }
...> )

With both transformation and type casting 

iex> System.put_env("TESTD_DB_HOST_", "localhost")
iex> EnvConfig.parse(
...>   prefix: "TESTD_DB",
...>   transform_keys: &String.trim(&1, "_"),
...>   want_values: %{
...>     host: :string
...>   }
...> )
[host: "localhost"]

Indexed list of configs 

iex> System.put_env("TESTE_DB_0_HOST", "localhost")
iex> System.put_env("TESTE_DB_1_HOST", "remote")
iex> EnvConfig.parse(
...>   prefix: "TESTE_DB",
...>   want_values: %{
...>     host: :string
...>   },
...>   indexed_list: true
...> )
[[host: "localhost"], [host: "remote"]]

maybe_want(input, arg2, want_values)

parse(input \\ nil, opts)