Env is an improved application configuration reader for Elixir.
Env allows you to access easily the configuration of your application
similar to what Application.get_env/3
does, but understands the
{:system, "NAME"}
convention of using system environment variables
in application configuration.
When Env initially retrieves the configuration it will walk recursively
any keyword lists and properly replace any occurrences of:
{:system, "NAME"}
or {:system, "NAME", default}
with value extracted
from the environment using System.get_env("NAME")
.
When a tuple without default value is used, but the environment variable is not set an exception will be raised.
Result of any lookups (both successful and not) is cached in an ETS table -
the same mechanism that the Erlang VM uses internally for storing regular
application configuration. This guarantees that subsequent lookups are as
fast as are those using functions from Application
module.
When you expect the configuration to change, you can use Env.refresh/3
to
read the value again ignoring the cache or Env.clear/1
and Env.clear/2
in
order to clear the cache.
WARNING: because Env uses ETS table to store it's cache it is not available
at compile-time. When you need some compile-time configuration using regular
Application.get_env/3
is probably the best option. This should not be a huge
problem in practice, because configuration should be moved as much as possible
to the runtime, allowing for easy changes, which is not possible with compile-time
settings.
The package can be installed as:
- Add env to your list of dependencies in
mix.exs
:
def deps do
[{:env, "~> 0.1"}]
end
- Ensure env is started before your application:
def application do
[applications: [:env]]
end
With configuration in config/config.exs
as follows:
config :my_app, :key,
enable_server: true,
host: [port: {:system, "PORT", 80}],
secret_key_base: {:system, "SECRET_KEY_BASE"}
And environment where PORT
is not set, while SECRET_KEY_BASE
has value foo
You can access it with Env
using:
Env.fetch!(:my_app, :key)
[enable_server: true, host: [port: 80], secret_key_base: "foo"]
All functions used for accessing the environment accept a :transformer
option. This function can be used to parse any configuration read from system
environment - all values access from the environment are strings.
A binary function passes as the :transformer
will receive path for the current
key as the first argument, and the value from the environment as the second one.
Using the example from above, we could use that mechanism to force port to
always be an integer:
transformer = fn
[:key, :host, :port], value -> String.to_integer(value)
_, value -> value
end
And pass it to one of the reader functions:
Env.fetch(:my_app, :key, transformer: transformer)
{:ok, [enable_server: true, host: [port: 80], secret_key_base: "foo"]}
Copyright 2016 Michał Muskała
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.