-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Binary parsing with random access. -- -- Binary parsing with random access. The target file to be parsed is -- loaded into memory at the start (represented as an IOUArray Int -- Word8). Parsing proceeds by moving a cursor around, the array is left -- intact. This allows _jumping_ inside the file and contrasts with other -- parser combinators that progress via consuming input. -- -- * Caveat * - the above of course means that the target file is obliged -- to be small enough to fit into memory. -- -- ** MAJOR CAVEAT ** - kangaroo is somewhat half-baked at the moment - -- the parsing machinery seems good but the combinators and primitive -- parsers need more work. I've only released it on Hackage because I'm -- now using it with Hurdle which was already on Hackage. -- -- Currently kangaroo is twinned with its own library of formatting -- combinators, at some point this is likely to be put into its own -- package -- -- Changelog: -- --
    --
  1. 3.0 Documented the primitive parsers. char renamed -- anyChar to match Parsec's convention. Rationalized exports -- from ParseMonad module.
    2. --
  2. 2.0 Changes to ParseMonad - parsing within a region simplified, -- temporarily added JoinPrint.
    3. --
  3. 1.0 First version.
    4. --
@package kangaroo @version 0.3.0 -- | Printing with join-strings. module Text.PrettyPrint.JoinPrint data Doc empty :: Doc null :: Doc -> Bool -- | length on a Doc is O(1). length :: Doc -> Int (<>) :: Doc -> Doc -> Doc (<+>) :: Doc -> Doc -> Doc (<%>) :: Doc -> Doc -> Doc vcat :: [Doc] -> Doc hcat :: [Doc] -> Doc hsep :: [Doc] -> Doc text :: String -> Doc char :: Char -> Doc int :: Int -> Doc integer :: Integer -> Doc integral :: (Integral a) => a -> Doc sglspace :: Doc dblspace :: Doc comma :: Doc semicolon :: Doc punctuate :: Doc -> [Doc] -> Doc enclose :: Doc -> Doc -> Doc -> Doc squotes :: Doc -> Doc dquotes :: Doc -> Doc parens :: Doc -> Doc brackets :: Doc -> Doc braces :: Doc -> Doc angles :: Doc -> Doc lparen :: Doc rparen :: Doc lbracket :: Doc rbracket :: Doc lbrace :: Doc rbrace :: Doc langle :: Doc rangle :: Doc replicateChar :: Int -> Char -> Doc spacer :: Int -> Doc padl :: Int -> Char -> Doc -> Doc padr :: Int -> Char -> Doc -> Doc truncl :: Int -> Doc -> Doc truncr :: Int -> Doc -> Doc -- | Rendering is simple because there is no notion of fitting. render :: Doc -> String renderIO :: Doc -> IO () -- | hex : i -> Doc -- -- Print i as hexadecimal, no zero padding. -- -- Negative numbers are printed as a string of asterisks. hex :: (Integral a) => a -> Doc hex2 :: Word8 -> Doc hex4 :: Word16 -> Doc hex8 :: Word32 -> Doc -- | oxhex : pad-length * i -> Doc -- -- Print i in hexadecimal, padding with '0' to the supplied -- pad-length and prefixing with "0x". -- -- Negative numbers are printed as a string of asterisks. oxhex :: (Integral a) => Int -> a -> Doc oxhex2 :: Word8 -> Doc oxhex4 :: Word16 -> Doc oxhex8 :: Word32 -> Doc hexdump :: Int -> Int -> [Word8] -> Doc -- | Kangaroo parse monad with env. module Data.ParserCombinators.KangarooReader type Kangaroo e a = GenKangaroo e a parse :: Kangaroo e a -> e -> FilePath -> IO (Either ParseErr a) runKangaroo :: Kangaroo e a -> e -> FilePath -> IO (Either ParseErr a) ask :: Kangaroo e e type ParseErr = String -- | RegionCoda - represents three useful final positions: -- --
    --
  1. dalpunto - 'from the point' - Run the parser within a region and -- return to where you came from.
    2. --
  2. alfermata - 'to the stop' - Run the parser within a region, the -- cursor remains wherever the parse finished.
    3. --
  3. alfine - 'to the end' - Run the parser within a region and jump to -- the right-end of the region after the parse.
    4. --
