Binary

https://hackage.haskell.org/package/binary-0.8.9.3/docs/
Admin
Binary is a Haskell library for serializing and deserializing data structures to and from binary...
Tokens:39,481
Snippets:215
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Alternative Instance for Get Monad - <|>

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Implements the '<|>' (alternative) operator for the Get monad. It tries the first Get action; if it fails, it pushes back the input and tries the second Get action.

```Haskell
<|> :: forall a. Get a -> Get a -> Get a
f <|> g = do
    (decoder, bs) <- runAndKeepTrack f
    case decoder of
      Done inp x -> C $ \_ ks -> ks inp x
      Fail _ _   -> g
      _          -> error "Binary: impossible"
```

--------------------------------

### Install binary package using cabal-install

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/package/binary

This snippet shows how to update the package list and install the latest version of the 'binary' package from Hackage using the cabal-install tool.

```bash
$ cabal update
$ cabal install binary
```

--------------------------------

### Haskell: Incremental Parsing with Decoder and runGetIncremental

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get

Introduces the incremental input interface for parsing. runGetIncremental starts a Get monad computation, returning a Decoder. The Decoder can then be fed with ByteString chunks (or Nothing for end-of-input) to progressively produce a result, handle errors, or request more data.

```Haskell
data Decoder a
  = Fail !ByteString !ByteOffset String
  | Partial (Maybe ByteString -> Decoder a)
  | Done !ByteString !ByteOffset a

runGetIncremental :: Get a -> Decoder a
```

--------------------------------

### Haskell: Simplify Binary Instance Get Method

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Shows a more concise way to implement the 'get' method for a 'Binary' instance using monadic combinators like 'getWord8', 'liftM', and 'liftM3'. This reduces boilerplate code.

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

--------------------------------

### Alternative Instance for Get Monad - empty

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Implements the 'empty' behavior for the Alternative instance of the Get monad. It always fails with a specific error message indicating the source of the failure.

```Haskell
empty :: forall a. Get a
empty = C $ \_ _ -> Fail "Data.Binary.Get(Alternative).empty"
```

--------------------------------

### Alternative Instance for Get Monad - many

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Implements the 'many' function for the Alternative instance of the Get monad. It applies a Get action zero or more times, collecting the results.

```Haskell
many :: forall a. Get a -> Get [a]
many p = do
    v <- Just <$> p
    case v of
      Nothing -> return []
      Just x  -> do
        xs <- many p
        return (x:xs)
```

--------------------------------

### Alternative Instance for Get Monad - some

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Implements the 'some' function for the Alternative instance of the Get monad. It applies a Get action one or more times, collecting the results.

```Haskell
some :: forall a. Get a -> Get [a]
some p = (:) <$> p <*> many p
```

--------------------------------

### Binary Instance for Ordering

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Ordering' type.

```Haskell
put :: Ordering -> Put
get :: Get Ordering
putList :: [Ordering] -> Put
```

--------------------------------

### Haskell: Running Get with State and ByteOffset

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get

Demonstrates how to execute a Get monad computation and retrieve the resulting value along with the remaining ByteString and the current ByteOffset. This is useful for inspecting the state after a parsing operation.

```Haskell
runGetState :: Get a -> ByteString -> ByteOffset -> (a, ByteString, ByteOffset)
```

--------------------------------

### Get Monad Definition and Instances

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Defines the Get monad, its associated Decoder data type, and instances for Monad and MonadFail. It handles different parsing states like failure, partial consumption, completion, and byte reading.

