Prednote

This module provides everything you need for most uses of Prednote. The core type of Prednote is the Pred, which is a rose Tree of predicates along with some additional information, such as a plan, which shows you how the Pred will be evaluated without actually having to apply it to a particular subject. When evaluating a Pred, you can also display a report describing the evaluation process.

This module builds Pred with reports that make sparing use of color; for example, True results have [TRUE] indicated in green, [FALSE] in red, and short circuits (that is, Pred that were evaluated without evaluating all their child Pred) indicated in yellow. They are also nicely indented to indicate the structure of the Tree.

If you want more control over how your results are formatted, examine Prednote.Core and Prednote.Format. Prednote.Comparisons builds on this module to provide Pred to use for common comparisons (such as greater than, less than, etc.) Prednote.Expressions helps you parse infix or postfix (i.e. RPN) expressions.

This module exports some names that conflict with Prelude names, so you might want to do something like

import qualified Prednote as P

Pred

data Pred a

A rose tree of predicates.

Instances

Contravariant Pred

Show (Pred a)

Visibility

Upon evaluation, each Pred has a visibility, indicated with Visible. It can be either shown or hidden. The visibility of a Pred does not affect any of the results, nor does it affect how the Pred is shown in the plan; rather, it affects only how the result of the Pred is shown in the report. If a Pred is hidden, its value and the value of its children is not shown in the report.

data Visible

Is this result visible? If not, report will not show it.

Instances

Eq Visible

Ord Visible

Show Visible

shown :: Visible

Shown by report

hidden :: Visible

Hidden by report

visibility

Arguments

:: (Bool -> Visible)

When applied to the result of the Pred, this function returns the desired visibility.

-> Pred a

-> Pred a

Creates a Pred with its visibility modified.

reveal :: Pred a -> Pred a

Creates a Pred that is always shown.

hide :: Pred a -> Pred a

Creates a Pred that is always hidden.

showTrue :: Pred a -> Pred a

Creates a Pred that is shown only if its result is True.

showFalse :: Pred a -> Pred a

Creates a Pred that is shown only if its result is False.

Predicates

These Pred have no child Pred.

predicate

Arguments

:: Text

Static label

-> (a -> Text)

Computes the dynamic label. Do not indicate whether the result is True or False; this is automatically done for you.

-> (a -> Bool)

Predicate function

-> Pred a

Builds predicates.

true :: Pred a

Always returns True and is always visible.

false :: Pred a

Always returns False and is always visible.

same :: Pred Bool

Returns the subject as is; is always visible.

Combinators

These functions combine one more more Pred to create a new Pred; the argument Pred become children of the new Pred.

all :: [Pred a] -> Pred a

No child Pred may be False. An empty list of child Pred returns True. Always visible.

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

Creates all Pred that are always visible.

any :: [Pred a] -> Pred a

At least one child Pred must be True. An empty list of child Pred returns False. Always visible.

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

Creates any Pred that are always visible.

not :: Pred a -> Pred a

Negation. Always visible.

wrap

Arguments

:: Text

Static label

-> (a -> Text)

Computes the dynamic label. Do not indicate whether the result is True or False; this is automatically done for you.

-> (a -> b)

-> Pred b

-> Pred a

Makes an existing Pred the child of a new Pred. The new Pred has the same result as the child Pred. The new Pred is always visible and never short circuits.

Fanout

These functions allow you to take a single subject and split it into multiple subjects, applying a Pred to each subject that results. As a simple example, this allows you to build a Pred [Int] that combines Pred that test individual Int along with Pred that examine the entire list of [Int].

fanAll :: (a -> [b]) -> Pred b -> Pred a

No fanned-out item may be False. An empty list of child items returns True.

fanAny :: (a -> [b]) -> Pred b -> Pred a

At least one fanned-out item must be True. An empty list of child items returns False.

fanAtLeast :: Int -> (a -> [b]) -> Pred b -> Pred a

At least the given number of child items must be True.

Reports and plans

A plan displays a Pred without evaluating it, while a report shows the process through which a Pred was evaluated for a particular subject.

data Output

The result of evaluating a Pred.

Instances

Show Output

plan :: Pred a -> [Chunk]

Indents and formats static labels for display. This is a plan for how the Pred would be applied.

evaluate :: Pred a -> a -> Tree Output

Evaluates a Pred by applying it to a subject.

report :: Tree Output -> [Chunk]

Indents and formats output for display.

Evaluation and reporting

These functions use report, evaluate, or both.

test :: Pred a -> a -> Bool

Applies a Pred to a single subject and returns the result.

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

Like test but also returns the accompanying report.

filter :: Pred a -> [a] -> [a]

Like filter.

filterV :: Pred a -> [a] -> ([a], [Chunk])

Like filter but also returns a list of report, with one report for each list item.