@spec fetch_env_as(String.t(), Enviable.Conversion.conversion(), keyword()) ::
  {:ok, term()} | :error

Returns the value of an environment variable converted to the target type as {:ok, term()} or :error if the variable is unset.

Supported primitive conversions are:

• :atom (Enviable.Conversion.convert_atom/0, fetch_env_as_atom/2)
• :boolean (Enviable.Conversion.convert_boolean/0, fetch_env_as_boolean/2)
• :charlist (Enviable.Conversion.convert_charlist/0, fetch_env_as_charlist/1)
• :decimal (Enviable.Conversion.convert_decimal/0, fetch_env_as_decimal/1)
• :elixir (Enviable.Conversion.convert_elixir/0, fetch_env_as_elixir/1)
• :erlang (Enviable.Conversion.convert_erlang/0, fetch_env_as_erlang/1)
• :float (Enviable.Conversion.convert_float/0, fetch_env_as_float/1)
• :integer (Enviable.Conversion.convert_integer/0, fetch_env_as_integer/2)
• :json (Enviable.Conversion.convert_json/0, fetch_env_as_json/2)
• :log_level (Enviable.Conversion.convert_log_level/0, fetch_env_as_log_level/1)
• :module (Enviable.Conversion.convert_module/0, fetch_env_as_module/2)
• :pem (Enviable.Conversion.convert_pem/0, fetch_env_as_pem/2)
• :safe_atom (Enviable.Conversion.convert_safe_atom/0, fetch_env_as_safe_atom/2)
• :safe_module (Enviable.Conversion.convert_safe_module/0, fetch_env_as_safe_module/2)

Supported encoded conversions are:

• :base16 (Enviable.Conversion.encoded_base16/0, fetch_env_as_base16/2)
• :base32 (Enviable.Conversion.encoded_base32/0, fetch_env_as_base32/2)
• :base64, :url_base64 (Enviable.Conversion.encoded_base64/0, fetch_env_as_base64/2, fetch_env_as_url_base64/2)
• :hex32 (Enviable.Conversion.encoded_hex32/0, fetch_env_as_hex32/2)
• :list (Enviable.Conversion.encoded_list/0, fetch_env_as_list/2)

See Enviable.Conversion for supported type conversions and options, but note that any default values are ignored for fetch_env_as/3 and related fetch_env_as_* functions.

Examples

iex> Enviable.fetch_env_as("UNSET", :atom)
:error

iex> Enviable.fetch_env_as("UNSET", :float)
:error

iex> Enviable.fetch_env_as("UNSET", :base16)
:error

iex> Enviable.put_env("NAME", "fetch_env_as")
iex> Enviable.fetch_env_as("NAME", :atom)
{:ok, :fetch_env_as}

iex> Enviable.put_env("NAME", "FETCH_ENV_AS")
iex> Enviable.fetch_env_as("NAME", :safe_atom, downcase: true)
{:ok, :fetch_env_as}

iex> Enviable.fetch_env_as("UNSET", :float, default: "3.5")
:error

iex> Enviable.fetch_env_as("UNSET", :float, default: 3.5)
:error

iex> Enviable.put_env("FLOAT", "3")
iex> Enviable.fetch_env_as("FLOAT", :float)
{:ok, 3.0}

iex> Enviable.put_env("FLOAT", "3.1")
iex> Enviable.fetch_env_as("FLOAT", :float)
{:ok, 3.1}

