-- 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 Either type, rather than just calling -- error. module Text.ParserCombinators.HuttonMeijerWallace newtype Parser s t e a -- | The parser type is parametrised on the types of the state s, -- the input tokens t, error-type e, and the result -- value a. 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 error to halt the program. (This is the -- original exported behaviour - to allow the caller to deal with the -- error differently, see papply'.) 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 a. many :: Parser s t e a -> Parser s t e [a] -- | Deliver one or more values of a. many1 :: Parser s t e a -> Parser s t e [a] -- | Deliver zero or more values of a separated by b's. sepby :: Parser s t e a -> Parser s t e b -> Parser s t e [a] -- | Deliver one or more values of a separated by b'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 Monadic Parser -- Combinators. Some changes to the library have been made in the -- move from Gofer to Haskell: -- -- 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 Commitment 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 PolyParse 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 next and -- satisfy. 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 -- | x discard y parses both x and y, but discards the -- result of y. Rather like const 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 -- | adjustErrBad is just like adjustErr 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 -- except 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. bracket open (commit close) -- item 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] -- | manyFinally' is like manyFinally, except when the -- terminator parser overlaps with the element parser. In manyFinally -- e t, the parser t is tried only when parser e -- fails, whereas in manyFinally' e t, the parser t is -- always tried first, then parser e only if the terminator is -- not found. For instance, manyFinally (accept 01) (accept -- 0) on input 0101010 returns -- [01,01,01], whereas -- manyFinally' with the same arguments and input returns -- []. manyFinally' :: PolyParse p => p a -> p z -> p [a] module Text.ParserCombinators.Poly.ByteStringChar -- | This Parser 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 -- | p onFail q 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 -- | manySatisfy p is a more efficient fused version of many -- (satisfy p) manySatisfy :: (Char -> Bool) -> Parser ByteString -- | many1Satisfy p is a more efficient fused version of many1 -- (satisfy p) 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 Parse is a replacement for Read, operating -- over String input. Essentially, it permits better error messages for -- why something failed to parse. It is rather important that -- parse can read back exactly what is generated by the -- corresponding instance of show. To apply a parser to some -- text, use runParser. 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 Parser 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 -- | p onFail q 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 -- | manySatisfy p is a more efficient fused version of many -- (satisfy p) manySatisfy :: (Char -> Bool) -> Parser Text -- | many1Satisfy p is a more efficient fused version of many1 -- (satisfy p) 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 Parser 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 -- | p onFail q 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 -- | manySatisfy p is a more efficient fused version of many -- (satisfy p) manySatisfy :: (Char -> Bool) -> Parser s Text -- | many1Satisfy p is a more efficient fused version of many1 -- (satisfy p) 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 Parser 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 -- | p onFail q 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 Parser 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 -- | p onFail q 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 newtype 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 -- | p onFail q 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 Parser 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 -- | p onFail q 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 Parser 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 -- | p onFail q 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 newtype 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 -- | p onFail q 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 callback 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 callback kind -- of architecture instead. The lexer returns a single token at a time, -- together with a continuation. The next 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 Parser 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 LexReturn. 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 -- | p onFail q 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 Parser 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 -- | p onFail q 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 -- | manySatisfy p is a more efficient fused version of many -- (satisfy p) manySatisfy :: (Word8 -> Bool) -> Parser ByteString -- | many1Satisfy p is a more efficient fused version of many1 -- (satisfy p) 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 Parse is a replacement for Read, operating -- over String input. Essentially, it permits better error messages for -- why something failed to parse. It is rather important that -- parse can read back exactly what is generated by the -- corresponding instance of show. To apply a parser to some -- text, use runParser. 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