Optium v0.2.0 Optium
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
returnsOptium.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 returnstrue
if it is valid, orfalse
otherwise. If validator returns a non-boolean,parse/2
will raiseArgumentError
.: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.
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.
Summary
Types
validation_opt :: {:required, boolean} | {:default, term} | {:validator, validator}
Functions
Parses, validates and normalizes options based on passed Optium schema
See documentation for Optium
module for more info.