KeywordValidator v2.0.1

View Source KeywordValidator (KeywordValidator v2.0.1)

Functions for validating keyword lists.

The main function in this module is validate/2, which allows developers to validate a keyword list against a given schema.

A schema is a keyword list that matches the keys for the keyword list. The values in the schema represent the options available during validation.

iex> KeywordValidator.validate([foo: :bar], [foo: [is: :atom]])
{:ok, [foo: :bar]}

iex> KeywordValidator.validate([foo: :bar], [foo: [is: :integer]])
{:error, [foo: ["must be an integer"]]}

Link to this section Summary

Types

base_schema()

A keyword base schema.

custom_validator()

Custom validation logic for key values.

invalid()

An invalid keyword key.

option()

Individual validation options.

options()

All validation options.

schema()

A keyword schema.

value_is()

Various value :is options.

value_opt()

Individual value options.

value_opts()

All value options.

Functions

docs(schema)

Builds documentation for a given schema.

schema!(schema)

Prepares a schema or raises an ArgumentError exception if invalid.

validate!(keyword, schema, opts \\ [])

The same as validate/2 but raises an ArgumentError exception if invalid.

validate(keyword, schema, opts \\ [])

Validates a keyword list using the provided schema.

Link to this section Types

Link to this type

base_schema()

View Source 
@type base_schema() :: keyword(value_opts())

A keyword base schema.

Link to this type

custom_validator()

View Source 
@type custom_validator() ::
  (key :: atom(), value :: any() -> [] | [error :: binary()])
  | {module(), function :: atom()}

Custom validation logic for key values.

Link to this type

invalid()

View Source 
@type invalid() :: keyword([String.t()])

An invalid keyword key.

Link to this type

option()

View Source 
@type option() :: {:strict, boolean()}

Individual validation options.

Link to this type

options()

View Source 
@type options() :: [option()]

All validation options.

Link to this type

schema()

View Source 
@type schema() :: base_schema() | struct()

A keyword schema.

Link to this type

value_is()

View Source 
@type value_is() ::
  {:=, any()}
  | :any
  | :atom
  | :binary
  | :bitstring
  | :boolean
  | :float
  | :fun
  | {:fun, arity :: non_neg_integer()}
  | {:in, [any()]}
  | :integer
  | :keyword
  | {:keyword, schema()}
  | :list
  | {:list, value_is()}
  | :map
  | :mfa
  | :mod
  | :mod_args
  | :mod_fun
  | :number
  | {:one_of, [value_is()]}
  | :pid
  | :port
  | :struct
  | {:struct, module()}
  | :timeout
  | :tuple
  | {:tuple, size :: non_neg_integer()}
  | {:tuple, tuple_value_types :: tuple()}

Various value :is options.

Link to this type

value_opt()

View Source 
@type value_opt() ::
  {:is, value_is()}
  | {:default, any()}
  | {:required, boolean()}
  | {:custom, [custom_validator()]}
  | {:doc, false | binary()}

Individual value options.

Link to this type

value_opts()

View Source 
@type value_opts() :: [value_opt()]

All value options.

Link to this section Functions

Link to this function

docs(schema)

View Source 
@spec docs(schema()) :: binary()

Builds documentation for a given schema.

This can be used to inject documentation in your docstrings. For example:

@options_schema KeywordValidator.schema!([key: [type: :any, doc: "Some option."]])

@doc "Options:\n#{KeywordValidator.docs(@options_schema)}"

This will automatically generate documentation that includes information on required keys and default values.

Link to this function

schema!(schema)

View Source 
@spec schema!(base_schema()) :: struct()

Prepares a schema or raises an ArgumentError exception if invalid.

A schema is a keyword list of keys and value options.

This is the preferred method of providing a validation schema as it ensures your schema is valid and avoids running additional validation on each invocation. You can then declare your schema as a module attribute:

@opts_schema KeywordValidator.schema!([...])

KeywordValidator.validate!(keyword, @opts_schema)

