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


-- | Syntactic sugar improving 'assert' and 'error'
--   
--   This library contains syntactic sugar that makes it easier to write
--   simple contracts with <a>assert</a> and <a>error</a> and report the
--   values that violate contracts.
@package assert-failure
@version 0.1.2.1


-- | Syntactic sugar that improves the usability of <a>assert</a> and
--   <a>error</a>. 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`

-- | A helper function for <a>error</a>. To be used as in
--   
--   <pre>
--   case xs of
--     0 : _ -&gt; error $ "insignificant zero" `showFailure` xs
--   </pre>
--   
--   Fixing the first argument to <tt>String</tt> instead of anything
--   Showable prevents warnings about defaulting, even when
--   <tt>OverloadedStrings</tt> extension is enabled.
showFailure :: Show v => String -> v -> String
infix 2 `showFailure`

-- | Syntactic sugar for the pair operation, to be used for <a>blame</a> as
--   in
--   
--   <pre>
--   assert (age &lt; 120 `blame` "age too high" `swith` age) $ savings / (120 - age)
--   </pre>
--   
--   Fixing the first component of the pair to <tt>String</tt> prevents
--   warnings about defaulting, even when <tt>OverloadedStrings</tt>
--   extension is enabled.
swith :: String -> v -> (String, v)
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

-- | Like <a>error</a>, but shows the source position (in newer GHCs
--   <tt>error</tt> shows source position as well, hence deprecation) 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>

-- | <i>Deprecated: use <a>error</a> and <a>showFailure</a> instead, now
--   that <a>error</a> prints source positions.</i>
failure :: Show a => (forall x. Bool -> x -> x) -> a -> b
infix 1 `failure`

-- | Syntactic sugar for the pair operation, to be used for <a>blame</a> as
--   in
--   
--   <pre>
--   assert (age &lt; 120 `blame` "age too high" `twith` age) $ savings / (120 - age)
--   </pre>
--   
--   Fixing the first component of the pair to <tt>Text</tt> prevents
--   warnings about defaulting, even when <tt>OverloadedStrings</tt>
--   extension is enabled.

-- | <i>Deprecated: consider using <a>swith</a> instead, because GHC
--   optimizes constant Strings better than Texts.</i>
twith :: Text -> b -> (Text, b)
infix 2 `twith`

-- | 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 (in newer GHCs <tt>error</tt>
--   shows source position as well, hence deprecation). Used as in
--   
--   <pre>
--   assert `forceEither` parseOrFailWithMessage code
--   </pre>

-- | <i>Deprecated: use 'either (error . show) id' instead, now that
--   <a>error</a> prints source positions.</i>
forceEither :: Show a => (forall x. Bool -> x -> x) -> Either a b -> b
infix 1 `forceEither`