# Skogsra

[![Build Status](]( [![Hex pm](]( [![ downloads](](

> The _Skogsrå_ was a mythical creature of the forest that appears in the form
> of a small, beautiful woman with a seemingly friendly temperament. However,
> those who are enticed into following her into the forest are never seen
> again.

This library attempts to improve the use of OS environment variables for
application configuration:

  * Automatic type casting of values.
  * Options documentation.
  * Variables defaults.

## Small Example

You would create a settings module and define the e.g:

defmodule MyApp.Settings do
  use Skogsra

  system_env :some_service_port,
    default: 4000

  app_env :some_service_hostname, :my_app, :hostname,
    domain: MyApp.Domain,
    default: "localhost"

and you would use it in a module as follows:

defmodule MyApp.SomeModule do
  alias MyApp.Setting


  def connect do
    hostname = Settings.some_service_hostname()
    port = Settings.some_service_port()

    SomeService.connect(hostname, port)


### Example Explanation

The module `MyApp.Settings` will have two functions e.g:

  * `some_service_port/0`: Returns the port as an integer. Calling this
    function is roughly equivalent to the following code (without the automatic
    type casting):

    System.get_env("SOME_SERVICE_PORT") || 4000

  * `some_service_hostname/0`: Returns the hostname as a binary. Calling this
    function is roughly equivalent to the following code (without the automatic
    type casting):

    case System.get_env("SOME_SERVICE_HOSTNAME") do
      nil ->
        |> Application.get_env(MyApp.Domain, [])
        |> Keyword.get(:hostname, "localhost")
      value ->

Things to note:
  1. The functions have the same name as the OS environment variable, but in
     lower case.
  2. The functions infer the type from the `default` value. If no default value
     is provided, it will be casted as binary by default.
  3. Both functions try to retrieve and cast the value of an OS environment
     variable, but the one declared with `app_env` searches for `:my_app`
     configuration if the OS environment variable is empty:

     config :my_app, MyApp.Domain,
       hostname: "some_hostname"

If the default value is not present, Skogsra cannot infer the type, unless the
type is set with the option `type`. The possible values for `type` are
`:integer`, `:float`, `:boolean`, `:atom` and `:binary`.

## Recommended Usage

The recommended way of using this project is to define a `.env` file in the
root of your project with the variables that you want to define e.g:


and then when `source`ing the file right before you execute your application.
In `bash` (or `zsh`) would be like this:

$ source .env

The previous step can be automated by adding the following code to your
`~/.bashrc` (or `~/.zshrc`):

# BEGIN: Auto env

export LAST_ENV=

function auto_env_on_chpwd() {
  if [ -n "$env_type" ]
    if [ ! -r "$env_file" ]
      echo -e "\e[33mFile $env_file does not exist.\e[0m"

  if [ -r "$env_file" ]
    if [ -z "$LAST_ENV" ] && [ -r "$LAST_ENV" ]
      `cat $LAST_ENV | sed -e 's/^export \([0-9a-zA-Z\_]*\)=.*$/unset \1/'`
      echo -e "\e[32mUnloaded ENV VARS defined in \"$LAST_ENV\"\e[0m"
    export LAST_ENV="$env_file"
    source $LAST_ENV
    echo -e "\e[32mLoaded \"$LAST_ENV\"\e[0m"

chpwd_functions=(${chpwd_functions[@]} "auto_env_on_chpwd")

if [ -n "$TMUX" ]; then

alias change_to='function _change_to() {auto_env_on_chpwd $1}; _change_to'

# END: Auto env

The previous code will attempt to `source` any `.env` file every time you
change directory e.g:

/home/alex $ cd my_app
Loaded "/home/alex/my_app/.env"

/home/alex/my_app $ echo "$SOME_SERVICE_PORT"

Additionally, the command `change_to <ENV>` is included. To keep your `prod`,
`dev` and `test` environment variables separated, just create a
`.env.${MIX_ENV}` in the root directory of your project. And when you want to
use the variables set in one of those files, just run the following:

$ change_to dev # Will use `` instead of `.env`

## Installation

The package can be installed by adding `skogsra` to your list of dependencies
in `mix.exs`:

def deps do
  [{:skogsra, "~> 0.2"}]

## Author

Alexander de Sousa.

## License

`Skogsra` is released under the MIT License. See the LICENSE file for further