<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <!--Rendered using the Haskell Html Library v0.2--> <HTML ><HEAD ><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8" ><TITLE >Data.Binary</TITLE ><LINK HREF="haddock.css" REL="stylesheet" TYPE="text/css" ><SCRIPT SRC="haddock-util.js" TYPE="text/javascript" ></SCRIPT ><SCRIPT TYPE="text/javascript" >window.onload = function () {setSynopsis("mini_Data-Binary.html")};</SCRIPT ></HEAD ><BODY ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="topbar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><IMG SRC="haskell_icon.gif" WIDTH="16" HEIGHT="16" ALT=" " ></TD ><TD CLASS="title" >ghc-binary-0.5.0.2: Binary serialisation for Haskell values using lazy ByteStrings</TD ><TD CLASS="topbut" ><A HREF="index.html" >Contents</A ></TD ><TD CLASS="topbut" ><A HREF="doc-index.html" >Index</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="modulebar" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD ><FONT SIZE="6" >Data.Binary</FONT ></TD ><TD ALIGN="right" ><TABLE CLASS="narrow" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="infohead" >Portability</TD ><TD CLASS="infoval" >portable to Hugs and GHC. Requires the FFI and some flexible instances</TD ></TR ><TR ><TD CLASS="infohead" >Stability</TD ><TD CLASS="infoval" >unstable</TD ></TR ><TR ><TD CLASS="infohead" >Maintainer</TD ><TD CLASS="infoval" >Lennart Kolmodin <kolmodin@dtek.chalmers.se></TD ></TR ></TABLE ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="section4" ><B >Contents</B ></TD ></TR ><TR ><TD ><DL ><DT ><A HREF="#1" >The Binary class </A ></DT ><DT ><A HREF="#2" >The Get and Put monads </A ></DT ><DT ><A HREF="#3" >Useful helpers for writing instances </A ></DT ><DT ><A HREF="#4" >Binary serialisation </A ></DT ><DT ><A HREF="#5" >IO functions for serialisation </A ></DT ></DL ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Description</TD ></TR ><TR ><TD CLASS="doc" ><P >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 <TT >ByteString</TT > can then be written to disk, sent over the network, or futher processed (for example, compressed with gzip). </P ><P >The <TT ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A ></TT > package is notable in that it provides both pure, and high performance serialisation. </P ><P >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. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" >Synopsis</TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >class</SPAN > <A HREF="#t%3ABinary" >Binary</A > t <SPAN CLASS="keyword" >where</SPAN ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="#v%3Aput" >put</A > :: t -> <A HREF="Data-Binary.html#t%3APut" >Put</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aget" >get</A > :: <A HREF="Data-Binary.html#t%3AGet" >Get</A > t</TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >data</SPAN > <A HREF="#t%3AGet" >Get</A > a</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >type</SPAN > <A HREF="#t%3APut" >Put</A > = <A HREF="Data-Binary-Put.html#t%3APutM" >PutM</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AputWord8" >putWord8</A > :: <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord8" >Word8</A > -> <A HREF="Data-Binary.html#t%3APut" >Put</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AgetWord8" >getWord8</A > :: <A HREF="Data-Binary.html#t%3AGet" >Get</A > <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord8" >Word8</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Aencode" >encode</A > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => a -> <A HREF="../bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3Adecode" >decode</A > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="../bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> a</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AencodeFile" >encodeFile</A > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="../base-4.2.0.2/System-IO.html#t%3AFilePath" >FilePath</A > -> a -> <A HREF="../base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="#v%3AdecodeFile" >decodeFile</A > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="../base-4.2.0.2/System-IO.html#t%3AFilePath" >FilePath</A > -> <A HREF="../base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > a</TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" >module <A HREF="../base-4.2.0.2/Data-Word.html" >Data.Word</A ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="1" ><A NAME="1" >The Binary class </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >class</SPAN > <A NAME="t:Binary" ><A NAME="t%3ABinary" ></A ></A ><B >Binary</B > t <SPAN CLASS="keyword" >where</SPAN ></TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="ndoc" ><P >The <TT >Binary</TT > class provides <TT ><A HREF="Data-Binary.html#v%3Aput" >put</A ></TT > and <TT ><A HREF="Data-Binary.html#v%3Aget" >get</A ></TT >, methods to encode and decode a Haskell value to a lazy ByteString. It mirrors the Read and Show classes for textual representation of Haskell types, and is suitable for serialising Haskell values to disk, over the network. </P ><P >For parsing and generating simple external binary formats (e.g. C structures), Binary may be used, but in general is not suitable for complex protocols. Instead use the Put and Get primitives directly. </P ><P >Instances of Binary should satisfy the following property: </P ><PRE > decode . encode == id </PRE ><P >That is, the <TT ><A HREF="Data-Binary.html#v%3Aget" >get</A ></TT > and <TT ><A HREF="Data-Binary.html#v%3Aput" >put</A ></TT > methods should be the inverse of each other. A range of instances are provided for basic Haskell types. </P ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="section4" >Methods</TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A NAME="v:put" ><A NAME="v%3Aput" ></A ></A ><B >put</B > :: t -> <A HREF="Data-Binary.html#t%3APut" >Put</A ></TD ></TR ><TR ><TD CLASS="doc" >Encode a value in the Put monad. </TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:get" ><A NAME="v%3Aget" ></A ></A ><B >get</B > :: <A HREF="Data-Binary.html#t%3AGet" >Get</A > t</TD ></TR ><TR ><TD CLASS="doc" >Decode a value in the Get monad </TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s8" ></TD ></TR ><TR ><TD CLASS="section4" ><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:Binary')" ALT="show/hide" > Instances</TD ></TR ><TR ><TD CLASS="body" ><DIV ID="i:Binary" STYLE="display:block;" ><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Bool.html#t%3ABool" >Bool</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Char.html#t%3AChar" >Char</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Prelude.html#t%3ADouble" >Double</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Prelude.html#t%3AFloat" >Float</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Int.html#t%3AInt" >Int</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Int.html#t%3AInt8" >Int8</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Int.html#t%3AInt16" >Int16</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Int.html#t%3AInt32" >Int32</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Int.html#t%3AInt64" >Int64</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Prelude.html#t%3AInteger" >Integer</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Ord.html#t%3AOrdering" >Ordering</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord" >Word</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord8" >Word8</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord16" >Word16</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord32" >Word32</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord64" >Word64</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > ()</TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../bytestring-0.9.1.7/Data-ByteString.html#t%3AByteString" >ByteString</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > <A HREF="../containers-0.3.0.0/Data-IntSet.html#t%3AIntSet" >IntSet</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > [a]</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="../base-4.2.0.2/Prelude.html#t%3AIntegral" >Integral</A > a) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../base-4.2.0.2/Data-Ratio.html#t%3ARatio" >Ratio</A > a)</TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../base-4.2.0.2/Data-Maybe.html#t%3AMaybe" >Maybe</A > a)</TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../containers-0.3.0.0/Data-Tree.html#t%3ATree" >Tree</A > e)</TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../containers-0.3.0.0/Data-IntMap.html#t%3AIntMap" >IntMap</A > e)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="../base-4.2.0.2/Data-Ord.html#t%3AOrd" >Ord</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../containers-0.3.0.0/Data-Set.html#t%3ASet" >Set</A > a)</TD ></TR ><TR ><TD CLASS="decl" ><A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../containers-0.3.0.0/Data-Sequence.html#t%3ASeq" >Seq</A > e)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../base-4.2.0.2/Data-Either.html#t%3AEither" >Either</A > a b)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > i, <A HREF="../base-4.2.0.2/Data-Ix.html#t%3AIx" >Ix</A > i, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e, <A HREF="../array-0.3.0.1/Data-Array-IArray.html#t%3AIArray" >IArray</A > <A HREF="../array-0.3.0.1/Data-Array-Unboxed.html#t%3AUArray" >UArray</A > e) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../array-0.3.0.1/Data-Array-Unboxed.html#t%3AUArray" >UArray</A > i e)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > i, <A HREF="../base-4.2.0.2/Data-Ix.html#t%3AIx" >Ix</A > i, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../array-0.3.0.1/Data-Array.html#t%3AArray" >Array</A > i e)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="../base-4.2.0.2/Data-Ord.html#t%3AOrd" >Ord</A > k, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > k, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (<A HREF="../containers-0.3.0.0/Data-Map.html#t%3AMap" >Map</A > k e)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > d) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c, d)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > d, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c, d, e)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > d, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > f) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c, d, e, f)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > d, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > f, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > g) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c, d, e, f, g)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > d, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > f, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > g, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > h) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c, d, e, f, g, h)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > d, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > f, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > g, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > h, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > i) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c, d, e, f, g, h, i)</TD ></TR ><TR ><TD CLASS="decl" >(<A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > b, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > c, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > d, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > e, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > f, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > g, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > h, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > i, <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > j) => <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > (a, b, c, d, e, f, g, h, i, j)</TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="doc" ><P >To serialise a custom type, an instance of Binary for that type is required. For example, suppose we have a data structure: </P ><PRE > data Exp = IntE Int | OpE String Exp Exp deriving Show </PRE ><P >We can encode values of this type into bytestrings using the following instance, which proceeds by recursively breaking down the structure to serialise: </P ><PRE > 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) </PRE ><P >Note how we write an initial tag byte to indicate each variant of the data type. </P ><P >We can simplify the writing of <TT ><A HREF="Data-Binary.html#v%3Aget" >get</A ></TT > instances using monadic combinators: </P ><PRE > get = do tag <- getWord8 case tag of 0 -> liftM IntE get 1 -> liftM3 OpE get get get </PRE ><P >The generation of Binary instances has been automated by a script using Scrap Your Boilerplate generics. Use the script here: <A HREF="http://darcs.haskell.org/binary/tools/derive/BinaryDerive.hs" >http://darcs.haskell.org/binary/tools/derive/BinaryDerive.hs</A >. </P ><P >To derive the instance for a type, load this script into GHCi, and bring your type into scope. Your type can then have its Binary instances derived as follows: </P ><PRE > $ ghci -fglasgow-exts BinaryDerive.hs *BinaryDerive> :l Example.hs *Main> deriveM (undefined :: Drinks) instance Binary Main.Drinks where put (Beer a) = putWord8 0 >> put a put Coffee = putWord8 1 put Tea = putWord8 2 put EnergyDrink = putWord8 3 put Water = putWord8 4 put Wine = putWord8 5 put Whisky = putWord8 6 get = do tag_ <- getWord8 case tag_ of 0 -> get >>= \a -> return (Beer a) 1 -> return Coffee 2 -> return Tea 3 -> return EnergyDrink 4 -> return Water 5 -> return Wine 6 -> return Whisky </PRE ><P >To serialise this to a bytestring, we use <TT ><A HREF="Data-Binary.html#v%3Aencode" >encode</A ></TT >, which packs the data structure into a binary format, in a lazy bytestring </P ><PRE > > let e = OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) > let v = encode e </PRE ><P >Where v is a binary encoded data structure. To reconstruct the original data, we use <TT ><A HREF="Data-Binary.html#v%3Adecode" >decode</A ></TT > </P ><PRE > > decode v :: Exp OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) </PRE ><P >The lazy ByteString that results from <TT ><A HREF="Data-Binary.html#v%3Aencode" >encode</A ></TT > can be written to disk, and read from disk using Data.ByteString.Lazy IO functions, such as hPutStr or writeFile: </P ><PRE > > writeFile "/tmp/exp.txt" (encode e) </PRE ><P >And read back with: </P ><PRE > > readFile "/tmp/exp.txt" >>= return . decode :: IO Exp OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) </PRE ><P >We can also directly serialise a value to and from a Handle, or a file: </P ><PRE > > v <- decodeFile "/tmp/exp.txt" :: IO Exp OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2)) </PRE ><P >And write a value to disk </P ><PRE > > encodeFile "/tmp/a.txt" v </PRE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="2" ><A NAME="2" >The Get and Put monads </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >data</SPAN > <A NAME="t:Get" ><A NAME="t%3AGet" ></A ></A ><B >Get</B > a </TD ></TR ><TR ><TD CLASS="body" ><TABLE CLASS="vanilla" CELLSPACING="0" CELLPADDING="0" ><TR ><TD CLASS="ndoc" >The Get monad is just a State monad carrying around the input ByteString We treat it as a strict state monad. </TD ></TR ><TR ><TD CLASS="section4" ><IMG SRC="minus.gif" CLASS="coll" ONCLICK="toggle(this,'i:Get')" ALT="show/hide" > Instances</TD ></TR ><TR ><TD CLASS="body" ><DIV ID="i:Get" STYLE="display:block;" ><TABLE CLASS="vanilla" CELLSPACING="1" CELLPADDING="0" ><TR ><TD CLASS="decl" ><A HREF="../base-4.2.0.2/Control-Monad.html#t%3AMonad" >Monad</A > <A HREF="Data-Binary.html#t%3AGet" >Get</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="../base-4.2.0.2/Control-Monad.html#t%3AFunctor" >Functor</A > <A HREF="Data-Binary.html#t%3AGet" >Get</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="../base-4.2.0.2/Control-Monad-Fix.html#t%3AMonadFix" >MonadFix</A > <A HREF="Data-Binary.html#t%3AGet" >Get</A ></TD ></TR ><TR ><TD CLASS="decl" ><A HREF="../base-4.2.0.2/Control-Applicative.html#t%3AApplicative" >Applicative</A > <A HREF="Data-Binary.html#t%3AGet" >Get</A ></TD ></TR ></TABLE ></DIV ></TD ></TR ></TABLE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><SPAN CLASS="keyword" >type</SPAN > <A NAME="t:Put" ><A NAME="t%3APut" ></A ></A ><B >Put</B > = <A HREF="Data-Binary-Put.html#t%3APutM" >PutM</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="doc" >Put merely lifts Builder into a Writer monad, applied to (). </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="3" ><A NAME="3" >Useful helpers for writing instances </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:putWord8" ><A NAME="v%3AputWord8" ></A ></A ><B >putWord8</B > :: <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord8" >Word8</A > -> <A HREF="Data-Binary.html#t%3APut" >Put</A ></TD ></TR ><TR ><TD CLASS="doc" >Efficiently write a byte into the output buffer </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:getWord8" ><A NAME="v%3AgetWord8" ></A ></A ><B >getWord8</B > :: <A HREF="Data-Binary.html#t%3AGet" >Get</A > <A HREF="../base-4.2.0.2/Data-Word.html#t%3AWord8" >Word8</A ></TD ></TR ><TR ><TD CLASS="doc" >Read a Word8 from the monad state </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="4" ><A NAME="4" >Binary serialisation </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:encode" ><A NAME="v%3Aencode" ></A ></A ><B >encode</B > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => a -> <A HREF="../bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A ></TD ></TR ><TR ><TD CLASS="doc" >Encode a value using binary serialisation to a lazy ByteString. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:decode" ><A NAME="v%3Adecode" ></A ></A ><B >decode</B > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="../bytestring-0.9.1.7/Data-ByteString-Lazy.html#t%3AByteString" >ByteString</A > -> a</TD ></TR ><TR ><TD CLASS="doc" >Decode a value from a lazy ByteString, reconstructing the original structure. </TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="section1" ><A NAME="5" ><A NAME="5" >IO functions for serialisation </A ></A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:encodeFile" ><A NAME="v%3AencodeFile" ></A ></A ><B >encodeFile</B > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="../base-4.2.0.2/System-IO.html#t%3AFilePath" >FilePath</A > -> a -> <A HREF="../base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > <A HREF="../ghc-prim-0.2.0.0/GHC-Unit.html#t%3A%28%29" >()</A ></TD ></TR ><TR ><TD CLASS="doc" ><P >Lazily serialise a value to a file </P ><P >This is just a convenience function, it's defined simply as: </P ><PRE > encodeFile f = B.writeFile f . encode </PRE ><P >So for example if you wanted to compress as well, you could use: </P ><PRE > B.writeFile f . compress . encode </PRE ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" ><A NAME="v:decodeFile" ><A NAME="v%3AdecodeFile" ></A ></A ><B >decodeFile</B > :: <A HREF="Data-Binary.html#t%3ABinary" >Binary</A > a => <A HREF="../base-4.2.0.2/System-IO.html#t%3AFilePath" >FilePath</A > -> <A HREF="../base-4.2.0.2/System-IO.html#t%3AIO" >IO</A > a</TD ></TR ><TR ><TD CLASS="doc" ><P >Lazily reconstruct a value previously written to a file. </P ><P >This is just a convenience function, it's defined simply as: </P ><PRE > decodeFile f = return . decode =<< B.readFile f </PRE ><P >So for example if you wanted to decompress as well, you could use: </P ><PRE > return . decode . decompress =<< B.readFile f </PRE ><P >After contructing the data from the input file, <TT ><A HREF="Data-Binary.html#v%3AdecodeFile" >decodeFile</A ></TT > checks if the file is empty, and in doing so will force the associated file handle closed, if it is indeed empty. If the file is not empty, it is up to the decoding instance to consume the rest of the data, or otherwise finalise the resource. </P ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="decl" >module <A HREF="../base-4.2.0.2/Data-Word.html" >Data.Word</A ></TD ></TR ><TR ><TD CLASS="s15" ></TD ></TR ><TR ><TD CLASS="botbar" >Produced by <A HREF="http://www.haskell.org/haddock/" >Haddock</A > version 2.6.1</TD ></TR ></TABLE ></BODY ></HTML >