iex> red = Base.encode16("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as("NAME", :base16, case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as("NAME", {:base16, :string}, case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as("NAME", {:base16, :atom}, case: :lower, downcase: true)
{:ok, :red}

@spec fetch_env_as!(String.t(), Enviable.Conversion.conversion(), keyword()) :: term()

Returns the value of an environment variable converted to the target type or raises an exception if the variable is unset.

Supported primitive conversions are:

• :atom (Enviable.Conversion.convert_atom/0, fetch_env_as_atom!/2)
• :boolean (Enviable.Conversion.convert_boolean/0, fetch_env_as_boolean!/2)
• :charlist (Enviable.Conversion.convert_charlist/0, fetch_env_as_charlist!/2)
• :decimal (Enviable.Conversion.convert_decimal/0, fetch_env_as_decimal!/2)
• :elixir (Enviable.Conversion.convert_elixir/0, fetch_env_as_elixir!/1)
• :erlang (Enviable.Conversion.convert_erlang/0, fetch_env_as_erlang!/1)
• :float (Enviable.Conversion.convert_float/0, fetch_env_as_float!/2)
• :integer (Enviable.Conversion.convert_integer/0, fetch_env_as_integer!/2)
• :json (Enviable.Conversion.convert_json/0, fetch_env_as_json!/2)
• :log_level (Enviable.Conversion.convert_log_level/0, fetch_env_as_log_level!/2)
• :module (Enviable.Conversion.convert_module/0, fetch_env_as_module!/2)
• :pem (Enviable.Conversion.convert_pem/0, fetch_env_as_pem!/2)
• :safe_atom (Enviable.Conversion.convert_safe_atom/0, fetch_env_as_safe_atom!/2)
• :safe_module (Enviable.Conversion.convert_safe_module/0, fetch_env_as_safe_module!/2)

Supported encoded conversions are:

• :base16 (Enviable.Conversion.encoded_base16/0, fetch_env_as_base16!/2)
• :base32 (Enviable.Conversion.encoded_base32/0, fetch_env_as_base32!/2)
• :base64, :url_base64 (Enviable.Conversion.encoded_base64/0, fetch_env_as_base64!/2, fetch_env_as_url_base64!/2)
• :hex32 (Enviable.Conversion.encoded_hex32/0, fetch_env_as_hex32!/2)
• :list (Enviable.Conversion.encoded_list/0, fetch_env_as_list!/2)

See Enviable.Conversion for supported type conversions and options, but note that any documented default values are ignored for fetch_env_as!/3 and related fetch_env_as_*! functions.

Examples

iex> Enviable.fetch_env_as!("UNSET", :atom)
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.fetch_env_as!("UNSET", :float)
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.fetch_env_as!("UNSET", :base16)
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("NAME", "fetch_env_as!")
iex> Enviable.fetch_env_as!("NAME", :atom)
:fetch_env_as!

iex> Enviable.put_env("NAME", "FETCH_ENV_AS!")
iex> Enviable.fetch_env_as!("NAME", :safe_atom, downcase: true)
:fetch_env_as!

iex> Enviable.fetch_env_as!("UNSET", :float, default: "3.5")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.fetch_env_as!("UNSET", :float, default: 3.5)
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("FLOAT", "3")
iex> Enviable.fetch_env_as!("FLOAT", :float)
3.0

iex> Enviable.put_env("FLOAT", "3.1")
iex> Enviable.fetch_env_as!("FLOAT", :float)
3.1

iex> red = Base.encode16("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as!("NAME", :base16, case: :lower)
"RED"
iex> Enviable.fetch_env_as!("NAME", {:base16, :string}, case: :lower)
"RED"
iex> Enviable.fetch_env_as!("NAME", {:base16, :atom}, case: :lower, downcase: true)
:red

@spec fetch_env_as_atom(String.t(), [
  {:allowed, [atom()]} | Enviable.Conversion.opt_downcase()
]) ::
  {:ok, atom()} | :error

Returns the value of an environment variable converted to atom/0 as {:ok, atom()} or :error if the variable is unset.

Options

• :allowed: A list of atom/0 values indicating permitted atoms and used as a lookup table, if present. Any value not found will result in an exception.
• :downcase: See Enviable.Conversion.opt_downcase/0.
• :upcase: See Enviable.Conversion.opt_upcase/0.

Examples

iex> Enviable.fetch_env_as_atom("UNSET")
:error

iex> Enviable.put_env("NAME", "fetch_env_as_atom")
iex> Enviable.fetch_env_as_atom("NAME")
{:ok,  :fetch_env_as_atom}

@spec fetch_env_as_atom!(String.t(), [
  {:allowed, [atom()]} | Enviable.Conversion.opt_downcase()
]) ::
  atom()

Returns the value of an environment variable converted to atom/0 or raises an exception if the variable is unset.

Options

• :allowed: A list of atom/0 values indicating permitted atoms and used as a lookup table, if present. Any value not found will result in an exception.
• :downcase: See Enviable.Conversion.opt_downcase/0.
• :upcase: See Enviable.Conversion.opt_upcase/0.

Examples

iex> Enviable.fetch_env_as_atom!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("NAME", "fetch_env_as_atom!")
iex> Enviable.fetch_env_as_atom!("NAME")
:fetch_env_as_atom!

@spec fetch_env_as_base16(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed
) :: :error | {:ok, term()}

Returns the value of an environment variable decoded as a base 16 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.decode16/2, which must be :upper, :lower, or :mixed.

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode16("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_base16("NAME", case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as_base16("NAME", as: :string, case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as_base16("NAME", as: :atom, case: :lower, downcase: true)
{:ok, :red}

@spec fetch_env_as_base16!(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed
) :: term()

Returns the value of an environment variable decoded as a base 16 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.decode16/2, which must be :upper, :lower, or :mixed.

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode16("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_base16!("NAME", case: :lower)
"RED"
iex> Enviable.fetch_env_as_base16!("NAME", as: :string, case: :lower)
"RED"
iex> Enviable.fetch_env_as_base16!("NAME", as: :atom, case: :lower, downcase: true)
:red

@spec fetch_env_as_base32(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: :error | {:ok, term()}

Returns the value of an environment variable decoded as a base 32 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.decode32/2, which must be :upper, :lower, or :mixed.
• :padding: The boolean value of :padding passed to Base.decode32/2. The default is false (the opposite of Base.decode32/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode32("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_base32("NAME", case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as_base32("NAME", as: :string, case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as_base32("NAME", as: :atom, case: :lower, downcase: true)
{:ok, :red}

@spec fetch_env_as_base32!(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: term()

Returns the value of an environment variable decoded as a base 32 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.decode32/2, which must be :upper, :lower, or :mixed.
• :padding: The boolean value of :padding passed to Base.decode32/2. The default is false (the opposite of Base.decode32/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode32("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_base32!("NAME", case: :lower)
"RED"
iex> Enviable.fetch_env_as_base32!("NAME", as: :string, case: :lower)
"RED"
iex> Enviable.fetch_env_as_base32!("NAME", as: :atom, case: :lower, downcase: true)
:red

@spec fetch_env_as_base64(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: :error | {:ok, term()}

Returns the value of an environment variable decoded as a base 64 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :ignore_whitespace: Whether to ignore whitespace values. The default is true, the opposite default for both Base.decode64/2 and Base.url_decode64/2.
• :padding: The boolean value of :padding passed to Base.decode64/2. The default is false (the opposite of Base.decode64/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode64("RED", padding: true)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_base64("NAME", padding: false)
{:ok, "RED"}
iex> Enviable.fetch_env_as_base64("NAME", as: :string, padding: true)
{:ok, "RED"}
iex> Enviable.fetch_env_as_base64("NAME", as: :atom, downcase: true, padding: false)
{:ok, :red}

@spec fetch_env_as_base64!(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: term()

Returns the value of an environment variable decoded as a base 64 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :ignore_whitespace: Whether to ignore whitespace values. The default is true, the opposite default for both Base.decode64/2 and Base.url_decode64/2.
• :padding: The boolean value of :padding passed to Base.decode64/2. The default is false (the opposite of Base.decode64/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode64("RED", padding: true)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_base64!("NAME", padding: false)
"RED"
iex> Enviable.fetch_env_as_base64!("NAME", as: :string, padding: true)
"RED"
iex> Enviable.fetch_env_as_base64!("NAME", as: :atom, downcase: true, padding: false)
:red

@spec fetch_env_as_boolean(String.t(), [
  Enviable.Conversion.opt_downcase() | {:truthy | :falsy, [binary()]}
]) :: {:ok, boolean()} | :error

Returns the value of an environment variable converted to a boolean/0 value as {:ok, boolean()} or :error if the variable is unset.

This function will always result in a boolean/0 value. Unless configured with truthy or falsy, only the values "1" and "true" will be converted to true and any other value will result in false.

Options

• :truthy: a list of string values to be compared for truth values. If the value of the environment variable matches these values, true will be returned; other values will result in false. Mutually exclusive with falsy.

• :falsy: a list of string values to be compared for false values. If the value of the environment variable matches these values, false will be returned; other values will result in true. Mutually exclusive with truthy.

• :downcase: either false (the default), true, or the mode parameter for String.downcase/2 (:default, :ascii, :greek, or :turkic).

  The default :downcase value for boolean conversions can be changed at compile time through application configuration:

  config :enviable, :boolean_downcase, true
  config :enviable, :boolean_downcase, :default
  config :enviable, :boolean_downcase, :ascii

  In the next major version of Enviable, the default :downcase value will be changing to :default.

Examples

iex> Enviable.fetch_env_as_boolean("UNSET")
:error

iex> Enviable.put_env("FLAG", "1")
iex> Enviable.fetch_env_as_boolean("FLAG")
{:ok, true}

iex> Enviable.put_env("FLAG", "something")
iex> Enviable.fetch_env_as_boolean("FLAG")
{:ok, false}

iex> Enviable.put_env("FLAG", "oui")
iex> Enviable.fetch_env_as_boolean("FLAG", truthy: ["oui"])
{:ok, true}

iex> Enviable.put_env("FLAG", "OUI")
iex> Enviable.fetch_env_as_boolean("FLAG", truthy: ["oui"])
{:ok, false}

iex> Enviable.put_env("FLAG", "OUI")
iex> Enviable.fetch_env_as_boolean("FLAG", truthy: ["oui"], downcase: true)
{:ok, true}

iex> Enviable.put_env("FLAG", "NON")
iex> Enviable.fetch_env_as_boolean("FLAG", falsy: ["non"])
{:ok, true}

iex> Enviable.put_env("FLAG", "NON")
iex> Enviable.fetch_env_as_boolean("FLAG", falsy: ["non"], downcase: true)
{:ok, false}

@spec fetch_env_as_boolean!(String.t(), [
  Enviable.Conversion.opt_downcase() | {:truthy | :falsy, [binary()]}
]) :: boolean()

Returns the value of an environment variable converted to a boolean/0 value or raises an exception if the variable is unset.

This function will always result in a boolean/0 value. Unless configured with truthy or falsy, only the values "1" and "true" will be converted to true and any other value will result in false.

Options

• :truthy: a list of string values to be compared for truth values. If the value of the environment variable matches these values, true will be returned; other values will result in false. Mutually exclusive with falsy.

• :falsy: a list of string values to be compared for false values. If the value of the environment variable matches these values, false will be returned; other values will result in true. Mutually exclusive with truthy.

• :downcase: either false (the default), true, or the mode parameter for String.downcase/2 (:default, :ascii, :greek, or :turkic).

  The default :downcase value for boolean conversions can be changed at compile time through application configuration:

  config :enviable, :boolean_downcase, true
  config :enviable, :boolean_downcase, :default
  config :enviable, :boolean_downcase, :ascii

  In the next major version of Enviable, the default :downcase value will be changing to :default.

Examples

iex> Enviable.fetch_env_as_boolean!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("FLAG", "1")
iex> Enviable.fetch_env_as_boolean!("FLAG")
true

iex> Enviable.put_env("FLAG", "something")
iex> Enviable.fetch_env_as_boolean!("FLAG")
false

iex> Enviable.put_env("FLAG", "oui")
iex> Enviable.fetch_env_as_boolean!("FLAG", truthy: ["oui"])
true

iex> Enviable.put_env("FLAG", "OUI")
iex> Enviable.fetch_env_as_boolean!("FLAG", truthy: ["oui"])
false

iex> Enviable.put_env("FLAG", "OUI")
iex> Enviable.fetch_env_as_boolean!("FLAG", truthy: ["oui"], downcase: true)
true

iex> Enviable.put_env("FLAG", "NON")
iex> Enviable.fetch_env_as_boolean!("FLAG", falsy: ["non"])
true

iex> Enviable.put_env("FLAG", "NON")
iex> Enviable.fetch_env_as_boolean!("FLAG", falsy: ["non"], downcase: true)
false

@spec fetch_env_as_charlist(String.t()) :: {:ok, charlist()} | :error

Returns the value of an environment variable converted to a charlist/0 as {:ok, charlist()} or :error if the variable is unset.

Examples

iex> Enviable.fetch_env_as_charlist("UNSET")
:error

iex> Enviable.put_env("NAME", "fetch_env_as")
iex> Enviable.fetch_env_as_charlist("NAME")
{:ok, ~c"fetch_env_as"}

@spec fetch_env_as_charlist!(String.t()) :: charlist()

Returns the value of an environment variable converted to a charlist/0 or raises an exception if the variable is unset.

Examples

iex> Enviable.fetch_env_as_charlist!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("NAME", "fetch_env_as")
iex> Enviable.fetch_env_as_charlist!("NAME")
~c"fetch_env_as"

@spec fetch_env_as_decimal(String.t()) :: {:ok, Decimal.t()} | :error

Returns the value of an environment variable converted to a Decimal.t/0 value as {:ok, Decimal.t()} or :error if the variable is unset.

Examples

iex> Enviable.fetch_env_as_decimal("UNSET")
:error

iex> Enviable.put_env("DECIMAL", "1")
iex> Enviable.fetch_env_as_decimal("DECIMAL")
{:ok, Decimal.new("1")}

iex> Enviable.put_env("DECIMAL", "ff")
iex> Enviable.fetch_env_as_decimal("DECIMAL")
** (Enviable.ConversionError) could not convert environment variable "DECIMAL" to type decimal

@spec fetch_env_as_decimal!(String.t()) :: Decimal.t()

Returns the value of an environment variable converted to a Decimal.t/0 value or :error if the variable is unset.

Examples

iex> Enviable.fetch_env_as_decimal!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("DECIMAL", "1")
iex> Enviable.fetch_env_as_decimal!("DECIMAL")
Decimal.new("1")

iex> Enviable.put_env("DECIMAL", "ff")
iex> Enviable.fetch_env_as_decimal!("DECIMAL")
** (Enviable.ConversionError) could not convert environment variable "DECIMAL" to type decimal

@spec fetch_env_as_elixir(String.t()) :: {:ok, term()} | :error

Returns the value of an environment variable parsed and evaluated as Elixir code with the result as {:ok, term()}, or :error if the environment variable is not set.

This can be used for tuples, complex map declarations, or other expressions difficult to represent with other types. Longer code blocks should be encoded as base 64 text and decoded as {:base64, :elixir}.

Examples

iex> Enviable.fetch_env_as_elixir("UNSET")
:error

iex> Enviable.put_env("TERM", "11000..11100//3")
iex> Enviable.fetch_env_as_elixir("TERM")
{:ok, 11000..11100//3}

@spec fetch_env_as_elixir!(String.t()) :: term()

Returns the value of an environment variable parsed and evaluated as Elixir code with the result , or raises an exception if the environment variable is not set.

This can be used for tuples, complex map declarations, or other expressions difficult to represent with other types. Longer code blocks should be encoded as base 64 text and decoded as {:base64, :elixir}.

Examples

iex> Enviable.fetch_env_as_elixir!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("TERM", "11000..11100//3")
iex> Enviable.fetch_env_as_elixir!("TERM")
11000..11100//3

@spec fetch_env_as_erlang(String.t()) :: {:ok, term()} | :error

Returns the value of an environment variable parsed and evaluated as Erlang code with the result as {:ok, term()}, or :error if the environment variable is not set.

This can be used for tuples, complex map declarations, or other expressions difficult to represent with other types. Longer code blocks should be encoded as base 64 text and decoded as {:base64, :erlang}.

Examples

iex> Enviable.fetch_env_as_erlang("UNSET")
:error

iex> Enviable.put_env("TERM", "{ok, true}.")
iex> Enviable.fetch_env_as_erlang("TERM")
{:ok, {:ok, true}}

@spec fetch_env_as_erlang!(String.t()) :: term()

Returns the value of an environment variable parsed and evaluated as Erlang code with the result , or raises an exception if the environment variable is not set.

This can be used for tuples, complex map declarations, or other expressions difficult to represent with other types. Longer code blocks should be encoded as base 64 text and decoded as {:base64, :erlang}.

Examples

iex> Enviable.fetch_env_as_erlang!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("TERM", "{ok, true}.")
iex> Enviable.fetch_env_as_erlang!("TERM")
{:ok, true}

@spec fetch_env_as_float(String.t()) :: {:ok, float()} | :error

Returns the value of an environment variable converted to a float/0 value as {:ok, float()} or :error if the variable is unset.

Examples

iex> Enviable.fetch_env_as_float("UNSET")
:error

iex> Enviable.put_env("FLOAT", "1")
iex> Enviable.fetch_env_as_float("FLOAT")
{:ok, 1.0}

iex> Enviable.put_env("FLOAT", "ff")
iex> Enviable.fetch_env_as_float("FLOAT")
** (Enviable.ConversionError) could not convert environment variable "FLOAT" to type float

@spec fetch_env_as_float!(String.t()) :: float()

Returns the value of an environment variable converted to a float/0 value or :error if the variable is unset.

Examples

iex> Enviable.fetch_env_as_float!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("FLOAT", "1")
iex> Enviable.fetch_env_as_float!("FLOAT")
1.0

iex> Enviable.put_env("FLOAT", "ff")
iex> Enviable.fetch_env_as_float!("FLOAT")
** (Enviable.ConversionError) could not convert environment variable "FLOAT" to type float

@spec fetch_env_as_hex32(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: :error | {:ok, term()}

Returns the value of an environment variable decoded as a base 32 hex encoded string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.hex_decode32/2, which must be :upper, :lower, or :mixed.
• :padding: The boolean value of :padding passed to hex.decode32/2. The default is false (the opposite of Base.hex_decode32/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.hex_encode32("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_hex32("NAME", case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as_hex32("NAME", as: :string, case: :lower)
{:ok, "RED"}
iex> Enviable.fetch_env_as_hex32("NAME", as: :atom, case: :lower, downcase: true)
{:ok, :red}

@spec fetch_env_as_hex32!(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: term()

Returns the value of an environment variable decoded as a base 32 hex encoded string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.hex_decode32/2, which must be :upper, :lower, or :mixed.
• :padding: The boolean value of :padding passed to hex.decode32/2. The default is false (the opposite of Base.hex_decode32/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.hex_encode32("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_hex32!("NAME", case: :lower)
"RED"
iex> Enviable.fetch_env_as_hex32!("NAME", as: :string, case: :lower)
"RED"
iex> Enviable.fetch_env_as_hex32!("NAME", as: :atom, case: :lower, downcase: true)
:red

@spec fetch_env_as_integer(String.t(), [{:base, 2..36}]) :: {:ok, integer()} | :error

Returns the value of an environment variable converted to a integer/0 value as {:ok, integer()} or :error if the variable is unset.

Options

• :base: The base (2..36) for integer conversion. Defaults to base 10 like String.to_integer/2.

Failure to parse the value of the environment variable will result in an exception.

Examples

iex> Enviable.fetch_env_as_integer("UNSET")
:error

iex> Enviable.put_env("PORT", "5432")
iex> Enviable.fetch_env_as_integer("PORT")
{:ok, 5432}

iex> Enviable.put_env("PORT", "18eb")
iex> Enviable.fetch_env_as_integer("PORT")
** (Enviable.ConversionError) could not convert environment variable "PORT" to type integer

iex> Enviable.put_env("PORT", "18EB")
iex> Enviable.fetch_env_as_integer("PORT", base: 16)
{:ok, 6379}

@spec fetch_env_as_integer!(String.t(), [{:base, 2..36}]) :: integer()

Returns the value of an environment variable converted to a integer/0 value or raises an exception if the variable is unset.

Options

• :base: The base (2..36) for integer conversion. Defaults to base 10 like String.to_integer/2.

Failure to parse the value of the environment variable will result in an exception.

Examples

iex> Enviable.fetch_env_as_integer!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("PORT", "5432")
iex> Enviable.fetch_env_as_integer!("PORT")
5432

iex> Enviable.put_env("PORT", "18eb")
iex> Enviable.fetch_env_as_integer!("PORT")
** (Enviable.ConversionError) could not convert environment variable "PORT" to type integer

iex> Enviable.put_env("PORT", "18EB")
iex> Enviable.fetch_env_as_integer!("PORT", base: 16)
6379

@spec fetch_env_as_json(String.t(), [
  {:engine, module() | (String.t() -> Enviable.Conversion.json())}
]) ::
  {:ok, Enviable.Conversion.json()} | :error

Returns the value of an environment variable converted to a Enviable.Conversion.json/0 value as {:ok, Conversion.json()} or :error if the variable is unset.

Options

• :engine: The JSON engine to use. May be provided as a module/0 (which must export decode/1), an arity 1 function, or a mfa/0 tuple. When provided with a mfa/0, the variable value will be passed as the first parameter.

  If the engine produces {:ok, json_value} or an expected JSON type result, it will be considered successful. Any other result will be treated as failure.

  The default JSON engine is :json if the Erlang/OTP :json module is available (Erlang/OTP 27+) or provided by json_polyfill. Otherwise, Jason is the default engine. This choice may be overridden with application configuration, as this example shows using Thoas.

  import Config
  
  config :enviable, :json_engine, :thoas

Examples

iex> Enviable.fetch_env_as_json("UNSET")
:error

iex> Enviable.put_env("JSON", ~S|[{"foo":"bar"}]|)
iex> Enviable.fetch_env_as_json("JSON")
{:ok, [%{"foo" => "bar"}]}

iex> Enviable.put_env("JSON", "ff")
iex> Enviable.fetch_env_as_json("JSON")
** (Enviable.ConversionError) could not convert environment variable "JSON" to type json

@spec fetch_env_as_json!(String.t(), [
  {:engine, module() | (String.t() -> Enviable.Conversion.json())}
]) ::
  Enviable.Conversion.json()

Returns the value of an environment variable converted to a Enviable.Conversion.json/0 value or raises an exception if the variable is unset.

Options

• :engine: The JSON engine to use. May be provided as a module/0 (which must export decode/1), an arity 1 function, or a mfa/0 tuple. When provided with a mfa/0, the variable value will be passed as the first parameter.

  If the engine produces {:ok, json_value} or an expected JSON type result, it will be considered successful. Any other result will be treated as failure.

  The default JSON engine is :json if the Erlang/OTP :json module is available (Erlang/OTP 27+) or provided by json_polyfill. Otherwise, Jason is the default engine. This choice may be overridden with application configuration, as this example shows using Thoas.

  import Config
  
  config :enviable, :json_engine, :thoas

Examples

iex> Enviable.fetch_env_as_json!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("JSON", ~S|[{"foo":"bar"}]|)
iex> Enviable.fetch_env_as_json!("JSON")
[%{"foo" => "bar"}]

iex> Enviable.put_env("JSON", "ff")
iex> Enviable.fetch_env_as_json!("JSON")
** (Enviable.ConversionError) could not convert environment variable "JSON" to type json

@spec fetch_env_as_list(String.t(), [
  {:default, term()}
  | {:as, :string | Enviable.Conversion.primitive()}
  | {:delimiter, String.t(), [String.t()], Regex.t(), :binary.cp()}
  | {:parts, pos_integer() | :infinity}
  | {:trim, boolean()}
  | {:on,
     :all | :first | :all_but_first | :none | :all_names | [binary() | atom()]}
  | {:include_captures, boolean()}
]) :: :error | {:ok, list()}

Returns the value of an environment variable parsed as a delimiter-separated list.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Each entry must conform to the permitted type provided in :as.
• :delimiter: The delimiter used to separate the list. This must be a pattern accepted by String.split/3 (a string, a list of strings, a compiled binary pattern, or a regular expression). Defaults to ",".
• :parts: The maximum number of parts to split into (pos_integer/0 or :infinity). Passed to String.split/3.
• :trim: A boolean option whether empty entries should be omitted.

When the pattern is a regular expression, Regex.split/3 options are also supported:

• :on: specifies which captures to split the string on, and in what order. Defaults to :first which means captures inside the regex do not affect the splitting process.
• :include_captures: when true, includes in the result the matches of the regular expression. The matches are not counted towards the maximum number of parts if combined with the :parts option. Defaults to false.

If :as is provided, the options for that type may also be provided.

Examples

iex> Enviable.put_env("LIST", "1,2,3")
iex> Enviable.fetch_env_as_list("LIST")
{:ok, ["1", "2", "3"]}
iex> Enviable.fetch_env_as_list("LIST", as: :integer)
{:ok, [1, 2, 3]}

iex> Enviable.put_env("LIST", "1;2;3")
iex> Enviable.fetch_env_as_list("LIST", delimiter: ";")
{:ok, ["1", "2", "3"]}
iex> Enviable.fetch_env_as_list("LIST", as: :integer, delimiter: ";")
{:ok, [1, 2, 3]}

@spec fetch_env_as_list!(String.t(), [
  {:default, term()}
  | {:as, :string | Enviable.Conversion.primitive()}
  | {:delimiter, String.t(), [String.t()], Regex.t(), :binary.cp()}
  | {:parts, pos_integer() | :infinity}
  | {:trim, boolean()}
  | {:on,
     :all | :first | :all_but_first | :none | :all_names | [binary() | atom()]}
  | {:include_captures, boolean()}
]) :: list()

Returns the value of an environment variable parsed as a delimiter-separated list.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Each entry must conform to the permitted type provided in :as.
• :delimiter: The delimiter used to separate the list. This must be a pattern accepted by String.split/3 (a string, a list of strings, a compiled binary pattern, or a regular expression). Defaults to ",".
• :parts: The maximum number of parts to split into (pos_integer/0 or :infinity). Passed to String.split/3.
• :trim: A boolean option whether empty entries should be omitted.

When the pattern is a regular expression, Regex.split/3 options are also supported:

• :on: specifies which captures to split the string on, and in what order. Defaults to :first which means captures inside the regex do not affect the splitting process.
• :include_captures: when true, includes in the result the matches of the regular expression. The matches are not counted towards the maximum number of parts if combined with the :parts option. Defaults to false.

If :as is provided, the options for that type may also be provided.

Examples

iex> Enviable.put_env("LIST", "1,2,3")
iex> Enviable.fetch_env_as_list!("LIST")
["1", "2", "3"]
iex> Enviable.fetch_env_as_list!("LIST", as: :integer)
[1, 2, 3]

iex> Enviable.put_env("LIST", "1;2;3")
iex> Enviable.fetch_env_as_list!("LIST", delimiter: ";")
["1", "2", "3"]
iex> Enviable.fetch_env_as_list!("LIST", as: :integer, delimiter: ";")
[1, 2, 3]

@spec fetch_env_as_log_level(String.t()) ::
  {:ok, Enviable.Conversion.log_level()} | :error

Returns the value of an environment variable converted to a log level atom/0 for Logger.configure/1 as {:ok, atom()} or :error if the variable is unset.

Examples

iex> Enviable.fetch_env_as_log_level("UNSET")
:error

iex> Enviable.put_env("LOG_LEVEL", "critical")
iex> Enviable.fetch_env_as_log_level("LOG_LEVEL")
{:ok, :critical}

@spec fetch_env_as_log_level!(String.t()) :: Enviable.Conversion.log_level()

Returns the value of an environment variable converted to a log level atom/0 for Logger.configure/1 or raises an exception if the variable is unset.

Examples

iex> Enviable.fetch_env_as_log_level!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("LOG_LEVEL", "critical")
iex> Enviable.fetch_env_as_log_level!("LOG_LEVEL")
:critical

@spec fetch_env_as_module(String.t(), [{:allowed, [module()]}]) ::
  {:ok, module()} | :error

Returns the value of an environment variable converted to module/0 as {:ok, module()} or :error if the variable is unset.

Options

• :allowed: A list of module/0 values indicating permitted module and used as a lookup table, if present. Any value not found will result in an exception.

Examples

iex> Enviable.fetch_env_as_module("UNSET")
:error

iex> Enviable.put_env("NAME", "Enviable")
iex> Enviable.fetch_env_as_module("NAME")
{:ok, Elixir.Enviable}

@spec fetch_env_as_module!(String.t(), [{:allowed, [module()]}]) :: module()

Returns the value of an environment variable converted to module/0 or raises an exception if the variable is unset.

Options

• :allowed: A list of module/0 values indicating permitted module and used as a lookup table, if present. Any value not found will result in an exception.

Examples

iex> Enviable.fetch_env_as_module!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("NAME", "Enviable")
iex> Enviable.fetch_env_as_module!("NAME")
Elixir.Enviable

@spec fetch_env_as_pem(String.t(), [{:filter, boolean() | :cert | :key}]) ::
  {:ok, Enviable.Conversion.pem()} | :error

Returns the value of an environment variable converted from a PEM string through :public_key.pem_decode/1 as {:ok, value} or :error if the variable is unset.

Options

• :filter: Filters the output of :public_key.pem_decode/1. Permitted values are false, true, :cert, or :key. The default is true.
  • false: the list is returned without processing, suitable for further processing with :public_key.pem_entry_decode/2.
  • true: returns the first unencrypted :PrivateKeyInfo found, a list of unencrypted :Certificate records, or an empty list.
  • :cert: returns a list of unencrypted :Certificate records or raises an exception if none are found.
  • :key: returns the first unencrypted :PrivateKeyIinfo record or raises an exception if one is not found.

Examples

iex> Enviable.fetch_env_as_pem("UNSET")
:error

iex> Enviable.put_env("PEM", "")
iex> Enviable.fetch_env_as_pem("PEM")
{:ok, []}

@spec fetch_env_as_pem!(String.t(), [{:filter, boolean() | :cert | :key}]) ::
  Enviable.Conversion.pem()

Returns the value of an environment variable converted from a PEM string through :public_key.pem_decode/1 or raises an exception if the variable is unset.

Options

• :filter: Filters the output of :public_key.pem_decode/1. Permitted values are false, true, :cert, or :key. The default is true.
  • false: the list is returned without processing, suitable for further processing with :public_key.pem_entry_decode/2.
  • true: returns the first unencrypted :PrivateKeyInfo found, a list of unencrypted :Certificate records, or an empty list.
  • :cert: returns a list of unencrypted :Certificate records or raises an exception if none are found.
  • :key: returns the first unencrypted :PrivateKeyIinfo record or raises an exception if one is not found.

Examples

iex> Enviable.fetch_env_as_pem!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("PEM", "")
iex> Enviable.fetch_env_as_pem!("PEM")
[]

@spec fetch_env_as_safe_atom(String.t(), [
  {:allowed, [atom()]} | Enviable.Conversion.opt_downcase()
]) ::
  {:ok, atom()} | :error

Returns the value of an environment variable converted to an existing atom/0 as {:ok, atom()} or :error if the variable is unset.

Options

• :allowed: A list of atom/0 values indicating permitted atoms and used as a lookup table, if present. Any value not found will result in an exception.
• :downcase: See Enviable.Conversion.opt_downcase/0.
• :upcase: See Enviable.Conversion.opt_upcase/0.

Examples

iex> Enviable.fetch_env_as_safe_atom("UNSET")
:error

iex> Enviable.put_env("NAME", "FETCH_ENV_AS_SAFE_ATOM")
iex> Enviable.fetch_env_as_safe_atom("NAME", downcase: true)
{:ok, :fetch_env_as_safe_atom}

@spec fetch_env_as_safe_atom!(String.t(), [
  {:allowed, [atom()]} | Enviable.Conversion.opt_downcase()
]) ::
  atom()

Returns the value of an environment variable converted to an existing atom/0 or raises an exception if the variable is unset.

Options

• :allowed: A list of atom/0 values indicating permitted atoms and used as a lookup table, if present. Any value not found will result in an exception.
• :downcase: See Enviable.Conversion.opt_downcase/0.
• :upcase: See Enviable.Conversion.opt_upcase/0.

Examples

iex> Enviable.fetch_env_as_safe_atom!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("NAME", "FETCH_ENV_AS_SAFE_ATOM!")
iex> Enviable.fetch_env_as_safe_atom!("NAME", downcase: true)
:fetch_env_as_safe_atom!

@spec fetch_env_as_safe_module(String.t(), [{:allowed, [module()]}]) ::
  {:ok, module()} | :error

Returns the value of an environment variable converted to module/0 as {:ok, module()} or :error if the variable is unset. The resulting module/0 must already exist.

Options

• :allowed: A list of module/0 values indicating permitted module and used as a lookup table, if present. Any value not found will result in an exception.

Examples

iex> Enviable.fetch_env_as_safe_module("UNSET")
:error

iex> Enviable.put_env("NAME", "Enviable")
iex> Enviable.fetch_env_as_safe_module("NAME")
{:ok, Elixir.Enviable}

@spec fetch_env_as_safe_module!(String.t(), [{:allowed, [module()]}]) :: module()

Returns the value of an environment variable converted to module/0 or raises an exception if the variable is unset. The resulting module/0 must already exist.

Options

• :allowed: A list of module/0 values indicating permitted module and used as a lookup table, if present. Any value not found will result in an exception.

Examples

iex> Enviable.fetch_env_as_safe_module!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("NAME", "Enviable")
iex> Enviable.fetch_env_as_safe_module!("NAME")
Elixir.Enviable

@spec fetch_env_as_url_base64(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: :error | {:ok, term()}

Returns the value of an environment variable decoded as a URL-safe base 64 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :ignore_whitespace: Whether to ignore whitespace values. The default is true, the opposite default for both Base.decode64/2 and Base.url_decode64/2.
• :padding: The boolean value of :padding passed to Base.decode64/2. The default is false (the opposite of Base.decode64/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.url_encode64("RED", padding: true)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_url_base64("NAME", padding: false)
{:ok, "RED"}
iex> Enviable.fetch_env_as_url_base64("NAME", as: :string, padding: true)
{:ok, "RED"}
iex> Enviable.fetch_env_as_url_base64("NAME", as: :atom, downcase: true, padding: false)
{:ok, :red}

@spec fetch_env_as_url_base64!(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: term()

Returns the value of an environment variable decoded as a URL-safe base 64 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :ignore_whitespace: Whether to ignore whitespace values. The default is true, the opposite default for both Base.decode64/2 and Base.url_decode64/2.
• :padding: The boolean value of :padding passed to Base.decode64/2. The default is false (the opposite of Base.decode64/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.url_encode64("RED", padding: true)
iex> Enviable.put_env("NAME", red)
iex> Enviable.fetch_env_as_url_base64!("NAME", padding: false)
"RED"
iex> Enviable.fetch_env_as_url_base64!("NAME", as: :string, padding: true)
"RED"
iex> Enviable.fetch_env_as_url_base64!("NAME", as: :atom, downcase: true, padding: false)
:red

@spec fetch_env_boolean(
  String.t(),
  keyword()
) :: {:ok, boolean()} | :error

Returns the value of an environment variable as {:ok, t:boolean/0} value or :error if the variable is unset. See fetch_env_as_boolean/2 or more details.

Examples

iex> Enviable.fetch_env_boolean("UNSET")
:error

iex> Enviable.put_env("FLAG", "1")
iex> Enviable.fetch_env_boolean("FLAG")
{:ok, true}

@spec fetch_env_boolean!(
  String.t(),
  keyword()
) :: boolean()

Returns the value of an environment variable converted to a boolean/0 value or raises an exception if the variable is unset. See fetch_env_as_boolean!/2 for details.

iex> Enviable.fetch_env_boolean!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("FLAG", "1")
iex> Enviable.fetch_env_boolean!("FLAG")
true

@spec fetch_env_integer(
  String.t(),
  keyword()
) :: {:ok, integer()} | :error

Returns the value of an environment variable as {:ok, t:integer/0} or :error if the variable is unset. See fetch_env_as_integer/2 for details.

Examples

iex> Enviable.fetch_env_integer("UNSET")
:error

iex> Enviable.put_env("PORT", "1")
iex> Enviable.fetch_env_integer("PORT")
{:ok, 1}

@spec fetch_env_integer!(
  String.t(),
  keyword()
) :: integer()

Returns the value of an environment variable converted to a integer/0 value raises an exception if the variable is unset. See fetch_env_as_integer!/2 for details.

Examples

iex> Enviable.fetch_env_integer!("UNSET")
** (System.EnvError) could not fetch environment variable "UNSET" because it is not set

iex> Enviable.put_env("PORT", "1")
iex> Enviable.fetch_env_integer!("PORT")
1

@spec get_env_as(String.t(), Enviable.Conversion.conversion(), keyword()) ::
  nil | term()

Returns the value of an environment variable converted to the target type or a default value if the variable is unset. If no default is provided, nil is returned (unless converting to :boolean, which will return false).

Supported primitive conversions are:

• :atom (Enviable.Conversion.convert_atom/0, get_env_as_atom/2)
• :boolean (Enviable.Conversion.convert_boolean/0, get_env_as_boolean/2)
• :charlist (Enviable.Conversion.convert_charlist/0, get_env_as_charlist/2)
• :decimal (Enviable.Conversion.convert_decimal/0, get_env_as_decimal/2)
• :elixir (Enviable.Conversion.convert_elixir/0, get_env_as_elixir/1)
• :erlang (Enviable.Conversion.convert_erlang/0, get_env_as_erlang/1)
• :float (Enviable.Conversion.convert_float/0, get_env_as_float/2)
• :integer (Enviable.Conversion.convert_integer/0, get_env_as_integer/2)
• :json (Enviable.Conversion.convert_json/0, get_env_as_json/2)
• :log_level (Enviable.Conversion.convert_log_level/0, get_env_as_log_level/2)
• :module (Enviable.Conversion.convert_module/0, get_env_as_module/2)
• :pem (Enviable.Conversion.convert_pem/0, get_env_as_pem/2)
• :safe_atom (Enviable.Conversion.convert_safe_atom/0, get_env_as_safe_atom/2)
• :safe_module (Enviable.Conversion.convert_safe_module/0, get_env_as_safe_module/2)

Supported encoded conversions are:

• :base16 (Enviable.Conversion.encoded_base16/0, get_env_as_base16/2)
• :base32 (Enviable.Conversion.encoded_base32/0, get_env_as_base32/2)
• :base64, :url_base64 (Enviable.Conversion.encoded_base64/0, get_env_as_base64/2, get_env_as_url_base64/2)
• :hex32 (Enviable.Conversion.encoded_hex32/0, get_env_as_hex32/2)
• :list (Enviable.Conversion.encoded_list/0, get_env_as_list/2)

See Enviable.Conversion for supported type conversions and options.

Value Conversion and Default Values

Value conversion will be applied only to values contained in the requested environment variable. Default values are used only when the environment variable is unset. There is a meaningful difference between an unset environment variable (where System.get_env/1 will return nil) and an empty environment variable (where System.get_env/1 returns "").

$ FOO= elixir -e 'IO.inspect([foo: System.get_env("FOO"), bar: System.get_env("BAR")])'
[foo: "", bar: nil]

Examples

iex> Enviable.get_env_as("UNSET", :atom)
nil

iex> Enviable.get_env_as("UNSET", :float)
nil

iex> Enviable.get_env_as("UNSET", :base16)
nil

iex> Enviable.put_env("NAME", "get_env_as")
iex> Enviable.get_env_as("NAME", :atom)
:get_env_as

iex> Enviable.put_env("NAME", "GET_ENV_AS")
iex> Enviable.get_env_as("NAME", :safe_atom, downcase: true)
:get_env_as

iex> Enviable.get_env_as("FLOAT", :float, default: "3.5")
3.5

iex> Enviable.get_env_as("FLOAT", :float, default: 3.5)
3.5

iex> Enviable.put_env("FLOAT", "3")
iex> Enviable.get_env_as("FLOAT", :float)
3.0

iex> Enviable.put_env("FLOAT", "3.1")
iex> Enviable.get_env_as("FLOAT", :float)
3.1

iex> red = Base.encode16("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.get_env_as("NAME", :base16, case: :lower)
"RED"
iex> Enviable.get_env_as("NAME", {:base16, :string}, case: :lower)
"RED"
iex> Enviable.get_env_as("NAME", {:base16, :atom}, case: :lower, downcase: true)
:red

iex> Enviable.put_env("LIST", "1,2,3")
iex> Enviable.get_env_as("LIST", :list)
["1", "2", "3"]
iex> Enviable.get_env_as("LIST", {:list, :integer})
[1, 2, 3]

iex> Enviable.put_env("LIST", "1;2;3")
iex> Enviable.get_env_as("LIST", :list, delimiter: ";")
["1", "2", "3"]
iex> Enviable.get_env_as("LIST", {:list, :integer}, delimiter: ";")
[1, 2, 3]

@spec get_env_as_atom(
  String.t(),
  atom()
  | binary()
  | [
      {:allowed, [atom()]}
      | {:default, atom() | binary()}
      | Enviable.Conversion.opt_downcase()
    ]
) :: nil | atom()

Returns the value of an environment variable converted to atom/0 or a default value if the variable is unset. If no default is provided, nil is returned.

Options

• :allowed: A list of atom/0 values indicating permitted atoms and used as a lookup table, if present. Any value not found will result in an exception.
• :default: The atom/0 or binary/0 value representing the atom value to use if the environment variable is unset (nil). If the :allowed option is present, the default value must be one of the permitted values.
• :downcase: See Enviable.Conversion.opt_downcase/0.
• :upcase: See Enviable.Conversion.opt_upcase/0.

A shorthand for the default option may be provided as a atom/0 value.

Examples

iex> Enviable.get_env_as_atom("UNSET")
nil

iex> Enviable.get_env_as_atom("UNSET", :default)
:default

iex> Enviable.get_env_as_atom("UNSET", default: :default)
:default

iex> Enviable.put_env("NAME", "get_env_as_atom")
iex> Enviable.get_env_as_atom("NAME")
:get_env_as_atom

@spec get_env_as_base16(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed
) :: nil | term()

Returns the value of an environment variable decoded as a base 16 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.decode16/2, which must be :upper, :lower, or :mixed.

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode16("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.get_env_as_base16("NAME", case: :lower)
"RED"
iex> Enviable.get_env_as_base16("NAME", as: :string, case: :lower)
"RED"
iex> Enviable.get_env_as_base16("NAME", as: :atom, case: :lower, downcase: true)
:red

@spec get_env_as_base32(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: nil | term()

Returns the value of an environment variable decoded as a base 32 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :case: The value of :case passed to Base.decode32/2, which must be :upper, :lower, or :mixed.
• :padding: The boolean value of :padding passed to Base.decode32/2. The default is false (the opposite of Base.decode32/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode32("RED", case: :lower)
iex> Enviable.put_env("NAME", red)
iex> Enviable.get_env_as_base32("NAME", case: :lower)
"RED"
iex> Enviable.get_env_as_base32("NAME", as: :string, case: :lower)
"RED"
iex> Enviable.get_env_as_base32("NAME", as: :atom, case: :lower, downcase: true)
:red

@spec get_env_as_base64(String.t(),
  default: term(),
  as: :string | Enviable.Conversion.primitive(),
  case: :upper | :lower | :mixed,
  padding: boolean()
) :: nil | term()

Returns the value of an environment variable decoded as a base 64 string.

Options

• :as: The type of value that the encoded string is to be parsed as once decoded. Must be either :string (the same as not providing as: :string) or a t:Conversion.primit/0 value.
• :default: The default value to be used. Must conform to the permitted type provided in :as.
• :ignore_whitespace: Whether to ignore whitespace values. The default is true, the opposite default for both Base.decode64/2 and Base.url_decode64/2.
• :padding: The boolean value of :padding passed to Base.decode64/2. The default is false (the opposite of Base.decode64/2).

If :as is provided, the options for that type may also be provided.

Examples

iex> red = Base.encode64("RED", padding: true)
iex> Enviable.put_env("NAME", red)
iex> Enviable.get_env_as_base64("NAME", padding: false)
"RED"
iex> Enviable.get_env_as_base64("NAME", as: :string, padding: true)
"RED"
iex> Enviable.get_env_as_base64("NAME", as: :atom, downcase: true, padding: false)
:red