@type convert_atom() :: :atom

Indicates a conversion to atom/0.

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 opt_downcase/0.
• :upcase: See opt_upcase/0.

@type convert_boolean() :: :boolean

Indicates a conversion to boolean/0. This conversion will always result in a true or false value.

Options

• :default: The default value, which must be true or false. The default value is false.

• :downcase: This option controls a type conversion's case folding mode passed to String.downcase/2. The default is false. true has the same meaning as :default.

  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.

• :truthy, :falsy: Only one of :truthy or :falsy may be specified. It must be a list of binary/0 values. If neither is specified, the default is truthy: ~w[1 true].

  • :truthy: if the value to convert is in this list, the result will be true

  • :falsy: if the value to convert is in this list, the result will be false

In a future version of Enviable, the default value of :downcase for boolean conversions will change from false to true.

@type convert_charlist() :: :charlist

Indicates a conversion to charlist/0.

Options

• :default: The default value, either as a charlist/0 or binary/0.

@type convert_decimal() :: :decimal

Indicates a conversion to Decimal.t/0.

Options

• :default: The default value, either as Decimal.t/0, float/0, integer/0, or binary/0 (the latter three must convert cleanly to Decimal.t/0).

@type convert_elixir() :: :elixir

Indicates a conversion from a Elixir code string (:elixir) by parsing and evaluating the environment variable value.

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.put_env("PORT", "11000..11100//3")
iex> Enviable.get_env_as("PORT", :elixir)
11000..11100//3

@type convert_erlang() :: :erlang

Indicates a conversion from a Erlang code string (:erlang) by parsing and evaluating the environment variable value.

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.put_env("COLOR", "{ok, true}.")
iex> Enviable.get_env_as("COLOR", :erlang)
{:ok, true}

@type convert_float() :: :float

Indicates a conversion to float/0.

Options

• :default: The default value, either as float/0, integer/0 (which will be converted to float), or binary/0 (which must parse cleanly as float).

@type convert_integer() :: :integer

Indicates a conversion to integer/0.

Options

• :base: The base (an integer value 2..36). Default is 10.
• :default: The default value. If specified as a binary/0, it must be expressed in the :base value and convert cleanly to an integer.

@type convert_json() :: :json

Indicates a conversion from JSON, which may result in nil, binary/0, boolean/0, list/0, map/0, or number/0 values.

Options

• :default: The default value, which may be any valid JSON type.

• :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 module is selected from the :enviable application configuration option :json_engine. If this is unset, the default value is one of the following, in order:

  • JSON if the Elixir JSON module is available (Elixir 1.18+)
  • :json if the Erlang/OTP 27+ :json module is available or if json_polyfill is installed
  • Jason

  This example shows using Thoas as the JSON engine..

  import Config
  
  config :enviable, :json_engine, :thoas

@type convert_log_level() :: :log_level

Indicates a conversion to log level atom/0 for Logger.configure/1.

This conversion is always case-insensitive, and the result will be one of :emergency, :alert, :critical, :error, :warning, :warn, :notice, :info, :debug, :all, or :none.

Options

• :default: The default atom value. Must be a valid value.

@type convert_module() :: :module

Indicates a conversion to module/0.

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.
• :default: The module/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.

@type convert_pem() :: :pem

Indicates a conversion from a PEM string through :public_key.pem_decode/1.

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.

@type convert_safe_atom() :: :safe_atom

Indicates a conversion to atom/0.

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 opt_downcase/0.
• :upcase: See opt_upcase/0.

@type convert_safe_module() :: :safe_module

Indicates a conversion to module/0.

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.
• :default: The module/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.

@type encoded_base16() :: :base16 | {:base16, :string | primitive()}

Decodes the value from a base 16 encoded string. If a secondary type is provided, a further conversion pass is made using the secondary type.

Options

• :case: The value of :case passed to Base.decode16/2, which must be :upper, :lower, or :mixed.

If a secondary type is provided, the options for that type may also be provided.

@type encoded_base32() :: :base32 | {:base32, :string | primitive()}

Decodes the value from a base 32 encoded string. If a secondary type is provided, a further conversion pass is made using the secondary type.

Options

• :case: The value of :case passed to Base.decode32/2, which must be :upper, :lower, or :mixed. The default is :upper.
• :padding: The boolean value of :padding passed to Base.decode32/2. The default is false (the opposite of Base.decode32/2).

If a secondary type is provided, the options for that type may also be provided.

@type encoded_base64() ::
  :base64 | :url_base64 | {:base64 | :url_base64, :string | primitive()}

Decodes the value from a base 64 encoded string. If a secondary type is provided, a further conversion pass is made using the secondary type.

Options

• :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 a secondary type is provided, the options for that type may also be provided.

@type encoded_hex32() :: :hex32 | {:hex32, :string | primitive()}

Decodes the value from a base 32 hex encoded string with extended hexadecimal alphabet. If a secondary type is provided, a further conversion pass is made using the secondary type.

Options

• :case: The value of :case passed to Base.hex_decode32/2, which must be :upper, :lower, or :mixed. The default is :upper.
• :padding: The boolean value of :padding passed to Base.hex_decode32/2. The default is false (the opposite of Base.hex_decode32/2).

If a secondary type is provided, the options for that type may also be provided.

@type encoded_list() :: :list | {:list, :string | primitive()}

Decodes the value from a string as a delimiter-separated list. If a secondary type is provided, a further conversion pass is made using the secondary type.

Options

• :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 a secondary type is provided, the options for that type may also be provided.

@type json() ::
  nil
  | String.t()
  | boolean()
  | number()
  | [json()]
  | %{optional(String.t()) => json()}

A value which can be serialized from JSON.

@type log_level() :: Logger.level() | :all | :none

Supported log levels.

@type opt_downcase() ::
  {:downcase, true | false | :default | :ascii | :greek | :turkic}

This option controls a type conversion's case folding mode passed to String.downcase/2.

The default is false. true has the same meaning as :default.

This is mutually exclusive with upcase.

@type opt_upcase() :: {:upcase, true | false | :default | :ascii | :greek | :turkic}

This option controls a type conversion's case folding mode passed to String.upcase/2.

The default is false. true has the same meaning as :default.

This is mutually exclusive with downcase.

@type pem() ::
  [:public_key.pem_entry()]
  | binary()
  | [{:Certificate, binary(), :not_encrypted}]

Possible return types for convert_pem/0 conversions.

The return types are variant on the conversion :filter option value:

• true: either an unencrypted primary key binary/0 or a list of unencrypted certificates ([{:Certificate, ct, :not_encrypted}]);
• false: an unmodified list of :public_key.pem_entry/0.
• :cert: list of unencrypted certificates ([{:Certificate, ct, :not_encrypted}]).
• :key: unencrypted primary key binary/0

The default is true.