value-options

 Value Options

  • :is - The value type associated with the key. Must be one of KeywordValidator.value_is/0. Defaults to :any.
  • :default - The default value for the key if not provided one.
  • :required - Boolean representing whether the key is required or not. Defaults to false.
  • :custom - A list of two-arity functions or tuples in the format {module, function} that serve as custom validators. The function will be given the key and value as arguments, and must return a list of string errors (or an empty list if no errors are present). Defaults to [].
  • :doc - Documentation for the option. Defaults to false.

is-options

 Is Options

The following value types are available for use with the :is option:

  • {:=, value} - Equal to value.
  • :any - Any value.
  • :atom - An atom.
  • :binary - A binary.
  • :bitstring - A bitstring.
  • :boolean - A boolean.
  • :float - A float.
  • :fun - A function.
  • {:fun, arity} - A function with specified arity.
  • {:in, [value]} - In the list of values.
  • :integer - An integer.
  • :keyword - A keyword list.
  • {:keyword, schema} - A keyword with the provided schema.
  • :list - A list.
  • :map - A map.
  • :mfa - A module, function and args.
  • :mod_args - A module and args.
  • :mod_fun - A module and function.
  • :mod - A module.
  • :number - A number.
  • {:one_of, [type]} - Any one of the provided types.
  • :pid - A PID.
  • :port - A port.
  • :struct - A struct.
  • {:struct, type} - A struct of the provided type.
  • :timeout - A timeout (integer or :infinite).
  • :tuple - A tuple.
  • {:tuple, size} - A tuple of the provided size.
  • {:tuple, tuple} - A tuple with the provided tuple types.
Link to this function

validate!(keyword, schema, opts \\ [])

View Source 
@spec validate!(keyword(), schema(), options()) :: Keyword.t()

The same as validate/2 but raises an ArgumentError exception if invalid.

example

 Example 

iex> KeywordValidator.validate!([foo: :bar], [foo: [is: :atom, required: true]])
[foo: :foo]

iex> KeywordValidator.validate!([foo: "bar"], [foo: [is: :atom, required: true]])
** (ArgumentError) Invalid keyword given.

Keyword:

[foo: "bar"]

Invalid:

foo: ["must be an atom"]
Link to this function

validate(keyword, schema, opts \\ [])

View Source 
@spec validate(keyword(), schema(), options()) ::
  {:ok, keyword()} | {:error, invalid()}

Validates a keyword list using the provided schema.

A schema is a keyword list (or prepared schema via schema!/1) - with each key representing a key in your keyword list. The values in the schema keyword list represent the options available for validation.

If the validation passes, we are returned a two-item tuple of {:ok, keyword}. Otherwise, returns {:error, invalid} - where invalid is a keyword list of errors.

schema

 Schema

Please see schema!/1 for options available when building schemas.

options

 Options

  • :strict - Boolean representing whether extra keys will become errors. Defaults to true.

examples

 Examples 

iex> KeywordValidator.validate([foo: :foo], [foo: [is: :atom, required: true]])
{:ok, [foo: :foo]}

iex> KeywordValidator.validate([foo: :foo], [bar: [is: :any]])
{:error, [foo: ["is not a valid key"]]}

iex> KeywordValidator.validate([foo: :foo], [bar: [is: :any]], strict: false)
{:ok, []}

iex> KeywordValidator.validate([foo: :foo], [foo: [is: {:in, [:one, :two]}]])
{:error, [foo: ["must be one of: [:one, :two]"]]}

iex> KeywordValidator.validate([foo: {:foo, 1}], [foo: [is: {:tuple, {:atom, :integer}}]])
{:ok, [foo: {:foo, 1}]}

iex> KeywordValidator.validate([foo: ["one", 2]], [foo: [is: {:list, :binary}]])
{:error, [foo: ["must be a list of type :binary"]]}

iex> KeywordValidator.validate([foo: %Foo{}], [foo: [is: {:struct, Bar}]])
{:error, [foo: ["must be a struct of type Bar"]]}

iex> KeywordValidator.validate([foo: "foo"], [foo: [is: :any, custom: [fn key, val -> ["some error"] end]]])
{:error, [foo: ["some error"]]}