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
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.
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
Link to this section Types
schema :: %{optional(key) => validation_opts} | [{key, validation_opts}]
validation_opt :: {:required, boolean} | {:default, term} | {:validator, validator}
Link to this section Functions
Compiles the schema into a parser
Parses, validates and normalizes options using provided parser or schema
See documentation for Optium
module for more info.
Same as parse/2
, but raises an exception instead of returning it