-- 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.4.1


-- | 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.Base

-- | The <tt>PolyParse</tt> class is an abstraction over all the current
--   concrete representations of monadic 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.
--   
--   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) => PolyParse p
commit :: PolyParse p => p a -> p a
adjustErr :: PolyParse p => p a -> (String -> String) -> p a
onFail :: PolyParse p => p a -> p a -> p a
oneOf' :: PolyParse p => [(String, p a)] -> p a
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

-- | <a>optional</a> indicates whether the parser succeeded through the
--   Maybe type.
optional :: PolyParse p => p a -> p (Maybe a)

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

-- | 'many p' parses a list of elements with individual parser p. Cannot
--   fail, since an empty list is a valid return value.
many :: PolyParse p => 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.
bracket :: PolyParse p => p bra -> p ket -> p a -> p a

-- | 'manyFinally e t' parses a possibly-empty sequence of e's, terminated
--   by a t. The final t 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]

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 PolyState
--   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.
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])
next :: Parser t t
eof :: Parser t ()
satisfy :: (t -> Bool) -> Parser t t

-- | 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 Monad (Parser t)
instance Functor (Parser t)
instance Functor (Result z)

module Text.ParserCombinators.Poly.Lazy

-- | 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 PolyState
--   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 gradations of wrongness. This should
--   only be used for writing very primitive parsers - really it is an
--   internal detail of the library.
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])
next :: Parser t t
eof :: Parser t ()
satisfy :: (t -> Bool) -> Parser t t

-- | 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 Monad (Parser t)
instance Functor (Parser t)
instance Functor (Result z)

module Text.ParserCombinators.Poly.State

-- | 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 PolyState
--   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 gradations of wrongness. This should
--   only be used for writing very primitive parsers - really it is an
--   internal detail of the library.
data Result z s a
Success :: z -> s -> a -> Result z s a
Failure :: z -> s -> String -> Result z s a
Committed :: (Result z s a) -> Result z s a

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

-- | 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 Monad (Parser s t)
instance Functor (Parser s t)
instance Functor (Result z s)

module Text.ParserCombinators.Poly.StateLazy

-- | 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 PolyState
--   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 gradations of wrongness. This should
--   only be used for writing very primitive parsers - really it is an
--   internal detail of the library.
data Result z s a
Success :: z -> s -> a -> Result z s a
Failure :: z -> s -> String -> Result z s a
Committed :: (Result z s a) -> Result z s a

-- | Apply a parser to an input token sequence.
runParser :: Parser s t a -> s -> [t] -> (a, s, [t])
next :: Parser s t t
eof :: Parser s t ()
satisfy :: (t -> Bool) -> Parser s t t
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 PolyParse (Parser s t)
instance Monad (Parser s t)
instance Functor (Parser s t)
instance Functor (Result z s)

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.
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)
next :: Parser Char
eof :: Parser ()
satisfy :: (Char -> Bool) -> Parser Char

-- | 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 Monad Parser
instance Functor Parser
instance Functor (Result z)

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
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
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

-- | parseUnsignedInteger uses the underlying ByteString readInteger, so
--   will be a lot faster than the generic character-by-character parseInt.
parseUnsignedInteger :: TextParser Integer
parseFloat :: RealFrac a => TextParser a
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

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
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
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