Mix.Config

Module for defining, reading and merging app configurations.

Most commonly, this module is used to define your own configuration:

use Mix.Config

config :plug,
  key1: "value1",
  key2: "value2"

import_config "#{Mix.env}.exs"

All config/* macros, including import_config/1, are used to help define such configuration files.

Furthermore, this module provides functions like read!/1, merge/2 and friends which help manipulate configurations in general.

Configuration set using Mix.Config will set the application env, so that Application.get_env/3 and other Application functions can be used at run or compile time to retrieve or change the configuration.

For example, the :key1 value from application :plug (see above) can be retrieved with:

"value1" = Application.fetch_env!(:plug, :key1)

Summary

Functions

config(app, opts)

Configures the given application

config(app, key, opts)

Configures the given key for the given application

import_config(path_or_wildcard)

Imports configuration from the given file or files

merge(config1, config2)

Merges two configurations

persist(config)

Persists the given configuration by modifying the configured applications environment

read!(file, loaded_paths \\ [])

Reads and validates a configuration file

read_wildcard!(path, loaded_paths \\ [])

Reads many configuration files given by wildcard into a single config

validate!(config)

Validates a configuration

Functions

config(app, opts) (macro)

Configures the given application.

Keyword lists are always deep merged.

Examples

The given opts are merged into the existing configuration for the given app. Conflicting keys are overridden by the ones specified in opts. For example, the declaration below:

config :lager,
  log_level: :warn,
  mode: :truncate

config :lager,
  log_level: :info,
  threshold: 1024

Will have a final configuration of:

[log_level: :info, mode: :truncate, threshold: 1024]

This final configuration can be retrieved at run or compile time:

Application.get_all_env(:lager)

config(app, key, opts) (macro)

Configures the given key for the given application.

Keyword lists are always deep merged.

Examples

The given opts are merged into the existing values for key in the given app. Conflicting keys are overridden by the ones specified in opts. For example, given the two configurations below:

config :ecto, Repo,
  log_level: :warn,
  adapter: Ecto.Adapters.Postgres

config :ecto, Repo,
  log_level: :info,
  pool_size: 10

the final value of the configuration for the Repo key in the :ecto application will be:

[log_level: :info, pool_size: 10, adapter: Ecto.Adapters.Postgres]

This final value can be retrieved at runtime or compile time with:

Application.get_env(:ecto, Repo)

import_config(path_or_wildcard) (macro)

Imports configuration from the given file or files.

If path_or_wildcard is a wildcard, then all the files matching that wildcard will be imported; if no file matches the wildcard, no errors are raised. If path_or_wildcard is not a wildcard but a path to a single file, then that file is imported; in case the file doesn’t exist, an error is raised. This behaviour is analogous to the one for read_wildcard!/1.

If path/wildcard is a relative path/wildcard, it will be expanded relatively to the directory the current configuration file is in.

Examples

This is often used to emulate configuration across environments:

import_config "#{Mix.env}.exs"

Or to import files from children in umbrella projects:

import_config "../apps/*/config/config.exs"

merge(config1, config2)

Merges two configurations.

The configuration of each application is merged together with the values in the second one having higher preference than the first in case of conflicts.

Examples

iex> Mix.Config.merge([app: [k: :v1]], [app: [k: :v2]])
[app: [k: :v2]]

iex> Mix.Config.merge([app1: []], [app2: []])
[app1: [], app2: []]

persist(config)

Persists the given configuration by modifying the configured applications environment.

config should be a list of {app, app_config} tuples or a %{app => app_config} map where app are the applications to be configured and app_config are the configuration (as key-value pairs) for each of those applications.

Returns the configured applications.

Examples

Mix.Config.persist(logger: [level: :error], my_app: [my_config: 1])
#=> [:logger, :my_app]

read!(file, loaded_paths \\ [])

Reads and validates a configuration file.

file is the path to the configuration file to be read. If that file doesn’t exist or if there’s an error loading it, a Mix.Config.LoadError exception will be raised.

loaded_paths is a list of configuration files that have been previously read. If file exists in loaded_paths, a Mix.Config.LoadError exception will be raised.

read_wildcard!(path, loaded_paths \\ [])

Reads many configuration files given by wildcard into a single config.

Raises an error if path is a concrete filename (with no wildcards) but the corresponding file does not exist; if path matches no files, no errors are raised.

loaded_paths is a list of configuration files that have been previously read.

validate!(config)

Validates a configuration.

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/mix/1.6.6/Mix.Config.html