| ||||||||||||||||||||||

| ||||||||||||||||||||||

| ||||||||||||||||||||||

Description | ||||||||||||||||||||||

Binary serialisation of Haskell values to and from lazy ByteStrings.
The Binary library provides methods for encoding Haskell values as
streams of bytes directly in memory. The resulting The Values are always encoded in network order (big endian) form, and encoded data should be portable across machine endianess, word size, or compiler version. For example, data encoded using the Binary class could be written from GHC, and read back in Hugs. | ||||||||||||||||||||||

Synopsis | ||||||||||||||||||||||

| ||||||||||||||||||||||

The Binary class | ||||||||||||||||||||||

class Binary t where | ||||||||||||||||||||||

| ||||||||||||||||||||||

To serialise a custom type, an instance of Binary for that type is required. For example, suppose we have a data structure: data Exp = IntE Int | OpE String Exp Exp deriving Show We can encode values of this type into bytestrings using the following instance, which proceeds by recursively breaking down the structure to serialise: instance Binary Exp where put (IntE i) = do put (0 :: Word8) put i put (OpE s e1 e2) = do put (1 :: Word8) put s put e1 put e2 get = do t <- get :: Get Word8 case t of 0 -> do i <- get return (IntE i) 1 -> do s <- get e1 <- get e2 <- get return (OpE s e1 e2) Note how we write an initial tag byte to indicate each variant of the data type. To serialise this to a bytestring, we use > let e = OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) > let v = encode e Where v is a binary encoded data structure. To reconstruct the
original data, we use > decode v :: Exp OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) The lazy ByteString that results from > writeFile "/tmp/exp.txt" (encode e) And read back with: > readFile "/tmp/exp.txt" >>= return . decode :: IO Exp OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) We can also directly serialise a value to and from a Handle, or a file: > v <- decodeFile "/tmp/exp.txt" :: IO Exp OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) And write a value to disk > encodeFile "/tmp/a.txt" v | ||||||||||||||||||||||

The Get and Put monads | ||||||||||||||||||||||

data Get a | ||||||||||||||||||||||

| ||||||||||||||||||||||

type Put = PutM () | ||||||||||||||||||||||

Useful helpers for writing instances | ||||||||||||||||||||||

putWord8 :: Word8 -> Put | ||||||||||||||||||||||

Efficiently write a byte into the output buffer | ||||||||||||||||||||||

getWord8 :: Get Word8 | ||||||||||||||||||||||

Read a Word8 from the monad state | ||||||||||||||||||||||

Binary serialisation | ||||||||||||||||||||||

encode :: Binary a => a -> ByteString | ||||||||||||||||||||||

Encode a value using binary serialisation to a lazy ByteString. | ||||||||||||||||||||||

decode :: Binary a => ByteString -> a | ||||||||||||||||||||||

Decode a value from a lazy ByteString, reconstructing the original structure. | ||||||||||||||||||||||

IO functions for serialisation | ||||||||||||||||||||||

encodeFile :: Binary a => FilePath -> a -> IO () | ||||||||||||||||||||||

Lazily serialise a value to a file This is just a convenience function, it's defined simply as: encodeFile f = B.writeFile f . encode So for example if you wanted to compress as well, you could use: B.writeFile f . compress . encode | ||||||||||||||||||||||

decodeFile :: Binary a => FilePath -> IO a | ||||||||||||||||||||||

Lazily reconstruct a value previously written to a file This is just a convenience function, it's defined simply as: decodeFile f = return . decode =<< B.readFile f So for example if you wanted to decompress as well, you could use: return . decode . decompress =<< B.readFile f | ||||||||||||||||||||||

module Data.Word | ||||||||||||||||||||||

Produced by Haddock version 0.8 |