```Haskell
{-# LANGUAGE CPP, RankNTypes, MagicHash, BangPatterns, TypeFamilies #-}

module Data.Binary.Get.Internal (

    -- * The Get type
      Get
    , runCont
    , Decoder(..)
    , runGetIncremental

    , readN
    , readNWith

    -- * Parsing
    , bytesRead
    , isolate

    -- * With input chunks
    , withInputChunks
    , Consume
    , failOnEOF

    , get
    , put
    , ensureN

    -- * Utility
    , remaining
    , getBytes
    , isEmpty
    , lookAhead
    , lookAheadM
    , lookAheadE
    , label

    -- ** ByteStrings
    , getByteString

    ) where

import Foreign
import qualified Data.ByteString as B
import qualified Data.ByteString.Unsafe as B

import Control.Applicative
import Control.Monad
#if MIN_VERSION_base(4,9,0)
import qualified Control.Monad.Fail as Fail
#endif

import Data.Binary.Internal ( accursedUnutterablePerformIO )

-- | A decoder produced by running a 'Get' monad.
data Decoder a = Fail !B.ByteString String
              -- ^ The decoder ran into an error. The decoder either used
              -- 'fail' or was not provided enough input.
              | Partial (Maybe B.ByteString -> Decoder a)
              -- ^ The decoder has consumed the available input and needs
              -- more to continue. Provide 'Just' if more input is available
              -- and 'Nothing' otherwise, and you will get a new 'Decoder'.
              | Done !B.ByteString a
              -- ^ The decoder has successfully finished. Except for the
              -- output value you also get the unused input.
              | BytesRead {-# UNPACK #-} !Int64 (Int64 -> Decoder a)
              -- ^ The decoder needs to know the current position in the input.
              -- Given the number of bytes remaning in the decoder, the outer
              -- decoder runner needs to calculate the position and
              -- resume the decoding.

-- unrolled codensity/state monad
newtype Get a = C { runCont :: forall r. B.ByteString -> Success a r -> Decoder r }

type Success a r = B.ByteString -> a -> Decoder r

instance Monad Get where
  return :: forall a. a -> Get a
  return = pure

  >>= :: forall a b. Get a -> (a -> Get b) -> Get b
  (>>=) = bindG
#if !(MIN_VERSION_base(4,9,0))
  fail = failG -- base < 4.9
#elif !(MIN_VERSION_base(4,13,0))
  fail = Fail.fail -- base < 4.13
#endif
-- NB: Starting with base-4.13, the `fail` method
--     has been removed from the `Monad`-class
--     according to the MonadFail proposal (MFP) schedule
--     which completes the process that started with base-4.9.

#if MIN_VERSION_base(4,9,0)
instance Fail.MonadFail Get where
  fail :: forall a. String -> Get a
  fail = failG
#endif

bindG :: Get a -> (a -> Get b) -> Get b
bindG (C c) f = C $ \i ks -> c i (\i' a -> runCont (f a) i' ks)
{-# INLINE bindG #-}

failG :: String -> Get a
failG str = C $ \_ _ -> Fail.fail str

```

--------------------------------

### Haskell Applicative Instance for Get

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Implements the Applicative typeclass for the Get monad, providing 'pure' for lifting values and '<*>' (using apG) for sequencing computations.

```Haskell
instance Applicative Get where
  pure :: forall a. a -> Get a
pure = \a
x -> (forall r. ByteString -> Success a r -> Decoder r) -> Get a
forall a.
(forall r. ByteString -> Success a r -> Decoder r) -> Get a
C ((forall r. ByteString -> Success a r -> Decoder r) -> Get a)
-> (forall r. ByteString -> Success a r -> Decoder r) -> Get a
forall a b. (a -> b) -> a -> b
$ \ByteString
s Success a r
ks -> Success a r
ks ByteString
s a
x
  {-# INLINE [0] pure #-}
  <*> :: forall a b. Get (a -> b) -> Get a -> Get b
(<*>) = Get (a -> b) -> Get a -> Get b
forall a b. Get (a -> b) -> Get a -> Get b
apG
  {-# INLINE (<*>) #}
```

--------------------------------

### Binary Instance for ShortByteString

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'ShortByteString' type.

```Haskell
put :: ShortByteString -> Put
get :: Get ShortByteString
putList :: [ShortByteString] -> Put
```

--------------------------------

### Binary Instance for Word32

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Word32' type.

```Haskell
put :: Word32 -> Put
get :: Get Word32
putList :: [Word32] -> Put
```

--------------------------------

### Binary Instance for All

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'All' type. This instance was introduced in version 0.8.4.0.

