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 ByteString can then be written to disk, sent over the network, or further processed (for example, compressed with gzip).

The binary package is notable in that it provides both pure, and high performance serialisation.

Values encoded using the Binary class are always encoded in network order (big endian) form, and encoded data should be portable across machine endianness, word size, or compiler version. For example, data encoded using the Binary class could be written on any machine, and read back on any another.

If the specifics of the data format is not important to you, for example, you are more interested in serializing and deserializing values than in which format will be used, it is possible to derive Binary instances using the generic support. See GBinary.

If you have specific requirements about the encoding format, you can use the encoding and decoding primitives directly, see the modules Data.Binary.Get and Data.Binary.Put.

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.

We can simplify the writing of get instances using monadic combinators:

       get = do tag <- getWord8
                case tag of
                    0 -> liftM  IntE get
                    1 -> liftM3 OpE  get get get

To serialise this to a bytestring, we use encode, which packs the data structure into a binary format, in a lazy bytestring

 > 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

 > decode v :: Exp
 OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2))

The lazy ByteString that results from encode can be written to disk, and read from disk using Data.ByteString.Lazy IO functions, such as hPutStr or writeFile:

 > 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

Beginning with GHC 7.2, it is possible to use binary serialization without writing any instance boilerplate code.

 {-# LANGUAGE DeriveGeneric #-}

 import Data.Binary
 import GHC.Generics (Generic)

 data Foo = Foo
          deriving (Generic)

 -- GHC will automatically fill out the instance
 instance Binary Foo

This mechanism makes use of GHC's efficient built-in generics support.