Specs

env(variable :: binary(), type :: atom(), default :: any()) ::
  any() | no_return()

Reads a system environment variable and converts its output or returns a default value.

If the given system environment variable is set, its value is converted to the given type. The default value is only used when the system environment variable is not set; the default value is retur as-is, without conversion. This allows greater control of the output.

Although this relies on System.fetch_env/1, it may still raise an error if an unsupported type is provided or if non-empty values are required.

The conversion is delegated to Dotenvy.Transformer.to/2 -- see its documentation for a list of supported types.

Examples

iex> env("PORT", :integer, 5432)
5433
iex> env("NOT_SET", :boolean, %{not: "converted"})
%{not: "converted"}
iex> System.put_env("HOST", "")
iex> env("HOST", :string!, "localhost")
** (Dotenvy.Transformer.Error) non-empty value required

Specs

env!(variable :: binary(), type :: atom()) :: any() | no_return()

Reads the given system environment variable and converts its value to the given type.

This relies on System.fetch_env!/1 so it will raise if a variable is not set or if empty values are encounted when non-empty values are required.

The conversion is delegated to Dotenvy.Transformer.to/2 -- see its documentation for a list of supported types.

Examples

iex> env!("PORT", :integer)
5432
iex> env!("ENABLED", :boolean)
true

Specs

source(files :: binary() | [binary()], opts :: keyword()) ::
  {:ok, %{optional(String.t()) => String.t()}} | {:error, any()}

Like Bash's source command, this loads the given file(s) and sets the corresponding system environment variables using a side effect function (&System.put_env/1 by default).

Files are processed in the order they are given. Values parsed from one file may override values parsed from previous files: the last file parsed has final say. The :overwrite? option determines how the parsed values will be merged with the existing system values.

Options

• :overwrite? boolean indicating whether or not values parsed from provided .env files should overwrite existing system environment variables. It is recommended to keep this false: setting it to true means that you cannot set variables on the command line, e.g. LOG_LEVEL=debug iex -S mix Default: false

• :parser module that implements Dotenvy.parse/3 callback. Default: Dotenvy.Parser

• :require_files specifies which of the given files (if any) must be present. When true, all the listed files must exist. When false, none of the listed files must exist. When some of the files are required and some are optional, provide a list specifying which files are required. Default: false

• :side_effect an arity 1 function called after the successful parsing of each of the given files. The default is &System.put_env/1, which will have the effect of setting system environment variables based on the results of the file parsing.

• :vars a map with string keys representing the starting pool of variables. Default: output of System.get_env/0.

Examples

iex> Dotenvy.source(".env")
{:ok, %{
  "PWD" => "/users/home",
  "DATABASE_URL" => "postgres://postgres:postgres@localhost/myapp",
  # ...etc...
  }
}

# If you only want to return the parsed contents of the listed files
# ignoring system environment variables altogether
iex> Dotenvy.source(["file1", "file2"], side_effect: false, vars: %{})

Specs

source!(files :: binary() | [binary()], opts :: keyword()) ::
  %{optional(String.t()) => String.t()} | no_return()

As source/2, but returns map on success or raises on error.