# `Skogsra`
[🔗](https://github.com/gmtprime/skogsra/blob/v2.5.2/lib/skogsra.ex#L1)

This module defines the macros needed to use `Skogsra` e.g:

```elixir
defmodule MyApp.Settings do
  use Skogsra

  @envdoc "My hostname"
  app_env :my_hostname, :myapp, :hostname,
    default: "localhost"
end
```

# `__using__`
*macro* 

Imports `app_env/3` and `app_env/4`. Additionally generates the function
`template(`
For now is just equivalent to use `import Skogsra`.

# `app_env`
*macro* 

```elixir
@spec app_env(atom(), atom(), atom() | binary() | [any()], keyword()) :: Macro.t()
```

Creates a function to retrieve specific environment/application variables
values.

The function created is named `function_name` and will get the value
associated with an application called `app_name` and one or several
`parameters` keys. Optionally, receives a list of `options`.

Available options:

Option          | Type                    | Default              | Description
:-------------- | :---------------------- | :------------------- | :----------
`default`       | `any`                   | `nil`                | Sets the Default value for the variable.
`type`          | `Skogsra.Env.type()`    | `:binary`            | Sets the explicit type for the variable.
`os_env`        | `binary`                | autogenerated        | Overrides automatically generated OS environment variable name.
`binding_order` | `Skogra.Env.bindings()` | `[:system, :config]` | Sets the load order for variable binding.
`binding_skip`  | `Skogra.Env.bindings()` | `[]`                 | Which variable bindings should be skipped.
`required`      | `boolean`               | `false`              | Whether the variable is required or not.
`cached`        | `boolean`               | `true`               | Whether the variable should be cached or not.
`namespace`     | `module`                | `nil`                | Overrides any namespace.
`env_overrides` | `keyword`               | `[]`                 | Overrides `default` and `required` properties for a specific environment.

e.g:

For the following declaration:

```
app_env :db_password, :myapp, [:mydb, :password],
  default: "password",
```

will generate:

- `db_password/0` and `db_password/1` for getting the variable's value
without or with namespace respectively. It returns `:ok` and `:error`
tuples.
- `db_password!/0` and `db_password!/1` for getting the variable's value
without or with namespace respectively. It fails on error.
- `reload_db_password/0` and `reload_db_password/1` for reloading the
variable's value in the cache without or with namespace respectively.
- `put_db_password/1` and `put_db_password/2` for settings a new value for
the variable directly to the cache without or with namespace respectively.

A call to `db_password/0` will try to get a value:

1. From the OS environment variable `$MYAPP_MYDB_PASSWORD` (can be overriden
   by the option `os_env`).
2. From the configuration file e.g:
   ```
   config :myapp,
     mydb: [password: "some password"]
   ```
3. From the default value if it exists (In this case, it would return
   `"password"`).

A call to `db_password/1` with namespace `Test` will try to get a value:

1. From the OS environment variable `$TEST_MYAPP_MYDB_PASSWORD`.
2. From the configuration file e.g:
   ```
   config :myapp, Test,
     mydb: [password: "some test password"]
   ```
3. From the OS environment variable `$MYAPP_MYDB_PASSWORDT`.
4. From the configuraton file e.g:
   ```
   config :myapp,
     mydb: [password: "some password"]
   ```
5. From the default value if it exists. In our example, `"password"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*