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


-- | Utility functions for testing your attoparsec parsers with hspec
--   
--   This package provides some helper functions for testing attoparsec
--   parsers with hspec.
--   
--   See the documentation in <tt>Test.Hspec.Attoparsec</tt> for examples,
--   or this package's own test suite.
@package hspec-attoparsec
@version 0.1.0.2


-- | A <a>Source</a> class that ties parser types and input types to give
--   you a uniform interface for testing your parsers, without caring about
--   the input type.
module Test.Hspec.Attoparsec.Source

-- | A class where each instance will just teach how to get an Either or
--   the specific result type associated to the parser for the given input
--   type.
class (Eq string, Show string, IsString string) => Source parser string string' result | string -> parser, string -> result, string -> string'

-- | Feed some input to a parser and extract the result as either a failure
--   <a>String</a> or an actually parsed value. Can be read as <i>fed
--   to</i>.
--   
--   <pre>
--   -- "&lt;a ...&gt;" fed to an HTML parser 
--   "&lt;a href=\"/foo\"&gt;Go to foo&lt;/a&gt;" ~&gt; htmlParser :: Either String a
--   </pre>
(~>) :: Source parser string string' result => string -> parser string' a -> Either String a

-- | Feed some input to a parser and extract it as the appropriate result
--   type from that module.
--   
--   This is not currently useful in the library per se, but is used in
--   test-suites directly where we generally only deal with one concrete
--   set of parser, input and result types. This lets us inspect the result
--   in any way we want, e.g in conjunction with <tt>shouldSatisfy</tt> or
--   a custom hspec combinator.
(~?>) :: Source parser string string' result => string -> parser string' a -> result a

-- | Class for generically inspecting unconsumed input
class Leftover r s | r -> s

-- | Get the unconsumed input from the result of a parser
--   
--   Returns <a>Nothing</a> if the unconsumed input is ""
leftover :: Leftover r s => r a -> Maybe s
instance Test.Hspec.Attoparsec.Source.Leftover Data.Attoparsec.ByteString.Internal.Result Data.ByteString.Internal.ByteString
instance Test.Hspec.Attoparsec.Source.Leftover Data.Attoparsec.ByteString.Lazy.Result Data.ByteString.Lazy.Internal.ByteString
instance Test.Hspec.Attoparsec.Source.Leftover Data.Attoparsec.Text.Internal.Result Data.Text.Internal.Text
instance Test.Hspec.Attoparsec.Source.Leftover Data.Attoparsec.Text.Lazy.Result Data.Text.Internal.Lazy.Text
instance Test.Hspec.Attoparsec.Source.Source Data.Attoparsec.Internal.Types.Parser Data.ByteString.Internal.ByteString Data.ByteString.Internal.ByteString Data.Attoparsec.ByteString.Internal.Result
instance Test.Hspec.Attoparsec.Source.Source Data.Attoparsec.Internal.Types.Parser Data.ByteString.Lazy.Internal.ByteString Data.ByteString.Internal.ByteString Data.Attoparsec.ByteString.Lazy.Result
instance Test.Hspec.Attoparsec.Source.Source Data.Attoparsec.Internal.Types.Parser Data.Text.Internal.Text Data.Text.Internal.Text Data.Attoparsec.Text.Internal.Result
instance Test.Hspec.Attoparsec.Source.Source Data.Attoparsec.Internal.Types.Parser Data.Text.Internal.Lazy.Text Data.Text.Internal.Text Data.Attoparsec.Text.Lazy.Result


-- | Utility functions for testing <tt>attoparsec</tt> parsers, each one
--   providing an example of how to use it.
module Test.Hspec.Attoparsec

-- | Create an expectation by saying what the result should be. Intended to
--   be used with <a>~&gt;</a> as follows:
--   
--   <pre>
--   "&lt;!-- foo --&gt;" ~&gt; htmlCommentParser
--     `shouldParse` TagComment " foo "
--   </pre>
shouldParse :: (Eq a, Show a) => Either String a -> a -> Expectation

-- | Create an expectation by saying that the parser should successfully
--   parse a value and that this value should satisfy some predicate.
--   
--   This can fail if the parsing doesn't succeed or if it succeeds but the
--   value doesn't match the predicate.
--   
--   <pre>
--   "&gt;&gt;&gt;" ~&gt; many (char '&gt;')
--     `parseSatisfies` ((==3) . length)
--   </pre>
parseSatisfies :: Show a => Either String a -> (a -> Bool) -> Expectation

-- | Check that a parser succeeds on some given input
--   
--   <pre>
--   char 'x' `shouldSucceedOn` "x"
--   </pre>
shouldSucceedOn :: (Source p s s' r, Show a) => p s' a -> s -> Expectation

-- | Check that a parser fails on some given input
--   
--   <pre>
--   char 'x' `shouldFailOn` "a"
--   </pre>
shouldFailOn :: (Source p s s' r, Show a) => p s' a -> s -> Expectation

-- | Checking that the given parser succeeds and yields the given part of
--   the input unconsumed. Intended to be used in conjunction with
--   <a>~?&gt;</a>
--   
--   <pre>
--   ("xa" :: Text) ~?&gt; char 'x'
--     `leavesUnconsumed` "a"
--   </pre>
leavesUnconsumed :: (Source p s s' r, Leftover r s) => r a -> s -> Expectation

-- | A class where each instance will just teach how to get an Either or
--   the specific result type associated to the parser for the given input
--   type.
class (Eq string, Show string, IsString string) => Source parser string string' result | string -> parser, string -> result, string -> string'

-- | Feed some input to a parser and extract the result as either a failure
--   <a>String</a> or an actually parsed value. Can be read as <i>fed
--   to</i>.
--   
--   <pre>
--   -- "&lt;a ...&gt;" fed to an HTML parser 
--   "&lt;a href=\"/foo\"&gt;Go to foo&lt;/a&gt;" ~&gt; htmlParser :: Either String a
--   </pre>
(~>) :: Source parser string string' result => string -> parser string' a -> Either String a

-- | Feed some input to a parser and extract it as the appropriate result
--   type from that module.
--   
--   This is not currently useful in the library per se, but is used in
--   test-suites directly where we generally only deal with one concrete
--   set of parser, input and result types. This lets us inspect the result
--   in any way we want, e.g in conjunction with <tt>shouldSatisfy</tt> or
--   a custom hspec combinator.
(~?>) :: Source parser string string' result => string -> parser string' a -> result a

-- | Class for generically inspecting unconsumed input
class Leftover r s | r -> s

-- | Get the unconsumed input from the result of a parser
--   
--   Returns <a>Nothing</a> if the unconsumed input is ""
leftover :: Leftover r s => r a -> Maybe s