data RegionCoda Dalpunto :: RegionCoda Alfermata :: RegionCoda Alfine :: RegionCoda type RegionName = String -- | Lift an IO action into the Kangaroo monad. liftIOAction :: IO a -> GenKangaroo ust a -- | Report a parse error. -- -- Source position is appended to the supplied error message reportError :: ParseErr -> GenKangaroo ust a -- | substError : parser * error_msg -> parser -- -- substError is equivalent to Parsec's <?> -- combinator. -- -- Run the supplied parser, if the parse succeeds return the result, -- otherwise override the original error message with the supplied -- error_msg. substError :: GenKangaroo ust a -> ParseErr -> GenKangaroo ust a -- | Parse a single byte. -- -- If the cursor is beyond the end of the current region a parse-error is -- thrown with reportError. word8 :: GenKangaroo ust Word8 -- | satisfy : predicate -> parser -- -- Parse a single byte and apply the predicate to it. On True -- return the parsed byte, on False throw a parse-error with -- reportError. satisfy :: (Word8 -> Bool) -> GenKangaroo ust Word8 -- | checkWord8 : predicate -> opt parser -- -- Byte parser with backtracking when the match fails. -- -- Parse a single byte and apply the predicate to the result. On success -- return (Just answer), on failure move the cursor position -- back one and return Nothing. checkWord8 :: (Word8 -> Bool) -> GenKangaroo ust (Maybe Word8) -- | Backtracking parser similar to Parsec's try. -- -- Try the supplied parser, if the parse succeeds with no parse-errors -- return (Just answer). If a parse-error is generated, discard -- the parse-error, return the cursor to the initial position and return -- Nothing. opt :: GenKangaroo ust a -> GenKangaroo ust (Maybe a) -- | position : -> cursor-position -- -- Return the current cursor position position :: GenKangaroo ust Int -- | region : -> (region-start, cursor-position, -- region-end) -- -- Return the current parse region and the current position of the cursor -- within it. region :: GenKangaroo ust (Int, Int, Int) -- | atEnd - is the cursor at the end of the current region? atEnd :: GenKangaroo ust Bool -- | lengthRemaining : -> distance-to-region-end -- -- Distance from the current cursor position to the end of the current -- region lengthRemaining :: GenKangaroo ust Int -- | regionSize : -> region-length -- -- Size of the current region. regionSize :: GenKangaroo ust Int -- | intraparse : name * coda * abs_region_start * region_length -- * parser -> parser -- -- Create a new region within the current one and run the supplied -- parser. The cursor position is moved to the start of the new region. -- The value of coda determines where the cursor is positioned -- after a successful parse. -- -- intraparse throws a parse error if the supplied -- absolute-region-start is not located within the current region, or if -- the right-boundary of the new region (abs_region_start + -- region_length) extends beyond the right-boundary of the current -- region. intraparse :: RegionName -> RegionCoda -> RegionStart -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advance : name * coda * abs_region_start * parser -> -- parser -- -- A variation of intraparse - the new region starts at the -- supplied abs_region_start and continues to the end of the -- current region. -- -- advance throws a parse error if the new start position is not -- within the current region. advance :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advanceRelative : name * coda * distance * parser -> -- parser -- -- A variation of advance - the start of the new region is -- calculated from the current-cursor-position + the supplied -- distance. -- -- advanceRelative throws a parse error if the new start position -- is not within the current region. advanceRelative :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrict : name * coda * distance * parser -> -- parser -- -- A variation of intraparse - create a new region as a -- restriction of the current one and run the supplied parser. The new -- region starts at the current coursor position, the right-boundary is -- restricted to the current-cursor-position + the supplied -- distance. -- -- restrict throws a parse error if the right-boundary of the new -- region extends beyond the current region. restrict :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrictToPos : region-name * coda * abs-end-pos * parser -- -> parser -- -- A variantion of restrict - the new region takes the current -- cursor position for the left-boundary and the supplied -- absolute-end-position (abs-end-pos) as the right-boundary. -- -- restrictToPos throws a parse error if the abs-end-pos -- extends beyond the right-boundary of the current region. restrictToPos :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a printHexAll :: GenKangaroo ust () printRegionStack :: GenKangaroo ust () manyTill :: GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust [a] genericManyTill :: (a -> c -> c) -> c -> GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust c manyTillPC :: GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust ([a], a) genericManyTillPC :: (a -> b -> b) -> b -> GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust (b, a) count :: Int -> GenKangaroo ust a -> GenKangaroo ust [a] countPrefixed :: (Integral i) => GenKangaroo ust i -> GenKangaroo ust a -> GenKangaroo ust (i, [a]) genericCount :: (a -> b -> b) -> b -> Int -> GenKangaroo ust a -> GenKangaroo ust b runOn :: GenKangaroo ust a -> GenKangaroo ust [a] genericRunOn :: (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b -- | Apply parse then apply the check, if the check fails report the error -- message. postCheck :: GenKangaroo ust a -> (a -> Bool) -> String -> GenKangaroo ust a -- | Build a value by while the test holds. When the test fails the -- position is not backtracked, instead we use the "failing" element with -- lastOp potentially still building the value with it. buildWhile :: (a -> Bool) -> (a -> b -> b) -> (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b buildPrimitive :: Int -> (Word8 -> Bool) -> (Word8 -> b -> b) -> b -> GenKangaroo ust b -- | Attempt to parse the supplied single character (the supplied char must -- be in the ASCII range 0-255). -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. char :: Char -> GenKangaroo ust Char -- | Parse any single character. The parser consumes one byte and uses -- chr to convert it. anyChar :: GenKangaroo ust Char -- | Parse a string of the supplied length n. -- -- If n is less than or equal to zero the empty string is -- returned. text :: Int -> GenKangaroo ust String -- | Parse the supplied string. All characters should be within the range -- 0-255. -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. string :: String -> GenKangaroo ust String -- | Parse a null-terminated C-style string. cstring :: GenKangaroo ust String -- | Parse the literal 0x00. w8Zero :: GenKangaroo ust Word8 -- | Get n bytes. -- -- If n is less than or equal to zero an empty list is returned. getBytes :: (Integral a) => a -> GenKangaroo ust [Word8] -- | Parse a single byte, returning it as an Int8. -- -- The conversion from a byte (0-255) to an Int8 uses the Prelude -- function fromIntegral. -- -- The conversion is summarized as: -- -- 
--   0..127   = 0..127
--   128      = -128
--   129      = -127
--   130      = -126
--   ...
--   254      = -2
--   255      = -1   
--   
--   wtoi :: Word8 -> Int8
--   wtoi i | i < 128   = i
--          | otherwise = -128 + (clearBit i 7)
--
int8 :: GenKangaroo ust Int8 -- | Parse a Word16 in big endian form. word16be :: GenKangaroo ust Word16 -- | Parse a "Word24" in big endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24be :: GenKangaroo ust Word32 -- | Parse a Word32 in big endian form. word32be :: GenKangaroo ust Word32 -- | Parse a Word64 in big endian form. word64be :: GenKangaroo ust Word64 -- | Parse a Word16 in little endian form. word16le :: GenKangaroo ust Word16 -- | Parse a "Word24" in little endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24le :: GenKangaroo ust Word32 -- | Parse a Word32 in little endian form. word32le :: GenKangaroo ust Word32 -- | Parse an Int16 in big endian form. -- -- The ans is parsed as a Word16 (big endian) then converted to an Int16 -- using the Prelude function fromIntegral. int16be :: GenKangaroo ust Int16 -- | Parse an Int32 in big endian form. -- -- The ans is parsed as a Word32 (big endian) then converted to an Int32 -- using the Prelude function fromIntegral. int32be :: GenKangaroo ust Int32 -- | Parse an Int16 in little endian form. -- -- The ans is parsed as a Word16 (little endian) then converted to an -- Int16 using the Prelude function fromIntegral. int16le :: GenKangaroo ust Int16 -- | Parse an Int32 in little endian form. -- -- The ans is parsed as a Word32 (little endian) then converted to an -- Int32 using the Prelude function fromIntegral. int32le :: GenKangaroo ust Int32 -- | Parse an 4-byte IEEE single precision float. -- -- NOTE - THIS FUNCTION IS UNTESTED! ieeeFloatSP :: (Fractional a) => GenKangaroo ust a -- | Kangaroo parse monad with user env, logging and state. module Data.ParserCombinators.KangarooRWS type Kangaroo r w st a = GenKangaroo (r, w, st) a parse :: (Monoid w) => Kangaroo r w st a -> r -> st -> FilePath -> IO (Either ParseErr a) runKangaroo :: (Monoid w) => Kangaroo r w st a -> r -> st -> FilePath -> IO (Either ParseErr a, w, st) evalKangaroo :: (Monoid w) => Kangaroo r w st a -> r -> st -> FilePath -> IO (Either ParseErr a, w) execKangaroo :: (Monoid w) => Kangaroo r w st a -> r -> st -> FilePath -> IO st put :: st -> Kangaroo r w st () get :: Kangaroo r w st st modify :: (st -> st) -> Kangaroo r w st () gets :: (st -> a) -> Kangaroo r w st a tell :: (Monoid w) => w -> Kangaroo r w st () ask :: Kangaroo r w st r type ParseErr = String -- | RegionCoda - represents three useful final positions: -- --
    --
  1. dalpunto - 'from the point' - Run the parser within a region and -- return to where you came from.
    2. --
  2. alfermata - 'to the stop' - Run the parser within a region, the -- cursor remains wherever the parse finished.
    3. --
  3. alfine - 'to the end' - Run the parser within a region and jump to -- the right-end of the region after the parse.
    4. --
data RegionCoda Dalpunto :: RegionCoda Alfermata :: RegionCoda Alfine :: RegionCoda type RegionName = String -- | Lift an IO action into the Kangaroo monad. liftIOAction :: IO a -> GenKangaroo ust a -- | Report a parse error. -- -- Source position is appended to the supplied error message reportError :: ParseErr -> GenKangaroo ust a -- | substError : parser * error_msg -> parser -- -- substError is equivalent to Parsec's <?> -- combinator. -- -- Run the supplied parser, if the parse succeeds return the result, -- otherwise override the original error message with the supplied -- error_msg. substError :: GenKangaroo ust a -> ParseErr -> GenKangaroo ust a -- | Parse a single byte. -- -- If the cursor is beyond the end of the current region a parse-error is -- thrown with reportError. word8 :: GenKangaroo ust Word8 -- | satisfy : predicate -> parser -- -- Parse a single byte and apply the predicate to it. On True -- return the parsed byte, on False throw a parse-error with -- reportError. satisfy :: (Word8 -> Bool) -> GenKangaroo ust Word8 -- | checkWord8 : predicate -> opt parser -- -- Byte parser with backtracking when the match fails. -- -- Parse a single byte and apply the predicate to the result. On success -- return (Just answer), on failure move the cursor position -- back one and return Nothing. checkWord8 :: (Word8 -> Bool) -> GenKangaroo ust (Maybe Word8) -- | Backtracking parser similar to Parsec's try. -- -- Try the supplied parser, if the parse succeeds with no parse-errors -- return (Just answer). If a parse-error is generated, discard -- the parse-error, return the cursor to the initial position and return -- Nothing. opt :: GenKangaroo ust a -> GenKangaroo ust (Maybe a) -- | position : -> cursor-position -- -- Return the current cursor position position :: GenKangaroo ust Int -- | region : -> (region-start, cursor-position, -- region-end) -- -- Return the current parse region and the current position of the cursor -- within it. region :: GenKangaroo ust (Int, Int, Int) -- | atEnd - is the cursor at the end of the current region? atEnd :: GenKangaroo ust Bool -- | lengthRemaining : -> distance-to-region-end -- -- Distance from the current cursor position to the end of the current -- region lengthRemaining :: GenKangaroo ust Int -- | regionSize : -> region-length -- -- Size of the current region. regionSize :: GenKangaroo ust Int -- | intraparse : name * coda * abs_region_start * region_length -- * parser -> parser -- -- Create a new region within the current one and run the supplied -- parser. The cursor position is moved to the start of the new region. -- The value of coda determines where the cursor is positioned -- after a successful parse. -- -- intraparse throws a parse error if the supplied -- absolute-region-start is not located within the current region, or if -- the right-boundary of the new region (abs_region_start + -- region_length) extends beyond the right-boundary of the current -- region. intraparse :: RegionName -> RegionCoda -> RegionStart -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advance : name * coda * abs_region_start * parser -> -- parser -- -- A variation of intraparse - the new region starts at the -- supplied abs_region_start and continues to the end of the -- current region. -- -- advance throws a parse error if the new start position is not -- within the current region. advance :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advanceRelative : name * coda * distance * parser -> -- parser -- -- A variation of advance - the start of the new region is -- calculated from the current-cursor-position + the supplied -- distance. -- -- advanceRelative throws a parse error if the new start position -- is not within the current region. advanceRelative :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrict : name * coda * distance * parser -> -- parser -- -- A variation of intraparse - create a new region as a -- restriction of the current one and run the supplied parser. The new -- region starts at the current coursor position, the right-boundary is -- restricted to the current-cursor-position + the supplied -- distance. -- -- restrict throws a parse error if the right-boundary of the new -- region extends beyond the current region. restrict :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrictToPos : region-name * coda * abs-end-pos * parser -- -> parser -- -- A variantion of restrict - the new region takes the current -- cursor position for the left-boundary and the supplied -- absolute-end-position (abs-end-pos) as the right-boundary. -- -- restrictToPos throws a parse error if the abs-end-pos -- extends beyond the right-boundary of the current region. restrictToPos :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a printHexAll :: GenKangaroo ust () printRegionStack :: GenKangaroo ust () manyTill :: GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust [a] genericManyTill :: (a -> c -> c) -> c -> GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust c manyTillPC :: GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust ([a], a) genericManyTillPC :: (a -> b -> b) -> b -> GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust (b, a) count :: Int -> GenKangaroo ust a -> GenKangaroo ust [a] countPrefixed :: (Integral i) => GenKangaroo ust i -> GenKangaroo ust a -> GenKangaroo ust (i, [a]) genericCount :: (a -> b -> b) -> b -> Int -> GenKangaroo ust a -> GenKangaroo ust b runOn :: GenKangaroo ust a -> GenKangaroo ust [a] genericRunOn :: (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b -- | Apply parse then apply the check, if the check fails report the error -- message. postCheck :: GenKangaroo ust a -> (a -> Bool) -> String -> GenKangaroo ust a -- | Build a value by while the test holds. When the test fails the -- position is not backtracked, instead we use the "failing" element with -- lastOp potentially still building the value with it. buildWhile :: (a -> Bool) -> (a -> b -> b) -> (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b buildPrimitive :: Int -> (Word8 -> Bool) -> (Word8 -> b -> b) -> b -> GenKangaroo ust b -- | Attempt to parse the supplied single character (the supplied char must -- be in the ASCII range 0-255). -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. char :: Char -> GenKangaroo ust Char -- | Parse any single character. The parser consumes one byte and uses -- chr to convert it. anyChar :: GenKangaroo ust Char -- | Parse a string of the supplied length n. -- -- If n is less than or equal to zero the empty string is -- returned. text :: Int -> GenKangaroo ust String -- | Parse the supplied string. All characters should be within the range -- 0-255. -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. string :: String -> GenKangaroo ust String -- | Parse a null-terminated C-style string. cstring :: GenKangaroo ust String -- | Parse the literal 0x00. w8Zero :: GenKangaroo ust Word8 -- | Get n bytes. -- -- If n is less than or equal to zero an empty list is returned. getBytes :: (Integral a) => a -> GenKangaroo ust [Word8] -- | Parse a single byte, returning it as an Int8. -- -- The conversion from a byte (0-255) to an Int8 uses the Prelude -- function fromIntegral. -- -- The conversion is summarized as: -- -- 
--   0..127   = 0..127
--   128      = -128
--   129      = -127
--   130      = -126
--   ...
--   254      = -2
--   255      = -1   
--   
--   wtoi :: Word8 -> Int8
--   wtoi i | i < 128   = i
--          | otherwise = -128 + (clearBit i 7)
--
int8 :: GenKangaroo ust Int8 -- | Parse a Word16 in big endian form. word16be :: GenKangaroo ust Word16 -- | Parse a "Word24" in big endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24be :: GenKangaroo ust Word32 -- | Parse a Word32 in big endian form. word32be :: GenKangaroo ust Word32 -- | Parse a Word64 in big endian form. word64be :: GenKangaroo ust Word64 -- | Parse a Word16 in little endian form. word16le :: GenKangaroo ust Word16 -- | Parse a "Word24" in little endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24le :: GenKangaroo ust Word32 -- | Parse a Word32 in little endian form. word32le :: GenKangaroo ust Word32 -- | Parse an Int16 in big endian form. -- -- The ans is parsed as a Word16 (big endian) then converted to an Int16 -- using the Prelude function fromIntegral. int16be :: GenKangaroo ust Int16 -- | Parse an Int32 in big endian form. -- -- The ans is parsed as a Word32 (big endian) then converted to an Int32 -- using the Prelude function fromIntegral. int32be :: GenKangaroo ust Int32 -- | Parse an Int16 in little endian form. -- -- The ans is parsed as a Word16 (little endian) then converted to an -- Int16 using the Prelude function fromIntegral. int16le :: GenKangaroo ust Int16 -- | Parse an Int32 in little endian form. -- -- The ans is parsed as a Word32 (little endian) then converted to an -- Int32 using the Prelude function fromIntegral. int32le :: GenKangaroo ust Int32 -- | Parse an 4-byte IEEE single precision float. -- -- NOTE - THIS FUNCTION IS UNTESTED! ieeeFloatSP :: (Fractional a) => GenKangaroo ust a -- | Kangaroo parse monad with user state. module Data.ParserCombinators.KangarooState manyTill :: GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust [a] genericManyTill :: (a -> c -> c) -> c -> GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust c manyTillPC :: GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust ([a], a) genericManyTillPC :: (a -> b -> b) -> b -> GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust (b, a) count :: Int -> GenKangaroo ust a -> GenKangaroo ust [a] countPrefixed :: (Integral i) => GenKangaroo ust i -> GenKangaroo ust a -> GenKangaroo ust (i, [a]) genericCount :: (a -> b -> b) -> b -> Int -> GenKangaroo ust a -> GenKangaroo ust b runOn :: GenKangaroo ust a -> GenKangaroo ust [a] genericRunOn :: (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b -- | Apply parse then apply the check, if the check fails report the error -- message. postCheck :: GenKangaroo ust a -> (a -> Bool) -> String -> GenKangaroo ust a -- | Build a value by while the test holds. When the test fails the -- position is not backtracked, instead we use the "failing" element with -- lastOp potentially still building the value with it. buildWhile :: (a -> Bool) -> (a -> b -> b) -> (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b buildPrimitive :: Int -> (Word8 -> Bool) -> (Word8 -> b -> b) -> b -> GenKangaroo ust b -- | Kangaroo is not a transformer as IO is always at the 'bottom' of the -- effect stack. Like the original Parsec it is parametric on user state -- (refered to as ust). data GenKangaroo ust a type ParseErr = String -- | RegionCoda - represents three useful final positions: -- --
    --
  1. dalpunto - 'from the point' - Run the parser within a region and -- return to where you came from.
    2. --
  2. alfermata - 'to the stop' - Run the parser within a region, the -- cursor remains wherever the parse finished.
    3. --
  3. alfine - 'to the end' - Run the parser within a region and jump to -- the right-end of the region after the parse.
    4. --
data RegionCoda Dalpunto :: RegionCoda Alfermata :: RegionCoda Alfine :: RegionCoda type RegionName = String -- | Primitive monadic run function - other modules should export type -- specific specializations of this function... runGenKangaroo :: GenKangaroo ust a -> ust -> FilePath -> IO (Either ParseErr a, ust) -- | Lift an IO action into the Kangaroo monad. liftIOAction :: IO a -> GenKangaroo ust a throwErr :: ParseErr -> GenKangaroo ust a getUserSt :: GenKangaroo ust ust putUserSt :: ust -> GenKangaroo ust () modifyUserSt :: (ust -> ust) -> GenKangaroo ust () -- | Report a parse error. -- -- Source position is appended to the supplied error message reportError :: ParseErr -> GenKangaroo ust a -- | substError : parser * error_msg -> parser -- -- substError is equivalent to Parsec's <?> -- combinator. -- -- Run the supplied parser, if the parse succeeds return the result, -- otherwise override the original error message with the supplied -- error_msg. substError :: GenKangaroo ust a -> ParseErr -> GenKangaroo ust a -- | Parse a single byte. -- -- If the cursor is beyond the end of the current region a parse-error is -- thrown with reportError. word8 :: GenKangaroo ust Word8 -- | satisfy : predicate -> parser -- -- Parse a single byte and apply the predicate to it. On True -- return the parsed byte, on False throw a parse-error with -- reportError. satisfy :: (Word8 -> Bool) -> GenKangaroo ust Word8 -- | checkWord8 : predicate -> opt parser -- -- Byte parser with backtracking when the match fails. -- -- Parse a single byte and apply the predicate to the result. On success -- return (Just answer), on failure move the cursor position -- back one and return Nothing. checkWord8 :: (Word8 -> Bool) -> GenKangaroo ust (Maybe Word8) -- | Backtracking parser similar to Parsec's try. -- -- Try the supplied parser, if the parse succeeds with no parse-errors -- return (Just answer). If a parse-error is generated, discard -- the parse-error, return the cursor to the initial position and return -- Nothing. opt :: GenKangaroo ust a -> GenKangaroo ust (Maybe a) -- | position : -> cursor-position -- -- Return the current cursor position position :: GenKangaroo ust Int -- | region : -> (region-start, cursor-position, -- region-end) -- -- Return the current parse region and the current position of the cursor -- within it. region :: GenKangaroo ust (Int, Int, Int) -- | atEnd - is the cursor at the end of the current region? atEnd :: GenKangaroo ust Bool -- | lengthRemaining : -> distance-to-region-end -- -- Distance from the current cursor position to the end of the current -- region lengthRemaining :: GenKangaroo ust Int -- | regionSize : -> region-length -- -- Size of the current region. regionSize :: GenKangaroo ust Int -- | intraparse : name * coda * abs_region_start * region_length -- * parser -> parser -- -- Create a new region within the current one and run the supplied -- parser. The cursor position is moved to the start of the new region. -- The value of coda determines where the cursor is positioned -- after a successful parse. -- -- intraparse throws a parse error if the supplied -- absolute-region-start is not located within the current region, or if -- the right-boundary of the new region (abs_region_start + -- region_length) extends beyond the right-boundary of the current -- region. intraparse :: RegionName -> RegionCoda -> RegionStart -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advance : name * coda * abs_region_start * parser -> -- parser -- -- A variation of intraparse - the new region starts at the -- supplied abs_region_start and continues to the end of the -- current region. -- -- advance throws a parse error if the new start position is not -- within the current region. advance :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advanceRelative : name * coda * distance * parser -> -- parser -- -- A variation of advance - the start of the new region is -- calculated from the current-cursor-position + the supplied -- distance. -- -- advanceRelative throws a parse error if the new start position -- is not within the current region. advanceRelative :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrict : name * coda * distance * parser -> -- parser -- -- A variation of intraparse - create a new region as a -- restriction of the current one and run the supplied parser. The new -- region starts at the current coursor position, the right-boundary is -- restricted to the current-cursor-position + the supplied -- distance. -- -- restrict throws a parse error if the right-boundary of the new -- region extends beyond the current region. restrict :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrictToPos : region-name * coda * abs-end-pos * parser -- -> parser -- -- A variantion of restrict - the new region takes the current -- cursor position for the left-boundary and the supplied -- absolute-end-position (abs-end-pos) as the right-boundary. -- -- restrictToPos throws a parse error if the abs-end-pos -- extends beyond the right-boundary of the current region. restrictToPos :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a printHexAll :: GenKangaroo ust () printRegionStack :: GenKangaroo ust () -- | Attempt to parse the supplied single character (the supplied char must -- be in the ASCII range 0-255). -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. char :: Char -> GenKangaroo ust Char -- | Parse any single character. The parser consumes one byte and uses -- chr to convert it. anyChar :: GenKangaroo ust Char -- | Parse a string of the supplied length n. -- -- If n is less than or equal to zero the empty string is -- returned. text :: Int -> GenKangaroo ust String -- | Parse the supplied string. All characters should be within the range -- 0-255. -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. string :: String -> GenKangaroo ust String -- | Parse a null-terminated C-style string. cstring :: GenKangaroo ust String -- | Parse the literal 0x00. w8Zero :: GenKangaroo ust Word8 -- | Get n bytes. -- -- If n is less than or equal to zero an empty list is returned. getBytes :: (Integral a) => a -> GenKangaroo ust [Word8] -- | Parse a single byte, returning it as an Int8. -- -- The conversion from a byte (0-255) to an Int8 uses the Prelude -- function fromIntegral. -- -- The conversion is summarized as: -- -- 
--   0..127   = 0..127
--   128      = -128
--   129      = -127
--   130      = -126
--   ...
--   254      = -2
--   255      = -1   
--   
--   wtoi :: Word8 -> Int8
--   wtoi i | i < 128   = i
--          | otherwise = -128 + (clearBit i 7)
--
int8 :: GenKangaroo ust Int8 -- | Parse a Word16 in big endian form. word16be :: GenKangaroo ust Word16 -- | Parse a "Word24" in big endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24be :: GenKangaroo ust Word32 -- | Parse a Word32 in big endian form. word32be :: GenKangaroo ust Word32 -- | Parse a Word64 in big endian form. word64be :: GenKangaroo ust Word64 -- | Parse a Word16 in little endian form. word16le :: GenKangaroo ust Word16 -- | Parse a "Word24" in little endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24le :: GenKangaroo ust Word32 -- | Parse a Word32 in little endian form. word32le :: GenKangaroo ust Word32 -- | Parse an Int16 in big endian form. -- -- The ans is parsed as a Word16 (big endian) then converted to an Int16 -- using the Prelude function fromIntegral. int16be :: GenKangaroo ust Int16 -- | Parse an Int32 in big endian form. -- -- The ans is parsed as a Word32 (big endian) then converted to an Int32 -- using the Prelude function fromIntegral. int32be :: GenKangaroo ust Int32 -- | Parse an Int16 in little endian form. -- -- The ans is parsed as a Word16 (little endian) then converted to an -- Int16 using the Prelude function fromIntegral. int16le :: GenKangaroo ust Int16 -- | Parse an Int32 in little endian form. -- -- The ans is parsed as a Word32 (little endian) then converted to an -- Int32 using the Prelude function fromIntegral. int32le :: GenKangaroo ust Int32 -- | Parse an 4-byte IEEE single precision float. -- -- NOTE - THIS FUNCTION IS UNTESTED! ieeeFloatSP :: (Fractional a) => GenKangaroo ust a type Kangaroo st a = GenKangaroo st a parse :: Kangaroo st a -> st -> FilePath -> IO (Either ParseErr a) runKangaroo :: Kangaroo st a -> st -> FilePath -> IO (Either ParseErr a, st) evalKangaroo :: Kangaroo st a -> st -> FilePath -> IO (Either ParseErr a) execKangaroo :: Kangaroo st a -> st -> FilePath -> IO st put :: st -> Kangaroo st () get :: Kangaroo st st modify :: (st -> st) -> Kangaroo st () gets :: (st -> a) -> Kangaroo st a -- | Kangaroo parse monad with logging. module Data.ParserCombinators.KangarooWriter type Kangaroo r a = GenKangaroo r a parse :: (Monoid w) => Kangaroo w a -> FilePath -> IO (Either ParseErr a, w) runKangaroo :: (Monoid w) => Kangaroo w a -> FilePath -> IO (Either ParseErr a, w) tell :: (Monoid w) => w -> Kangaroo w () type ParseErr = String -- | RegionCoda - represents three useful final positions: -- --
    --
  1. dalpunto - 'from the point' - Run the parser within a region and -- return to where you came from.
    2. --
  2. alfermata - 'to the stop' - Run the parser within a region, the -- cursor remains wherever the parse finished.
    3. --
  3. alfine - 'to the end' - Run the parser within a region and jump to -- the right-end of the region after the parse.
    4. --
data RegionCoda Dalpunto :: RegionCoda Alfermata :: RegionCoda Alfine :: RegionCoda type RegionName = String -- | Lift an IO action into the Kangaroo monad. liftIOAction :: IO a -> GenKangaroo ust a -- | Report a parse error. -- -- Source position is appended to the supplied error message reportError :: ParseErr -> GenKangaroo ust a -- | substError : parser * error_msg -> parser -- -- substError is equivalent to Parsec's <?> -- combinator. -- -- Run the supplied parser, if the parse succeeds return the result, -- otherwise override the original error message with the supplied -- error_msg. substError :: GenKangaroo ust a -> ParseErr -> GenKangaroo ust a -- | Parse a single byte. -- -- If the cursor is beyond the end of the current region a parse-error is -- thrown with reportError. word8 :: GenKangaroo ust Word8 -- | satisfy : predicate -> parser -- -- Parse a single byte and apply the predicate to it. On True -- return the parsed byte, on False throw a parse-error with -- reportError. satisfy :: (Word8 -> Bool) -> GenKangaroo ust Word8 -- | checkWord8 : predicate -> opt parser -- -- Byte parser with backtracking when the match fails. -- -- Parse a single byte and apply the predicate to the result. On success -- return (Just answer), on failure move the cursor position -- back one and return Nothing. checkWord8 :: (Word8 -> Bool) -> GenKangaroo ust (Maybe Word8) -- | Backtracking parser similar to Parsec's try. -- -- Try the supplied parser, if the parse succeeds with no parse-errors -- return (Just answer). If a parse-error is generated, discard -- the parse-error, return the cursor to the initial position and return -- Nothing. opt :: GenKangaroo ust a -> GenKangaroo ust (Maybe a) -- | position : -> cursor-position -- -- Return the current cursor position position :: GenKangaroo ust Int -- | region : -> (region-start, cursor-position, -- region-end) -- -- Return the current parse region and the current position of the cursor -- within it. region :: GenKangaroo ust (Int, Int, Int) -- | atEnd - is the cursor at the end of the current region? atEnd :: GenKangaroo ust Bool -- | lengthRemaining : -> distance-to-region-end -- -- Distance from the current cursor position to the end of the current -- region lengthRemaining :: GenKangaroo ust Int -- | regionSize : -> region-length -- -- Size of the current region. regionSize :: GenKangaroo ust Int -- | intraparse : name * coda * abs_region_start * region_length -- * parser -> parser -- -- Create a new region within the current one and run the supplied -- parser. The cursor position is moved to the start of the new region. -- The value of coda determines where the cursor is positioned -- after a successful parse. -- -- intraparse throws a parse error if the supplied -- absolute-region-start is not located within the current region, or if -- the right-boundary of the new region (abs_region_start + -- region_length) extends beyond the right-boundary of the current -- region. intraparse :: RegionName -> RegionCoda -> RegionStart -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advance : name * coda * abs_region_start * parser -> -- parser -- -- A variation of intraparse - the new region starts at the -- supplied abs_region_start and continues to the end of the -- current region. -- -- advance throws a parse error if the new start position is not -- within the current region. advance :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advanceRelative : name * coda * distance * parser -> -- parser -- -- A variation of advance - the start of the new region is -- calculated from the current-cursor-position + the supplied -- distance. -- -- advanceRelative throws a parse error if the new start position -- is not within the current region. advanceRelative :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrict : name * coda * distance * parser -> -- parser -- -- A variation of intraparse - create a new region as a -- restriction of the current one and run the supplied parser. The new -- region starts at the current coursor position, the right-boundary is -- restricted to the current-cursor-position + the supplied -- distance. -- -- restrict throws a parse error if the right-boundary of the new -- region extends beyond the current region. restrict :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrictToPos : region-name * coda * abs-end-pos * parser -- -> parser -- -- A variantion of restrict - the new region takes the current -- cursor position for the left-boundary and the supplied -- absolute-end-position (abs-end-pos) as the right-boundary. -- -- restrictToPos throws a parse error if the abs-end-pos -- extends beyond the right-boundary of the current region. restrictToPos :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a printHexAll :: GenKangaroo ust () printRegionStack :: GenKangaroo ust () manyTill :: GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust [a] genericManyTill :: (a -> c -> c) -> c -> GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust c manyTillPC :: GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust ([a], a) genericManyTillPC :: (a -> b -> b) -> b -> GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust (b, a) count :: Int -> GenKangaroo ust a -> GenKangaroo ust [a] countPrefixed :: (Integral i) => GenKangaroo ust i -> GenKangaroo ust a -> GenKangaroo ust (i, [a]) genericCount :: (a -> b -> b) -> b -> Int -> GenKangaroo ust a -> GenKangaroo ust b runOn :: GenKangaroo ust a -> GenKangaroo ust [a] genericRunOn :: (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b -- | Apply parse then apply the check, if the check fails report the error -- message. postCheck :: GenKangaroo ust a -> (a -> Bool) -> String -> GenKangaroo ust a -- | Build a value by while the test holds. When the test fails the -- position is not backtracked, instead we use the "failing" element with -- lastOp potentially still building the value with it. buildWhile :: (a -> Bool) -> (a -> b -> b) -> (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b buildPrimitive :: Int -> (Word8 -> Bool) -> (Word8 -> b -> b) -> b -> GenKangaroo ust b -- | Attempt to parse the supplied single character (the supplied char must -- be in the ASCII range 0-255). -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. char :: Char -> GenKangaroo ust Char -- | Parse any single character. The parser consumes one byte and uses -- chr to convert it. anyChar :: GenKangaroo ust Char -- | Parse a string of the supplied length n. -- -- If n is less than or equal to zero the empty string is -- returned. text :: Int -> GenKangaroo ust String -- | Parse the supplied string. All characters should be within the range -- 0-255. -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. string :: String -> GenKangaroo ust String -- | Parse a null-terminated C-style string. cstring :: GenKangaroo ust String -- | Parse the literal 0x00. w8Zero :: GenKangaroo ust Word8 -- | Get n bytes. -- -- If n is less than or equal to zero an empty list is returned. getBytes :: (Integral a) => a -> GenKangaroo ust [Word8] -- | Parse a single byte, returning it as an Int8. -- -- The conversion from a byte (0-255) to an Int8 uses the Prelude -- function fromIntegral. -- -- The conversion is summarized as: -- -- 
--   0..127   = 0..127
--   128      = -128
--   129      = -127
--   130      = -126
--   ...
--   254      = -2
--   255      = -1   
--   
--   wtoi :: Word8 -> Int8
--   wtoi i | i < 128   = i
--          | otherwise = -128 + (clearBit i 7)
--
int8 :: GenKangaroo ust Int8 -- | Parse a Word16 in big endian form. word16be :: GenKangaroo ust Word16 -- | Parse a "Word24" in big endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24be :: GenKangaroo ust Word32 -- | Parse a Word32 in big endian form. word32be :: GenKangaroo ust Word32 -- | Parse a Word64 in big endian form. word64be :: GenKangaroo ust Word64 -- | Parse a Word16 in little endian form. word16le :: GenKangaroo ust Word16 -- | Parse a "Word24" in little endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24le :: GenKangaroo ust Word32 -- | Parse a Word32 in little endian form. word32le :: GenKangaroo ust Word32 -- | Parse an Int16 in big endian form. -- -- The ans is parsed as a Word16 (big endian) then converted to an Int16 -- using the Prelude function fromIntegral. int16be :: GenKangaroo ust Int16 -- | Parse an Int32 in big endian form. -- -- The ans is parsed as a Word32 (big endian) then converted to an Int32 -- using the Prelude function fromIntegral. int32be :: GenKangaroo ust Int32 -- | Parse an Int16 in little endian form. -- -- The ans is parsed as a Word16 (little endian) then converted to an -- Int16 using the Prelude function fromIntegral. int16le :: GenKangaroo ust Int16 -- | Parse an Int32 in little endian form. -- -- The ans is parsed as a Word32 (little endian) then converted to an -- Int32 using the Prelude function fromIntegral. int32le :: GenKangaroo ust Int32 -- | Parse an 4-byte IEEE single precision float. -- -- NOTE - THIS FUNCTION IS UNTESTED! ieeeFloatSP :: (Fractional a) => GenKangaroo ust a -- | Binary parser combinators with random access module Data.ParserCombinators.Kangaroo type Kangaroo a = GenKangaroo () a runKangaroo :: Kangaroo a -> FilePath -> IO (Either ParseErr a) parse :: Kangaroo a -> FilePath -> IO (Either ParseErr a) type ParseErr = String -- | RegionCoda - represents three useful final positions: -- --
    --
  1. dalpunto - 'from the point' - Run the parser within a region and -- return to where you came from.
    2. --
  2. alfermata - 'to the stop' - Run the parser within a region, the -- cursor remains wherever the parse finished.
    3. --
  3. alfine - 'to the end' - Run the parser within a region and jump to -- the right-end of the region after the parse.
    4. --
data RegionCoda Dalpunto :: RegionCoda Alfermata :: RegionCoda Alfine :: RegionCoda type RegionName = String -- | Lift an IO action into the Kangaroo monad. liftIOAction :: IO a -> GenKangaroo ust a -- | Report a parse error. -- -- Source position is appended to the supplied error message reportError :: ParseErr -> GenKangaroo ust a -- | substError : parser * error_msg -> parser -- -- substError is equivalent to Parsec's <?> -- combinator. -- -- Run the supplied parser, if the parse succeeds return the result, -- otherwise override the original error message with the supplied -- error_msg. substError :: GenKangaroo ust a -> ParseErr -> GenKangaroo ust a -- | Parse a single byte. -- -- If the cursor is beyond the end of the current region a parse-error is -- thrown with reportError. word8 :: GenKangaroo ust Word8 -- | satisfy : predicate -> parser -- -- Parse a single byte and apply the predicate to it. On True -- return the parsed byte, on False throw a parse-error with -- reportError. satisfy :: (Word8 -> Bool) -> GenKangaroo ust Word8 -- | checkWord8 : predicate -> opt parser -- -- Byte parser with backtracking when the match fails. -- -- Parse a single byte and apply the predicate to the result. On success -- return (Just answer), on failure move the cursor position -- back one and return Nothing. checkWord8 :: (Word8 -> Bool) -> GenKangaroo ust (Maybe Word8) -- | Backtracking parser similar to Parsec's try. -- -- Try the supplied parser, if the parse succeeds with no parse-errors -- return (Just answer). If a parse-error is generated, discard -- the parse-error, return the cursor to the initial position and return -- Nothing. opt :: GenKangaroo ust a -> GenKangaroo ust (Maybe a) -- | position : -> cursor-position -- -- Return the current cursor position position :: GenKangaroo ust Int -- | region : -> (region-start, cursor-position, -- region-end) -- -- Return the current parse region and the current position of the cursor -- within it. region :: GenKangaroo ust (Int, Int, Int) -- | atEnd - is the cursor at the end of the current region? atEnd :: GenKangaroo ust Bool -- | lengthRemaining : -> distance-to-region-end -- -- Distance from the current cursor position to the end of the current -- region lengthRemaining :: GenKangaroo ust Int -- | regionSize : -> region-length -- -- Size of the current region. regionSize :: GenKangaroo ust Int -- | intraparse : name * coda * abs_region_start * region_length -- * parser -> parser -- -- Create a new region within the current one and run the supplied -- parser. The cursor position is moved to the start of the new region. -- The value of coda determines where the cursor is positioned -- after a successful parse. -- -- intraparse throws a parse error if the supplied -- absolute-region-start is not located within the current region, or if -- the right-boundary of the new region (abs_region_start + -- region_length) extends beyond the right-boundary of the current -- region. intraparse :: RegionName -> RegionCoda -> RegionStart -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advance : name * coda * abs_region_start * parser -> -- parser -- -- A variation of intraparse - the new region starts at the -- supplied abs_region_start and continues to the end of the -- current region. -- -- advance throws a parse error if the new start position is not -- within the current region. advance :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | advanceRelative : name * coda * distance * parser -> -- parser -- -- A variation of advance - the start of the new region is -- calculated from the current-cursor-position + the supplied -- distance. -- -- advanceRelative throws a parse error if the new start position -- is not within the current region. advanceRelative :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrict : name * coda * distance * parser -> -- parser -- -- A variation of intraparse - create a new region as a -- restriction of the current one and run the supplied parser. The new -- region starts at the current coursor position, the right-boundary is -- restricted to the current-cursor-position + the supplied -- distance. -- -- restrict throws a parse error if the right-boundary of the new -- region extends beyond the current region. restrict :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a -- | restrictToPos : region-name * coda * abs-end-pos * parser -- -> parser -- -- A variantion of restrict - the new region takes the current -- cursor position for the left-boundary and the supplied -- absolute-end-position (abs-end-pos) as the right-boundary. -- -- restrictToPos throws a parse error if the abs-end-pos -- extends beyond the right-boundary of the current region. restrictToPos :: RegionName -> RegionCoda -> Int -> GenKangaroo ust a -> GenKangaroo ust a printHexAll :: GenKangaroo ust () printRegionStack :: GenKangaroo ust () manyTill :: GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust [a] genericManyTill :: (a -> c -> c) -> c -> GenKangaroo ust a -> GenKangaroo ust b -> GenKangaroo ust c manyTillPC :: GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust ([a], a) genericManyTillPC :: (a -> b -> b) -> b -> GenKangaroo ust a -> (a -> Bool) -> GenKangaroo ust (b, a) count :: Int -> GenKangaroo ust a -> GenKangaroo ust [a] countPrefixed :: (Integral i) => GenKangaroo ust i -> GenKangaroo ust a -> GenKangaroo ust (i, [a]) genericCount :: (a -> b -> b) -> b -> Int -> GenKangaroo ust a -> GenKangaroo ust b runOn :: GenKangaroo ust a -> GenKangaroo ust [a] genericRunOn :: (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b -- | Apply parse then apply the check, if the check fails report the error -- message. postCheck :: GenKangaroo ust a -> (a -> Bool) -> String -> GenKangaroo ust a -- | Build a value by while the test holds. When the test fails the -- position is not backtracked, instead we use the "failing" element with -- lastOp potentially still building the value with it. buildWhile :: (a -> Bool) -> (a -> b -> b) -> (a -> b -> b) -> b -> GenKangaroo ust a -> GenKangaroo ust b buildPrimitive :: Int -> (Word8 -> Bool) -> (Word8 -> b -> b) -> b -> GenKangaroo ust b -- | Attempt to parse the supplied single character (the supplied char must -- be in the ASCII range 0-255). -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. char :: Char -> GenKangaroo ust Char -- | Parse any single character. The parser consumes one byte and uses -- chr to convert it. anyChar :: GenKangaroo ust Char -- | Parse a string of the supplied length n. -- -- If n is less than or equal to zero the empty string is -- returned. text :: Int -> GenKangaroo ust String -- | Parse the supplied string. All characters should be within the range -- 0-255. -- -- If the parse succeeds return the char, otherwise a parse-error will be -- thrown with reportError. string :: String -> GenKangaroo ust String -- | Parse a null-terminated C-style string. cstring :: GenKangaroo ust String -- | Parse the literal 0x00. w8Zero :: GenKangaroo ust Word8 -- | Get n bytes. -- -- If n is less than or equal to zero an empty list is returned. getBytes :: (Integral a) => a -> GenKangaroo ust [Word8] -- | Parse a single byte, returning it as an Int8. -- -- The conversion from a byte (0-255) to an Int8 uses the Prelude -- function fromIntegral. -- -- The conversion is summarized as: -- -- 
--   0..127   = 0..127
--   128      = -128
--   129      = -127
--   130      = -126
--   ...
--   254      = -2
--   255      = -1   
--   
--   wtoi :: Word8 -> Int8
--   wtoi i | i < 128   = i
--          | otherwise = -128 + (clearBit i 7)
--
int8 :: GenKangaroo ust Int8 -- | Parse a Word16 in big endian form. word16be :: GenKangaroo ust Word16 -- | Parse a "Word24" in big endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24be :: GenKangaroo ust Word32 -- | Parse a Word32 in big endian form. word32be :: GenKangaroo ust Word32 -- | Parse a Word64 in big endian form. word64be :: GenKangaroo ust Word64 -- | Parse a Word16 in little endian form. word16le :: GenKangaroo ust Word16 -- | Parse a "Word24" in little endian form. -- -- 3 bytes are read - the answer is returned as a Word32. word24le :: GenKangaroo ust Word32 -- | Parse a Word32 in little endian form. word32le :: GenKangaroo ust Word32 -- | Parse an Int16 in big endian form. -- -- The ans is parsed as a Word16 (big endian) then converted to an Int16 -- using the Prelude function fromIntegral. int16be :: GenKangaroo ust Int16 -- | Parse an Int32 in big endian form. -- -- The ans is parsed as a Word32 (big endian) then converted to an Int32 -- using the Prelude function fromIntegral. int32be :: GenKangaroo ust Int32 -- | Parse an Int16 in little endian form. -- -- The ans is parsed as a Word16 (little endian) then converted to an -- Int16 using the Prelude function fromIntegral. int16le :: GenKangaroo ust Int16 -- | Parse an Int32 in little endian form. -- -- The ans is parsed as a Word32 (little endian) then converted to an -- Int32 using the Prelude function fromIntegral. int32le :: GenKangaroo ust Int32 -- | Parse an 4-byte IEEE single precision float. -- -- NOTE - THIS FUNCTION IS UNTESTED! ieeeFloatSP :: (Fractional a) => GenKangaroo ust a