skogsra v0.1.1 Skogsra View Source

This library attempts to improve the use of OS environment variables and application configuration. You would create a settings module e.g:

defmodule Settings do
  use Skogsra

  # Rather equivalent to `System.get_env("POSTGRES_PORT") || 5432` (misses
  # the automatic casting to integer). Generates the function
  # `Settings.postgres_port/0`.
  @spec portgres_port() :: integer()
  system_env :postgres_port,
    default: 5432

  # Equivalent to
  # ```
  # System.get_env("POSTGRES_HOSTNAME") ||
  # (Application.get_env(:my_app, MyApp.Repo, []) |>
  #  Keyword.get(:hostname, "localhost"))
  # ```
  # Generates the function Settings.postgres_hostname/0
  @spec postgres_hostname() :: binary()
  app_env :postgres_hostname, :my_app, :hostname,
    domain: MyApp.Repo
    default: "localhost"
end

It can be used in the configuration file as well e.g:

config :my_app, MyApp.Repo,
  adapter: Ecto.Adapters.Postgres,
  hostname: Skogsra.get_env("POSTGRES_HOSTNAME", "localhost"),
  port: Skogsra.get_env_as(:integer, "POSTGRES_PORT", "5432"),
  (...)

Or from a module:

defmodule MyApp do
  @port Skogsra.get_app_env "POSTGRES_PORT", :my_app, :port,
    domain: MyApp.Repo,
    default: 5432

  @spec get_port() :: integer()
  def get_port, do: @port
end

Link to this section Summary

Functions

For now is just equivalent to use import Skogsra

Macro that receives the name of the OS environment variable, the name of the app, the name of the option key and some optional Keyword list with options and generates a function with arity 0 with the same name of the OS environment variable, but in lower case e.g. "FOO" would generate the function foo/0

Gets the OS environment variable by its name. If it’s not found, attempts to get the application configuration option by the app name and the option key. Optionally receives a Keyword list of options

Gets the OS environment variable by its name and cast it the the type of the default value. If no default value is provided, returns a string. If the OS environment variable is not found, returns the default value

Gets the OS environment variable by its name and casts it to the provided type. If the OS environment variable is not found, returns the default value

Macro that receives the name of the OS environment variable and some optional Keyword list with options and generates a function with arity 0 with the same name of the OS environment variable, but in lower case e.g. "FOO" would generate the function foo/0

Link to this section Functions

For now is just equivalent to use import Skogsra.

Link to this macro app_env(name, app, key, opts \\ []) View Source (macro)

Macro that receives the name of the OS environment variable, the name of the app, the name of the option key and some optional Keyword list with options and generates a function with arity 0 with the same name of the OS environment variable, but in lower case e.g. "FOO" would generate the function foo/0.

The available options are:

  • :static - Whether the computation of the OS environment variable or application configuration option is done on compiling time or not. By default its value is false.
  • :default - Default value in case the OS environment variable and the application configuration option don’t exist. By default is nil.
  • :type - The type of the OS environment variable. By default is the type of the default value. If there is no default value, the default type is binary. The available types are :binary, :integer, :float, :boolean and :atom.
  • :domain - The key to search in the configuration file e.g in:

    config :my_app, MyApp.Repo,
      adapter: Ecto.Adapters.Postgres,
      (...)

    the domain would be MyApp.Repo. By default, there is no domain.

e.g

defmodule Settings do
  use Skogsra

  app_env :foo, :my_app, :foo,
    default: 42,
    type: :integer,
    domain: MyApp.Domain
end

This would generate the function Settings.foo/0 that would search for the OS environment variable "FOO" and cast it to integer on runtime. If the OS environment variable is not found, attempts to search for the :foo configuration option for the application :my_app and the domain MyApp.Domain. If nothing is found either, it defaults to 42.

Calling Settings.foo/0 without a domain set is equivalent to:

with value when not is_nil(value) <- System.get_env("FOO"),
     {number, _} <- Integer.parse(value) do
  number
else
  _ ->
    Application.get_env(:my_app, :foo, 42)
end

Calling Settings.foo/0 With a domain set is equivalent to:

with value when not is_nil(value) <- System.get_env("FOO"),
     {number, _} <- Integer.parse(value) do
  number
else
  _ ->
    opts = Application.get_env(:my_app, MyApp.Domain, [])
    Keyword.get(opts, :foo, 42)
end
Link to this function get_app_env(name, app, key, options \\ []) View Source
get_app_env(binary, atom, atom, list) :: term

Gets the OS environment variable by its name. If it’s not found, attempts to get the application configuration option by the app name and the option key. Optionally receives a Keyword list of options

i.e:

  • :default - Default value in case the OS environment variable and the application configuration option don’t exist. By default is nil.
  • :type - The type of the OS environment variable. By default is the type of the default value. If there is no default value, the default type is binary. The available types are :binary, :integer, :float, :boolean and :atom.
  • :domain - The key to search in the configuration file e.g in:

    config :my_app, MyApp.Repo,
      adapter: Ecto.Adapters.Postgres,
      hostname: "localhost",
      (...)

    the domain would be MyApp.Repo. By default, there is no domain.

e.g:

defmodule MyApp do
  def get_hostname do
    get_app_env("POSTGRES_HOSTNAME", :my_app, :hostname, domain: MyApp.Repo)
  end
end
Link to this function get_env(name, default \\ nil) View Source
get_env(binary, term) :: term

Gets the OS environment variable by its name and cast it the the type of the default value. If no default value is provided, returns a string. If the OS environment variable is not found, returns the default value.

config :my_app, MyApp.Repo,
  adapter: Ecto.Adapters.Postgres,
  hostname: Skogsra.get_env("POSTGRES_HOSTNAME", "localhost"),
  (...)
Link to this function get_env_as(type, name, default \\ nil) View Source
get_env_as(atom, binary, term) :: term

Gets the OS environment variable by its name and casts it to the provided type. If the OS environment variable is not found, returns the default value.

config :my_app, MyApp.Repo,
  adapter: Ecto.Adapters.Postgres,
  hostname: Skogsra.get_env("POSTGRES_HOSTNAME", "localhost"),
  port: Skogsra.get_env_as(:integer, "POSTGRES_PORT", 5432),
  (...)
Link to this macro system_env(name, opts \\ []) View Source (macro)

Macro that receives the name of the OS environment variable and some optional Keyword list with options and generates a function with arity 0 with the same name of the OS environment variable, but in lower case e.g. "FOO" would generate the function foo/0.

The available options are:

  • :static - Whether the computation of the OS environment variable is done on compiling time or not. By default its value is false.
  • :default - Default value in case the OS environment variable doesn’t exist. By default is nil.
  • :type - The type of the OS environment variable. By default is the type of the default value. If there is no default value, the default type is binary. The available types are :binary, :integer, :float, :boolean and :atom.

e.g

defmodule Settings do
  use Skogsra

  system_env :foo,
    default: 42,
    type: :integer
end

This would generate the function Settings.foo/0 that would search for the OS environment variable "FOO" and cast it to integer on runtime and defaults to 42.