-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Library for checking and normalization of data (e.g. from web forms)
--   
--   Library for checking and normalization of data (e.g. from web forms).
@package data-check
@version 0.1.0


-- | This module provides generalized approach to checking and verification
--   of data, it's useful, for example, for validation of fields on web
--   forms.
--   
--   Typically, there are a number of transformations and checks you may
--   want to perform on a particular type of data, such as text. Thus, it
--   makes sense to create all those transformations and checks once and
--   then combine them to get more complex validators that may vary on
--   per-field basis.
--   
--   Certainly, if we can normalize and validate, we should normalize
--   first. However, if we have many normalizing operations, we need a way
--   to specify in which order they should be performed, or result can be
--   unpredictable.
--   
--   To specify order in which transformations are performed,
--   <a>normalizer</a> and <a>normalizerM</a> functions take a “priority”
--   argument, which is just a <a>Natural</a> number. The bigger the
--   number, the later the function will be applied, so the transformation
--   with priority 0 will always run first.
--   
--   This method applies to validators just as well. It's possible to
--   create a vocabulary of validators that can be mixed together and the
--   result will be always deterministic.
--   
--   To support more real-world use cases, every check can be performed
--   inside of a monad, allowing to query a database for example.
--   
--   One last thing to note is that every normalizer and every validator
--   should have a unique priority number. Normalizers (and validators)
--   with the same priority will overwrite each other. This is by design.
--   Note that normalizer won't override validator with the same priority
--   though, their priority-spaces are separate.
module Data.Check

-- | Create a normalizing <a>Checker</a>. Every normalizer has a priority —
--   the bigger the number, the later the normalizer runs. Every normalizer
--   you use should have a unique priority number.
normalizer :: Monad m => Natural -> (a -> a) -> Checker m e a

-- | The same as <a>normalizer</a>, but allows to perform normalization
--   inside of a monad.
normalizerM :: Monad m => Natural -> (a -> m a) -> Checker m e a

-- | Create a validating <a>Checker</a>. Every validator has a priority —
--   the bigger the number, the later the validation step runs. Every
--   validator you use should have a unique priority number.
validator :: Monad m => Natural -> (a -> Maybe e) -> Checker m e a

-- | The same as <a>validator</a>, but allows to perform normalization
--   inside of a monad.
validatorM :: Monad m => Natural -> (a -> m (Maybe e)) -> Checker m e a

-- | <tt><a>Checker</a> m e a</tt> is a checker that checks value of type
--   <tt>a</tt>, can perform the check in <tt>m</tt> monad, returning
--   <tt>e</tt> message when check fails.
--   
--   <a>Checker</a> is a <a>Semigroup</a> and <a>Monoid</a> — this is how
--   you combine different checkers and build more complex ones.
data Checker m e a

-- | Run a <a>Checker</a> on given value. This is version for cases when
--   all transformations and validations are pure.
runChecker :: Checker Identity e a -> a -> Either e a

-- | Version of <a>runChecker</a> that can run transformations and checks
--   in any monad.
runCheckerM :: Monad m => Checker m e a -> a -> m (Either e a)
instance GHC.Classes.Eq (Data.Check.Normalizer m a)
instance GHC.Classes.Ord (Data.Check.Normalizer m a)
instance GHC.Classes.Eq (Data.Check.Validator m e a)
instance GHC.Classes.Ord (Data.Check.Validator m e a)
instance Data.Semigroup.Semigroup (Data.Check.Checker m e a)
instance GHC.Base.Monad m => GHC.Base.Monoid (Data.Check.Checker m e a)