KeywordValidator v0.1.1 KeywordValidator View Source

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 simply a map that matches the keys for the keyword list. The values in the schema represent the options available during validation.

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

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

Link to this section Summary

Functions

Validates a keyword list using the provided schema.

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

Link to this section Types

Link to this type

invalid() View Source
invalid() :: [{atom(), [String.t()]}]

Link to this type

key_opt() View Source
key_opt() ::
  {:default, any()}
  | {:required, boolean()}
  | {:type, val_type() | [val_type()]}
  | {:format, Regex.t()}
  | {:custom, (atom(), any() -> [] | [binary()])}
  | {:inclusion, list()}
  | {:exclusion, list()}

Link to this type

key_opts() View Source
key_opts() :: [key_opt()]

Link to this type

schema() View Source
schema() :: %{optional(atom()) => key_opts()}

Link to this type

val_type() View Source
val_type() ::
  :any
  | :atom
  | :bistring
  | :boolean
  | :float
  | :function
  | {:function, arity :: non_neg_integer()}
  | :integer
  | :list
  | {:list, val_type()}
  | :map
  | :number
  | :pid
  | :port
  | :struct
  | {:struct, module()}
  | :tuple
  | {:tuple, size :: non_neg_integer()}

Link to this section Functions

Link to this function

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

Validates a keyword list using the provided schema.

A schema is a simple map, with each key representing a key in your keyword list. The values in the map 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 Options

  • :required - boolean representing whether the key is required or not, defaults to false
  • :default - the default value for the key if not provided one, defaults to nil
  • :type - the type associated with the key value. must be one of val_type/0
  • :format - a regex used to validate string format
  • :inclusion - a list of items that the value must be a included in
  • :exclusion - a list of items that the value must not be included in
  • :custom - a list of two-arity functions 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)

Example

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

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

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

iex> KeywordValidator.validate([foo: "foo"], %{foo: [format: ~r/foo/]})
{:ok, [foo: "foo"]}

iex> KeywordValidator.validate([foo: "foo"], %{foo: [custom: [fn key, val -> ["some error"] end]]})
{:error, [foo: ["some error"]]}
Link to this function

validate!(keyword, schema) View Source
validate!(keyword(), schema()) :: any()

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

Example

iex> KeywordValidator.validate!([foo: :foo], %{foo: [type: :atom, required: true]})
[foo: :foo]

iex> KeywordValidator.validate!([foo: :foo], %{foo: [inclusion: [:one, :two]]})
** (ArgumentError) Invalid keyword given.

Keyword:

[foo: :foo]

Invalid:

foo: ["must be one of: [:one, :two]"]