-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A binary serialization library -- -- A binary serialization library, similar to binary, that introduces an -- isolate primitive for parser isolation, and replaces the asynchronous -- errors with a user-handleable Either type. Similar to binary in -- performance, but uses a strict ByteString instead of a lazy -- ByteString, thus restricting it to operating on finite inputs. @package cereal @version 0.2 -- | Efficient construction of lazy bytestrings. module Data.Serialize.Builder -- | A Builder is an efficient way to build lazy ByteStrings. -- There are several functions for constructing Builders, but only -- one to inspect them: to extract any data, you have to turn them into -- lazy ByteStrings using toLazyByteString. -- -- Internally, a Builder constructs a lazy L.Bytestring -- by filling byte arrays piece by piece. As each buffer is filled, it is -- 'popped' off, to become a new chunk of the resulting lazy -- ByteString. All this is hidden from the user of the -- Builder. data Builder toByteString :: Builder -> ByteString -- | O(n). Extract a lazy ByteString from a Builder. -- The construction work takes place if and when the relevant part of the -- lazy ByteString is demanded. toLazyByteString :: Builder -> ByteString -- | O(1). The empty Builder, satisfying -- -- empty :: Builder -- | O(1). A Builder taking a single byte, satisfying -- -- singleton :: Word8 -> Builder -- | O(1). The concatenation of two Builders, an associative -- operation with identity empty, satisfying -- -- append :: Builder -> Builder -> Builder -- | O(1). A Builder taking a ByteString, satisfying -- -- fromByteString :: ByteString -> Builder -- | O(1). A Builder taking a lazy ByteString, satisfying -- -- fromLazyByteString :: ByteString -> Builder -- | O(1). Pop the ByteString we have constructed so far, if -- any, yielding a new chunk in the result lazy ByteString. flush :: Builder -- | Write a Word16 in big endian format putWord16be :: Word16 -> Builder -- | Write a Word32 in big endian format putWord32be :: Word32 -> Builder -- | Write a Word64 in big endian format putWord64be :: Word64 -> Builder -- | Write a Word16 in little endian format putWord16le :: Word16 -> Builder -- | Write a Word32 in little endian format putWord32le :: Word32 -> Builder -- | Write a Word64 in little endian format putWord64le :: Word64 -> Builder -- | O(1). A Builder taking a single native machine word. The word -- is written in host order, host endian form, for the machine you're on. -- On a 64 bit machine the Word is an 8 byte value, on a 32 bit machine, -- 4 bytes. Values written this way are not portable to different endian -- or word sized machines, without conversion. putWordhost :: Word -> Builder -- | Write a Word16 in native host order and host endianness. 2 bytes will -- be written, unaligned. putWord16host :: Word16 -> Builder -- | Write a Word32 in native host order and host endianness. 4 bytes will -- be written, unaligned. putWord32host :: Word32 -> Builder -- | Write a Word64 in native host order. On a 32 bit machine we write two -- host order Word32s, in big endian form. 8 bytes will be written, -- unaligned. putWord64host :: Word64 -> Builder instance Monoid Builder -- | The Get monad. A monad for efficiently building structures from strict -- ByteStrings module Data.Serialize.Get -- | The Get monad is an Exception and State monad. data Get a -- | Run the Get monad applies a get-based parser on the input -- ByteString runGet :: Get a -> ByteString -> Either String a -- | Run the Get monad applies a get-based parser on the input -- ByteString. Additional to the result of get it returns the number of -- consumed bytes and the rest of the input. runGetState :: Get a -> ByteString -> Int -> Either String (a, ByteString) -- | Isolate an action to operating within a fixed block of bytes. The -- action is required to consume all the bytes that it is isolated to. isolate :: String -> Int -> Get a -> Get a label :: String -> Get a -> Get a -- | Skip ahead n bytes. Fails if fewer than n bytes are -- available. skip :: Int -> Get () -- | Skip ahead n bytes. No error if there isn't enough bytes. uncheckedSkip :: Int -> Get () -- | Run ga, but return without consuming its input. Fails if -- ga fails. lookAhead :: Get a -> Get a -- | Like lookAhead, but consume the input if gma returns -- 'Just _'. Fails if gma fails. lookAheadM :: Get (Maybe a) -> Get (Maybe a) -- | Like lookAhead, but consume the input if gea returns -- 'Right _'. Fails if gea fails. lookAheadE :: Get (Either a b) -> Get (Either a b) -- | Get the next up to n bytes as a ByteString, without consuming -- them. uncheckedLookAhead :: Int -> Get ByteString -- | Pull n bytes from the input, as a strict ByteString. getBytes :: Int -> Get ByteString -- | Get the number of remaining unparsed bytes. Useful for checking -- whether all input has been consumed. Note that this forces the rest of -- the input. remaining :: Get Int -- | Test whether all input has been consumed, i.e. there are no remaining -- unparsed bytes. isEmpty :: Get Bool -- | Read a Word8 from the monad state getWord8 :: Get Word8 -- | An efficient get method for strict ByteStrings. Fails if fewer -- than n bytes are left in the input. This function creates a -- fresh copy of the underlying bytes. getByteString :: Int -> Get ByteString getLazyByteString :: Int64 -> Get ByteString -- | Read a Word16 in big endian format getWord16be :: Get Word16 -- | Read a Word32 in big endian format getWord32be :: Get Word32 -- | Read a Word64 in big endian format getWord64be :: Get Word64 -- | Read a Word16 in little endian format getWord16le :: Get Word16 -- | Read a Word32 in little endian format getWord32le :: Get Word32 -- | Read a Word64 in little endian format getWord64le :: Get Word64 -- | O(1). Read a single native machine word. The word is read in -- host order, host endian form, for the machine you're on. On a 64 bit -- machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes. getWordhost :: Get Word -- | O(1). Read a 2 byte Word16 in native host order and host -- endianness. getWord16host :: Get Word16 -- | O(1). Read a Word32 in native host order and host endianness. getWord32host :: Get Word32 -- | O(1). Read a Word64 in native host order and host endianess. getWord64host :: Get Word64 getTwoOf :: Get a -> Get b -> Get (a, b) -- | Get a list in the following format: Word64 (big endian format) element -- 1 ... element n getListOf :: Get a -> Get [a] -- | Get an IArray in the following format: index (lower bound) index -- (upper bound) Word64 (big endian format) element 1 ... element n getIArrayOf :: (Ix i, IArray a e) => Get i -> Get e -> Get (a i e) -- | Read as a list of lists. getTreeOf :: Get a -> Get (Tree a) -- | Get a sequence in the following format: Word64 (big endian format) -- element 1 ... element n getSeqOf :: Get a -> Get (Seq a) -- | Read as a list of pairs of key and element. getMapOf :: (Ord k) => Get k -> Get a -> Get (Map k a) -- | Read as a list of pairs of int and element. getIntMapOf :: Get Int -> Get a -> Get (IntMap a) -- | Read as a list of elements. getSetOf :: (Ord a) => Get a -> Get (Set a) -- | Read as a list of ints. getIntSetOf :: Get Int -> Get IntSet -- | Read in a Maybe in the following format: Word8 (0 for Nothing, -- anything else for Just) element (when Just) getMaybeOf :: Get a -> Get (Maybe a) -- | Read an Either, in the following format: Word8 (0 for Left, anything -- else for Right) element a when 0, element b otherwise getEitherOf :: Get a -> Get b -> Get (Either a b) instance MonadPlus Get instance Monad Get instance Alternative Get instance Applicative Get instance Functor Get -- | The Put monad. A monad for efficiently constructing lazy bytestrings. module Data.Serialize.Put -- | Put merely lifts Builder into a Writer monad, applied to (). type Put = PutM () -- | The PutM type. A Writer monad over the efficient Builder monoid. newtype PutM a Put :: PairS a -> PutM a unPut :: PutM a -> PairS a type Putter a = a -> Put -- | Run the Put monad with a serialiser runPut :: Put -> ByteString -- | Run the Put monad with a serialiser and get its result runPutM :: PutM a -> (a, ByteString) putBuilder :: Putter Builder -- | Run the Put monad execPut :: PutM a -> Builder -- | Pop the ByteString we have constructed so far, if any, yielding a new -- chunk in the result ByteString. flush :: Put -- | Efficiently write a byte into the output buffer putWord8 :: Putter Word8 -- | An efficient primitive to write a strict ByteString into the output -- buffer. It flushes the current buffer, and writes the argument into a -- new chunk. putByteString :: Putter ByteString -- | Write a lazy ByteString efficiently, simply appending the lazy -- ByteString chunks to the output buffer putLazyByteString :: Putter ByteString -- | Write a Word16 in big endian format putWord16be :: Putter Word16 -- | Write a Word32 in big endian format putWord32be :: Putter Word32 -- | Write a Word64 in big endian format putWord64be :: Putter Word64 -- | Write a Word16 in little endian format putWord16le :: Putter Word16 -- | Write a Word32 in little endian format putWord32le :: Putter Word32 -- | Write a Word64 in little endian format putWord64le :: Putter Word64 -- | O(1). Write a single native machine word. The word is written -- in host order, host endian form, for the machine you're on. On a 64 -- bit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes. -- Values written this way are not portable to different endian or word -- sized machines, without conversion. putWordhost :: Putter Word -- | O(1). Write a Word16 in native host order and host endianness. -- For portability issues see putWordhost. putWord16host :: Putter Word16 -- | O(1). Write a Word32 in native host order and host endianness. -- For portability issues see putWordhost. putWord32host :: Putter Word32 -- | O(1). Write a Word64 in native host order On a 32 bit machine -- we write two host order Word32s, in big endian form. For portability -- issues see putWordhost. putWord64host :: Putter Word64 putTwoOf :: Putter a -> Putter b -> Putter (a, b) putListOf :: Putter a -> Putter [a] putIArrayOf :: (Ix i, IArray a e) => Putter i -> Putter e -> Putter (a i e) putSeqOf :: Putter a -> Putter (Seq a) putTreeOf :: Putter a -> Putter (Tree a) putMapOf :: (Ord k) => Putter k -> Putter a -> Putter (Map k a) putIntMapOf :: Putter Int -> Putter a -> Putter (IntMap a) putSetOf :: Putter a -> Putter (Set a) putIntSetOf :: Putter Int -> Putter IntSet putMaybeOf :: Putter a -> Putter (Maybe a) putEitherOf :: Putter a -> Putter b -> Putter (Either a b) instance Monad PutM instance Applicative PutM instance Functor PutM module Data.Serialize class Serialize t put :: (Serialize t) => Putter t get :: (Serialize t) => Get t -- | The Get monad is an Exception and State monad. data Get a -- | Put merely lifts Builder into a Writer monad, applied to (). type Put = PutM () type Putter a = a -> Put -- | Efficiently write a byte into the output buffer putWord8 :: Putter Word8 -- | Read a Word8 from the monad state getWord8 :: Get Word8 -- | Encode a value using binary serialisation to a lazy ByteString. encode :: (Serialize a) => a -> ByteString -- | Decode a value from a lazy ByteString, reconstructing the original -- structure. decode :: (Serialize a) => ByteString -> Either String a instance (Serialize i, Ix i, Serialize e, IArray UArray e) => Serialize (UArray i e) instance (Serialize i, Ix i, Serialize e) => Serialize (Array i e) instance (Serialize e) => Serialize (Tree e) instance Serialize Float instance Serialize Double instance (Serialize e) => Serialize (Seq e) instance (Serialize e) => Serialize (IntMap e) instance Serialize IntSet instance (Ord k, Serialize k, Serialize e) => Serialize (Map k e) instance (Ord a, Serialize a) => Serialize (Set a) instance Serialize ByteString instance Serialize ByteString instance (Serialize a, Serialize b) => Serialize (Either a b) instance (Serialize a) => Serialize (Maybe a) instance (Serialize a) => Serialize [a] instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g, Serialize h, Serialize i, Serialize j) => Serialize (a, b, c, d, e, f, g, h, i, j) instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g, Serialize h, Serialize i) => Serialize (a, b, c, d, e, f, g, h, i) instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g, Serialize h) => Serialize (a, b, c, d, e, f, g, h) instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f, Serialize g) => Serialize (a, b, c, d, e, f, g) instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e, Serialize f) => Serialize (a, b, c, d, e, f) instance (Serialize a, Serialize b, Serialize c, Serialize d, Serialize e) => Serialize (a, b, c, d, e) instance (Serialize a, Serialize b, Serialize c, Serialize d) => Serialize (a, b, c, d) instance (Serialize a, Serialize b, Serialize c) => Serialize (a, b, c) instance (Serialize a, Serialize b) => Serialize (a, b) instance Serialize Char instance (Serialize a, Integral a) => Serialize (Ratio a) instance Serialize Integer instance Serialize Int instance Serialize Word instance Serialize Int64 instance Serialize Int32 instance Serialize Int16 instance Serialize Int8 instance Serialize Word64 instance Serialize Word32 instance Serialize Word16 instance Serialize Word8 instance Serialize Ordering instance Serialize Bool instance Serialize ()