-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Basic conditional and boolean operators with monadic variants.
--   
--   This library provides:
--   
--   <ul>
--   <li>Implementations of various overloaded conditional operations</li>
--   <li>Lifted monadic variants of those operations and common boolean
--   operators</li>
--   <li>A typeclass for boolean algebras.</li>
--   </ul>
--   
--   Feel free to send ideas and suggestions for new conditional operators
--   to the maintainer.
--   
--   Monadic looping constructs are not included as part of this package,
--   since the monad-loops package has a fairly complete collection of them
--   already.
@package cond
@version 0.4.1.1

module Data.Algebra.Boolean

-- | A class for boolean algebras. Instances of this class are expected to
--   obey all the laws of boolean algebra.
--   
--   Minimal complete definition: <a>true</a> or <a>false</a>, <a>not</a>
--   or <a>&lt;--&gt;</a>, <a>||</a> or <a>&amp;&amp;</a>.
class Boolean b where nand = not . and nor = not . or true = not false false = not true not = (<--> false) x && y = not (not x || not y) x || y = not (not x && not y) x `xor` y = (x || y) && (not (x && y)) x --> y = not x || y x <--> y = (x && y) || not (x || y) and = foldl' (&&) true or = foldl' (||) false all p = foldl' f true where f a b = a && p b any p = foldl' f false where f a b = a || p b

-- | Truth value, defined as the top of the bounded lattice
true :: Boolean b => b

-- | False value, defined as the bottom of the bounded lattice.
false :: Boolean b => b

-- | Logical negation.
not :: Boolean b => b -> b

-- | Logical conjunction. (infxr 3)
(&&) :: Boolean b => b -> b -> b

-- | Logical inclusive disjunction. (infixr 2)
(||) :: Boolean b => b -> b -> b

-- | Logical exclusive disjunction. (infixr 1)
xor :: Boolean b => b -> b -> b

-- | Logical implication. (infixr 1)
(-->) :: Boolean b => b -> b -> b

-- | Logical biconditional. (infixr 1)
(<-->) :: Boolean b => b -> b -> b

-- | The logical conjunction of several values.
and :: (Boolean b, Foldable t) => t b -> b

-- | The logical disjunction of several values.
or :: (Boolean b, Foldable t) => t b -> b

-- | The negated logical conjunction of several values.
--   
--   <pre>
--   <a>nand</a> = <a>not</a> . <a>and</a>
--   </pre>
nand :: (Boolean b, Foldable t) => t b -> b

-- | The logical conjunction of the mapping of a function over several
--   values.
all :: (Boolean b, Foldable t) => (a -> b) -> t a -> b

-- | The logical disjunction of the mapping of a function over several
--   values.
any :: (Boolean b, Foldable t) => (a -> b) -> t a -> b

-- | The negated logical disjunction of several values.
--   
--   <pre>
--   <a>nor</a> = <a>not</a> . <a>or</a>
--   </pre>
nor :: (Boolean b, Foldable t) => t b -> b

-- | Injection from <a>Bool</a> into a boolean algebra.
fromBool :: Boolean b => Bool -> b

-- | A newtype wrapper that derives a <a>Boolean</a> instance from any type
--   that is both a <a>Bits</a> instance and a <a>Num</a> instance, such
--   that boolean logic operations on the <a>Bitwise</a> wrapper correspond
--   to bitwise logic operations on the inner type. It should be noted that
--   <a>false</a> is defined as <a>Bitwise</a> 0 and <a>true</a> is defined
--   as <a>not</a> <a>false</a>.
--   
--   In addition, a number of other classes are automatically derived from
--   the inner type. These classes were chosen on the basis that many other
--   <a>Bits</a> instances defined in base are also instances of these
--   classes.
newtype Bitwise a
Bitwise :: a -> Bitwise a
[getBits] :: Bitwise a -> a
instance Text.Printf.PrintfArg a => Text.Printf.PrintfArg (Data.Algebra.Boolean.Bitwise a)
instance Foreign.Storable.Storable a => Foreign.Storable.Storable (Data.Algebra.Boolean.Bitwise a)
instance GHC.Arr.Ix a => GHC.Arr.Ix (Data.Algebra.Boolean.Bitwise a)
instance Data.Data.Data a => Data.Data.Data (Data.Algebra.Boolean.Bitwise a)
instance GHC.Real.Integral a => GHC.Real.Integral (Data.Algebra.Boolean.Bitwise a)
instance GHC.Real.Real a => GHC.Real.Real (Data.Algebra.Boolean.Bitwise a)
instance GHC.Read.Read a => GHC.Read.Read (Data.Algebra.Boolean.Bitwise a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Algebra.Boolean.Bitwise a)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Data.Algebra.Boolean.Bitwise a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Data.Algebra.Boolean.Bitwise a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Data.Algebra.Boolean.Bitwise a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Algebra.Boolean.Bitwise a)
instance Data.Bits.Bits a => Data.Bits.Bits (Data.Algebra.Boolean.Bitwise a)
instance GHC.Num.Num a => GHC.Num.Num (Data.Algebra.Boolean.Bitwise a)
instance Data.Algebra.Boolean.Boolean GHC.Types.Bool
instance Data.Algebra.Boolean.Boolean Data.Monoid.Any
instance Data.Algebra.Boolean.Boolean Data.Monoid.All
instance Data.Algebra.Boolean.Boolean (Data.Monoid.Dual GHC.Types.Bool)
instance Data.Algebra.Boolean.Boolean (Data.Monoid.Endo GHC.Types.Bool)
instance (Data.Algebra.Boolean.Boolean x, Data.Algebra.Boolean.Boolean y) => Data.Algebra.Boolean.Boolean (x, y)
instance (GHC.Num.Num a, Data.Bits.Bits a) => Data.Algebra.Boolean.Boolean (Data.Algebra.Boolean.Bitwise a)


