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


-- | Catchy combinators for HUnit
--   
--   Catchy combinators for HUnit:
--   <a>https://github.com/hspec/hspec-expectations#readme</a>
@package hspec-expectations
@version 0.8.2


-- | Experimental combinators, that may become part of the main
--   distribution, if they turn out to be useful for a wider audience.
module Test.Hspec.Expectations.Contrib

-- | Return <a>True</a> if the given value is a <a>Left</a>-value,
--   <a>False</a> otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isLeft (Left "foo")
--   True
--   
--   &gt;&gt;&gt; isLeft (Right 3)
--   False
--   </pre>
--   
--   Assuming a <a>Left</a> value signifies some sort of error, we can use
--   <a>isLeft</a> to write a very simple error-reporting function that
--   does absolutely nothing in the case of success, and outputs "ERROR" if
--   any error occurred.
--   
--   This example shows how <a>isLeft</a> might be used to avoid pattern
--   matching when one does not care about the value contained in the
--   constructor:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad ( when )
--   
--   &gt;&gt;&gt; let report e = when (isLeft e) $ putStrLn "ERROR"
--   
--   &gt;&gt;&gt; report (Right 1)
--   
--   &gt;&gt;&gt; report (Left "parse error")
--   ERROR
--   </pre>
isLeft :: Either a b -> Bool

-- | Return <a>True</a> if the given value is a <a>Right</a>-value,
--   <a>False</a> otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isRight (Left "foo")
--   False
--   
--   &gt;&gt;&gt; isRight (Right 3)
--   True
--   </pre>
--   
--   Assuming a <a>Left</a> value signifies some sort of error, we can use
--   <a>isRight</a> to write a very simple reporting function that only
--   outputs "SUCCESS" when a computation has succeeded.
--   
--   This example shows how <a>isRight</a> might be used to avoid pattern
--   matching when one does not care about the value contained in the
--   constructor:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad ( when )
--   
--   &gt;&gt;&gt; let report e = when (isRight e) $ putStrLn "SUCCESS"
--   
--   &gt;&gt;&gt; report (Left "parse error")
--   
--   &gt;&gt;&gt; report (Right 1)
--   SUCCESS
--   </pre>
isRight :: Either a b -> Bool


-- | Introductory documentation:
--   <a>https://github.com/sol/hspec-expectations#readme</a>
module Test.Hspec.Expectations
type Expectation = Assertion
expectationFailure :: HasCallStack => String -> Expectation

-- | <tt>actual `shouldBe` expected</tt> sets the expectation that
--   <tt>actual</tt> is equal to <tt>expected</tt>.
shouldBe :: (HasCallStack, Show a, Eq a) => a -> a -> Expectation
infix 1 `shouldBe`

-- | <tt>v `shouldSatisfy` p</tt> sets the expectation that <tt>p v</tt> is
--   <tt>True</tt>.
shouldSatisfy :: (HasCallStack, Show a) => a -> (a -> Bool) -> Expectation
infix 1 `shouldSatisfy`

-- | <tt>list `shouldStartWith` prefix</tt> sets the expectation that
--   <tt>list</tt> starts with <tt>prefix</tt>,
shouldStartWith :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation
infix 1 `shouldStartWith`

-- | <tt>list `shouldEndWith` suffix</tt> sets the expectation that
--   <tt>list</tt> ends with <tt>suffix</tt>,
shouldEndWith :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation
infix 1 `shouldEndWith`

-- | <tt>list `shouldContain` sublist</tt> sets the expectation that
--   <tt>sublist</tt> is contained, wholly and intact, anywhere in
--   <tt>list</tt>.
shouldContain :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation
infix 1 `shouldContain`

-- | <tt>xs `shouldMatchList` ys</tt> sets the expectation that <tt>xs</tt>
--   has the same elements that <tt>ys</tt> has, possibly in another order
shouldMatchList :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation
infix 1 `shouldMatchList`

-- | <tt>action `shouldReturn` expected</tt> sets the expectation that
--   <tt>action</tt> returns <tt>expected</tt>.
shouldReturn :: (HasCallStack, Show a, Eq a) => IO a -> a -> Expectation
infix 1 `shouldReturn`

-- | <tt>actual `shouldNotBe` notExpected</tt> sets the expectation that
--   <tt>actual</tt> is not equal to <tt>notExpected</tt>
shouldNotBe :: (HasCallStack, Show a, Eq a) => a -> a -> Expectation
infix 1 `shouldNotBe`

-- | <tt>v `shouldNotSatisfy` p</tt> sets the expectation that <tt>p v</tt>
--   is <tt>False</tt>.
shouldNotSatisfy :: (HasCallStack, Show a) => a -> (a -> Bool) -> Expectation
infix 1 `shouldNotSatisfy`

-- | <tt>list `shouldNotContain` sublist</tt> sets the expectation that
--   <tt>sublist</tt> is not contained anywhere in <tt>list</tt>.
shouldNotContain :: (HasCallStack, Show a, Eq a) => [a] -> [a] -> Expectation
infix 1 `shouldNotContain`

-- | <tt>action `shouldNotReturn` notExpected</tt> sets the expectation
--   that <tt>action</tt> does not return <tt>notExpected</tt>.
shouldNotReturn :: (HasCallStack, Show a, Eq a) => IO a -> a -> Expectation
infix 1 `shouldNotReturn`

-- | <tt>action `shouldThrow` selector</tt> sets the expectation that
--   <tt>action</tt> throws an exception. The precise nature of the
--   expected exception is described with a <a>Selector</a>.
shouldThrow :: (HasCallStack, Exception e) => IO a -> Selector e -> Expectation
infix 1 `shouldThrow`

-- | A <tt>Selector</tt> is a predicate; it can simultaneously constrain
--   the type and value of an exception.
type Selector a = a -> Bool
anyException :: Selector SomeException
anyErrorCall :: Selector ErrorCall
anyIOException :: Selector IOException
anyArithException :: Selector ArithException
errorCall :: String -> Selector ErrorCall

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack
