# gourd

An accessible config library for Erlang applications.

## Build

    rebar3 compile

## Usage

Add gourd to your rebar.config:

    {deps, [gourd]}.

Load the config at application startup.

    -module(example_app).
    -behaviour(application).
    -export([start/2, stop/1]).

    start(_StartType, _StartArgs) ->
        gourd:load(),
        example_sup:start_link().

    stop(_State) ->
        ok.

By default `gourd:load` will load `gourd.toml` from the application's
private directory and set config values for the calling application.

If the above example loaded a `gourd.toml` like this:

    hello = "world"

The config value of `hello` would be accessible like this:

    {ok, Hello} = application:get_env(example, hello).
    Hello == <<"world">>

The first set of keys in the TOML file are converted to atoms.

## Customize Loading

If gourd's default's don't suit you. The `gourd` library supports `load/1` and `load/2`.

Specify the application you want `priv/gourd.toml` to apply to:

    gourd:load(example).

To specify the application and the path to load the config file from:

    gourd:load(example, "priv/other_gourd.toml")

OR outside of the priv dir:

    gourd:load(example, "config.toml")

## Environment Variables

It is common to need to load a environment variables at the start of your application.

This feature is supported in `gourd` by parsing special values in strings and replacing them with their corresponding
environment variables.

Assuming these environment variables are present in the running process:

    export WORLD="world"
    export ENV="prod"
    export AWS_REGION="us-east-1"

We can load these as part of the config with a TOML file like this:

    hello = "${WORLD}"
    env = "${ENV}"
    aws_region = "${AWS_REGION}"

This would result in a config that looked like this:

    #{hello => <<"world">>,
      env => <<"prod">>,
      aws_region => <<"us-east-1">>}

Special values can even be parsed in the middle of a string:

    bucket = "example-${ENV}-${AWS_REGION}"

Would return a config like this:

    #{bucket => <<"example-prod-us-east-1">>}

String replacing even works in nested data structures. With the exception that map keys are not replaced.

A toml file like this:

    list_values = ["hello", "${WORLD}"]

    [map_values]
    key1 = "stuff"
    key2 = "${ENV}stuff"

Would return a config like this:

    #{list_values => [<<"hello">>, <<"world">>],
      map_values => #{<<"key1">> => <<"stuff">>,
                      <<"key2">> => <<"prodstuff">>}}