Knigge v1.0.0 Knigge.Options 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, defaults to the useing __MODULE__
  • config_key the configuration key from which Knigge should fetch the implementation, defaults to the useing __MODULE__ and is only used when otp_app is passed
  • delegate_at an atom defining when delegation should happen, either :compile_time or :runtime, defaults to :compile_time
  • do_not_delegate a keyword list defining callbacks for which no delegation should happen
  • warn if set to false this disables all warnings generated by Knigge, use with care

Link to this section Summary

Functions

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

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.

Applies the defaults to the given options

Link to this section Types

Link to this type

behaviour()

View Source
behaviour() :: module()
Link to this type

config_key()

View Source
config_key() :: atom()
Link to this type

delegate_at()

View Source
delegate_at() :: :compile_time | :runtime
Link to this type

do_not_delegate()

View Source
do_not_delegate() :: keyword(arity())
Link to this type

implementation()

View Source
implementation() :: module()
Link to this type

optional()

View Source
optional() :: [
  behaviour: behaviour(),
  config_key: config_key(),
  delegate_at: delegate_at(),
  do_not_delegate: do_not_delegate(),
  warn: warn()
]
Link to this type

otp_app()

View Source
otp_app() :: atom()
Link to this type

required()

View Source
required() :: {:implementation, implementation()} | {:otp_app, otp_app()}
Link to this type

t()

View Source
t() :: %Knigge.Options{
  behaviour: behaviour(),
  check_if_exists?: term(),
  config_key: term(),
  delegate_at: delegate_at(),
  do_not_delegate: do_not_delegate(),
  implementation: implementation() | {:config, otp_app(), config_key()},
  warn: warn()
}

Link to this section Functions

Link to this function

new(opts)

View Source
new(options :: raw()) :: t()

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

Link to this function

validate!(opts)

View Source
validate!(raw()) :: no_return()

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: :compailtime)
** (ArgumentError) Knigge received invalid value for `delegate_at`. Expected :compile_time or :runtime but received: :compailtime
Link to this function

with_defaults(opts)

View Source
with_defaults(raw()) :: raw()

Applies the defaults to the given options:

  • check_if_exists? = true
  • delegate_at = :compile_time
  • do_not_delegate = []
  • warn = true