Crutches.Option (imagine_cms v6.3.7)

Convenience functions for dealing with function option handling.

This provides a mechanism for declaring default options and merging these with those given by any caller.

Usage

When you have a function with the following head, the use of this module may be beneficial. Of course you can have as much required args as you want. options is a keyword list.

def foo(args, options)

Usage is pretty simple. Declare a module attribute with the name of your function. It should be a keyword list with the keys :valid and :defaults. :valid should contain a list of atoms. :defaults should contain another keyword list with the default options of your function.

Example

@function_name [
  valid: ~w(foo bar)a
  defaults: [
    foo: "some",
    bar: "value"
  ]
]

When this is done, you can declare your function head like this:

def function_name(args, opts \ []])

And then you're all set to actually write the meat of your function. (You of course don't need a function head if your function only consists of one clause.)

def function_name(args, opts) do
  # This validates and merges the options, throwing on error.
  opts = Crutches.Options.combine!(opts, @function_name)

  # You can now use the options.
  do_something_with(opts[:foo])
end

Link to this section Summary

Types

error()

key()

ok(value)

t()

t(value)

value()

Functions

all_valid?(opts, valid)

Check opts for keys not in valid.

combine(opts, config)

Validates the opts keyword list according to config, combines defaults.

combine(opts, config, combinator)

Validate opts according to config, combines according to combinator

combine!(opts, config)

This function is the same as combine/2, except it returns options on validation succes and throws ArgumentError on validation failure.

combine!(opts, config, combinator)

Throwing version of combine/3

validate(opts, valid)

Checks a opts for keys not in valid.

validate!(opts, valid)

Throwing version of Option.validate

Link to this section Types

error()

Specs

error() :: {:error, any()}

key()

Specs

key() :: atom()

ok(value)

Specs

ok(value) :: {:ok, value}

t()

Specs

t() :: [{key(), value()}]

t(value)

Specs

t(value) :: [{key(), value}]

value()

Specs

value() :: any()

Link to this section Functions

all_valid?(opts, valid)

Specs

all_valid?(t(), [atom()]) :: boolean()

Check opts for keys not in valid.

Return false when a bad key is found, otherwise return true.

Examples

iex> Option.all_valid?([good: "", good_opt: ".", bad: "!"], [:good, :good_opt])
false

iex> Option.all_valid?([good: "", good_opt: "."], [:good, :good_opt])
true

combine(opts, config)

Specs

combine(t(), t([atom()]) | t(t())) :: ok(t()) | error()

Validates the opts keyword list according to config, combines defaults.

For intended use see the module documentation.

Config variable

The config parameter should be a keyword list with the following keys:

:valid ([atom]) --- Parameters that your function accepts.
:defaults ([atom: any]) --- Default values for the options in :valid.

Returns {:ok, opts} on succes, {:error, invalid_keys} on failure.

Examples

iex> config = [valid: ~w(foo bar)a, defaults: [foo: "some", bar: "value"]]
iex> Option.combine([foo: "another"], config)
{:ok, [bar: "value", foo: "another"]}

iex> config = [valid: ~w(bar baz)a, defaults: [bar: "good", baz: "values"]]
iex> Option.combine([boom: "this blows up"], config)
{:error, [:boom]}

combine(opts, config, combinator)

Specs

combine(t(), t() | t(t()), (t(), t() -> t())) :: ok(t()) | error()

Validate opts according to config, combines according to combinator

Behavior is the same as combine/2, except that you can specify how opts and config[:defaults] are merged by passing a combinator function.

This function should combine the two keyword lists into one. It receives config[:defaults] as the first parameter and the validated opts as the second.

Examples

Contrived example showing of the use of combinator.

iex> config = [valid: ~w(foo bar)a, defaults: [foo: "some", bar: "value"]]
iex> combinator = &Keyword.merge/2
iex> Option.combine([foo: "again"], config, combinator)
{:ok, [bar: "value", foo: "again"]}

combine!(opts, config)

Specs

combine!(t(), t([atom()]) | t(t())) :: t()

This function is the same as combine/2, except it returns options on validation succes and throws ArgumentError on validation failure.

Examples

iex> config = [valid: ~w(foo bar)a, defaults: [foo: "some", bar: "value"]]
iex> Option.combine!([foo: "another"], config)
[bar: "value", foo: "another"]

iex> config = [valid: ~w(bar baz)a, defaults: [bar: "good", baz: "values"]]
iex> Option.combine!([boom: "this blows up"], config)
** (ArgumentError) invalid key boom

combine!(opts, config, combinator)

Specs

combine!(t(), t() | t(t()), (t(), t() -> t())) :: t()

Throwing version of combine/3

Examples

iex> config = [valid: ~w(foo bar)a, defaults: [foo: "some", bar: "value"]]
iex> combinator = fn(_, _) -> nil end
iex> Option.combine!([baz: "fail"], config, combinator)
** (ArgumentError) invalid key baz

validate(opts, valid)

Specs

validate(t(), [atom()]) :: ok([]) | error()

Checks a opts for keys not in valid.

Returns {:ok, []} if all options are kosher, otherwise {:error, list}, where list is a list of all invalid keys.

Examples

iex> Option.validate([good: "", good_opt: ""], [:good, :good_opt])
{:ok, []}

iex> Option.validate([good: "", bad: ""], [:good])
{:error, [:bad]}

validate!(opts, valid)

Specs

validate!(t(), [atom()]) :: true

Throwing version of Option.validate

Examples

iex> Option.validate!([good: "", bad: ""], [:good])
** (ArgumentError) invalid key bad

iex> Option.validate!([good: "", bad: "", worse: ""], [:good])
** (ArgumentError) invalid key bad, worse

iex> Option.validate!([good: ""], [:good])
true