Knigge.Options (Knigge v1.4.1) View Source

Specifies valid Knigge-options and allows to validate and encapsulate the options in a struct.

Knigge differentiates between required and optional options:

Required

Knigge requires a way to determine the implementation to delegate to. As such it requires one of the following options (but not both):

implementation directly passes the implementation to delegate to
otp_app specifies the application for which the implementation has been configured

If both or neither are given an ArgumentError is being raised.

Optional

These options do not have to be given but control aspects on how Knigge does delegation:

`behaviour`

The behaviour for which Knigge should generate delegations.

Default: the useing __MODULE__.

`config_key`

The configuration key from which Knigge should fetch the implementation.

Is only used when otp_app is passed.

Default: the useing __MODULE__

`default`

A module which Knigge should use when no implementation was configured.

Is only used when otp_app is passed.

Default: nil; Knigge will raise an error when no implementation is configured.

`delegate_at_runtime?`

A switch to move delegation to runtime, by defauly Knigge does as much work as possible at compile time. Accepts:

a boolean (true always delegate at runtime | false always at compile time)
one or many environment names (atom or list of atoms) - only delegate at runtime in the given environments
[only: <envs>] - equivalent to the option above
[except: <envs>] - only delegates at runtime if the current environment is not contained in the list

Default: Application.get_env(:knigge, :delegate_at_runtime?, [only: :test])

`do_not_delegate`

A keyword list defining callbacks for which no delegation should happen.

Default: []

`warn`

Allows to control in which environments Knigge should generate warnings, use with care. Accepts:

a boolean (true always warns | false never warns)
one or many environment names (atom or list of atoms) - only warns in the given environments
[only: <envs>] - equivalent to the option above
[except: <envs>] - only warns if the current environment is not contained in the list

Default: Application.get_env(:knigge, :warn, true)

Link to this section Summary

Types

behaviour()

boolean_or_envs()

config_key()

default()

delegate_at()

do_not_delegate()

envs()

optional()

otp_app()

raw()

required()

t()

Functions

new(opts)

Checks the validity of the given opts (validate!/1), applies defaults and puts them into the Knigge.Options-struct.

validate!(opts)

Validates the options passed to Knigge. It ensures that the required keys are present and that no unknown keys are passed to Knigge which might indicate a spelling error.

with_defaults(opts)

Applies the defaults to the given options

Link to this section Types

behaviour()

Specs

behaviour() :: module()

boolean_or_envs()

Specs

boolean_or_envs() ::
  boolean() | envs() | [{:only, envs()}] | [{:except, envs()}]

config_key()

Specs

config_key() :: atom()

default()

Specs

default() :: nil | module()

delegate_at()

Specs

delegate_at() :: :compile_time | :runtime

do_not_delegate()

Specs

do_not_delegate() :: keyword(arity())

envs()

Specs

envs() :: atom() | [atom()]

optional()

Specs

optional() :: [
  behaviour: behaviour(),
  config_key: config_key(),
  default: default(),
  delegate_at_runtime?: boolean_or_envs(),
  do_not_delegate: do_not_delegate(),
  warn: boolean_or_envs()
]

otp_app()

Specs

otp_app() :: atom()

raw()

Specs

raw() :: [required() | [optional()]]

required()

Specs

required() :: {:implementation, module()} | {:otp_app, otp_app()}

t()

Specs

t() :: %Knigge.Options{
  behaviour: behaviour(),
  default: default(),
  delegate_at_runtime?: boolean(),
  do_not_delegate: do_not_delegate(),
  implementation: module() | {:config, otp_app(), config_key()},
  warn: boolean()
}

Link to this section Functions

new(opts)

Specs

new(options :: raw()) :: t()

Checks the validity of the given opts (validate!/1), applies defaults and puts them into the Knigge.Options-struct.

validate!(opts)

Specs

validate!(opts :: raw()) :: no_return() | opts when opts: raw()

Validates the options passed to Knigge. It ensures that the required keys are present and that no unknown keys are passed to Knigge which might indicate a spelling error.

See the moduledocs for details on required and optional options.

Examples

iex> Knigge.Options.validate!([1, 2, 3])
** (ArgumentError) Knigge expects a keyword list as options, instead received: [1, 2, 3]

iex> Knigge.Options.validate!([])
** (ArgumentError) Knigge expects either the :implementation or the :otp_app option but neither was given.

iex> Knigge.Options.validate!(implementation: SomeModule)
[implementation: SomeModule]

iex> Knigge.Options.validate!(otp_app: :knigge)
[otp_app: :knigge]

iex> Knigge.Options.validate!(implementation: SomeModule, otp_app: :knigge)
** (ArgumentError) Knigge expects either the :implementation or the :otp_app option but both were given.

iex> Knigge.Options.validate!(otp_app: :knigge, the_answer_to_everything: 42, another_weird_option: 1337)
** (ArgumentError) Knigge received unexpected options: [the_answer_to_everything: 42, another_weird_option: 1337]

iex> Knigge.Options.validate!(otp_app: "knigge")
** (ArgumentError) Knigge received invalid value for `otp_app`. Expected atom but received: "knigge"

iex> Knigge.Options.validate!(otp_app: :knigge, delegate_at_runtime?: "test")
** (ArgumentError) Knigge received invalid value for `delegate_at_runtime?`. Expected boolean or environment (atom or list of atoms) but received: "test"

with_defaults(opts)

Specs

with_defaults(raw()) :: raw()

Applies the defaults to the given options:

delegate_at_runtime? = [only: :test]
do_not_delegate = []
warn = true