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


-- | A library for writing predicates and transformations over predicates in Haskell
--   
--   This package provides ways to write predicates such that they compose
--   nicely and are easy to debug.
@package predicate-transformers
@version 0.16.0.0


-- | This library is based on the notion of a predicate transformer, the
--   below type <tt>PT a b</tt>, which is a function from <tt>a</tt> to
--   predicates on <tt>b</tt>. They act as a sort of compositional "matcher
--   language". Composing these predicate transformers is meant to be
--   analogous to composing optics and there are utilities for using
--   predicate transformers with (<a>lens</a>-style) optics.
--   
--   Some predicate transformers provided by other libraries: <a>all</a>,
--   <a>any</a> (base) <a>either</a> (base) <a>allOf</a> (lens)
module PredicateTransformers

-- | Class of possible predicate results. This is mostly a lattice with
--   <a>otherHand</a> as disjunction, <a>also</a> as conjunction,
--   <a>stop</a> as the falsy value, and <a>continue</a> as the truthy
--   value. There may be multiple falsy values, however.
class Predicatory a
otherHand :: Predicatory a => a -> a -> a
also :: Predicatory a => a -> a -> a
stop :: (Predicatory a, HasCallStack) => v -> Doc ann -> a
continue :: Predicatory a => a
infixr 2 `otherHand`
infixr 3 `also`

-- | Class of predicate results which can be checked for failure, by
--   triggering an action.
class Exceptional a
assess :: Exceptional a => a -> IO () -> a

-- | The exception thrown by predicates of type `IO ()` by default. Other
--   IOExceptions will work fine.
data PredicateFailed
PredicateFailed :: !CallStack -> Doc ann -> actual -> PredicateFailed

-- | A convenient alias for predicates.
type Pred p a = a -> p

-- | Predicate transformers form a category where composition is ordinary
--   function composition. Forms a category with <a>.</a> and <a>id</a>.
--   Multiple are already provided by the standard library, for instance
--   <a>all</a> and <a>any</a>.
type PT p a b = Pred p a -> Pred p b

-- | Operate on the <a>Just</a> branch of a <a>Maybe</a>, or fail.
predJust :: Predicatory p => PT p a (Maybe a)

-- | Operate on the <a>Left</a> branch of an <a>Either</a>, or fail.
predLeft :: Predicatory p => PT p e (Either e a)

-- | Operate on the <a>Right</a> branch of an <a>Either</a>, or fail.
predRight :: Predicatory p => PT p a (Either e a)

-- | Operate on the last value in a foldable, or fail if it's not present.
endingWith :: (HasCallStack, Predicatory p, Foldable f) => PT p a (f a)

-- | Operate on the first value in a foldable, or fail if it's not present.
startingWith :: (HasCallStack, Predicatory p, Foldable f) => PT p a (f a)

-- | Require that a <tt>Fold</tt> has a single element, and operate on that
--   element.
soleElementOf :: (HasCallStack, Predicatory p) => Fold s a -> PT p a s

-- | Require that a <tt>Foldable</tt> has a single element, and operate on
--   that element.
soleElement :: (Predicatory p, Foldable f) => PT p a (f a)

-- | Require that a <tt>Prism</tt> matches, and apply the predicate to its
--   contents.
match :: Predicatory p => Prism' s a -> PT p a s

-- | Only test the <tt>k</tt>th element of a foldable.
kth :: (Predicatory p, Foldable f) => Int -> PT p a (f a)

-- | Given a list of predicates and a list of values, ensure that each
--   predicate holds for each respective value. Fails if the two lists have
--   different lengths.
predList :: (HasCallStack, Predicatory p) => [Pred p a] -> [a] -> p

-- | Given a functor-full of predicates, and a functor-full of values,
--   ensure that the structures of the two functors match and apply all of
--   the predicates to all of the values. Generalized version of
--   <tt>list</tt>.
predful :: (HasCallStack, Predicatory p, Eq (f ()), Functor f, Foldable f) => f (Pred p a) -> Pred p (f a)

-- | Given a representable functor-full of predicates, and a functor-full
--   of values, yield a representable functor-full of booleans. Similar to
--   <a>predful</a>.
predCompose :: Representable f => f (Pred p a) -> f a -> f p

-- | Test all predicates against one value.
allTrue :: (Predicatory p, Foldable f) => f (Pred p a) -> Pred p a

-- | Check that a predicate is true for all values behind a generalized
--   getter and that there's at least one value for which it's true.
allOf1 :: (HasCallStack, Predicatory p) => Fold s a -> PT p a s

-- | Sugar for tupling.
pattern (:=>) :: a -> b -> (a, b)

-- | A pair of predicates, made into a predicate on pairs.
pair :: Predicatory p => Pred p a -> Pred p b -> Pred p (a, b)

-- | Flipped function composition; <tt>pf f</tt> for a function <tt>f</tt>
--   is a predicate transformer such that <tt>pf f p i == p (f i)</tt>.
pt :: (a -> b) -> PT p b a

-- | Higher precedence <a>$</a>, to work well with <a>&amp;</a>.
(?) :: (a -> b) -> a -> b
infixr 8 ?

-- | Prints the input of a predicate, for debugging.
traced :: Show a => (a -> String) -> PT c a a

-- | Prints the input of a predicate, for debugging.
tracedShow :: Show a => PT c a a

-- | Prints the input of a predicate, if the predicate fails, using
--   <a>Show</a>. Requires that the predicate's output type can be checked
--   for failure.
traceFailShow :: (Exceptional p, Predicatory p, Show a) => PT p a a

-- | Prints the input of a predicate over functions, if the predicate
--   fails. Requires that the predicate's output type can be checked for
--   failure.
traceFail :: (Predicatory p, Exceptional p) => (a -> String) -> PT p a a

-- | Predicate which always succeeds.
something :: Predicatory p => Pred p a

-- | Predicate which triggers full evaluation of its input and succeeds.
--   Useful for testing that an exception isn't thrown.
forced :: (Predicatory p, NFData a) => Pred p a

-- | Predicate on equality.
equals :: (HasCallStack, Predicatory p, Eq a) => a -> Pred p a

-- | Check that all of the input predicates are satisfied.
satAll :: Predicatory p => [Pred p a] -> Pred p a
instance GHC.Exception.Type.Exception PredicateTransformers.PredicateFailed
instance PredicateTransformers.Exceptional GHC.Types.Bool
instance PredicateTransformers.Exceptional a => PredicateTransformers.Exceptional (e -> a)
instance (a GHC.Types.~ ()) => PredicateTransformers.Exceptional (GHC.Types.IO a)
instance PredicateTransformers.Predicatory GHC.Types.Bool
instance PredicateTransformers.Predicatory a => PredicateTransformers.Predicatory (e -> a)
instance (a GHC.Types.~ ()) => PredicateTransformers.Predicatory (GHC.Types.IO a)
instance GHC.Show.Show PredicateTransformers.PredicateFailed