-- 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 assert and error and report the
--   values that violate contracts.
@package assert-failure
@version 0.1.3.0

-- | Syntactic sugar that improves the usability of assert and
--   error. The original assert function is here
--   re-exported for convenience.
--   
--   Make sure to enable assertions for your cabal package, e.g., by
--   setting
--   
--   
--   ghc-options: -fno-ignore-asserts
--   
--   
--   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 True, then the result is the
--   second argument. Otherwise an AssertionFailed exception is
--   raised, containing a String with the source file and line
--   number of the call to assert.
--   
--   Assertions can normally be turned on or off with a compiler flag (for
--   GHC, assertions are normally on unless optimisation is turned on with
--   -O or the -fignore-asserts option is given). When
--   assertions are turned off, the first argument to assert 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
--   
--   
--   assert (age < 120 `blame` age) $ savings / (120 - age)
--   
blame :: Show v => Bool -> v -> Bool
infix 1 `blame`

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

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

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

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

-- | Deprecated: consider using swith instead, for simplicity,
--   because GHC optimizes lazy String constants very well.
twith :: Text -> b -> (Text, b)
infix 2 `twith`

-- | Like error, but shows the source position (in newer GHCs
--   error shows source position as well, hence deprecation) and
--   also the value to blame for the failure. To be used as in
--   
--   
--   case xs of
--     0 : _ -> assert `failure` (xs, "has an insignificant zero")
--   

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

-- | Assuming that Left signifies an error condition, check the
--   Either value and, if Left is encountered, fail
--   outright and show the error message (in newer GHCs error
--   shows source position as well, hence deprecation). Used as in
--   
--   
--   assert `forceEither` parseOrFailWithMessage code
--   

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