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


-- | Syntactic sugar improving 'assert' and 'error'
--   
--   This library contains syntactic sugar that improves the usability of
--   <a>assert</a> and <a>error</a>. This is actually a bunch of hacks
--   wrapping the original <a>assert</a> function, see inside.
--   
--   See also <a>http://hackage.haskell.org/package/loch</a>,
--   <a>http://hackage.haskell.org/package/assert</a> and
--   <a>https://ghc.haskell.org/trac/ghc/ticket/5273</a>.
@package assert-failure
@version 0.1.1.0


-- | Syntactic sugar that improves the usability of <a>assert</a> and
--   <a>error</a>.
--   
--   This is actually a bunch of hacks wrapping the original
--   <tt>assert</tt> function, which is, as of GHC 7.8, the only simple way
--   of obtaining source positions. The original <tt>assert</tt> function
--   is here re-exported for convenience.
--   
--   Make sure to enable assertions for your cabal package, e.g., by
--   setting
--   
--   <pre>
--   ghc-options: -fno-ignore-asserts
--   </pre>
--   
--   in your .cabal file. Otherwise, some of the functions will have no
--   effect at all.
module Control.Exception.Assert.Sugar

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

-- | If the condition fails, display the value blamed for the failure. Used
--   as in
--   
--   <pre>
--   assert (age &lt; 120 `blame` age) $ savings / (120 - age)
--   </pre>
blame :: Show a => Bool -> a -> Bool
infix 1 `blame`

-- | Like <a>error</a>, but shows the source position and also the value to
--   blame for the failure. To be used as in
--   
--   <pre>
--   case xs of
--     0 : _ -&gt; assert `failure` (xs, "has an insignificant zero")
--   </pre>
failure :: Show a => (forall x. Bool -> x -> x) -> a -> b
infix 1 `failure`

-- | Syntactic sugar for the pair operation, to be used in <a>blame</a> and
--   <a>failure</a> as in
--   
--   <pre>
--   assert (age &lt; 120 `blame` "age too high" `twith` age) $ savings / (120 - age)
--   </pre>
--   
--   or
--   
--   <pre>
--   case xs of
--     0 : _ -&gt; assert `failure` "insignificant zero" `twith` xs
--   </pre>
--   
--   Fixing the first component of the pair to <tt>Text</tt> prevents
--   warnings about defaulting.
twith :: Text -> b -> (Text, b)
infix 2 `twith`

-- | The same as <a>twith</a>, but for <a>String</a>, not <a>Text</a>.
--   
--   Syntactic sugar for the pair operation, to be used in <a>blame</a> and
--   <a>failure</a> as in
--   
--   <pre>
--   assert (age &lt; 120 `blame` "age too high" `swith` age) $ savings / (120 - age)
--   </pre>
--   
--   or
--   
--   <pre>
--   case xs of
--     0 : _ -&gt; assert `failure` "insignificant zero" `swith` xs
--   </pre>
--   
--   Fixing the first component of the pair to <tt>String</tt> prevents
--   warnings about defaulting.
swith :: String -> b -> (String, b)
infix 2 `swith`

-- | Like <a>all</a>, but if the predicate fails, blame all the list
--   elements and especially those for which it fails. To be used as in
--   
--   <pre>
--   assert (allB (&lt;= height) [yf, y1, y2])
--   </pre>
allB :: Show a => (a -> Bool) -> [a] -> Bool

-- | To be used in place of the verbose <tt>(return ())</tt>, as in
--   
--   <pre>
--   do k &lt;- getK7 r
--      assert (k &lt;= maxK `blame` "K7 too large" `twith` r) skip
--      return $ k &gt;= averageK
--   </pre>
skip :: Monad m => m ()

-- | Assuming that <tt>Left</tt> signifies an error condition, check the
--   <tt>Either</tt> value and, if <tt>Left</tt> is encountered, fail
--   outright and show the error message. Used as in
--   
--   <pre>
--   assert `forceEither` parseOrFailWithMessage code
--   </pre>
forceEither :: Show a => (forall x. Bool -> x -> x) -> Either a b -> b
infix 1 `forceEither`