-- | A convenient set of useful conditional operators.
module Control.Conditional

-- | Conversion of values to <a>Bool</a>.
--   
--   Instances of <a>ToBool</a> that are also <a>Boolean</a> should obey
--   the following laws:
--   
--   <pre>
--   p || q = if toBool p then true else q
--   </pre>
--   
--   <pre>
--   p &amp;&amp; q = if toBool p then q else false
--   </pre>
class ToBool bool
toBool :: ToBool bool => bool -> Bool

-- | A simple conditional operator
if' :: ToBool bool => bool -> a -> a -> a

-- | <a>if'</a> with the <a>Bool</a> argument at the end (infixr 1).
(??) :: ToBool bool => a -> a -> bool -> a

-- | A catamorphism (aka fold) for booleans. This is analogous to
--   <a>foldr</a>, <a>maybe</a>, and <a>either</a>. The first argument is
--   the false case, the second argument is the true case, and the last
--   argument is the predicate value.
bool :: (ToBool bool) => a -> a -> bool -> a

-- | <a>if'</a> lifted to <a>Monad</a>. Unlike <a>liftM3</a> <a>if'</a>,
--   this is short-circuiting in the monad, such that only the predicate
--   action and one of the remaining argument actions are executed.
ifM :: (ToBool bool, Monad m) => m bool -> m a -> m a -> m a

-- | Lifted inclusive disjunction. Unlike <a>liftM2</a> (<a>||</a>), This
--   function is short-circuiting in the monad. Fixity is the same as
--   <a>||</a> (infixr 2).
(<||>) :: (ToBool bool, Boolean bool, Monad m) => m bool -> m bool -> m bool

-- | Lifted conjunction. Unlike <a>liftM2</a> (<a>&amp;&amp;</a>), this
--   function is short-circuiting in the monad. Fixity is the same as
--   <a>&amp;&amp;</a> (infxr 3).
(<&&>) :: (ToBool bool, Boolean bool, Monad m) => m bool -> m bool -> m bool

-- | Lifted boolean negation.
notM :: (Boolean bool, Monad m) => m bool -> m bool

-- | Lifted boolean exclusive disjunction.
xorM :: (Boolean bool, Monad m) => m bool -> m bool -> m bool

-- | Lisp-style conditionals. If no conditions match, then a runtime
--   exception is thrown. Here's a trivial example:
--   
--   <pre>
--   signum x = cond [(x &gt; 0     , 1 )
--                   ,(x &lt; 0     , -1)
--                   ,(otherwise , 0 )]
--   </pre>
cond :: ToBool bool => [(bool, a)] -> a

-- | Analogous to the <a>cond</a> function with a default value supplied,
--   which will be used when no condition in the list is matched.
condDefault :: ToBool bool => a -> [(bool, a)] -> a

-- | Lisp-style conditionals generalized over <a>MonadPlus</a>. If no
--   conditions match, then the result is <a>mzero</a>. This is a safer
--   variant of <a>cond</a>.
--   
--   Here's a highly contrived example using <a>fromMaybe</a>:
--   
--   <pre>
--   signum x = fromMaybe 0 . condPlus $ [(x &gt; 0, 1 ) 
--                                       ,(x &lt; 0, -1)]
--   </pre>
--   
--   Alternatively, you could use the <a>&lt;|</a> operator from Hoare's
--   ternary conditional choice operator, like so:
--   
--   <pre>
--   signum x = 0 &lt;| condPlus [(x &gt; 0, 1 ) 
--                            ,(x &lt; 0, -1)]
--   </pre>
condPlus :: (ToBool bool, MonadPlus m) => [(bool, a)] -> m a

