prednote-0.28.0.2: Evaluate and display trees of predicates

Prednote.Core

Synopsis

# Predicates and their creation

newtype Pred a Source

Predicates. Is an instance of `Contravariant`, which allows you to change the type using `contramap`. Though the constructor is exported, ordinarily you shouldn't need to use it; other functions in this module create `Pred` and manipulate them as needed.

Constructors

 Pred (a -> Result)

Instances

 Contravariant Pred Show (Pred a)

predicate :: Show a => Text -> (a -> Bool) -> Pred a Source

Creates a new `Pred`. In `predicate cond f`, `cond` describes the condition, while `f` gives the predicate function. For example, if `f` is `(> 5)`, then `cond` might be ```"is greater than 5"```.

# Predicate combinators

## Primitive combinators

You might consider these combinators to be "primitive" in the sense that you can build a `Pred` for any user-defined type by using these combinators alone, along with `contramap`. Use `&&&`, `|||`, and `contramap` to analyze product types. Use `switch` and `contramap` to analyze sum types. For a simple example, see the source code for `maybe`, which is a simple sum type. For more complicated examples, see the source code for `any` and `all`, as a list is a sum type where one of the summands is a (recursive!) product type.

(&&&) :: Pred a -> Pred a -> Pred a infixr 3 Source

And. Returns `True` if both argument `Pred` return `True`. Is lazy in its second argment; if the first argument returns `False`, the second is ignored.

(|||) :: Pred a -> Pred a -> Pred a infixr 2 Source

Or. Returns `True` if either argument `Pred` returns `True`. Is lazy in its second argument; if the first argument returns `True`, the second argument is ignored.

not :: Pred a -> Pred a Source

Negation. Returns `True` if the argument `Pred` returns `False`.

switch :: Pred a -> Pred b -> Pred (Either a b) Source

Uses the appropriate `Pred` depending on the `Either` value. In `test (switch l r) e`, the resulting `Pred` returns the result of `l` if `e` is `Left` or the result of `r` if `e` is `Right`. Is lazy, so the the argument `Pred` that is not used is ignored.

## Convenience combinators

These were written using entirely the "primitive" combinators given above.

any :: Pred a -> Pred [a] Source

Like `any`; is `True` if any of the list items are `True`. An empty list returns `False`. Is lazy; will stop processing if it encounters a `True` item.

all :: Pred a -> Pred [a] Source

Like `all`; is `True` if none of the list items is `False`. An empty list returns `True`. Is lazy; will stop processing if it encouters a `False` item.

data Nothing Source

Represents `Nothing` of `Maybe`.

Instances

 Show Nothing

Arguments

 :: Pred Nothing What to do on `Nothing`. Usually you wil use `true` or `false`. -> Pred a Analyzes `Just` values. -> Pred (Maybe a)

Create a `Pred` for `Maybe`.

# Labeling

addLabel :: Text -> Pred a -> Pred a Source

Adds descriptive text to a `Pred`. Gives useful information for the user. The label is added to the top `Pred` in the tree; any existing labels are also retained. Labels that were added last will be printed first. For an example of this, see the source code for `any` and `all`.

# Constant predicates

true :: Show a => Pred a Source

Always returns `True`

false :: Show a => Pred a Source

Always returns `False`

Always returns its argument

# Evaluating predicates

test :: Pred a -> a -> Bool Source

Runs a `Pred` against a value.

verboseTest :: Pred a -> a -> ([Chunk], Bool) Source

Runs a `Pred` against a particular value; also returns a list of `Chunk` describing the steps of evaulation.

verboseTestStdout :: Pred a -> a -> IO Bool Source

Like `verboseTest`, but results are printed to standard output. Primarily for use in debugging or in a REPL.

# Results and converting them to `Chunk`s

Usually you will not need these functions and types, as the functions and types above should meet most use cases; however, these are here so the test suites can use them, and in case you need them.

newtype Condition Source

Describes the condition; for example, for a `Pred Int`, this might be `is greater than 5`; for a `Pred String`, this might be `begins with "Hello"`.

Constructors

 Condition [Chunk]

Instances

 Eq Condition Ord Condition Show Condition

newtype Value Source

Stores the representation of a value; created using ```pack . show```.

Constructors

 Value Text

Instances

 Eq Value Ord Value Show Value

newtype Label Source

Gives additional information about a particular `Pred` to aid the user when viewing the output.

Constructors

 Label Text

Instances

 Eq Label Ord Label Show Label

data Labeled a Source

Any type that is accompanied by a set of labels.

Constructors

 Labeled [Label] a

Instances

 Functor Labeled Eq a => Eq (Labeled a) Ord a => Ord (Labeled a) Show a => Show (Labeled a)

data Passed Source

A `Pred` that returned `True`

Constructors

 PTerminal Value Condition A `Pred` created with `predicate` PAnd (Labeled Passed) (Labeled Passed) A `Pred` created with `&&&` POr (Either (Labeled Passed) (Labeled Failed, Labeled Passed)) A `Pred` created with `|||` PNot (Labeled Failed) A `Pred` created with `not`

Instances

 Eq Passed Ord Passed Show Passed

data Failed Source

A `Pred` that returned `False`

Constructors

 FTerminal Value Condition A `Pred` created with `predicate` FAnd (Either (Labeled Failed) (Labeled Passed, Labeled Failed)) A `Pred` created with `&&&` FOr (Labeled Failed) (Labeled Failed) A `Pred` created with `|||` FNot (Labeled Passed) A `Pred` created with `not`

Instances

 Eq Failed Ord Failed Show Failed

newtype Result Source

The result of processing a `Pred`.

Constructors

 Result (Labeled (Either Failed Passed))

Instances

 Eq Result Ord Result Show Result

Returns whether this `Result` failed or passed.

Obtain a list of `Chunk` describing the evaluation process.

Arguments

 :: Int Number of levels of indentation -> Labeled Passed -> [Chunk]

Obtain a list of `Chunk` describing the evaluation process.

Arguments

 :: Int Number of levels of indentation -> Labeled Failed -> [Chunk]

Obtain a list of `Chunk` describing the evaluation process.