```Haskell
put :: All -> Put
get :: Get All
putList :: [All] -> Put
```

--------------------------------

### Binary Instance for Any

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Any' type. This instance was introduced in version 0.8.4.0.

```Haskell
put :: Any -> Put
get :: Get Any
putList :: [Any] -> Put
```

--------------------------------

### Haskell: Checking Input Status with Get

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get-Internal

Functions to check the state of the input stream within the Get monad. `isEmpty` tests if all input has been consumed.

```Haskell
isEmpty :: Get Bool Source
```

--------------------------------

### Haskell: Get Monad Instances

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Details the instances for the 'Get' monad, which is used for parsing binary data. This includes instances for MonadFail, Alternative, Applicative, Functor, Monad, and MonadPlus, providing monadic operations for data retrieval.

```Haskell
fail :: String -> Get a
empty :: Get a
(<|>) :: Get a -> Get a -> Get a
some :: Get a -> Get [a]
many :: Get a -> Get [a]
pure :: a -> Get a
(<*>) :: Get (a -> b) -> Get a -> Get b
liftA2 :: (a -> b -> c) -> Get a -> Get b -> Get c
(*>) :: Get a -> Get b -> Get b
(<*) :: Get a -> Get b -> Get a
fmap :: (a -> b) -> Get a -> Get b
(<$) :: a -> Get b -> Get a
(>>=) :: Get a -> (a -> Get b) -> Get b
(>>) :: Get a -> Get b -> Get b
return :: a -> Get a
mzero :: Get a
mplus :: Get a -> Get a -> Get a
```

--------------------------------

### Binary Instance for Word64

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Word64' type.

```Haskell
put :: Word64 -> Put
get :: Get Word64
putList :: [Word64] -> Put
```

--------------------------------

### Haskell: Handling Input Chunks with Get

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get-Internal

Provides functions for managing input chunks within the Get monad. `withInputChunks` allows processing input in chunks, while `Consume` defines how to consume data from a chunk.

```Haskell
withInputChunks :: s -> Consume s -> ([ByteString] -> b) -> ([ByteString] -> Get b) -> Get b Source
type Consume s = s -> ByteString -> Either s (ByteString, ByteString) Source
```

--------------------------------

### Binary Instance for Maybe

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides serialization and deserialization for `Maybe a` types, where `a` must also be an instance of `Binary`. It includes methods for putting a single `Maybe a`, getting a `Maybe a`, and putting a list of `Maybe a`.

```Haskell
Instance detailsDefined in Data.Binary.Class Methodsput :: Maybe a -> Put Source #get :: Get (Maybe a) Source #putList :: [Maybe a] -> Put Source #
```

--------------------------------

### Binary Instance for Word8

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Word8' type.

```Haskell
put :: Word8 -> Put
get :: Get Word8
putList :: [Word8] -> Put
```

--------------------------------

### Binary Instance for SomeTypeRep

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'SomeTypeRep' type.

```Haskell
put :: SomeTypeRep -> Put
get :: Get SomeTypeRep
putList :: [SomeTypeRep] -> Put
```

--------------------------------

### Binary Instance for Version

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Version' type. This instance was introduced in version 0.8.0.0.

```Haskell
put :: Version -> Put
get :: Get Version
putList :: [Version] -> Put
```

--------------------------------

### Binary Instance for Char

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Char' type.

```Haskell
put :: Char -> Put
get :: Get Char
putList :: [Char] -> Put
```

--------------------------------

### Binary Instance for Word16

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Word16' type.

```Haskell
put :: Word16 -> Put
get :: Get Word16
putList :: [Word16] -> Put
```

--------------------------------

### Binary Instance for Bool

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Bool' type.

```Haskell
put :: Bool -> Put
get :: Get Bool
putList :: [Bool] -> Put
```

--------------------------------

### Binary Instance for Tuples (2-element)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Enables serialization and deserialization for 2-element tuples `(a, b)`. Both `a` and `b` must be instances of `Binary`. The instance provides `put`, `get`, and `putList` methods.

