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 Boolish a where

Class of possible predicate results. This is almost a lattice with or as disjunction, and as conjunction, fail as the falsy value, and succeed as the truthy value. However there may be multiple falsy values, and and will pick the first one it's passed, whereas or will pick the second it's passed.

Methods

or :: a -> a -> a infixr 2

and :: a -> a -> a infixr 3

fail :: HasCallStack => Doc ann -> v -> a

succeed :: a

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

Check and execute a callback on failure.

Instances

Boolish Bool

Defined in PredicateTransformers

Methods

or :: Bool -> Bool -> Bool

and :: Bool -> Bool -> Bool

fail :: HasCallStack => Doc ann -> v -> Bool

succeed :: Bool

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

a ~ () => Boolish (IO a)

Defined in PredicateTransformers

Methods

or :: IO a -> IO a -> IO a

and :: IO a -> IO a -> IO a

fail :: HasCallStack => Doc ann -> v -> IO a

succeed :: IO a

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

Boolish a => Boolish (e -> a)

Defined in PredicateTransformers

Methods

or :: (e -> a) -> (e -> a) -> e -> a

and :: (e -> a) -> (e -> a) -> e -> a

fail :: HasCallStack => Doc ann -> v -> e -> a

succeed :: e -> a

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 (Doc ann) actual

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 = a -> p

A convenient alias for predicates.

type PT p a b = 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.

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

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

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

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

match :: (HasCallStack, Boolish p) => Getting [a] s a -> PT p a s

Require that a Prism matches, and apply the predicate to its contents. This works for folds, too.

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

Only test the kth element of a foldable.

list :: (HasCallStack, Boolish 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.

predful :: (HasCallStack, Boolish 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.

compose :: 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 predful.

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

Test all predicates against one value.

allOf1 :: (HasCallStack, Boolish p) => Getting [a] 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 :: Boolish p => Pred p a -> Pred p b -> Pred p (a, b)

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

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

Flipped function composition; pf f for a function f is a predicate transformer such that pf f p i == p (f i).

(?) :: (a -> b) -> a -> b infixr 8

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 :: (Boolish 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 :: Boolish 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.

forced :: (Boolish 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 :: (HasCallStack, Boolish p, Eq a) => a -> Pred p a

Predicate on equality.