@type conversion() :: primitive() | encoded()

All supported conversions.

@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

• :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 is true

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

@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 (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 is passed as the first parameter.

  If the engine produces {:ok, json_value} or an expected JSON type result, it is considered successful. Any other result is 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 is 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 convert_timeout() :: :timeout

Indicates a conversion to timeout/0.

Supported only on Elixir 1.17+.

Timeout Values

Timeout values are specified as non-negative integer values with optional suffixes or the word infinity. The integer part may have underscores (_) separating digits like Elixir itself.

If no suffix is present, the value is in milliseconds. Supported suffixes are:

• week, weeks, w: the number of weeks (always 7 days)
• day, days, d: the number of days (always 24 hours)
• hour, hours, h: the number of hours (always 60 minutes)
• minute, minutes, m: the number of minutes (always 60 seconds)
• second, seconds, s: the number of seconds (always 1000 milliseconds)
• millisecond, milliseconds, ms: the number of milliseconds

Suffixes may be present with or without a space (30s and 30 s are the same value), and multiple timeouts may be chained (1h 30m), but may not be duplicated. See Kernel.to_timeout/1 for more details.

Only lowercase suffixes are supported.

@type encoded() ::
  encoded_base16()
  | encoded_base32()
  | encoded_hex32()
  | encoded_base64()
  | encoded_list()

All supported encoded conversions.

@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.

@type primitive() ::
  convert_atom()
  | convert_boolean()
  | convert_charlist()
  | convert_decimal()
  | convert_elixir()
  | convert_erlang()
  | convert_float()
  | convert_integer()
  | convert_json()
  | convert_module()
  | convert_pem()
  | convert_safe_atom()
  | convert_safe_module()
  | convert_timeout()

All supported primitive conversions.

@type timeout_default() ::
  binary()
  | {:week | :day | :hour | :minute | :second | :millisecond, non_neg_integer()}
  | timeout()
  | Duration.t()

Supported default values for timeout conversions.