```Haskell
(Binary a, Binary b) => Binary (a, b) Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: (a, b) -> Put Source #get :: Get (a, b) Source #putList :: [(a, b)] -> Put Source #
```

--------------------------------

### Binary Instance for Unit Type

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the unit type '()'.

```Haskell
put :: () -> Put
get :: Get ()
putList :: [()] -> Put
```

--------------------------------

### Binary Instance for IntSet

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'IntSet' type.

```Haskell
put :: IntSet -> Put
get :: Get IntSet
putList :: [IntSet] -> Put
```

--------------------------------

### Binary Instance for Tuples (6-element)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Handles serialization and deserialization for 6-element tuples `(a, b, c, d, e, f)`. All types `a` through `f` must be instances of `Binary`. The instance provides `put`, `get`, and `putList` methods.

```Haskell
(Binary a, Binary b, Binary c, Binary d, Binary e, Binary f) => Binary (a, b, c, d, e, f) Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: (a, b, c, d, e, f) -> Put Source #get :: Get (a, b, c, d, e, f) Source #putList :: [(a, b, c, d, e, f)] -> Put Source #
```

--------------------------------

### Binary Instance for Tuples (3-element)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides serialization and deserialization for 3-element tuples `(a, b, c)`. All types `a`, `b`, and `c` must be instances of `Binary`. The instance includes `put`, `get`, and `putList` methods.

```Haskell
(Binary a, Binary b, Binary c) => Binary (a, b, c) Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: (a, b, c) -> Put Source #get :: Get (a, b, c) Source #putList :: [(a, b, c)] -> Put Source #
```

--------------------------------

### Binary Instance for Lists

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Enables serialization and deserialization for lists of elements (`[a]`), provided that the element type `a` is an instance of `Binary`. The methods include `put`, `get`, and `putList` for lists.

```Haskell
Binary a => Binary [a] Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: [a] -> Put Source #get :: Get [a] Source #putList :: [[a]] -> Put Source #
```

--------------------------------

### Binary Instance for Int64

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Int64' type.

```Haskell
put :: Int64 -> Put
get :: Get Int64
putList :: [Int64] -> Put
```

--------------------------------

### Binary Instance for TyCon

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'TyCon' type. This instance was introduced in version 0.8.5.0.

```Haskell
put :: TyCon -> Put
get :: Get TyCon
putList :: [TyCon] -> Put
```

--------------------------------

### Binary Instance for Tuples (4-element)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Enables serialization and deserialization for 4-element tuples `(a, b, c, d)`. All types `a`, `b`, `c`, and `d` must be instances of `Binary`. The instance provides `put`, `get`, and `putList` methods.

```Haskell
(Binary a, Binary b, Binary c, Binary d) => Binary (a, b, c, d) Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: (a, b, c, d) -> Put Source #get :: Get (a, b, c, d) Source #putList :: [(a, b, c, d)] -> Put Source #
```

--------------------------------

### Binary Instance for Int32

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Int32' type.

```Haskell
put :: Int32 -> Put
get :: Get Int32
putList :: [Int32] -> Put
```

--------------------------------

### Binary Instance for Tuples (5-element)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Supports serialization and deserialization for 5-element tuples `(a, b, c, d, e)`. All types `a` through `e` must be instances of `Binary`. The instance includes `put`, `get`, and `putList` methods.

```Haskell
(Binary a, Binary b, Binary c, Binary d, Binary e) => Binary (a, b, c, d, e) Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: (a, b, c, d, e) -> Put Source #get :: Get (a, b, c, d, e) Source #putList :: [(a, b, c, d, e)] -> Put Source #
```

--------------------------------

### Binary Instance for KindRep

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'KindRep' type. This instance was introduced in version 0.8.5.0.

```Haskell
put :: KindRep -> Put
get :: Get KindRep
putList :: [KindRep] -> Put
```

--------------------------------

### Binary Instance for Natural

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides binary serialization (put) and deserialization (get) for the 'Natural' type. This instance was introduced in version 0.7.3.0.

```Haskell
put :: Natural -> Put
get :: Get Natural
putList :: [Natural] -> Put
```

