=======================================
:mod:`formular.validators` - Validators
=======================================
This module provides the built-in validators used by the fields and a helper
to create your own validator factory ( :func:`as_validator` ).

The validators used by Formular are simple functions, which take the form, an
initial value and the value which should be validated. If the validation is
successful the function returns ``True`` otherwise ``False``.

Error messages are handled by the field itself and are not created by the
validator, as they may differ in the context of the field.

If you want to use your own validators on an exisitng field type
checkout the :meth:`formular.fields.Field.register_as_validator`
documentation.

.. currentmodule:: formular.validators

.. _builtin-validators:

Built-in Validators
-------------------

.. function:: required(is_required)

   Validates if the value is ``True``, if `is_required` is ``True``, otherwise
   it validates always.

.. function:: requires(field_name)

   Validates if the value of the field with the given `field_name` exists, if
   the value of the validated field exists.

.. function:: equals(field_name)

   Validates if the value of the field with the given `field_name` is equal
   to the value of the validated field.

.. function:: min_length(min_length)

   Validates if the length of the value is greater then the given `min_length`.

.. function:: max_length(max_length)

   Validates if the length of the value is lesser then the given `max_length`.

.. function:: min_value(min_value)
   
   Validates if the value is greater then the given `max_value`.

.. function:: max_value(max_value)

   Validates if the value is lesser then the given `max_value`.

.. function:: is_email(email_required)

   Validates if the value is a valid e-mail address.

   .. warning:: This function does not implement rfc2822 completely.

   .. versionadded:: 0.2

Creating Your Own Validator Factory
-----------------------------------
If you want to create your own field type, you will have to create a validator
factory. Such a factory takes the initial value and returns a callable which
takes the form and the value which should be validated. This way the field does
not have to store the initial values.

The easiest way to create a validator factory, which can be put into
:class:`formular.fields.Field.validator_factories`, is to use
:func:`as_validator`.

.. autofunction:: as_validator