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


-- | A variety of alternative parser combinator libraries.
--   
--   A variety of alternative parser combinator libraries, including the
--   original HuttonMeijer set. The Poly sets have features like good error
--   reporting, arbitrary token type, running state, lazy parsing, and so
--   on. Finally, Text.Parse is a proposed replacement for the standard
--   Read class, for better deserialisation of Haskell values from Strings.
@package polyparse
@version 1.9


-- | This library of monadic parser combinators is based on the ones
--   defined by Graham Hutton and Erik Meijer. It has been extended by
--   Malcolm Wallace to use an abstract token type (no longer just a
--   string) as input, and to incorporate state in the monad, useful for
--   symbol tables, macros, and so on. Basic facilities for error reporting
--   have also been added, and later extended by Graham Klyne to return the
--   errors through an <tt>Either</tt> type, rather than just calling
--   <tt>error</tt>.
module Text.ParserCombinators.HuttonMeijerWallace
newtype Parser s t e a

-- | The parser type is parametrised on the types of the state <tt>s</tt>,
--   the input tokens <tt>t</tt>, error-type <tt>e</tt>, and the result
--   value <tt>a</tt>. The state and remaining input are threaded through
--   the monad.
P :: (s -> [Either e t] -> ParseResult s t e a) -> Parser s t e a

-- | Deliver the first remaining token.
item :: Parser s t e t

-- | Fail if end of input is not reached
eof :: Show p => Parser s (p, t) String ()