--------------------------------

### Build binary package with tests and benchmarks

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/package/binary

This snippet demonstrates cloning the 'binary' repository, updating dependencies, configuring the build to enable tests and benchmarks, and then building the package.

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

--------------------------------

### Binary Instance for TypeRep

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Supports serialization and deserialization for `TypeRep a` types, requiring `a` to be an instance of `Typeable`. The instance provides `put`, `get`, and `putList` methods for type representations.

```Haskell
Typeable a => Binary (TypeRep a) Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: TypeRep a -> Put Source #get :: Get (TypeRep a) Source #putList :: [TypeRep a] -> Put Source #
```

--------------------------------

### Run binary package test suite

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/package/binary

This command executes the test suite for the 'binary' package after it has been built.

```bash
$ cabal test
```

--------------------------------

### Binary Instance for Either

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Supports serialization and deserialization for `Either a b` types. Both `a` and `b` must be instances of `Binary`. The instance provides `put`, `get`, and `putList` methods for `Either` values.

```Haskell
(Binary a, Binary b) => Binary (Either a b) Source #|   
Instance detailsDefined in Data.Binary.Class Methodsput :: Either a b -> Put Source #get :: Get (Either a b) Source #putList :: [Either a b] -> Put Source #
```

--------------------------------

### Binary Instance for Custom Data Types (Haskell)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data

Demonstrates how to create a 'Binary' instance for a custom Haskell data type 'Exp'. It shows how to use 'put' and 'get' to serialize and deserialize the data, including handling different data constructors with tag bytes.

```Haskell
{-# LANGUAGE CPP #}
{-# LANGUAGE Trustworthy #}
-----------------------------------------------------------------------------
-- | 
-- Module      : Data.Binary
-- Copyright   : Lennart Kolmodin
-- License     : BSD3-style (see LICENSE)
-- 
-- Maintainer  : Lennart Kolmodin <kolmodin@gmail.com>
-- Stability   : unstable
-- Portability : portable to Hugs and GHC. Requires the FFI and some flexible instances.
-- 
-- Binary serialisation of Haskell values to and from lazy 'ByteString's.
-- 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 'GBinaryGet' and
-- 'GBinaryPut'.
-- 
-- 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".
-- 
-----------------------------------------------------------------------------

module Data.Binary ( 

    -- * The Binary class
      Binary(..)
    -- ** Example
    -- $example

    -- * Generic support
    -- $generics
    , GBinaryGet(..)
    , GBinaryPut(..)

    -- * The Get and Put monads
    , Get
    , Put

    -- * Useful helpers for writing instances
    , putWord8
    , getWord8

    -- * Binary serialisation
    , encode                    -- :: Binary a => a -> ByteString
    , decode                    -- :: Binary a => ByteString -> a
    , decodeOrFail

    -- * IO functions for serialisation
    , encodeFile                -- :: Binary a => FilePath -> a -> IO ()
    , decodeFile                -- :: Binary a => FilePath -> IO a
    , decodeFileOrFail

    , module Data.Word -- useful

    ) where

import Data.Word

import Data.Binary.Class
import Data.Binary.Put
import Data.Binary.Get
import Data.Binary.Generic ()

import qualified Data.ByteString as B ( hGet, length )
import Data.ByteString.Lazy (ByteString)
import qualified Data.ByteString.Lazy as L
import qualified Data.ByteString.Lazy.Internal as L ( defaultChunkSize )
import System.IO ( withBinaryFile, IOMode(ReadMode) )

------------------------------------------------------------------------

-- $example
-- 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:
-- 

```

--------------------------------

### Haskell Functor Instance for Get

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Implements the Functor typeclass for the Get monad, allowing a function to be mapped over the result of a Get computation using fmapG.

```Haskell
instance Functor Get where
  fmap :: forall a b. (a -> b) -> Get a -> Get b
fmap = (a -> b) -> Get a -> Get b
forall a b. (a -> b) -> Get a -> Get b
fmapG
```

--------------------------------

### Haskell: Labeling Decoders with Get

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get-Internal

