-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Extends binary with parsec/attoparsec style parsing combinators. -- -- Extends binary with parsec/attoparsec style parsing combinators. @package binary-parsers @version 0.2.2.0 -- | Simple, efficient combinator parsing for ByteString strings. module Data.Binary.Parser.Word8 -- | Match any byte, to perform lookahead. Returns Nothing if end of -- input has been reached. Does not consume any input. peekMaybe :: Get (Maybe Word8) -- | Match any byte, to perform lookahead. Does not consume any input, but -- will fail if end of input has been reached. peek :: Get Word8 -- | The parser satisfy p succeeds for any byte for which the -- predicate p returns True. Returns the byte that is -- actually parsed. -- -- 
--   digit = satisfy isDigit
--       where isDigit w = w >= 48 && w <= 57
--
satisfy :: (Word8 -> Bool) -> Get Word8 -- | The parser satisfyWith f p transforms a byte, and succeeds if -- the predicate p returns True on the transformed value. -- The parser returns the transformed byte that was parsed. satisfyWith :: (Word8 -> a) -> (a -> Bool) -> Get a -- | Match a specific byte. word8 :: Word8 -> Get () -- | Match any byte. anyWord8 :: Get Word8 -- | The parser skipWord8 p succeeds for any byte for which the -- predicate p returns True. skipWord8 :: (Word8 -> Bool) -> Get () -- | This is a faster version of skip for small N (smaller than -- chunk size). skipN :: Int -> Get () -- | Consume input as long as the predicate returns False or reach -- the end of input, and return the consumed input. takeTill :: (Word8 -> Bool) -> Get ByteString -- | Consume input as long as the predicate returns True or reach -- the end of input, and return the consumed input. takeWhile :: (Word8 -> Bool) -> Get ByteString -- | Similar to takeWhile, but requires the predicate to succeed on -- at least one byte of input: it will fail if the predicate never -- returns True or reach the end of input takeWhile1 :: (Word8 -> Bool) -> Get ByteString -- | Skip past input for as long as the predicate returns True. skipWhile :: (Word8 -> Bool) -> Get () -- | Skip over white space using isSpace. skipSpaces :: Get () -- | string s parses a sequence of bytes that identically match -- s. string :: ByteString -> Get () -- | A stateful scanner. The predicate consumes and transforms a state -- argument, and each transformed state is passed to successive -- invocations of the predicate on each byte of the input until one -- returns Nothing or the input ends. -- -- This parser does not fail. It will return an empty string if the -- predicate returns Nothing on the first byte of input. scan :: s -> (s -> Word8 -> Maybe s) -> Get ByteString -- | Similar to scan, but working on ByteString chunks, The -- predicate consumes a ByteString chunk and transforms a state -- argument, and each transformed state is passed to successive -- invocations of the predicate on each chunk of the input until one -- chunk got splited to Right (ByteString, ByteString) or the -- input ends. scanChunks :: s -> Consume s -> Get ByteString -- | Fast Word8 predicate for matching ASCII space characters -- -- 
--   isSpace w = w == 32 || w - 9 <= 4
--
isSpace :: Word8 -> Bool -- | Decimal digit predicate. isDigit :: Word8 -> Bool -- | Hex digit predicate. isHexDigit :: Word8 -> Bool -- | A predicate that matches either a space ' ' or horizontal tab -- '\t' character. isHorizontalSpace :: Word8 -> Bool -- | A predicate that matches either a carriage return '\r' or -- newline '\n' character. isEndOfLine :: Word8 -> Bool -- | Match either a single newline byte '\n', or a carriage return -- followed by a newline byte "\r\n". endOfLine :: Get () -- | Simple, efficient combinator parsing for numeric values. module Data.Binary.Parser.Numeric -- | Parse and decode an unsigned hexadecimal number. The hex digits -- 'a' through 'f' may be upper or lower case. -- -- This parser does not accept a leading "0x" string. hexadecimal :: (Integral a, Bits a) => Get a -- | Parse and decode an unsigned decimal number. decimal :: Integral a => Get a -- | Parse a number with an optional leading '+' or '-' -- sign character. signed :: Num a => Get a -> Get a -- | Parse a rational number. -- -- The syntax accepted by this parser is the same as for double. -- -- Note: this parser is not safe for use with inputs from -- untrusted sources. An input with a suitably large exponent such as -- "1e1000000000" will cause a huge Integer to be -- allocated, resulting in what is effectively a denial-of-service -- attack. -- -- In most cases, it is better to use double or scientific -- instead. rational :: Fractional a => Get a -- | Parse a rational number and round to Double. -- -- This parser accepts an optional leading sign character, followed by at -- least one decimal digit. The syntax similar to that accepted by the -- read function, with the exception that a trailing '.' -- or 'e' not followed by a number is not consumed. -- -- Examples with behaviour identical to read: -- -- 
--   parseOnly double "3"     == Right ("",1,3.0)
--   parseOnly double "3.1"   == Right ("",3,3.1)
--   parseOnly double "3e4"   == Right ("",3,30000.0)
--   parseOnly double "3.1e4" == Right ("",5,31000.0)
--
-- -- 
--   parseOnly double ".3"    == Left (".3",0,"takeWhile1")
--   parseOnly double "e3"    == Left ("e3",0,"takeWhile1")
--
-- -- Examples of differences from read: -- -- 
--   parseOnly double "3.foo" == Right (".foo",1,3.0)
--   parseOnly double "3e"    == Right ("e",1,3.0)
--
-- -- This function does not accept string representations of "NaN" or -- "Infinity". double :: Get Double -- | Parse a scientific number. -- -- The syntax accepted by this parser is the same as for double. scientific :: Get Scientific -- | Parse a scientific number and convert to result using a user supply -- function. -- -- The syntax accepted by this parser is the same as for double. scientifically :: (Scientific -> a) -> Get a -- | This module is intended for parsing text that is represented using an -- 8-bit character set, e.g. ASCII or ISO-8859-15. It does not -- make any attempt to deal with character encodings, multibyte -- characters, or wide characters. In particular, all attempts to use -- characters above code point U+00FF will give wrong answers. -- -- Code points below U+0100 are simply translated to and from their -- numeric values, so e.g. the code point U+00A4 becomes the byte -- 0xA4 (which is the Euro symbol in ISO-8859-15, but the -- generic currency sign in ISO-8859-1). Haskell Char values above -- U+00FF are truncated, so e.g. U+1D6B7 is truncated to the byte -- 0xB7. module Data.Binary.Parser.Char8 -- | Match any char, to perform lookahead. Returns Nothing if end of -- input has been reached. Does not consume any input. peekMaybe :: Get (Maybe Char) -- | Match any char, to perform lookahead. Does not consume any input, but -- will fail if end of input has been reached. peek :: Get Char -- | The parser satisfy p succeeds for any char for which the -- predicate p returns True. Returns the char that is -- actually parsed. satisfy :: (Char -> Bool) -> Get Char -- | The parser satisfyWith f p transforms a char, and succeeds if -- the predicate p returns True on the transformed value. -- The parser returns the transformed char that was parsed. satisfyWith :: (Char -> a) -> (a -> Bool) -> Get a -- | Match a specific character. char :: Char -> Get () -- | Match any character. anyChar :: Get Char -- | The parser skipChar p succeeds for any char for which the -- predicate p returns True. skipChar :: (Char -> Bool) -> Get () -- | Consume input as long as the predicate returns False or reach -- the end of input, and return the consumed input. takeTill :: (Char -> Bool) -> Get ByteString -- | Consume input as long as the predicate returns True or reach -- the end of input, and return the consumed input. takeWhile :: (Char -> Bool) -> Get ByteString takeWhile1 :: (Char -> Bool) -> Get ByteString -- | Skip past input for as long as the predicate returns True. skipWhile :: (Char -> Bool) -> Get () -- | Satisfy a literal string but ignoring case. stringCI :: ByteString -> Get ByteString -- | Fast predicate for matching ASCII space characters. -- -- Note: This predicate only gives correct answers for the ASCII -- encoding. For instance, it does not recognise U+00A0 (non-breaking -- space) as a space character, even though it is a valid ISO-8859-15 -- byte. For a Unicode-aware and only slightly slower predicate, use -- isSpace isSpace :: Char -> Bool -- | Decimal digit predicate. isDigit :: Char -> Bool -- | Hex digit predicate. isHexDigit :: Char -> Bool -- | A predicate that matches either a space ' ' or horizontal tab -- '\t' character. isHorizontalSpace :: Char -> Bool -- | A predicate that matches either a carriage return '\r' or -- newline '\n' character. isEndOfLine :: Char -> Bool -- | This library provide parsec/attoparsec style parsing combinators for -- binary package. By default, this module export combinators in -- Data.Binary.Get, Data.Binary.Parser.Word8 and -- Data.Binary.Parser.Numeric, for additional ASCII char parser, -- please check Data.Binary.Parser.Char8 module. -- -- The behaviour of parsers here is different to that of the -- similarly-named parser in Parsec, as this one is all-or-nothing. To -- illustrate the difference, the following parser will fail under Parsec -- given an input of "for": -- -- 
--   string "foo" <|> string "for"
--
-- -- The reason for its failure is that the first branch is a partial -- match, and will consume the letters 'f' and 'o' -- before failing. In binary-parsers, the above parser will -- succeed on that input, because the failed first branch will -- consume nothing. -- -- There're some redundant combinators get removed, for example: -- -- 
--   choice == asum
--   count == replicateM
--   atEnd == isEmpty
--   take == getByteString
--   many1 == some
--
-- -- For fast byte set operations, please use charset package. -- -- It's recommanded to use parseOnly, parseDetail... -- functions to run your parsers since these functions are faster than -- binary's counter part by avoiding a small constant overhead. Check -- parse for detail. -- --