-- | <a>cond</a> lifted to <a>Monad</a>. If no conditions match, a runtime
--   exception is thrown.
condM :: (ToBool bool, Monad m) => [(m bool, m a)] -> m a

-- | <a>condPlus</a> lifted to <a>Monad</a>. If no conditions match, then
--   <a>mzero</a> is returned.
condPlusM :: (ToBool bool, MonadPlus m) => [(m bool, m a)] -> m a

-- | A synonym for <a>return</a> <a>true</a>.
otherwiseM :: (Boolean bool, Monad m) => m bool

-- | Conditional composition. If the predicate is False, <a>id</a> is
--   returned instead of the second argument. This function, for example,
--   can be used to conditionally add functions to a composition chain.
(?.) :: (ToBool bool, Category cat) => bool -> cat a a -> cat a a

-- | Conditional monoid operator. If the predicate is <a>False</a>, the
--   second argument is replaced with <a>mempty</a>. The fixity of this
--   operator is one level higher than <a>&lt;&gt;</a>.
--   
--   It can also be used to chain multiple predicates together, like this:
--   
--   <pre>
--   even (length ls) ?&lt;&gt; not (null ls) ?&lt;&gt; ls
--   </pre>
(?<>) :: (ToBool bool, Monoid a) => bool -> a -> a

-- | Composes a predicate function and 2 functions into a single function.
--   The first function is called when the predicate yields True, the
--   second when the predicate yields False.
--   
--   Note that after importing <a>Control.Monad.Instances</a>,
--   <a>select</a> becomes a special case of <a>ifM</a>.
select :: ToBool bool => (a -> bool) -> (a -> b) -> (a -> b) -> (a -> b)

-- | <a>select</a> lifted to <a>Monad</a>.
selectM :: (ToBool bool, Monad m) => (a -> m bool) -> (a -> m b) -> (a -> m b) -> (a -> m b)

-- | An operator that allows you to write C-style ternary conditionals of
--   the form:
--   
--   <pre>
--   p ? t ?? f
--   </pre>
--   
--   Note that parentheses are required in order to chain sequences of
--   conditionals together. This is probably a good thing.
(?) :: b -> (b -> a) -> a

-- | Right bracket of the conditional choice operator. If the predicate is
--   <a>True</a>, returns <a>Nothing</a>, otherwise it returns <a>Just</a>
--   the right-hand argument.
(|>) :: ToBool bool => bool -> a -> Maybe a

-- | Left bracket of the conditional choice operator. This is equivalent to
--   <a>fromMaybe</a>
(<|) :: a -> Maybe a -> a

-- | A monadic variant of <a>|&gt;</a>.
(|>>) :: (ToBool bool, Monad m) => m bool -> m a -> m (Maybe a)

-- | A monadic variant of <a>&lt;|</a>.
(<<|) :: Monad m => m a -> m (Maybe a) -> m a

-- | Unicode rebinding of <a>|&gt;</a>.
(⊳) :: ToBool bool => bool -> a -> Maybe a

-- | Unicode rebinding of <a>&lt;|</a>.
(⊲) :: a -> Maybe a -> a

-- | Generalization of <a>guard</a>
guard :: (ToBool bool, MonadPlus m) => bool -> m ()

-- | A variant of <a>guard</a> with a monadic predicate.
guardM :: (ToBool bool, MonadPlus m) => m bool -> m ()

-- | Generalization of <a>when</a>
when :: (ToBool bool, Monad m) => bool -> m () -> m ()

-- | A variant of <a>when</a> with a monadic predicate.
whenM :: (ToBool bool, Monad m) => m bool -> m () -> m ()

-- | Generalization of <a>unless</a>
unless :: (Boolean bool, ToBool bool, Monad m) => bool -> m () -> m ()

-- | A variant of <a>unless</a> with a monadic predicate.
unlessM :: (ToBool bool, Boolean bool, Monad m) => m bool -> m () -> m ()
instance Control.Conditional.ToBool GHC.Types.Bool
instance Control.Conditional.ToBool Data.Monoid.Any
instance Control.Conditional.ToBool Data.Monoid.All
instance Control.Conditional.ToBool (Data.Monoid.Dual GHC.Types.Bool)
