PredicateTransformers

This library is based on the notion of a predicate transformer, the below type PT a b, which is a function from a to predicates on b. 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 (lens-style) optics.

Some predicate transformers provided by other libraries: all, any (base) either (base) allOf (lens)

Documentation

class Predicatory a where

Class of possible predicate results. This is mostly a lattice with otherHand as disjunction, also as conjunction, stop as the falsy value, and continue as the truthy value. There may be multiple falsy values, however. Note that test failure messages are not really the domain of this library. It's the author's hope that they can be mostly replaced by traceFail.

Methods

otherHand :: HasCallStack => a -> a -> a infixr 2

also :: HasCallStack => a -> a -> a infixr 3

stop :: HasCallStack => a

continue :: a

Instances

Predicatory Bool

Defined in PredicateTransformers

Methods

otherHand :: Bool -> Bool -> Bool

also :: Bool -> Bool -> Bool

stop :: Bool

continue :: Bool

Predicatory (IO ())

Defined in PredicateTransformers

Methods

otherHand :: IO () -> IO () -> IO ()

also :: IO () -> IO () -> IO ()

stop :: IO ()

continue :: IO ()

Predicatory a => Predicatory (e -> a)

Defined in PredicateTransformers

Methods

otherHand :: (e -> a) -> (e -> a) -> e -> a

also :: (e -> a) -> (e -> a) -> e -> a

stop :: e -> a

continue :: e -> a

class Exceptional a where

Class of predicate results which can be checked for failure, by triggering an action.

Methods

assess :: a -> IO () -> a

Instances

Exceptional Bool

Defined in PredicateTransformers

Methods

assess :: Bool -> IO () -> Bool

Exceptional (IO ())

Defined in PredicateTransformers

Methods

assess :: IO () -> IO () -> IO ()

Exceptional a => Exceptional (e -> a)

Defined in PredicateTransformers

Methods

assess :: (e -> a) -> IO () -> e -> a

data PredicateFailed

The exception thrown by predicates of type `IO ()` by default. Other IOExceptions will work fine.

Constructors

PredicateFailed !CallStack

Instances

Exception PredicateFailed

Defined in PredicateTransformers

Methods

toException :: PredicateFailed -> SomeException

fromException :: SomeException -> Maybe PredicateFailed

displayException :: PredicateFailed -> String

Show PredicateFailed

Defined in PredicateTransformers

Methods

showsPrec :: Int -> PredicateFailed -> ShowS

show :: PredicateFailed -> String

showList :: [PredicateFailed] -> ShowS

type Pred p a = HasCallStack => a -> p

A convenient alias for predicates.

type PT p a b = HasCallStack => Pred p a -> Pred p b

Predicate transformers form a category where composition is ordinary function composition. Forms a category with . and id. Multiple are already provided by the standard library, for instance all and any.

just :: Predicatory p => PT p a (Maybe a)

Operate on the Just branch of a Maybe, or fail.

left :: Predicatory p => PT p e (Either e a)

Operate on the Left branch of an Either, or fail.

right :: Predicatory p => PT p a (Either e a)

Operate on the Right branch of an Either, or fail.

endingWith :: (Predicatory p, Foldable f) => PT p a (f a)

Operate on the last value in a foldable, or fail if it's not present.

startingWith :: (Predicatory p, Foldable f) => PT p a (f a)

Operate on the first value in a foldable, or fail if it's not present.

soleElementOf :: Predicatory p => Fold s a -> PT p a s

Require that a Fold has a single element, and operate on that element.

soleElement :: (Predicatory p, Foldable f) => PT p a (f a)

Require that a Foldable has a single element, and operate on that element.

match :: Predicatory p => Prism' s a -> PT p a s

Require that a Prism matches, and apply the predicate to its contents.

kth :: (Predicatory p, Foldable f) => Int -> PT p a (f a)

Only test the kth element of a foldable.

list :: Predicatory p => [Pred p a] -> [a] -> p

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 :: (Predicatory p, Eq (f ()), Functor f, Foldable f) => f (Pred p a) -> Pred p (f 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 list.

distRep :: Representable f => f (Pred p a) -> f a -> f p

Given a representable functor-full of predicates, and a functor-full of values, yield a representable functor-full of booleans. Similar to dist.

allTrue :: (Predicatory p, Foldable f) => f (Pred p a) -> Pred p a

Test all predicates against one value.

allOf1 :: Predicatory p => Fold s a -> PT p a s

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.

pattern (:=>) :: a -> b -> (a, b)

Sugar for tupling.

pair :: Predicatory p => Pred p a -> Pred p b -> Pred p (a, b)

A pair of predicates, made into a predicate on pairs.

pt :: (a -> b) -> PT p b a

Flipped function composition; pt f for a function f is a predicate transformer.

(?) :: (a -> b) -> a -> b infixl 9

Higher precedence $, to work well with &.

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, for debugging.

traceFailShow :: (Exceptional p, Predicatory p, Show a) => PT p a a

Prints the input of a predicate, if the predicate fails, using Show. Requires that the predicate's output type can be checked for failure.

traceFail :: (Predicatory p, Exceptional p) => (a -> String) -> 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.

something :: Predicatory p => Pred p a

Predicate which always succeeds.

forced :: (Predicatory p, NFData a) => Pred p a

Predicate which triggers full evaluation of its input and succeeds. Useful for testing that an exception isn't thrown.

equals :: (Predicatory p, Eq a) => a -> Pred p a

Predicate on equality.

satAll :: Predicatory p => [Pred p a] -> Pred p a

Check that all of the input predicates are satisfied.