-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Packing and unpacking flat tables. -- -- Packing and unpacking flat tables. @package repa-convert @version 4.2.0.1 -- | Pre-defined data formats. module Data.Repa.Convert.Formats -- | Class of types that can be formatted in some default human readable -- ASCII way. class FormatAscii a where type family FormatAscii' a -- | Get the standard ASCII format for a value. -- -- The element value itself is not demanded. formatAscii :: FormatAscii a => a -> FormatAscii' a -- | Strict product type, written infix. data (:*:) a b :: * -> * -> * (:*:) :: SrictNotUnpackeda -> SrictNotUnpackedb -> (:*:) a b -- | Append fields without separators. data App f App :: f -> App f -- | Separate fields with the given character. -- -- data Sep f Sep :: Char -> f -> Sep f -- | Display fields as a tuple, like (x,y,z). data Tup f Tup :: f -> Tup f -- | Fixed length string. -- -- data FixAsc FixAsc :: Int -> FixAsc -- | Variable length raw string (with no quotes). data VarAsc VarAsc :: VarAsc -- | Variable length string in double quotes, and standard backslash -- encoding of special characters. data VarString VarString :: VarString -- | Human-readable ASCII Integer. data IntAsc IntAsc :: IntAsc -- | Human-readable ASCII integer, with leading zeros. data IntAsc0 IntAsc0 :: Int -> IntAsc0 -- | Human-readable ASCII Double. data DoubleAsc DoubleAsc :: DoubleAsc -- | Date32 in ASCII YYYYsMMsDD format. data YYYYsMMsDD YYYYsMMsDD :: Char -> YYYYsMMsDD -- | Date32 in ASCII DDsMMsYYYY format. data DDsMMsYYYY DDsMMsYYYY :: Char -> DDsMMsYYYY -- | Big-endian 8-bit unsigned word. data Word8be Word8be :: Word8be -- | Big-endian 8-bit signed integer. data Int8be Int8be :: Int8be -- | Big-endian 32-bit unsigned word. data Word16be Word16be :: Word16be data Int16be Int16be :: Int16be -- | Big-endian 32-bit unsigned word. data Word32be Word32be :: Word32be -- | Big-endian 32-bit signed integer. data Int32be Int32be :: Int32be -- | Big-endian 32-bit IEEE 754 float. data Float32be Float32be :: Float32be -- | Big-endian 64-bit unsigned word. data Word64be Word64be :: Word64be -- | Big-endian 64-bit signed integer. data Int64be Int64be :: Int64be -- | Big-endian 64-bit IEEE 754 float. data Float64be Float64be :: Float64be -- | This module provides the Format class definition, without -- exporting the pre-defined formats. module Data.Repa.Convert.Format -- | Relates a storage format to the Haskell type of the value that is -- stored in that format. class Format f where type family Value f -- | Yield the number of separate fields in this format. fieldCount :: Format f => f -> Int -- | Yield the minumum number of bytes that a value of this format will -- take up. -- -- Packing a value into this format is guaranteed to use at least this -- many bytes. This is exact for fixed-size formats. minSize :: Format f => f -> Int -- | For fixed size formats, yield their size (length) in bytes. -- -- Yields Nothing if this is not a fixed size format. fixedSize :: Format f => f -> Maybe Int -- | Yield the size of a value in the given format. -- -- Yields Nothing when a collection of values is to be packed into -- a fixed length format, but the size of the collection does not match -- the format. -- -- If fixedSize returns a size then packedSize returns the -- same size. packedSize :: Format f => f -> Value f -> Maybe Int -- | Class of storage formats that can have values packed and unpacked from -- foreign bufferes. -- -- The methods are written using continuations to make it easier for GHC -- to optimise its core code when packing/unpacking many fields. class Format format => Packable format -- | Pack a value into a buffer using the given format. pack :: Packable format => format -> Value format -> Packer -- | Unpack a value from a buffer using the given format. unpack :: Packable format => format -> Unpacker (Value format) -- | Packer wraps a function that can write to a buffer. data Packer Packer :: (Ptr Word8 -> (Ptr Word8 -> IO (Maybe (Ptr Word8))) -> IO (Maybe (Ptr Word8))) -> Packer -- | Takes start of buffer, packs data into it, and calls the continuation -- with a pointer to the byte just after the last one that was written. [fromPacker] :: Packer -> Ptr Word8 -> (Ptr Word8 -> IO (Maybe (Ptr Word8))) -> IO (Maybe (Ptr Word8)) -- | Pack data into the given buffer. -- -- PRECONDITION: The buffer needs to be big enough to hold the packed -- data, otherwise you'll corrupt the heap (bad). Use packedSize -- to work out how big it needs to be. unsafeRunPacker :: Packer -> Ptr Word8 -> IO (Maybe (Ptr Word8)) data Unpacker a Unpacker :: (forall b. Ptr Word8 -> Ptr Word8 -> (Word8 -> Bool) -> IO b -> (Ptr Word8 -> a -> IO b) -> IO b) -> Unpacker a -- | Takes pointers to the first byte in the buffer, the first byte after -- the buffer, and a special field terminating character. The field -- terminating character is used by variable length encodings where the -- length of the encoded data cannot be determined from the encoding -- itself. -- -- If a value can be successfully unpacked from the buffer then it is -- passed to the continuation, along with a pointer to the byte after the -- last one that was read. If not, then the fail action is invoked. [fromUnpacker] :: Unpacker a -> forall b. Ptr Word8 -> Ptr Word8 -> (Word8 -> Bool) -> IO b -> (Ptr Word8 -> a -> IO b) -> IO b -- | Unpack data from the given buffer. -- -- PRECONDITION: The buffer must be at least the minimum size of the -- format (minSize). This allows us to avoid repeatedly checking for -- buffer overrun when unpacking fixed size format. If the buffer is not -- long enough then you'll get an indeterminate result (bad). unsafeRunUnpacker :: Unpacker a -> Ptr Word8 -> Int -> (Word8 -> Bool) -> IO (Maybe (a, Ptr Word8)) -- | Convert tuples of Haskell values to and from ASCII or packed binary -- representations. -- -- This package is intended for cheap and cheerful serialisation and -- deserialisation of flat tables, where each row has a fixed format. If -- you have a table consisting of a couple hundred megs of -- Pipe-Separated-Variables issued by some filthy enterprise system, then -- this package is for you. -- -- If you want to parse context-free, or context-sensitive languages then -- try the parsec or attoparsec packages. If you have -- binary data that does not have a fixed format then try the -- binary or cereal packages. -- -- For testing purposes, use packToString which takes a format, a -- record, and returns a list of bytes. -- -- 
--   > import Data.Repa.Convert
--   
--   > let format   = Sep '|' (VarAsc :*: IntAsc :*: DoubleAsc :*: ())
--   > let Just str = packToString format ("foo" :*: 66 :*: 93.42 :*: ())
--   > str
--   "foo|66|93.42"
--
-- -- We can then unpack the raw bytes back to Haskell values with -- unpackFromString. -- -- 
--   > unpackFromString format str 
--   Just ("foo" :*: (66 :*: (93.42 :*: ())))
--
-- -- In production code use unsafeRunPacker and -- unsafeRunUnpacker to work directly with a buffer in foreign -- memory. -- -- module Data.Repa.Convert -- | Relates a storage format to the Haskell type of the value that is -- stored in that format. class Format f where type family Value f -- | Yield the number of separate fields in this format. fieldCount :: Format f => f -> Int -- | Yield the minumum number of bytes that a value of this format will -- take up. -- -- Packing a value into this format is guaranteed to use at least this -- many bytes. This is exact for fixed-size formats. minSize :: Format f => f -> Int -- | For fixed size formats, yield their size (length) in bytes. -- -- Yields Nothing if this is not a fixed size format. fixedSize :: Format f => f -> Maybe Int -- | Yield the size of a value in the given format. -- -- Yields Nothing when a collection of values is to be packed into -- a fixed length format, but the size of the collection does not match -- the format. -- -- If fixedSize returns a size then packedSize returns the -- same size. packedSize :: Format f => f -> Value f -> Maybe Int -- | Constrain the type of a value to match the given format. -- -- The value itself is not used. forFormat :: format -> Value format -> Value format -- | Constrain the type of some values to match the given format. -- -- The value itself is not used. listFormat :: format -> [Value format] -> [Value format] -- | Class of storage formats that can have values packed and unpacked from -- foreign bufferes. -- -- The methods are written using continuations to make it easier for GHC -- to optimise its core code when packing/unpacking many fields. class Format format => Packable format -- | Pack a value into a buffer using the given format. pack :: Packable format => format -> Value format -> Packer -- | Unpack a value from a buffer using the given format. unpack :: Packable format => format -> Unpacker (Value format) -- | Packer wraps a function that can write to a buffer. data Packer Packer :: (Ptr Word8 -> (Ptr Word8 -> IO (Maybe (Ptr Word8))) -> IO (Maybe (Ptr Word8))) -> Packer -- | Takes start of buffer, packs data into it, and calls the continuation -- with a pointer to the byte just after the last one that was written. [fromPacker] :: Packer -> Ptr Word8 -> (Ptr Word8 -> IO (Maybe (Ptr Word8))) -> IO (Maybe (Ptr Word8)) -- | Pack data into the given buffer. -- -- PRECONDITION: The buffer needs to be big enough to hold the packed -- data, otherwise you'll corrupt the heap (bad). Use packedSize -- to work out how big it needs to be. unsafeRunPacker :: Packer -> Ptr Word8 -> IO (Maybe (Ptr Word8)) data Unpacker a Unpacker :: (forall b. Ptr Word8 -> Ptr Word8 -> (Word8 -> Bool) -> IO b -> (Ptr Word8 -> a -> IO b) -> IO b) -> Unpacker a -- | Takes pointers to the first byte in the buffer, the first byte after -- the buffer, and a special field terminating character. The field -- terminating character is used by variable length encodings where the -- length of the encoded data cannot be determined from the encoding -- itself. -- -- If a value can be successfully unpacked from the buffer then it is -- passed to the continuation, along with a pointer to the byte after the -- last one that was read. If not, then the fail action is invoked. [fromUnpacker] :: Unpacker a -> forall b. Ptr Word8 -> Ptr Word8 -> (Word8 -> Bool) -> IO b -> (Ptr Word8 -> a -> IO b) -> IO b -- | Unpack data from the given buffer. -- -- PRECONDITION: The buffer must be at least the minimum size of the -- format (minSize). This allows us to avoid repeatedly checking for -- buffer overrun when unpacking fixed size format. If the buffer is not -- long enough then you'll get an indeterminate result (bad). unsafeRunUnpacker :: Unpacker a -> Ptr Word8 -> Int -> (Word8 -> Bool) -> IO (Maybe (a, Ptr Word8)) -- | Pack a value to a list of Word8 using the default Ascii format. packToAscii :: (FormatAscii a, Value (FormatAscii' a) ~ a, Packable (FormatAscii' a)) => a -> Maybe String -- | Pack a value to a list of Word8. packToList8 :: Packable format => format -> Value format -> Maybe [Word8] -- | Unpack a value from a list of Word8. unpackFromList8 :: Packable format => format -> [Word8] -> Maybe (Value format) -- | Pack a value to a String. packToString :: Packable format => format -> Value format -> Maybe String -- | Unpack a value from a String. unpackFromString :: Packable format => format -> String -> Maybe (Value format)