Merge pull request #115 from bgamari/needless-copies
[packages/binary.git] / README.md
1 # binary package #
2
3 [![Build Status](https://api.travis-ci.org/kolmodin/binary.png?branch=master)](http://travis-ci.org/kolmodin/binary)
4
5 *Efficient, pure binary serialisation using lazy ByteStrings.*
6
7 The ``binary`` package provides Data.Binary, containing the Binary class,
8 and associated methods, for serialising values to and from lazy
9 ByteStrings. 
10 A key feature of ``binary`` is that the interface is both pure, and efficient.
11 The ``binary`` package is portable to GHC and Hugs.
12
13 ## Installing binary from Hackage ##
14
15 ``binary`` is part of The Glasgow Haskell Compiler (GHC) and therefore if you
16 have either GHC or [The Haskell Platform](http://www.haskell.org/platform/)
17 installed, you already have ``binary``.
18
19 More recent versions of ``binary`` than you might have installed may be
20 available. You can use ``cabal-install`` to install a later version from
21 [Hackage](http://hackage.haskell.org/package/binary).
22
23     $ cabal update
24     $ cabal install binary
25
26 ## Building binary ##
27
28 ``binary`` comes with both a test suite and a set of benchmarks.
29 While developing, you probably want to enable both.
30 Here's how to get the latest version of the repository, configure and build.
31
32     $ git clone git@github.com:kolmodin/binary.git
33     $ cd binary
34     $ cabal update
35     $ cabal configure --enable-tests --enable-benchmarks
36     $ cabal build
37
38 Run the test suite.
39
40     $ cabal test
41
42 ## Using binary ##
43
44 First:
45
46     import Data.Binary
47
48 and then write an instance of Binary for the type you wish to serialise.
49 An example doing exactly this can be found in the Data.Binary module.
50 You can also use the Data.Binary.Builder module to efficiently build
51 lazy bytestrings using the ``Builder`` monoid. Or, alternatively, the
52 Data.Binary.Get and Data.Binary.Put to serialize/deserialize using
53 the ``Get`` and ``Put`` monads.
54
55 More information in the haddock documentation.
56
57 ## Deriving binary instances using GHC's Generic ##
58
59 Beginning with GHC 7.2, it is possible to use binary serialization without
60 writing any instance boilerplate code.
61
62 ```haskell
63 {-# LANGUAGE DeriveGeneric #-}
64
65 import Data.Binary
66 import GHC.Generics (Generic)
67
68 data Foo = Foo deriving (Generic)
69
70 -- GHC will automatically fill out the instance
71 instance Binary Foo
72 ```
73
74 ## Contributors ##
75
76 * Lennart Kolmodin
77 * Duncan Coutts
78 * Don Stewart
79 * Spencer Janssen
80 * David Himmelstrup
81 * Bj√∂rn Bringert
82 * Ross Paterson
83 * Einar Karttunen
84 * John Meacham
85 * Ulf Norell
86 * Tomasz Zielonka
87 * Stefan Karrmann
88 * Bryan O'Sullivan
89 * Bas van Dijk
90 * Florian Weimer
91
92 For a full list of contributors, see
93 [here](https://github.com/kolmodin/binary/graphs/contributors).