Allows adding descriptive labels to decoders. If a labeled decoder fails, its label is appended to the error message, aiding in debugging.

```Haskell
label :: String -> Get a -> Get a Source
```

--------------------------------

### Binary Instance for Fixed

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides serialization and deserialization for `Fixed a` types, introduced in version 0.8.0.0. The type `a` must be an instance of `Binary`. The instance includes `put`, `get`, and `putList` methods.

```Haskell
Binary (Fixed a) Source #| _Since: 0.8.0.0_  
Instance detailsDefined in Data.Binary.Class Methodsput :: Fixed a -> Put Source #get :: Get (Fixed a) Source #putList :: [Fixed a] -> Put Source #
```

--------------------------------

### Push Front Input Buffer

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

The `pushFront` function prepends a ByteString chunk to the input buffer. This allows for inserting data at the beginning of the buffer, effectively making it the next data to be processed.

```Haskell
pushFront :: ByteString -> Get ()
pushFront ByteString
bs = (forall r. ByteString -> Success () r -> Decoder r) -> Get ()
forall a.
(forall r. ByteString -> Success a r -> Decoder r) -> Get a
C ((forall r. ByteString -> Success () r -> Decoder r) -> Get ()) 
-> (forall r. ByteString -> Success () r -> Decoder r) -> Get ()

```

--------------------------------

### Haskell Get Monad: Map Function (fmapG)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

The fmapG function applies a pure function to the result of a Get computation. It's used to implement the Functor fmap operator for the Get monad.

```Haskell
fmapG :: (a -> b) -> Get a -> Get b
fmapG :: forall a b. (a -> b) -> Get a -> Get b
fmapG a -> b
f Get a
m = (forall r. ByteString -> Success b r -> Decoder r) -> Get b
forall a.
(forall r. ByteString -> Success a r -> Decoder r) -> Get a
C ((forall r. ByteString -> Success b r -> Decoder r) -> Get b)
-> (forall r. ByteString -> Success b r -> Decoder r) -> Get b
forall a b. (a -> b) -> a -> b
$ \ByteString
i Success b r
ks -> Get a -> forall r. ByteString -> Success a r -> Decoder r
forall a. Get a -> forall r. ByteString -> Success a r -> Decoder r
runCont Get a
m ByteString
i (\ByteString
i' a
a -> Success b r
ks ByteString
i' (a -> b
f a
a))
```

--------------------------------

### Haskell Get Monad: Sequence Functions (apG)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

The apG function sequences two Get computations, applying a function obtained from the first to the result of the second. It's used to implement the Applicative <*> operator for the Get monad.

```Haskell
apG :: Get (a -> b) -> Get a -> Get b
apG Get (a -> b)
d Get a
e = do
  a -> b
b <- Get (a -> b)
d
  a
a <- Get a
e
  b -> Get b
forall a. a -> Get a
forall (m :: * -> *) a. Monad m => a -> m a
return (a -> b
b a
a)
```

--------------------------------

### Haskell: Lazy IO Example for Decoding Trades

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get

Demonstrates a Haskell IO action 'lazyIOExample' that reads binary data from a file named 'trades.bin' using lazy I/O and then decodes a list of 'Trade' structures from the file content using the 'getTrades' decoder.

```Haskell
lazyIOExample :: IO [Trade]
lazyIOExample = do
  input <- BL.readFile "trades.bin"
  return (runGet getTrades input)
```

--------------------------------

### Haskell: Basic ByteString Operations with Get

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get-Internal

Core functions for interacting with ByteStrings in the Get monad. `get` retrieves the current chunk, `put` replaces it, and `ensureN` ensures a minimum number of bytes are available.

```Haskell
failOnEOF :: [ByteString] -> Get a Source
get :: Get ByteString Source
put :: ByteString -> Get () Source
ensureN :: Int -> Get () Source
```

--------------------------------

### Haskell Decoder Loop with `prompt'`

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

The `prompt'` function sets up a loop for decoding ByteStrings in Haskell. It handles partial reads, checks for empty strings, and either continues the loop or calls the provided continuation.

```Haskell
prompt' :: Decoder a -> (B.ByteString -> Decoder a) -> Decoder a
prompt' :: forall a. Decoder a -> (ByteString -> Decoder a) -> Decoder a
prompt' Decoder a
kf ByteString -> Decoder a
ks =
  let loop :: Decoder a
loop = 
        (Maybe ByteString -> Decoder a) -> Decoder a
forall a. (Maybe ByteString -> Decoder a) -> Decoder a
Partial ((Maybe ByteString -> Decoder a) -> Decoder a)
-> (Maybe ByteString -> Decoder a) -> Decoder a
forall a b. (a -> b) -> a -> b
$ \Maybe ByteString
sm ->
          case Maybe ByteString
sm of
            Just ByteString
s | ByteString -> Bool
B.null ByteString
s -> Decoder a
loop
                   | Bool
otherwise -> ByteString -> Decoder a
ks ByteString
s
            Maybe ByteString
Nothing -> Decoder a
kf
  in Decoder a
loop
```

--------------------------------

### Haskell: Incremental Decoding Example

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary-Get

Presents a Haskell function 'incrementalExample' that decodes 'Trade' data structures incrementally from a ByteString. It uses 'runGetIncremental' and a helper function 'go' to process chunks of data, allowing for streaming deserialization.

```Haskell
incrementalExample :: BL.ByteString -> [Trade]
incrementalExample input0 = go decoder input0
  where
    decoder = runGetIncremental getTrade
    go :: Decoder Trade -> BL.ByteString -> [Trade]
    go (Done leftover _consumed trade) input =
      trade : go decoder (BL.chunk leftover input)
    go (Partial k) input                     =
      go (k . takeHeadChunk $ input) (dropHeadChunk input)
    go (Fail _leftover _consumed msg) _input =
      error msg

takeHeadChunk :: BL.ByteString -> Maybe BS.ByteString
takeHeadChunk lbs = 
  case lbs of
    (BL.Chunk bs _) -> Just bs
    _ -> Nothing

dropHeadChunk :: BL.ByteString -> BL.ByteString
dropHeadChunk lbs = 
  case lbs of
    (BL.Chunk _ lbs') -> lbs'
    _ -> BL.Empty
```

--------------------------------

### Haskell Generic Binary Encoding/Decoding

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Provides generic support for deriving Binary instances using Generic programming. GBinaryGet and GBinaryPut classes are used to define generic get and put operations for data types.

```Haskell
class GBinaryGet f where
  gget :: Get (f t)

class GBinaryPut f where
  gput :: f t -> Put

```

--------------------------------

### Binary Instance for Arg

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Enables serialization and deserialization for `Arg a b` types, available since version 0.8.4.0. Both type parameters `a` and `b` must be instances of `Binary`. The instance provides `put`, `get`, and `putList` methods.

```Haskell
(Binary a, Binary b) => Binary (Arg a b) Source #| _Since: 0.8.4.0_  
Instance detailsDefined in Data.Binary.Class Methodsput :: Arg a b -> Put Source #get :: Get (Arg a b) Source #putList :: [Arg a b] -> Put Source #
```

--------------------------------

### Check for Empty Input in Get Monad

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

The isEmpty function determines if the input ByteString in the Get monad is empty. It returns True if empty, indicating all input has been consumed, and False otherwise.

```Haskell
isEmpty :: Get Bool
isEmpty = C $ \inp ks ->
    if B.null inp
      then ks inp True
      else ks inp False
```

--------------------------------

### Handle End-of-File in Get Monad

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

The failOnEOF function checks if all input has been consumed in the Get monad. If the input ByteString is empty, it succeeds; otherwise, it fails with a 'not enough bytes' message.

```Haskell
failOnEOF :: forall a. [ByteString] -> Get a
failOnEOF bs = C $ \_ _ ->
    if B.null bs
      then Fail bs "not enough bytes"
      else Fail bs "not enough bytes"
```

--------------------------------

### Haskell Show Instance for Decoder

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

