-- 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.
@package prednote
@version 0.28.0.0
module Prednote.Core
-- | 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.
newtype Pred a
Pred :: (a -> Result) -> Pred a
-- | 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 :: Show a => Text -> (a -> Bool) -> Pred a
-- | 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
-- | 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.
(|||) :: Pred a -> Pred a -> Pred a
-- | Negation. Returns True if the argument Pred returns
-- False.
not :: Pred a -> Pred a
-- | 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.
switch :: Pred a -> Pred b -> Pred (Either a b)
-- | 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.
any :: Pred a -> Pred [a]
-- | 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.
all :: Pred a -> Pred [a]
-- | Represents Nothing of Maybe.
data Nothing
-- | Create a Pred for Maybe.
maybe :: Pred Nothing -> Pred a -> Pred (Maybe a)
-- | 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 or the source code for
-- Prednote.Comparisons.
addLabel :: Text -> Pred a -> Pred a
-- | Always returns True
true :: Show a => Pred a
-- | Always returns False
false :: Show a => Pred a
-- | Always returns its argument
same :: Pred Bool
-- | Runs a Pred against a value.
test :: Pred a -> a -> Bool
-- | Runs a Pred against a particular value; also returns a list of
-- Chunk describing the steps of evaulation.
verboseTest :: Pred a -> a -> ([Chunk], Bool)
-- | Like verboseTest, but results are printed to standard output.
-- Primarily for use in debugging or in a REPL.
verboseTestStdout :: Pred a -> a -> IO Bool
-- | 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".
newtype Condition
Condition :: [Chunk] -> Condition
-- | Stores the representation of a value; created using pack
-- . show.
newtype Value
Value :: Text -> Value
-- | Gives additional information about a particular Pred to aid the
-- user when viewing the output.
newtype Label
Label :: Text -> Label
-- | Any type that is accompanied by a set of labels.
data Labeled a
Labeled :: [Label] -> a -> Labeled a
-- | A Pred that returned True
data Passed
-- | A Pred created with predicate
PTerminal :: Value -> Condition -> Passed
-- | A Pred created with &&&
PAnd :: (Labeled Passed) -> (Labeled Passed) -> Passed
-- | A Pred created with |||
POr :: (Either (Labeled Passed) (Labeled Failed, Labeled Passed)) -> Passed
-- | A Pred created with not
PNot :: (Labeled Failed) -> Passed
-- | A Pred that returned False
data Failed
-- | A Pred created with predicate
FTerminal :: Value -> Condition -> Failed
-- | A Pred created with &&&
FAnd :: (Either (Labeled Failed) (Labeled Passed, Labeled Failed)) -> Failed
-- | A Pred created with |||
FOr :: (Labeled Failed) -> (Labeled Failed) -> Failed
-- | A Pred created with not
FNot :: (Labeled Passed) -> Failed
-- | The result of processing a Pred.
newtype Result
Result :: (Labeled (Either Failed Passed)) -> Result
-- | Returns whether this Result failed or passed.
splitResult :: Result -> Either (Labeled Failed) (Labeled Passed)
-- | Obtain a list of Chunk describing the evaluation process.
resultToChunks :: Result -> [Chunk]
-- | Obtain a list of Chunk describing the evaluation process.
passedToChunks :: Int -> Labeled Passed -> [Chunk]
-- | Obtain a list of Chunk describing the evaluation process.
failedToChunks :: Int -> Labeled Failed -> [Chunk]
instance Eq Condition
instance Ord Condition
instance Show Condition
instance Eq Value
instance Ord Value
instance Show Value
instance Eq Label
instance Ord Label
instance Show Label
instance Eq a => Eq (Labeled a)
instance Ord a => Ord (Labeled a)
instance Show a => Show (Labeled a)
instance Eq Failed
instance Ord Failed
instance Show Failed
instance Eq Passed
instance Ord Passed
instance Show Passed
instance Eq Result
instance Ord Result
instance Show Result
instance Show Nothing
instance Show EndOfList
instance Contravariant Pred
instance Show (Pred a)
instance Functor Labeled
-- | 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 Pred. 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
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]
-- | 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
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 :: Show a => Text -> (a -> Ordering) -> Ordering -> Pred a
-- | Overloaded version of compareBy.
compare :: (Show a, Ord a) => a -> Ordering -> Pred a
-- | Builds a Pred that tests items for equality.
equalBy :: Show a => Text -> (a -> Bool) -> Pred a
-- | Overloaded version of equalBy.
equal :: (Eq a, Show a) => a -> Pred a
-- | Builds a Pred for items that might fail to return a comparison.
compareByMaybe :: Show a => Text -> (a -> Maybe Ordering) -> Ordering -> Pred a
greater :: (Show a, Ord a) => a -> Pred a
less :: (Show a, Ord a) => a -> Pred a
greaterEq :: (Show a, Ord a) => a -> Pred a
lessEq :: (Show a, Ord a) => a -> Pred a
notEq :: (Show a, Eq a) => a -> Pred a
greaterBy :: Show a => Text -> (a -> Ordering) -> Pred a
lessBy :: Show a => Text -> (a -> Ordering) -> Pred a
greaterEqBy :: Show a => Text -> (a -> Ordering) -> Pred a
lessEqBy :: Show a => Text -> (a -> Ordering) -> Pred a
notEqBy :: Show 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)
-- | Prednote - annotated predicates
--
-- This module exports all the types and functions you will ordinarily
-- need. Many names clash with Prelude names, because these names made
-- the most sense. But I didn't make any clashing operators, as I'm not
-- that much of a masochist. So you will probably want to do something
-- like
--
--
-- import qualified Prednote as P
-- import Prednote ((|||), (&&&))
--
--
-- For more documentation, first see Prednote.Prebuilt, and then
-- Prednote.Comparisons and then Prednote.Expressions. You
-- will need Prednote.Core only if you want to tinker under the
-- hood.
module Prednote