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

-- | Catchy combinators for HUnit
--   
--   Catchy combinators for HUnit:
--   https://github.com/hspec/hspec-expectations#readme
@package hspec-expectations
@version 0.8.4

-- | 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 True if the given value is a Left-value,
--   False otherwise.
--   
--   
Examples
--   
--   Basic usage:
--   
--   
--   >>> isLeft (Left "foo")
--   True
--   
--   >>> isLeft (Right 3)
--   False
--   
--   
--   Assuming a Left value signifies some sort of error, we can use
--   isLeft 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 isLeft might be used to avoid pattern
--   matching when one does not care about the value contained in the
--   constructor:
--   
--   
--   >>> import Control.Monad ( when )
--   
--   >>> let report e = when (isLeft e) $ putStrLn "ERROR"
--   
--   >>> report (Right 1)
--   
--   >>> report (Left "parse error")
--   ERROR
--   
isLeft :: Either a b -> Bool

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

-- | If you have a test case that has multiple assertions, you can use the
--   annotate function to provide a string message that will be
--   attached to the Expectation.
--   
--   
--   describe "annotate" $ do
--     it "adds the message" $ do
--       annotate "obvious falsehood" $ do
--         True shouldBe False
--   
--   ========>
--   
--   1) annotate, adds the message
--         obvious falsehood
--         expected: False
--          but got: True
--   
annotate :: String -> IO a -> IO a

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

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

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

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

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

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

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

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

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

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

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

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

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

-- | A Selector 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 ?callStack :: CallStack is an
--   implementation detail and should not be considered part of the
--   CallStack API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack
