-- 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.2.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.
module PredicateTransformers

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

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

-- | Functor from Hask^op to PT.
function :: (b -> a) -> PT a b

-- | Operate on the target of a prism, or fail.
match :: APrism s t a b -> PT a s

-- | Operate on the target of a getter.
getter :: Getting a s a -> PT a s

-- | Invert a predicate.
nay :: PT a a

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

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

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

-- | Operate on the last value in a list, or fail if it's not present.
endingWith :: PT a [a]

-- | Operate on the first value in a list, or fail if it's not present.
startingWith :: PT a [a]

-- | Require that a list has a single element, and operate on that element.
only :: PT a [a]

-- | Test all predicates against one value.
allTrue :: [Pred a] -> Pred 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.
dist :: [Pred a] -> Pred [a]

-- | 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
--   <a>dist</a>.
distF :: (Eq (f ()), Functor f, Foldable f) => f (Pred a) -> Pred (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>distF</a>.
distRep :: Representable f => f (a -> Bool) -> f a -> f Bool

-- | Sugar for tupling.
(==>) :: a -> b -> (a, b)
pair :: Pred a -> Pred b -> Pred (a, b)
eitherWay :: Pred a -> Pred b -> Pred (Either a b)

-- | Flipped function composition, meant to be used postfix.
(!) :: (b -> a) -> (a -> c) -> b -> c

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