The binary package

[Tags: bsd3, library]

Efficient, pure binary serialisation using lazy ByteStrings. Haskell values may be encoded to and from binary formats, written to disk as binary, or sent over the network. The format used can be automatically generated, or you can choose to implement a custom format if needed. Serialisation speeds of over 1 G/sec have been observed, so this library should be suitable for high performance scenarios.


[Skip to ReadMe]

Properties

Versions0.2, 0.3, 0.4, 0.4.1, 0.4.2, 0.4.3, 0.4.3.1, 0.4.4, 0.4.5, 0.5, 0.5.0.1, 0.5.0.2, 0.5.1.0, 0.5.1.1, 0.6.0.0, 0.6.1.0, 0.6.2.0, 0.6.3.0, 0.6.4.0, 0.7.0.0, 0.7.0.1, 0.7.1.0, 0.7.2.0, 0.7.2.1, 0.7.2.2, 0.7.2.3, 0.7.3.0, 0.7.4.0, 0.7.5.0, 0.7.6.0
Change logNone available
Dependenciesarray, base (>=3.0 && <4.8), bytestring (>=0.9), containers, ghc-prim [details]
LicenseBSD3
AuthorLennart Kolmodin <kolmodin@gmail.com>
MaintainerLennart Kolmodin, Don Stewart <dons00@gmail.com>
Stabilityprovisional
CategoryData, Parsing
Home pagehttps://github.com/kolmodin/binary
Source repositoryhead: git clone git://github.com/kolmodin/binary.git
UploadedWed May 1 17:04:32 UTC 2013 by LennartKolmodin
UpdatedSat Jan 10 12:49:57 UTC 2015 by HerbertValerioRiedel to revision 1
DistributionsDebian:0.7.2.1, Fedora:0.7.1.0, LTSHaskell:0.7.1.0, NixOS:0.7.5.0, Stackage:0.7.3.0
Downloads68949 total (1644 in last 30 days)
Votes
0 []
StatusDocs uploaded by user
Build status unknown [no reports yet]

Modules

[Index]

Flags

NameDescriptionDefault
developmentDisabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainers' corner

For package maintainers and hackage trustees

Readme for binary-0.7.1.0

binary package

Efficient, pure binary serialisation using lazy ByteStrings.

The binary package provides Data.Binary, containing the Binary class, and associated methods, for serialising values to and from lazy ByteStrings. A key feature of binary is that the interface is both pure, and efficient. The binary package is portable to GHC and Hugs.

Installing binary from Hackage

binary is part of The Glasgow Haskell Compiler (GHC) and therefore if you have either GHC or The Haskell Platform installed, you already have binary.

More recent versions of binary than you might have installed may be available. You can use cabal-install to install a later version from Hackage.

$ cabal update
$ cabal install binary

Building binary

binary comes with both a test suite and a set of benchmarks. While developing, you probably want to enable both. Here's how to get the latest version of the repository, configure and build.

$ git clone git@github.com:kolmodin/binary.git
$ cd binary
$ cabal update
$ cabal configure --enable-tests --enable-benchmarks
$ cabal build

Run the test suite.

$ cabal test

Using binary

First:

import Data.Binary

and then write an instance of Binary for the type you wish to serialise. An example doing exactly this can be found in the Data.Binary module. You can also use the Data.Binary.Builder module to efficiently build lazy bytestrings using the Builder monoid. Or, alternatively, the Data.Binary.Get and Data.Binary.Put to serialize/deserialize using the Get and Put monads.

More information in the haddock documentation.

Deriving binary instances

It is possible to mechanically derive new instances of Binary for your types, if they support the Data and Typeable classes. A script is provided in tools/derive. Here's an example of its use.

$ cd binary 
$ cd tools/derive 

$ ghci -fglasgow-exts BinaryDerive.hs

*BinaryDerive> :l Example.hs 

*Main> deriveM (undefined :: Exp)

instance Binary Main.Exp where
  put (ExpOr a b) = putWord8 0 >> put a >> put b
  put (ExpAnd a b) = putWord8 1 >> put a >> put b
  put (ExpEq a b) = putWord8 2 >> put a >> put b
  put (ExpNEq a b) = putWord8 3 >> put a >> put b
  put (ExpAdd a b) = putWord8 4 >> put a >> put b
  put (ExpSub a b) = putWord8 5 >> put a >> put b
  put (ExpVar a) = putWord8 6 >> put a
  put (ExpInt a) = putWord8 7 >> put a
  get = do
    tag_ <- getWord8
    case tag_ of
      0 -> get >>= \a -> get >>= \b -> return (ExpOr a b)
      1 -> get >>= \a -> get >>= \b -> return (ExpAnd a b)
      2 -> get >>= \a -> get >>= \b -> return (ExpEq a b)
      3 -> get >>= \a -> get >>= \b -> return (ExpNEq a b)
      4 -> get >>= \a -> get >>= \b -> return (ExpAdd a b)
      5 -> get >>= \a -> get >>= \b -> return (ExpSub a b)
      6 -> get >>= \a -> return (ExpVar a)
      7 -> get >>= \a -> return (ExpInt a)
      _ -> fail "no decoding"

Contributors