A few words on performance and backtracking

-- -- There's a common belief that parsers which support backtracking are -- slow, but it's not neccessarily true in binary, because binary doesn't -- do book keeping if you doesn't use <|>, lookAhead -- or their friends. Combinators in this library like peek, -- string... also try to avoid backtracking so it's faster to use -- them rather than do backtracking yourself, for example, peek is -- faster than lookAhead getWord8. In practice, -- protocols are often designed to avoid backtracking. For example, if -- you have following parser: -- -- 
--   branch1 <|> branch2 <|> (skipN 1 >> branch3)
--
-- -- And if you can select the right branch just by looking ahead one byte, -- then you can rewrite it to: -- -- 
--   w <- peek
--   if  | w == b1 -> branch1
--       | w == b2 -> branch2
--       | w == b3 -> skipN 1 >> branch3
--
-- -- Binary performs as fast as a non-backtracking parser as long as you -- construct your parser without using backtracking. And sometime -- backtracking is indeed neccessary, for example scientifically -- is almost impossible to implement correctly if you don't do -- backtracking. module Data.Binary.Parser -- | Alias to Get for attoparsec compatibility. type Parser a = Get a -- | Run a parser on ByteString. -- -- This function does not force a parser to consume all of its input. -- Instead, any residual input will be discarded. To force a parser to -- consume all of its input, use something like this: -- -- 
--   parseOnly (myParser <* endOfInput)
--
parseOnly :: Get a -> ByteString -> Either String a -- | Similar to parseOnly, but run a parser on lazy -- ByteString. parseLazy :: Get a -> ByteString -> Either String a -- | Run a parser on ByteString. -- -- This function return full parsing results: the rest of input, stop -- offest and fail message or parsing result. -- -- Since: 0.2.1.0 parseDetail :: Get a -> ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) -- | Similar to parseDetail, but run a parser on lazy -- ByteString. -- -- Since: 0.2.1.0 parseDetailLazy :: Get a -> ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) -- | Run a Get monad. See Decoder for what to do next, like -- providing input, handling decoding errors and to get the output value. -- -- This's faster than runGetIncremental becuase it provides an -- initial chunk rather than feeding empty and waiting for chunks, -- this overhead is noticeable when you're running small getters over -- short ByteString s. -- -- Since: 0.2.1.0 parse :: Get a -> ByteString -> Decoder a -- | Name the parser, in case failure occurs. () :: Get a -> String -> Get a -- | Match only if all input has been consumed. endOfInput :: Get () -- | option x p tries to apply action p. If p -- fails without consuming input, it returns the value x, -- otherwise the value returned by p. -- -- 
--   priority  = option 0 (digitToInt <$> digit)
--
option :: Alternative f => a -> f a -> f a -- | Combine two alternatives. eitherP :: (Alternative f) => f a -> f b -> f (Either a b) -- | Return both the result of a parse and the portion of the input that -- was consumed while it was being parsed. match :: Get a -> Get (ByteString, a) -- | many' p applies the action p zero or more -- times. Returns a list of the returned values of p. The value -- returned by p is forced to WHNF. -- -- 
--   word  = many' letter
--
many' :: (MonadPlus m) => m a -> m [a] -- | some' p applies the action p one or more -- times. Returns a list of the returned values of p. The value -- returned by p is forced to WHNF. -- -- 
--   word  = some' letter
--
some' :: (MonadPlus m) => m a -> m [a] -- | sepBy p sep applies zero or more occurrences of -- p, separated by sep. Returns a list of the values -- returned by p. -- -- 
--   commaSep p  = p `sepBy` (char ',')
--
sepBy :: Alternative f => f a -> f s -> f [a] -- | sepBy' p sep applies zero or more occurrences of -- p, separated by sep. Returns a list of the values -- returned by p. The value returned by p is forced to -- WHNF. -- -- 
--   commaSep p  = p `sepBy'` (char ',')
--
sepBy' :: (MonadPlus m) => m a -> m s -> m [a] -- | sepBy1 p sep applies one or more occurrences of -- p, separated by sep. Returns a list of the values -- returned by p. -- -- 
--   commaSep p  = p `sepBy1` (char ',')
--
sepBy1 :: Alternative f => f a -> f s -> f [a] -- | sepBy1' p sep applies one or more occurrences of -- p, separated by sep. Returns a list of the values -- returned by p. The value returned by p is forced to -- WHNF. -- -- 
--   commaSep p  = p `sepBy1'` (char ',')
--
sepBy1' :: (MonadPlus m) => m a -> m s -> m [a] -- | manyTill p end applies action p zero or more -- times until action end succeeds, and returns the list of -- values returned by p. This can be used to scan comments: -- -- 
--   simpleComment   = string "<!--" *> manyTill anyChar (string "-->")
--
-- -- (Note the overlapping parsers anyChar and string -- "-->". While this will work, it is not very efficient, as it -- will cause a lot of backtracking.) manyTill :: Alternative f => f a -> f b -> f [a] -- | manyTill' p end applies action p zero or more -- times until action end succeeds, and returns the list of -- values returned by p. This can be used to scan comments: -- -- 
--   simpleComment   = string "<!--" *> manyTill' anyChar (string "-->")
--
-- -- (Note the overlapping parsers anyChar and string -- "-->". While this will work, it is not very efficient, as it -- will cause a lot of backtracking.) -- -- The value returned by p is forced to WHNF. manyTill' :: (MonadPlus m) => m a -> m b -> m [a] -- | Skip zero or more instances of an action. skipMany :: Alternative f => f a -> f () -- | Skip one or more instances of an action. skipMany1 :: Alternative f => f a -> f ()