libghc-polyparse-doc 1.7-3build1 / usr / share / doc / libghc-polyparse-doc / html / polyparse.txt

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


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

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