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


-- | Helpers for Control.Exception.assert
--   
--   GHC supports compile-time toggling of run-time assertions via the
--   <tt>-fignore-asserts</tt> flag, which only effects a behavioural
--   change in <a>Control.Exception.assert</a>. Furthermore the reported
--   location only gives the use site of the aforementioned, making it
--   difficult to abstract over and hence cumbersome to use.
--   
--   This package aims to make assertions more convenient, and also
--   provides a rule to rewrite assertions to <a>id</a> when
--   <tt>-fignore-asserts</tt> is used.
@package assert
@version 0.0.1.0

module Control.Exception.Assert

-- | A distict <a>Exception</a> from <a>AssertionFailed</a>, so that we
--   stop fudging the exception message after the first
--   <a>mapException</a>.
--   
--   The name comes from abbreviating ‘assert’ and translating the result
--   to my native tongue.
newtype Arse
Arse :: String -> Arse

-- | Generic helper for <a>assert</a> that includes a descriptive message
--   to the <tt>AssertFailure</tt> exception if thrown. Use this to build
--   your own <a>assert</a> helpers, such as <a>byOrd</a>. A rule is
--   included which rewrites <a>assertMessage</a> to <a>id</a> when
--   compiling with <tt>-fignore-asserts</tt>.
assertMessage :: String -> String -> (a -> a) -> a -> a

-- | Assert that two values are equal.
--   
--   <pre>
--   &gt;&gt;&gt; byEq assert "Bool" False True ()
--   *** Exception: … Assertion failed "Bool", False ≠ True
--   </pre>
byEq :: (Eq x, Show x) => (Bool -> a -> a) -> String -> x -> x -> a -> a

-- | Assert that two values obey the given <a>Ordering</a>.
--   
--   <pre>
--   &gt;&gt;&gt; byOrd assert "Int" LT 0 1 ()
--   ()
--   </pre>
byOrd :: (Ord x, Show x) => (Bool -> a -> a) -> String -> Ordering -> x -> x -> a -> a

-- | Assert that a value satisfies the given predicate.
--   
--   <pre>
--   &gt;&gt;&gt; byPred assert "Odd" odd 4 ()
--   *** Exception: … Assertion failed "Odd", 4
--   </pre>
byPred :: Show x => (Bool -> a -> a) -> String -> (x -> Bool) -> x -> a -> a

-- | If the first argument evaluates to <a>True</a>, then the result is the
--   second argument. Otherwise an <tt>AssertionFailed</tt> exception is
--   raised, containing a <a>String</a> with the source file and line
--   number of the call to <a>assert</a>.
--   
--   Assertions can normally be turned on or off with a compiler flag (for
--   GHC, assertions are normally on unless optimisation is turned on with
--   <tt>-O</tt> or the <tt>-fignore-asserts</tt> option is given). When
--   assertions are turned off, the first argument to <a>assert</a> is
--   ignored, and the second argument is returned as the result.
assert :: Bool -> a -> a
instance Typeable Arse
instance Exception Arse
instance Show Arse