-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Evaluate and display trees of predicates
--
-- Build and evaluate trees of predicates. For example, you might build a
-- predicate of the type Int -> Bool. You do this by assembling
-- several predicates into a tree. You can then verbosely evaluate this
-- tree, showing why a particular result is reached.
--
-- prednote also provides modules to test several subjects against a
-- given predicate, and to parse infix or RPN expressions into a tree of
-- predicates.
--
-- tests are packaged separately in the prednote-tests package.
@package prednote
@version 0.26.0.4
-- | Pred core functions. If your needs are simple,
-- Prednote.Prebuilt is easier to use. However, the types and
-- functions in this module give you more control.
--
-- Each function in this module that returns a Pred returns one
-- with the following characteristics:
--
--
--
-- Upon evaluation:
--
--
--
-- Thus, the Pred created by this module are rather bare-bones,
-- but you can modify them as you see fit; Prednote.Prebuilt
-- already does this for you.
--
-- This module exports some names that conflict with Prelude names, so
-- you might want to do something like
--
--
-- import qualified Prednote.Pred.Core as P
--
module Prednote.Core
-- | Indicates how to display text. This function is applied to an
-- Int that is the level of indentation; each level of descent
-- through a tree of Pred increments this Int by one.
-- Because the function returns a list of Chunk, you can use
-- multiple colors. Typically this function will indent text accordingly,
-- with a newline at the end.
type Chunker = Int -> [Chunk]
-- | A rose tree of predicates.
data Pred a
Pred :: Tree Chunker -> (a -> Tree Output) -> Pred a
-- | A tree of static names, allowing you to identify the Pred
-- without applying it to a subject.
static :: Pred a -> Tree Chunker
-- | Evaluates a Pred by applying it to a subject.
evaluate :: Pred a -> a -> Tree Output
-- | The result of evaluating a Pred.
data Output
Output :: Bool -> Visible -> Maybe Chunker -> Chunker -> Output
result :: Output -> Bool
-- | Results that are not Visible are not shown by the report
-- function.
visible :: Output -> Visible
-- | Indicates whether there was a short circuit when evaluating this
-- Pred. A short circuit occurs when the Pred does not need
-- to evaluate all of its children in order to reach a result. If
-- Nothing, there was no short circuit; otherwise, this is a
-- Just with a Chunker providing a way to display the short
-- circuit.
short :: Output -> Maybe Chunker
-- | The dynamic label; this indicates how report will show the
-- Pred to the user after it has been evaluated.
dynamic :: Output -> Chunker
-- | Is this result visible? If not, report will not show it.
newtype Visible
Visible :: Bool -> Visible
unVisible :: Visible -> Bool
-- | Shown by report
shown :: Visible
-- | Hidden by report
hidden :: Visible
-- | No Pred in the list may be False for all to be
-- True. An empty list of Pred yields a Pred that
-- always returns True. May short circuit.
all :: [Pred a] -> Pred a
-- | At least one Pred in the list must be True for the
-- resulting Pred to be True. An empty list of Pred
-- yields a Pred that always returns False. May short
-- circuit.
any :: [Pred a] -> Pred a
-- | Negates the child Pred. Never short circuits.
not :: Pred a -> Pred a
-- | Fanout. May short circuit.
fan :: ([Bool] -> (Bool, Visible, Maybe Int)) -> (a -> [b]) -> Pred b -> Pred a
-- | Fanout all. The resulting Pred is True if no child item
-- returns False; an empty list of child items returns
-- True. May short circuit.
fanAll :: (a -> [b]) -> Pred b -> Pred a
-- | Fanout any. The resulting Pred is True if at least one
-- child item returns True; an empty list of child items returns
-- False. May short circuit.
fanAny :: (a -> [b]) -> Pred b -> Pred a
-- | Fanout at least. The resulting Pred is True if at least
-- the given number of child items return True. May short circuit.
fanAtLeast :: Int -> (a -> [b]) -> Pred b -> Pred a
-- | Indents and formats output for display.
report :: Int -> Tree Output -> [Chunk]
-- | Indents and formats static labels for display. This is a plan
-- for how the Pred would be applied.
plan :: Int -> Pred a -> [Chunk]
-- | Applies a Pred to a single subject and returns the
-- result.
test :: Pred a -> a -> Bool
-- | Like test but also returns the accompanying report.
testV :: Pred a -> a -> (Bool, [Chunk])
-- | Like filter.
filter :: Pred a -> [a] -> [a]
-- | Like filter but also returns a list of report, with one
-- report for each list item.
filterV :: Pred a -> [a] -> ([a], [Chunk])
-- | shorter x y is True if list x is shorter than list y. Lazier
-- than taking the length of each list and comparing the results.
shorter :: [a] -> [a] -> Bool
instance Eq Visible
instance Ord Visible
instance Show Visible
instance Show (Pred a)
instance Show Output
instance Contravariant Pred
-- | Functions used to format text. Typically you won't need these unless
-- you want tailored control over how your Pred are formatted.
module Prednote.Format
-- | A colorful label for True values.
lblTrue :: [Chunk]
-- | A colorful label for False values.
lblFalse :: [Chunk]
-- | Indent amount.
indentAmt :: Int
-- | Prefixes the given Text with colorful text to indicate
-- True or False as appropriate.
lblLine :: Bool -> Text -> [Chunk]
-- | Indents the given list of Chunk by the given Int
-- multipled by indentAmt. Appends a newline.
indent :: [Chunk] -> Int -> [Chunk]
-- | A label for a short circuit.
shortCir :: Int -> [Chunk]
-- | Indents a Text by the given Int multiplied by
-- indentAmt.
indentTxt :: Text -> Int -> [Chunk]
-- | Append two Text, with an intervening space if both Text
-- are not empty.
(<+>) :: Text -> Text -> Text
-- | Create a new Pred with a different static label.
rename :: Text -> Pred a -> Pred a
-- | Creates a new Pred with a result differing from the original
-- Pred.
changeOutput :: (a -> Output -> Output) -> Pred a -> Pred a
-- | Creates a new Pred with a different dynamic label.
speak :: (a -> Text) -> Pred a -> Pred a
-- | Creates a new Pred with any short circuits having a colorful
-- label.
speakShort :: Pred a -> Pred a
-- | Functions to work with Pred. This module works with
-- Text and produces Pred that make sparing use of color.
-- For more control over the Pred produced, use
-- Prednote.Pred.Core.
--
-- Exports some names that conflict with Prelude names, so you might want
-- to do something like
--
--
-- import qualified Prednote.Pred as P
--
module Prednote.Prebuilt
-- | Builds predicates.
predicate :: Text -> (a -> Text) -> (a -> Bool) -> Pred a
-- | Always returns True and is always visible.
true :: Pred a
-- | Always returns False and is always visible.
false :: Pred a
-- | Returns the subject as is; is always visible.
same :: Pred Bool
-- | 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.
wrap :: Text -> (a -> Text) -> (a -> b) -> Pred b -> Pred a
-- | Creates a Pred with its visibility modified.
visibility :: (Bool -> Visible) -> Pred a -> Pred a
-- | Creates a Pred that is always shown.
reveal :: Pred a -> Pred a
-- | Creates a Pred that is always hidden.
hide :: Pred a -> Pred a
-- | Creates a Pred that is shown only if its result is
-- True.
showTrue :: Pred a -> Pred a
-- | Creates a Pred that is shown only if its result is
-- False.
showFalse :: Pred a -> Pred a
-- | No child Pred may be False. An empty list of child
-- Pred returns True. Always visible.
all :: [Pred a] -> Pred a
-- | Creates all Pred that are always visible.
(&&&) :: Pred a -> Pred a -> Pred a
-- | At least one child Pred must be True. An empty list of
-- child Pred returns False. Always visible.
any :: [Pred a] -> Pred a
-- | Creates any Pred that are always visible.
(|||) :: Pred a -> Pred a -> Pred a
-- | Negation. Always visible.
not :: Pred a -> Pred a
-- | No fanned-out item may be False. An empty list of child items
-- returns True.
fanAll :: (a -> [b]) -> Pred b -> Pred a
-- | At least one fanned-out item must be True. An empty list of
-- child items returns False.
fanAny :: (a -> [b]) -> Pred b -> Pred a
-- | At least the given number of child items must be True.
fanAtLeast :: Int -> (a -> [b]) -> Pred b -> Pred a
module Prednote.Comparisons
-- | Build a Pred that compares items. The idea is that the item on the
-- right hand side is baked into the Pred and that the
-- Pred compares this single right-hand side to each left-hand
-- side item.
compareBy :: Text -> Text -> (a -> Text) -> (a -> Ordering) -> Ordering -> Pred a
-- | Overloaded version of compareBy.
compare :: (Show a, Ord a) => Text -> a -> Ordering -> Pred a
-- | Builds a Pred that tests items for equality.
equalBy :: Text -> Text -> (a -> Text) -> (a -> Bool) -> Pred a
-- | Overloaded version of equalBy.
equal :: (Eq a, Show a) => Text -> a -> Pred a
-- | Builds a Pred for items that might fail to return a
-- comparison.
compareByMaybe :: Text -> Text -> (a -> Text) -> (a -> Maybe Ordering) -> Ordering -> Pred a
greater :: (Show a, Ord a) => Text -> a -> Pred a
less :: (Show a, Ord a) => Text -> a -> Pred a
greaterEq :: (Show a, Ord a) => Text -> a -> Pred a
lessEq :: (Show a, Ord a) => Text -> a -> Pred a
notEq :: (Show a, Eq a) => Text -> a -> Pred a
greaterBy :: Text -> Text -> (a -> Text) -> (a -> Ordering) -> Pred a
lessBy :: Text -> Text -> (a -> Text) -> (a -> Ordering) -> Pred a
greaterEqBy :: Text -> Text -> (a -> Text) -> (a -> Ordering) -> Pred a
lessEqBy :: Text -> Text -> (a -> Text) -> (a -> Ordering) -> Pred a
notEqBy :: Text -> Text -> (a -> Text) -> (a -> Bool) -> Pred a
-- | Parses a string that contains text, such as >=, which
-- indicates which comparer to use. Returns the comparer.
parseComparer :: Text -> (Ordering -> Pred a) -> Maybe (Pred a)
-- | Postfix, or RPN, expression parsing.
--
-- This module parses RPN expressions where the operands are predicates
-- and the operators are one of and, or, or
-- not, where and and or are binary and
-- not is unary.
module Prednote.Expressions.RPN
data RPNToken a
TokOperand :: (Pred a) -> RPNToken a
TokOperator :: Operator -> RPNToken a
data Operator
OpAnd :: Operator
OpOr :: Operator
OpNot :: Operator
pushOperand :: Pred a -> [Pred a] -> [Pred a]
pushOperator :: Operator -> [Pred a] -> Either Text [Pred a]
pushToken :: [Pred a] -> RPNToken a -> Either Text [Pred a]
-- | Parses an RPN expression and returns the resulting Predbox. Fails if
-- there are no operands left on the stack or if there are multiple
-- operands left on the stack; the stack must contain exactly one operand
-- in order to succeed.
parseRPN :: Foldable f => f (RPNToken a) -> Either Text (Pred a)
instance Show Operator
instance Contravariant RPNToken
module Prednote.Expressions.Infix
data InfixToken a
TokRPN :: (RPNToken a) -> InfixToken a
TokParen :: Paren -> InfixToken a
data Paren
Open :: Paren
Close :: Paren
-- | Creates an RPN expression from an infix one. Fails only if there are
-- mismatched parentheses. It is possible to create a nonsensical RPN
-- expression; the RPN parser must catch this.
createRPN :: Foldable f => f (InfixToken a) -> Maybe [RPNToken a]
instance Contravariant InfixToken
-- | Handles parsing of both infix and RPN Predbox expressions.
module Prednote.Expressions
-- | Is this an infix or RPN expression?
data ExprDesc
Infix :: ExprDesc
RPN :: ExprDesc
type Error = Text
-- | A single type for both RPN tokens and infix tokens.
data Token a
-- | Creates Operands from Predbox.
operand :: Pred a -> Token a
-- | The And operator
opAnd :: Token a
-- | The Or operator
opOr :: Token a
-- | The Not operator
opNot :: Token a
-- | Open parentheses
openParen :: Token a
-- | Close parentheses
closeParen :: Token a
-- | Parses expressions. Fails if the expression is nonsensical in some way
-- (for example, unbalanced parentheses, parentheses in an RPN
-- expression, or multiple stack values remaining.) Works by first
-- changing infix expressions to RPN ones.
parseExpression :: ExprDesc -> [Token a] -> Either Error (Pred a)
instance Eq ExprDesc
instance Show ExprDesc
instance Contravariant Token
-- | 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
--
module Prednote
-- | A rose tree of predicates.
data Pred a
-- | Is this result visible? If not, report will not show it.
data Visible
-- | Shown by report
shown :: Visible
-- | Hidden by report
hidden :: Visible
-- | Creates a Pred with its visibility modified.
visibility :: (Bool -> Visible) -> Pred a -> Pred a
-- | Creates a Pred that is always shown.
reveal :: Pred a -> Pred a
-- | Creates a Pred that is always hidden.
hide :: Pred a -> Pred a
-- | Creates a Pred that is shown only if its result is
-- True.
showTrue :: Pred a -> Pred a
-- | Creates a Pred that is shown only if its result is
-- False.
showFalse :: Pred a -> Pred a
-- | Builds predicates.
predicate :: Text -> (a -> Text) -> (a -> Bool) -> Pred a
-- | Always returns True and is always visible.
true :: Pred a
-- | Always returns False and is always visible.
false :: Pred a
-- | Returns the subject as is; is always visible.
same :: Pred Bool
-- | No child Pred may be False. An empty list of child
-- Pred returns True. Always visible.
all :: [Pred a] -> Pred a
-- | Creates all Pred that are always visible.
(&&&) :: Pred a -> Pred a -> Pred a
-- | At least one child Pred must be True. An empty list of
-- child Pred returns False. Always visible.
any :: [Pred a] -> Pred a
-- | Creates any Pred that are always visible.
(|||) :: Pred a -> Pred a -> Pred a
-- | Negation. Always visible.
not :: Pred a -> 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.
wrap :: Text -> (a -> Text) -> (a -> b) -> Pred b -> Pred a
-- | No fanned-out item may be False. An empty list of child items
-- returns True.
fanAll :: (a -> [b]) -> Pred b -> Pred a
-- | At least one fanned-out item must be True. An empty list of
-- child items returns False.
fanAny :: (a -> [b]) -> Pred b -> Pred a
-- | At least the given number of child items must be True.
fanAtLeast :: Int -> (a -> [b]) -> Pred b -> Pred a
-- | The result of evaluating a Pred.
data Output
-- | Indents and formats static labels for display. This is a plan
-- for how the Pred would be applied.
plan :: Pred a -> [Chunk]
-- | Evaluates a Pred by applying it to a subject.
evaluate :: Pred a -> a -> Tree Output
-- | Indents and formats output for display.
report :: Tree Output -> [Chunk]
-- | Applies a Pred to a single subject and returns the
-- result.
test :: Pred a -> a -> Bool
-- | Like test but also returns the accompanying report.
testV :: Pred a -> a -> (Bool, [Chunk])
-- | Like filter.
filter :: Pred a -> [a] -> [a]
-- | Like filter but also returns a list of report, with one
-- report for each list item.
filterV :: Pred a -> [a] -> ([a], [Chunk])