-- | Apply the parser to some real input, given an initial state value. If
--   the parser fails, raise <a>error</a> to halt the program. (This is the
--   original exported behaviour - to allow the caller to deal with the
--   error differently, see <tt>papply'</tt>.)
papply :: Parser s t String a -> s -> [Either String t] -> [(a, s, [Either String t])]

-- | Apply the parser to some real input, given an initial state value. If
--   the parser fails, return a diagnostic message to the caller.
papply' :: Parser s t e a -> s -> [Either e t] -> Either e [(a, s, [Either e t])]

-- | A choice between parsers. Keep only the first success.
(+++) :: Parser s t e a -> Parser s t e a -> Parser s t e a

-- | Deliver the first token if it equals the argument.
tok :: Eq t => t -> Parser s (p, t) e t

-- | Deliver the first token if it does not equal the argument.
nottok :: Eq t => [t] -> Parser s (p, t) e t

-- | Deliver zero or more values of <tt>a</tt>.
many :: Parser s t e a -> Parser s t e [a]

-- | Deliver one or more values of <tt>a</tt>.
many1 :: Parser s t e a -> Parser s t e [a]

-- | Deliver zero or more values of <tt>a</tt> separated by <tt>b</tt>'s.
sepby :: Parser s t e a -> Parser s t e b -> Parser s t e [a]

-- | Deliver one or more values of <tt>a</tt> separated by <tt>b</tt>'s.
sepby1 :: Parser s t e a -> Parser s t e b -> Parser s t e [a]
chainl :: Parser s t e a -> Parser s t e (a -> a -> a) -> a -> Parser s t e a
chainl1 :: Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
chainr :: Parser s t e a -> Parser s t e (a -> a -> a) -> a -> Parser s t e a
chainr1 :: Parser s t e a -> Parser s t e (a -> a -> a) -> Parser s t e a
ops :: [(Parser s t e a, b)] -> Parser s t e b
bracket :: (Show p, Show t) => Parser s (p, t) e a -> Parser s (p, t) e b -> Parser s (p, t) e c -> Parser s (p, t) e b

-- | Accept a complete parse of the input only, no partial parses.
toEOF :: Show p => Parser s (p, t) String a -> Parser s (p, t) String a

-- | If the parser fails, generate an error message.
elserror :: (Show p, Show t) => Parser s (p, t) String a -> String -> Parser s (p, t) String a

-- | Update the internal state.
stupd :: (s -> s) -> Parser s t e ()

-- | Query the internal state.
stquery :: (s -> a) -> Parser s t e a

-- | Deliver the entire internal state.
stget :: Parser s t e s

-- | This is useful for recursively expanding macros. When the user-parser
--   recognises a macro use, it can lookup the macro expansion from the
--   parse state, lex it, and then stuff the lexed expansion back down into
--   the parser.
reparse :: [Either e t] -> Parser s t e ()
instance MonadPlus (Parser s t e)
instance Monad (Parser s t e)
instance Functor (Parser s t e)


-- | This Haskell script defines a library of parser combinators, and is
--   taken from sections 1-6 of our article <a>Monadic Parser
--   Combinators</a>. Some changes to the library have been made in the
--   move from Gofer to Haskell:
--   
--   <ul>
--   <li>Do notation is used in place of monad comprehension notation;</li>
--   <li>The parser datatype is defined using <a>newtype</a>, to avoid the
--   overhead of tagging and untagging parsers with the P constructor.</li>
--   </ul>
module Text.ParserCombinators.HuttonMeijer

-- | The parser monad
newtype Parser a
P :: ([Token] -> [(a, [Token])]) -> Parser a
item :: Parser Token
first :: Parser a -> Parser a
papply :: Parser a -> [Token] -> [(a, [Token])]
(+++) :: Parser a -> Parser a -> Parser a
sat :: (Token -> Bool) -> Parser Token
many :: Parser a -> Parser [a]
many1 :: Parser a -> Parser [a]
sepby :: Parser a -> Parser b -> Parser [a]
sepby1 :: Parser a -> Parser b -> Parser [a]
chainl :: Parser a -> Parser (a -> a -> a) -> a -> Parser a
chainl1 :: Parser a -> Parser (a -> a -> a) -> Parser a
chainr :: Parser a -> Parser (a -> a -> a) -> a -> Parser a
chainr1 :: Parser a -> Parser (a -> a -> a) -> Parser a
ops :: [(Parser a, b)] -> Parser b
bracket :: Parser a -> Parser b -> Parser c -> Parser b
char :: Char -> Parser Char
digit :: Parser Char
lower :: Parser Char
upper :: Parser Char
letter :: Parser Char
alphanum :: Parser Char
string :: String -> Parser String
ident :: Parser String
nat :: Parser Int
int :: Parser Int
spaces :: Parser ()
comment :: Parser ()
junk :: Parser ()
skip :: Parser a -> Parser a
token :: Parser a -> Parser a
natural :: Parser Int
integer :: Parser Int
symbol :: String -> Parser String
identifier :: [String] -> Parser String
instance MonadPlus Parser
instance Monad Parser
instance Functor Parser

module Text.ParserCombinators.Poly.Result

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Convert a Result to an Either, paired with the remaining unconsumed
--   input.
resultToEither :: Result z a -> (Either String a, z)
instance Functor (Result z)

module Text.ParserCombinators.Poly.Base

-- | The <tt>Commitment</tt> class is an abstraction over all the current
--   concrete representations of monadic/applicative parser combinators in
--   this package. The common feature is two-level error-handling. Some
--   primitives must be implemented specific to each parser type (e.g.
--   depending on whether the parser has a running state, or whether it is
--   lazy). But given those primitives, large numbers of combinators do not
--   depend any further on the internal structure of the particular parser.
class Commitment p
commit :: Commitment p => p a -> p a
adjustErr :: Commitment p => p a -> (String -> String) -> p a
oneOf' :: Commitment p => [(String, p a)] -> p a

-- | The <tt>PolyParse</tt> class is an abstraction gathering all of the
--   common features that a two-level error-handling parser requires: the
--   applicative parsing interface, the monadic interface, and commitment.
--   
--   There are two additional basic combinators that we expect to be
--   implemented afresh for every concrete type, but which (for technical
--   reasons) cannot be class methods. They are <tt>next</tt> and
--   <tt>satisfy</tt>.
class (Functor p, Monad p, Applicative p, Alternative p, Commitment p) => PolyParse p

-- | Apply a parsed function to a parsed value. Rather like ordinary
--   function application lifted into parsers.
apply :: PolyParse p => p (a -> b) -> p a -> p b

-- | <tt>x <a>discard</a> y</tt> parses both x and y, but discards the
--   result of y. Rather like <tt>const</tt> lifted into parsers.
discard :: PolyParse p => p a -> p b -> p a

-- | When a simple fail is not strong enough, use failBad for emphasis. An
--   emphasised (severe) error cannot be overridden by choice operators.
failBad :: PolyParse p => String -> p a

-- | <tt>adjustErrBad</tt> is just like <tt>adjustErr</tt> except it also
--   raises the severity of the error.
adjustErrBad :: PolyParse p => p a -> (String -> String) -> p a

-- | Helper for formatting error messages: indents all lines by a fixed
--   amount.
indent :: Int -> String -> String

-- | Parse the first alternative in the list that succeeds.
oneOf :: PolyParse p => [p a] -> p a

-- | 'exactly n p' parses precisely n items, using the parser p, in
--   sequence.
exactly :: PolyParse p => Int -> p a -> p [a]

-- | 'upto n p' parses n or fewer items, using the parser p, in sequence.
upto :: PolyParse p => Int -> p a -> p [a]

-- | Parse a non-empty list of items.
many1 :: PolyParse p => p a -> p [a]

-- | Parse a list of items separated by discarded junk.
sepBy :: PolyParse p => p a -> p sep -> p [a]

-- | Parse a non-empty list of items separated by discarded junk.
sepBy1 :: PolyParse p => p a -> p sep -> p [a]

-- | Parse a list of items, discarding the start, end, and separator items.
bracketSep :: PolyParse p => p bra -> p sep -> p ket -> p a -> p [a]

-- | Parse a bracketed item, discarding the brackets. If everything matches
--   <i>except</i> the closing bracket, the whole parse fails soft, which
--   can give less-than-satisfying error messages. If you want better error
--   messages, try calling with e.g. <tt>bracket open (commit close)
--   item</tt>
bracket :: PolyParse p => p bra -> p ket -> p a -> p a

-- | <tt>manyFinally e t</tt> parses a possibly-empty sequence of
--   <tt>e</tt>'s, terminated by a <tt>t</tt>. The final <tt>t</tt> is
--   discarded. Any parse failures could be due either to a badly-formed
--   terminator or a badly-formed element, so it raises both possible
--   errors.
manyFinally :: PolyParse p => p a -> p z -> p [a]

-- | <tt>manyFinally'</tt> is like <tt>manyFinally</tt>, except when the
--   terminator parser overlaps with the element parser. In <tt>manyFinally
--   e t</tt>, the parser <tt>t</tt> is tried only when parser <tt>e</tt>
--   fails, whereas in <tt>manyFinally' e t</tt>, the parser <tt>t</tt> is
--   always tried first, then parser <tt>e</tt> only if the terminator is
--   not found. For instance, <tt>manyFinally (accept <a>01</a>) (accept
--   <a>0</a>)</tt> on input <tt><a>0101010</a></tt> returns
--   <tt>[<a>01</a>,<a>01</a>,<a>01</a>]</tt>, whereas
--   <tt>manyFinally'</tt> with the same arguments and input returns
--   <tt>[]</tt>.
manyFinally' :: PolyParse p => p a -> p z -> p [a]

module Text.ParserCombinators.Poly.ByteStringChar

-- | This <tt>Parser</tt> datatype is a specialised parsing monad with
--   error reporting. Whereas the standard version can be used for
--   arbitrary token types, this version is specialised to ByteString input
--   only.
newtype Parser a
P :: (ByteString -> Result ByteString a) -> Parser a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser a -> ByteString -> (Either String a, ByteString)

-- | Simply return the next token in the input tokenstream.
next :: Parser Char

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (Char -> Bool) -> Parser Char

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser a -> Parser a -> Parser a

-- | <tt>manySatisfy p</tt> is a more efficient fused version of <tt>many
--   (satisfy p)</tt>
manySatisfy :: (Char -> Bool) -> Parser ByteString

-- | <tt>many1Satisfy p</tt> is a more efficient fused version of <tt>many1
--   (satisfy p)</tt>
many1Satisfy :: (Char -> Bool) -> Parser ByteString

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: ByteString -> Parser ()
instance PolyParse Parser
instance Alternative Parser
instance Applicative Parser
instance Commitment Parser
instance Monad Parser
instance Functor Parser

module Text.Parse.ByteString

-- | A synonym for a ByteString Parser, i.e. bytestring input (no state)
type TextParser a = Parser a

-- | The class <tt>Parse</tt> is a replacement for <tt>Read</tt>, operating
--   over String input. Essentially, it permits better error messages for
--   why something failed to parse. It is rather important that
--   <tt>parse</tt> can read back exactly what is generated by the
--   corresponding instance of <tt>show</tt>. To apply a parser to some
--   text, use <tt>runParser</tt>.
class Parse a where parse = parsePrec 0 parsePrec _ = optionalParens parse parseList = do { isWord "[]"; return [] } `onFail` do { isWord "["; isWord "]"; return [] } `onFail` bracketSep (isWord "[") (isWord ",") (isWord "]") (optionalParens parse) `adjustErr` ("Expected a list, but" ++)
parse :: Parse a => TextParser a
parsePrec :: Parse a => Int -> TextParser a
parseList :: Parse a => TextParser [a]

-- | If there already exists a Read instance for a type, then we can make a
--   Parser for it, but with only poor error-reporting. The string argument
--   is the expected type or value (for error-reporting only). Use of this
--   wrapper function is NOT recommended with ByteString, because there is
--   a lot of inefficiency in repeated conversions to/from String.
parseByRead :: Read a => String -> TextParser a

-- | If you have a TextParser for a type, you can easily make it into a
--   Read instance, by throwing away any error messages. Use of this
--   wrapper function is NOT recommended with ByteString, because there is
--   a lot of inefficiency in conversions to/from String.
readByParse :: TextParser a -> ReadS a

-- | If you have a TextParser for a type, you can easily make it into a
--   Read instance, by throwing away any error messages. Use of this
--   wrapper function is NOT recommended with ByteString, because there is
--   a lot of inefficiency in conversions to/from String.
readsPrecByParsePrec :: (Int -> TextParser a) -> Int -> ReadS a

-- | One lexical chunk (Haskell-style lexing).
word :: TextParser String

-- | Ensure that the next input word is the given string. (Note the input
--   is lexed as haskell, so wordbreaks at spaces, symbols, etc.)
isWord :: String -> TextParser String

-- | Allow optional nested string parens around an item.
optionalParens :: TextParser a -> TextParser a

-- | Allow nested parens around an item (one set required when Bool is
--   True).
parens :: Bool -> TextParser a -> TextParser a

-- | Deal with named field syntax. The string argument is the field name,
--   and the parser returns the value of the field.
field :: Parse a => String -> TextParser a

-- | Parse one of a bunch of alternative constructors. In the list
--   argument, the first element of the pair is the constructor name, and
--   the second is the parser for the rest of the value. The first matching
--   parse is returned.
constructors :: [(String, TextParser a)] -> TextParser a

-- | Parse one of the given nullary constructors (an enumeration). The
--   string argument is the name of the type, and the list argument should
--   contain all of the possible enumeration values.
enumeration :: Show a => String -> [a] -> TextParser a

-- | For any numeric parser, permit a negation sign in front of it.
parseSigned :: Real a => TextParser a -> TextParser a

-- | Parse any (unsigned) Integral numeric literal. Needs a base, radix,
--   isDigit predicate, and digitToInt converter, appropriate to the result
--   type.
parseInt :: Integral a => String -> a -> (Char -> Bool) -> (Char -> Int) -> TextParser a

-- | Parse a decimal, octal, or hexadecimal (unsigned) Integral numeric
--   literal.
parseDec :: Integral a => TextParser a

-- | Parse a decimal, octal, or hexadecimal (unsigned) Integral numeric
--   literal.
parseOct :: Integral a => TextParser a

-- | Parse a decimal, octal, or hexadecimal (unsigned) Integral numeric
--   literal.
parseHex :: Integral a => TextParser a

-- | parseUnsignedInteger uses the underlying ByteString readInteger, so
--   will be a lot faster than the generic character-by-character parseInt.
parseUnsignedInteger :: TextParser Integer

-- | Parse any (unsigned) Floating numeric literal, e.g. Float or Double.
parseFloat :: RealFrac a => TextParser a

-- | Parse a Haskell character literal.
parseLitChar :: TextParser Char

-- | Simply return the remaining input ByteString.
allAsByteString :: TextParser ByteString

-- | Simply return the remaining input as a String.
allAsString :: TextParser String
instance Parse a => Parse [a]
instance (Parse a, Parse b) => Parse (Either a b)
instance Parse a => Parse (Maybe a)
instance (Parse a, Parse b, Parse c) => Parse (a, b, c)
instance (Parse a, Parse b) => Parse (a, b)
instance Parse ()
instance Parse Ordering
instance Parse Bool
instance Parse Char
instance Parse Double
instance Parse Float
instance Parse Integer
instance Parse Int

module Text.ParserCombinators.Poly.Text

-- | This <tt>Parser</tt> datatype is a specialised parsing monad with
--   error reporting. Whereas the standard version can be used for
--   arbitrary token types, this version is specialised to Text input only.
newtype Parser a
P :: (Text -> Result Text a) -> Parser a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser a -> Text -> (Either String a, Text)

-- | Simply return the next token in the input tokenstream.
next :: Parser Char

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (Char -> Bool) -> Parser Char

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser a -> Parser a -> Parser a

-- | <tt>manySatisfy p</tt> is a more efficient fused version of <tt>many
--   (satisfy p)</tt>
manySatisfy :: (Char -> Bool) -> Parser Text

-- | <tt>many1Satisfy p</tt> is a more efficient fused version of <tt>many1
--   (satisfy p)</tt>
many1Satisfy :: (Char -> Bool) -> Parser Text

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: Text -> Parser ()
instance PolyParse Parser
instance Alternative Parser
instance Applicative Parser
instance Commitment Parser
instance Monad Parser
instance Functor Parser

module Text.ParserCombinators.Poly.StateText

-- | This <tt>Parser</tt> datatype is a specialised parsing monad with
--   error reporting. Whereas the standard version can be used for
--   arbitrary token types, this version is specialised to Text input only.
newtype Parser s a
P :: (s -> Text -> Result (Text, s) a) -> Parser s a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser s a -> s -> Text -> (Either String a, s, Text)

-- | Simply return the next token in the input tokenstream.
next :: Parser s Char

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser s ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (Char -> Bool) -> Parser s Char

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser s a -> Parser s a -> Parser s a

-- | <tt>manySatisfy p</tt> is a more efficient fused version of <tt>many
--   (satisfy p)</tt>
manySatisfy :: (Char -> Bool) -> Parser s Text

-- | <tt>many1Satisfy p</tt> is a more efficient fused version of <tt>many1
--   (satisfy p)</tt>
many1Satisfy :: (Char -> Bool) -> Parser s Text

-- | Update the internal state.
stUpdate :: (s -> s) -> Parser s ()

-- | Query the internal state.
stQuery :: (s -> a) -> Parser s a

-- | Deliver the entire internal state.
stGet :: Parser s s

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: Text -> Parser s ()
instance PolyParse (Parser s)
instance Alternative (Parser s)
instance Applicative (Parser s)
instance Commitment (Parser s)
instance Monad (Parser s)
instance Functor (Parser s)


-- | This module contains the definitions for a generic parser, without
--   running state. These are the parts that are shared between the Plain
--   and Lazy variations. Do not import this module directly, but only via
--   T.P.Poly.Plain or T.P.Poly.Lazy.
module Text.ParserCombinators.Poly.Parser

-- | This <tt>Parser</tt> datatype is a fairly generic parsing monad with
--   error reporting. It can be used for arbitrary token types, not just
--   String input. (If you require a running state, use module Poly.State
--   instead)
newtype Parser t a
P :: ([t] -> Result [t] a) -> Parser t a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Simply return the next token in the input tokenstream.
next :: Parser t t

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser t ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (t -> Bool) -> Parser t t

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser t a -> Parser t a -> Parser t a

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: [t] -> Parser t ()
instance Commitment (Parser t)
instance Monad (Parser t)
instance Functor (Parser t)

module Text.ParserCombinators.Poly.Plain

-- | This <tt>Parser</tt> datatype is a fairly generic parsing monad with
--   error reporting. It can be used for arbitrary token types, not just
--   String input. (If you require a running state, use module Poly.State
--   instead)
newtype Parser t a
P :: ([t] -> Result [t] a) -> Parser t a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser t a -> [t] -> (Either String a, [t])

-- | Simply return the next token in the input tokenstream.
next :: Parser t t

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser t ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (t -> Bool) -> Parser t t

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser t a -> Parser t a -> Parser t a

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: [t] -> Parser t ()
instance PolyParse (Parser t)
instance Alternative (Parser t)
instance Applicative (Parser t)

module Text.ParserCombinators.Poly.Lazy

-- | The only differences between a Plain and a Lazy parser are the
--   instance of Applicative, and the type (and implementation) of
--   runParser. We therefore need to <i>newtype</i> the original Parser
--   type, to allow it to have a different instance.
newtype Parser t a
P :: (Parser t a) -> Parser t a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser t a -> [t] -> (a, [t])

-- | Simply return the next token in the input tokenstream.
next :: Parser t t

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser t ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (t -> Bool) -> Parser t t

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser t a -> Parser t a -> Parser t a

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: [t] -> Parser t ()
instance Functor (Parser t)
instance Monad (Parser t)
instance Commitment (Parser t)
instance PolyParse (Parser t)
instance Alternative (Parser t)
instance Applicative (Parser t)


-- | This module contains the definitions for a generic parser, with
--   running state. These are the parts that are shared between the State
--   and StateLazy variations. Do not import this module directly, but only
--   via T.P.Poly.State or T.P.Poly.StateLazy.
module Text.ParserCombinators.Poly.StateParser

-- | This <tt>Parser</tt> datatype is a fairly generic parsing monad with
--   error reporting, and running state. It can be used for arbitrary token
--   types, not just String input. (If you do not require a running state,
--   use module Poly.Plain instead)
newtype Parser s t a
P :: (s -> [t] -> Result ([t], s) a) -> Parser s t a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Simply return the next token in the input tokenstream.
next :: Parser s t t

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser s t ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (t -> Bool) -> Parser s t t

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser s t a -> Parser s t a -> Parser s t a

-- | Update the internal state.
stUpdate :: (s -> s) -> Parser s t ()

-- | Query the internal state.
stQuery :: (s -> a) -> Parser s t a

-- | Deliver the entire internal state.
stGet :: Parser s t s

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: [t] -> Parser s t ()
instance Commitment (Parser s t)
instance Monad (Parser s t)
instance Functor (Parser s t)

module Text.ParserCombinators.Poly.State

-- | This <tt>Parser</tt> datatype is a fairly generic parsing monad with
--   error reporting, and running state. It can be used for arbitrary token
--   types, not just String input. (If you do not require a running state,
--   use module Poly.Plain instead)
newtype Parser s t a
P :: (s -> [t] -> Result ([t], s) a) -> Parser s t a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser s t a -> s -> [t] -> (Either String a, s, [t])

-- | Simply return the next token in the input tokenstream.
next :: Parser s t t

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser s t ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (t -> Bool) -> Parser s t t

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser s t a -> Parser s t a -> Parser s t a

-- | Update the internal state.
stUpdate :: (s -> s) -> Parser s t ()

-- | Query the internal state.
stQuery :: (s -> a) -> Parser s t a

-- | Deliver the entire internal state.
stGet :: Parser s t s

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: [t] -> Parser s t ()
instance PolyParse (Parser s t)
instance Alternative (Parser s t)
instance Applicative (Parser s t)

module Text.ParserCombinators.Poly.StateLazy

-- | The only differences between a State and a StateLazy parser are the
--   instance of Applicative, and the type (and implementation) of
--   runParser. We therefore need to <i>newtype</i> the original Parser
--   type, to allow it to have a different instance.
newtype Parser s t a
P :: (Parser s t a) -> Parser s t a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser s t a -> s -> [t] -> (a, s, [t])

-- | Simply return the next token in the input tokenstream.
next :: Parser s t t

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser s t ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (t -> Bool) -> Parser s t t

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser s t a -> Parser s t a -> Parser s t a
manyFinally :: Parser s t a -> Parser s t z -> Parser s t [a]

-- | Update the internal state.
stUpdate :: (s -> s) -> Parser s t ()

-- | Query the internal state.
stQuery :: (s -> a) -> Parser s t a

-- | Deliver the entire internal state.
stGet :: Parser s t s

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: [t] -> Parser s t ()
instance Functor (Parser s t)
instance Monad (Parser s t)
instance Commitment (Parser s t)
instance PolyParse (Parser s t)
instance Alternative (Parser s t)
instance Applicative (Parser s t)


-- | In a strict language, where creating the entire input list of tokens
--   in one shot may be infeasible, we can use a lazy <a>callback</a> kind
--   of architecture instead. The lexer returns a single token at a time,
--   together with a continuation.
--   
--   This module defines a Parser type (capable of use with the Poly
--   combinators), specialised to the callback-lexer style of input stream.
module Text.ParserCombinators.Poly.Lex

-- | In a strict language, where creating the entire input list of tokens
--   in one shot may be infeasible, we can use a lazy <a>callback</a> kind
--   of architecture instead. The lexer returns a single token at a time,
--   together with a continuation. The <tt>next</tt> parser is responsible
--   for pulling on the token stream, applying the continuation where
--   necessary.
data LexReturn t
LexReturn :: t -> String -> (String -> LexReturn t) -> LexReturn t
LexFinish :: LexReturn t

-- | This <tt>Parser</tt> datatype is a specialised parsing monad with
--   error reporting. This version is specialised to pre-lexed String
--   input, where the lexer has been written to yield a <tt>LexReturn</tt>.
newtype Parser t a
P :: (LexReturn t -> Result (LexReturn t) a) -> Parser t a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser t a -> LexReturn t -> (Either String a, String)

-- | Simply return the next token in the input tokenstream.
next :: Parser t t

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser t ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (t -> Bool) -> Parser t t

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser t a -> Parser t a -> Parser t a

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: [t] -> Parser t ()
instance PolyParse (Parser t)
instance Alternative (Parser t)
instance Applicative (Parser t)
instance Commitment (Parser t)
instance Monad (Parser t)
instance Functor (Parser t)

module Text.ParserCombinators.Poly.ByteString

-- | This <tt>Parser</tt> datatype is a specialised parsing monad with
--   error reporting. Whereas the standard version can be used for
--   arbitrary token types, this version is specialised to ByteString input
--   only.
newtype Parser a
P :: (ByteString -> Result ByteString a) -> Parser a

-- | A return type like Either, that distinguishes not only between right
--   and wrong answers, but also has commitment, so that a failure cannot
--   be undone. This should only be used for writing very primitive parsers
--   - really it is an internal detail of the library. The z type is the
--   remaining unconsumed input.
data Result z a
Success :: z -> a -> Result z a
Failure :: z -> String -> Result z a
Committed :: (Result z a) -> Result z a

-- | Apply a parser to an input token sequence.
runParser :: Parser a -> ByteString -> (Either String a, ByteString)

-- | Simply return the next token in the input tokenstream.
next :: Parser Word8

-- | Succeed if the end of file/input has been reached, fail otherwise.
eof :: Parser ()

-- | Return the next token if it satisfies the given predicate.
satisfy :: (Word8 -> Bool) -> Parser Word8

-- | <tt>p <a>onFail</a> q</tt> means parse p, unless p fails, in which
--   case parse q instead. Can be chained together to give multiple
--   attempts to parse something. (Note that q could itself be a failing
--   parser, e.g. to change the error message from that defined in p to
--   something different.) However, a severe failure in p cannot be
--   ignored.
onFail :: Parser a -> Parser a -> Parser a

-- | <tt>manySatisfy p</tt> is a more efficient fused version of <tt>many
--   (satisfy p)</tt>
manySatisfy :: (Word8 -> Bool) -> Parser ByteString

-- | <tt>many1Satisfy p</tt> is a more efficient fused version of <tt>many1
--   (satisfy p)</tt>
many1Satisfy :: (Word8 -> Bool) -> Parser ByteString

-- | Push some tokens back onto the front of the input stream and reparse.
--   This is useful e.g. for recursively expanding macros. When the
--   user-parser recognises a macro use, it can lookup the macro expansion
--   from the parse state, lex it, and then stuff the lexed expansion back
--   down into the parser.
reparse :: ByteString -> Parser ()
instance PolyParse Parser
instance Alternative Parser
instance Applicative Parser
instance Commitment Parser
instance Monad Parser
instance Functor Parser

module Text.ParserCombinators.Poly

module Text.Parse

-- | A synonym for Parser Char, i.e. string input (no state)
type TextParser a = Parser Char a

-- | The class <tt>Parse</tt> is a replacement for <tt>Read</tt>, operating
--   over String input. Essentially, it permits better error messages for
--   why something failed to parse. It is rather important that
--   <tt>parse</tt> can read back exactly what is generated by the
--   corresponding instance of <tt>show</tt>. To apply a parser to some
--   text, use <tt>runParser</tt>.
class Parse a where parse = parsePrec 0 parsePrec _ = optionalParens parse parseList = do { isWord "[]"; return [] } `onFail` do { isWord "["; isWord "]"; return [] } `onFail` bracketSep (isWord "[") (isWord ",") (isWord "]") (optionalParens parse) `adjustErr` ("Expected a list, but" ++)
parse :: Parse a => TextParser a
parsePrec :: Parse a => Int -> TextParser a
parseList :: Parse a => TextParser [a]

-- | If there already exists a Read instance for a type, then we can make a
--   Parser for it, but with only poor error-reporting. The string argument
--   is the expected type or value (for error-reporting only).
parseByRead :: Read a => String -> TextParser a

-- | If you have a TextParser for a type, you can easily make it into a
--   Read instance, by throwing away any error messages.
readByParse :: TextParser a -> ReadS a

-- | If you have a TextParser for a type, you can easily make it into a
--   Read instance, by throwing away any error messages.
readsPrecByParsePrec :: (Int -> TextParser a) -> Int -> ReadS a

-- | One lexical chunk. This is Haskell'98-style lexing - the result should
--   match Prelude.lex apart from better error-reporting.
word :: TextParser String

-- | Ensure that the next input word is the given string. (Note the input
--   is lexed as haskell, so wordbreaks at spaces, symbols, etc.)
isWord :: String -> TextParser String

-- | Allow nested parens around an item.
optionalParens :: TextParser a -> TextParser a

-- | Allow nested parens around an item (one set required when Bool is
--   True).
parens :: Bool -> TextParser a -> TextParser a

-- | Deal with named field syntax. The string argument is the field name,
--   and the parser returns the value of the field.
field :: Parse a => String -> TextParser a

-- | Parse one of a bunch of alternative constructors. In the list
--   argument, the first element of the pair is the constructor name, and
--   the second is the parser for the rest of the value. The first matching
--   parse is returned.
constructors :: [(String, TextParser a)] -> TextParser a

-- | Parse one of the given nullary constructors (an enumeration). The
--   string argument is the name of the type, and the list argument should
--   contain all of the possible enumeration values.
enumeration :: Show a => String -> [a] -> TextParser a
parseSigned :: Real a => TextParser a -> TextParser a
parseInt :: Integral a => String -> a -> (Char -> Bool) -> (Char -> Int) -> TextParser a
parseDec :: Integral a => TextParser a
parseOct :: Integral a => TextParser a
parseHex :: Integral a => TextParser a
parseFloat :: RealFrac a => TextParser a
parseLitChar :: TextParser Char

-- | Simply return the entire remaining input String.
allAsString :: TextParser String
instance Parse a => Parse [a]
instance (Parse a, Parse b) => Parse (Either a b)
instance Parse a => Parse (Maybe a)
instance (Parse a, Parse b, Parse c) => Parse (a, b, c)
instance (Parse a, Parse b) => Parse (a, b)
instance Parse ()
instance Parse Ordering
instance Parse Bool
instance Parse Char
instance Parse Double
instance Parse Float
instance Parse Integer
instance Parse Int