Provides a 'show' implementation for the Decoder type, allowing its state (Fail, Partial, Done, BytesRead) to be inspected.

```Haskell
instance (Show a) => Show (Decoder a) where
  show :: Decoder a -> String
show (Fail ByteString
_ String
msg) = String
"Fail: " String -> ShowS
forall a. [a] -> [a] -> [a]
++ String
msg
  show (Partial Maybe ByteString -> Decoder a
_) = String
"Partial _"
  show (Done ByteString
_ a
a) = String
"Done: " String -> ShowS
forall a. [a] -> [a] -> [a]
++ a -> String
forall a. Show a => a -> String
show a
a
  show (BytesRead Int64
_ Int64 -> Decoder a
_) = String
"BytesRead"
```

--------------------------------

### Haskell Get Monad: Incremental Parsing (runGetIncremental)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data.Binary.Get

The runGetIncremental function initiates the decoding process for a Get computation. It returns a Decoder, which can then be used to provide input and retrieve the final result or handle errors.

```Haskell
runGetIncremental :: Get a -> Decoder a
runGetIncremental :: forall a. Get a -> Decoder a
runGetIncremental Get a
g = Decoder a -> Decoder a
forall a. Decoder a -> Decoder a
noMeansNo (Decoder a -> Decoder a) -> Decoder a -> Decoder a
forall a b. (a -> b) -> a -> b
$ 
  Get a -> forall r. ByteString -> Success a r -> Decoder r
forall a. Get a -> forall r. ByteString -> Success a r -> Decoder r
runCont Get a
g ByteString
B.empty (\ByteString
i a
a -> Success a a
forall a. ByteString -> a -> Decoder a
Done ByteString
i a
a)
```

--------------------------------

### Encoding and Decoding Data with Binary (Haskell)

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data

Illustrates the usage of 'encode' and 'decode' functions from the Data.Binary library to serialize Haskell data structures into lazy ByteStrings and deserialize them back. It also shows how to write encoded data to a file and read it back.

```Haskell
import Data.Binary
import Data.ByteString.Lazy (ByteString)

-- Assuming 'Exp' is a data type with a 'Binary' instance defined
-- data Exp = IntE Int | OpE String Exp Exp deriving Show

-- Example usage:
-- let e = OpE "*" (IntE 7) (OpE "/" (IntE 4) (IntE 2))
-- let v = encode e
-- decode v :: Exp
-- writeFile "/tmp/exp.txt" (encode e)
-- decodeFile "/tmp/exp.txt" :: IO Exp
```

--------------------------------

### Haskell Binary Serialization with DeriveGeneric

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/src/Data

Demonstrates using the DeriveGeneric extension to automatically derive the Binary instance for a data type. This requires importing Data.Binary and GHC.Generics.

```Haskell
# LANGUAGE DeriveGeneric

import Data.Binary
import GHC.Generics (Generic)

data Foo =
  Foo
  deriving (Generic)

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

--------------------------------

### Haskell Get Monad Operations

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/doc-index

Defines operations for the Get monad, used for parsing binary data. This includes functions for consuming bytes, looking ahead, and handling parsing failures.

```Haskell
getBytes :: Int -> Get ByteString
get :: Get a
consume :: Get ByteString
lookAhead :: Get a -> Get a
lookAheadE :: Get a -> Get (Maybe a)
lookAheadM :: Get a -> Get (Maybe a)
isEmpty :: Get Bool
label :: String -> Get a -> Get a
isolate :: Int -> Get a -> Get a
failOnEOF :: Get a -> Get a
pushChunk :: ByteString -> Get ()
pushChunks :: [ByteString] -> Get ()
pushEndOfInput :: Get ()

```

--------------------------------

### Haskell Get and Put Monads

Source: https://hackage.haskell.org/package/binary-0.8.9.3/docs/Data-Binary

Defines the Get and Put monads for handling binary deserialization and serialization respectively. Put is a type alias for PutM (), representing a computation that produces a sequence of bytes.

```Haskell
data Get a
type Put = PutM ()

```
Tokens:
Raw