Editing Dealing with binary data (section)

====The <tt>BitGet</tt> monad====

As an alternative to bit twiddling, you can also use the <tt>BitGet</tt> monad.
This is another state-like monad, like <tt>Get</tt>, but here the state
includes the current bit-offset in the input. This means that you can easily pull out
unaligned data. Sadly, haddock is currently breaking when trying to generate the
documentation for <tt>BitGet</tt> so I'll start with an example. Again, you'll
need the
[http://hackage.haskell.org/package/binary-strict binary-strict] package installed.

Here's a description of the header of a DNS packet, direct from RFC 1035:

<pre>                                    1  1  1  1  1  1
      0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
    |                      ID                       |
    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
    |QR|   Opcode  |AA|TC|RD|RA|   Z    |   RCODE   |
    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
    |                    QDCOUNT                    |
    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
    |                    ANCOUNT                    |
    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
    |                    NSCOUNT                    |
    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
    |                    ARCOUNT                    |
    +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+</pre>

The actual fields don't matter, but here's a function for parsing it:

<haskell>
parseHeader :: G.Get Header
parseHeader = do
  id      <- G.getWord16be
  flags   <- G.getByteString 2
  qdcount <- fmap fromIntegral G.getWord16be
  ancount <- fmap fromIntegral G.getWord16be
  nscount <- fmap fromIntegral G.getWord16be
  arcount <- fmap fromIntegral G.getWord16be

  let r = BG.runBitGet flags (do
    isquery <- BG.getBit
    opcode <- BG.getAsWord8 4 >>= parseEnum
    aa <- BG.getBit
    tc <- BG.getBit
    rd <- BG.getBit
    ra <- BG.getBit

    BG.getAsWord8 3
    rcode <- BG.getAsWord8 4 >>= parseEnum

    return $ Header id isquery opcode aa tc rd ra rcode qdcount ancount nscount arcount)

  case r of
    Left error -> fail error
    Right x -> return x</haskell>

Here you can see that only the second line (from the ASCII-art diagram) is
parsed using <tt>BitGet</tt>. An outer <tt>Get</tt> monad is used for
everything else and the bit fields are pulled out with
<hask>getByteString</hask>. Again, <tt>BitGet</tt> is a strict monad and
returns an <tt>Either</tt>, but it doesn't return the remaining bytestring,
just because there's no obvious way to represent a bytestring of a fractional
number of bytes.

You can see the list of <tt>BitGet</tt> functions and their comments in the
[http://darcs.imperialviolet.org/darcsweb.cgi?r=binary-strict;a=headblob;f=/src/Data/Binary/Strict/BitGet.hs source code].