libghc-cond-doc 0.4.0.2-2 / usr / share / doc / libghc-cond-doc / html / cond.txt

-- 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.0.2

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 true = not false false = not true not = (<--> false) x && y = not (x || y) x || y = not (x && y) x xor y = (x || y) && (not (x && y)) x --> y = not x || y x <--> y = (x && y) || not (x || y)
true :: Boolean b => b
false :: Boolean b => b
not :: Boolean b => b -> b
(&&) :: Boolean b => b -> b -> b
(||) :: Boolean b => b -> b -> b
xor :: Boolean b => b -> b -> b
(-->) :: Boolean b => b -> b -> b
(<-->) :: Boolean b => b -> 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 Typeable1 Bitwise
instance Num a => Num (Bitwise a)
instance Bits a => Bits (Bitwise a)
instance Eq a => Eq (Bitwise a)
instance Ord a => Ord (Bitwise a)
instance Bounded a => Bounded (Bitwise a)
instance Enum a => Enum (Bitwise a)
instance Show a => Show (Bitwise a)
instance Read a => Read (Bitwise a)
instance Real a => Real (Bitwise a)
instance Integral a => Integral (Bitwise a)
instance Data a => Data (Bitwise a)
instance Ix a => Ix (Bitwise a)
instance Storable a => Storable (Bitwise a)
instance PrintfArg a => PrintfArg (Bitwise a)
instance (Num a, Bits a) => Boolean (Bitwise a)
instance Boolean (Endo Bool)
instance Boolean (Dual Bool)
instance Boolean All
instance Boolean Any
instance Boolean Bool


-- | 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, MonadPlus 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, MonadPlus 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 ToBool (Dual Bool)
instance ToBool All
instance ToBool Any
instance ToBool Bool