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

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

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

-- | 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 true 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) -> a -> TextParser a
parseDec :: Integral a => a -> TextParser a
parseOct :: Integral a => a -> TextParser a
parseHex :: Integral a => 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


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