Optium v0.3.0 Optium View Source

Functions for validating arguments passed in keyword lists

To validate options with Optium, you need to provide it a option schema. Schema is a map or a keyword list describing how each option should be validated.

Examples

%{port: [required: true, validator: &is_integer/1],
  address: [required: true, default: {0, 0, 0, 0}]}

Based on the schema above, Optium knows that :port option is required, and it will return an Optium.OptionMissingError if it is not provided. It will also check if provided :port is an integer, and return Optium.OptionInvalidError if it is not. :address is also required, but by defining a default value you make sure that no errors will be returned and that default value will be appended to parsed options list instead. Use Optium.parse/2 to parse and validate options:

iex> schema = %{port:    [required: true, validator: &is_integer/1],
...>            address: [required: true, default: {0, 0, 0, 0}]}
iex> [port: 12_345, address: {127, 0, 0, 1}] |> Optium.parse(schema)
{:ok, [port: 12_345, address: {127, 0, 0, 1}]}
iex> [port: 12_345] |> Optium.parse(schema)
{:ok, [address: {0, 0, 0, 0}, port: 12_345]}
iex> [address: {127, 0, 0, 1}] |> Optium.parse(schema)
{:error, %Optium.OptionMissingError{keys: [:port]}}
iex> [port: "12_345"] |> Optium.parse(schema)
{:error, %Optium.OptionInvalidError{keys: [:port]}}

There is also Optium.parse!/2, which follows Elixir’s convention of “bang functions” and raises and error instead of returning it.

iex> schema = %{port:    [required: true, validator: &is_integer/1],
...>            address: [required: true, default: {0, 0, 0, 0}]}
iex> [address: {127, 0, 0, 1}] |> Optium.parse!(schema)
** (Optium.OptionMissingError) option :port is required

Schema

Schemas are keyword lists or maps with atoms as keys, and validation options lists as values.

Supported validation options:

  • :required - parse/2 returns Optium.OptionMissingError if options is not present in the provided options list.
  • :default - this value will be put into provided options list if the corresponding key is missing. Overrides :required.
  • :validator - a function which takes an option’s value, and returns true if it is valid, or false otherwise. If validator returns a non-boolean, parse/2 will raise ArgumentError. :default values will be validated too.

Note that returned, validated options list contains only those options which keys are present in the schema. You can add an option to schema with empty validation options list (like %{key: []}), but it doesn’t make much sense because you most likely want to have some default value anyway.

Schema compilation

When schema is not constructed dynamically (which I believe is the most common scenario), you can compile it into a parser to avoid unnecessary processing in every call to parse/2:

@schema %{key: [default: 1]}
@parser Optium.compile(@schema)

def my_fun(opts) do
  opts
  |> Optium.parse!(@parser)
  |> do_stuff()
end

Error handling

As mentioned before, parse/2 returns {:error, error} tuple, where error is a relevant exception struct. All Optium exceptions implement Exception.message/1 callback, so you can use Exception.message(error) to provide nice error message to users of your functions. parse!/2 intercepts exception structs and raises them instead of returning.

Link to this section Summary

Functions

Compiles the schema into a parser

Parses, validates and normalizes options using provided parser or schema

Same as parse/2, but raises an exception instead of returning it

Link to this section Types

Link to this section Functions

Compiles the schema into a parser

Link to this function parse(opts, parser) View Source
parse(opts, parser | schema) ::
  {:ok, opts} |
  {:error, error}

Parses, validates and normalizes options using provided parser or schema

See documentation for Optium module for more info.

Link to this function parse!(opts, schema) View Source
parse!(opts, schema) :: opts | no_return

Same as parse/2, but raises an exception instead of returning it