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


-- | Class of types that can be constructed from their text representation
--   
--   This library provides the type class <a>HasParser</a> as a dual to
--   <a>Pretty</a>. Instances of this class provide a parser than can be
--   used to construct the type from its text representation.
@package parsec-class
@version 1.0.0.0

module Text.Parsec.Class.Orphans
instance GHC.Exception.Exception Text.Parsec.Error.ParseError


-- | <a>HasParser</a> can be considered a dual to <tt>Pretty</tt> like
--   <a>Read</a> is to <a>Show</a>. The class provides <a>Data.Parsec</a>
--   parsers for its instances that construct the type from its textual
--   representation. Combined with the <a>parseM</a> and <a>parse</a>
--   convenience functions, this class makes parsing simple. Unlike
--   <a>Read</a>, Parsec parsers return reasonable error messages in case
--   of failure. Also, there is a rich set of combinators and additional
--   libraries available for re-use.
module Text.Parsec.Class

-- | A simplified <a>ParsecT</a> parser that consumes some kind of
--   character stream without requiring any particular state state.
type CharParser st input m a = Stream st m Char => ParsecT st input m a

-- | Types that are instances of this class can be parsed and constructed
--   from some character based text representation.
class HasParser a
parser :: HasParser a => CharParser st input m a

-- | Parsers functions like <a>parse</a> or <a>parseM</a> use this type to
--   provide a helpful context in case the parser failes. Parsec uses the
--   synonym <a>SourceName</a> for the same purpose, but in fact this type
--   doesn't necessarily have to be a file name. It can be any name or
--   identifier. Oftentimes, it it's useful to pass the name of the type
--   that the parser attempted to parse.
type ErrorContext = String

-- | Convenience wrapper around <a>runParserT</a> that uses the
--   <a>HasParser</a> class to determine the desired parser for the given
--   result type. The function reports syntax errors via <a>fail</a>.
--   
--   <pre>
--   &gt;&gt;&gt; parseM "Natural" "987654321" :: IO Natural
--   987654321
--   
--   &gt;&gt;&gt; parseM "Natural" "123456789" :: Maybe Natural
--   Just 123456789
--   </pre>
--   
--   Please note that parsers run this way do not ignore any white space:
--   
--   <pre>
--   &gt;&gt;&gt; parseM "Natural" " 1" :: Maybe Natural
--   Nothing
--   
--   &gt;&gt;&gt; parseM "Natural" "1 " :: Maybe Natural
--   Nothing
--   </pre>
parseM :: (MonadFail m, Stream input m Char, HasParser a) => ErrorContext -> input -> m a

-- | Convenience wrapper around <a>runParser</a> that uses the
--   <a>HasParser</a> class to determine the desired parser for the given
--   result type. The function reports syntax errors by <a>throw</a>ing
--   <a>ParseError</a>. This approach is inherently impure and complicates
--   error handling greatly. Use this function only on occasions where
--   parser errors are fatal errors that your code cannot recover from. In
--   almost all cases, <a>parseM</a> is the better choice.
--   
--   <pre>
--   &gt;&gt;&gt; parse "Natural" "12345" :: Natural
--   12345
--   </pre>
--   
--   Like <a>parseM</a>, this function does not skip over any white space.
--   Use Parsec's primitive <a>runParser</a> or <a>runParserT</a> functions
--   if you don't like this behavior:
--   
--   <pre>
--   &gt;&gt;&gt; runParser (spaces &gt;&gt; parser) () "Natural" "  1  " :: Either ParseError Natural
--   Right 1
--   </pre>
parse :: (Stream input Identity Char, HasParser a) => ErrorContext -> input -> a
instance Text.Parsec.Class.HasParser GHC.Natural.Natural
