packer-messagepack

About

This package provides MessagePack serialization / deserialization built on top of Packer.

More precisely, this package exposes the following:

• the type class ToMsgPack:

class ToMsgPack a where
  toMsgPack :: a -> Packing ()
  msgPackSize :: MonadThrow m => a -> m Int64

• the type class FromMsgPack:

class FromMsgPack a where
  fromMsgPack :: Unpacking a

• the type Object:

data Object = ObjectString Text
            | ObjectBinary ByteString
            | ObjectUInt Word64
            | ObjectInt Int64
            | ObjectBool Bool
            | ObjectFloat32 Float
            | ObjectFloat64 Double
            | ObjectArray [Object]
            | ObjectMap (Map Object Object)
            | ObjectNil

• Instances for the following types:

  • Bool

  • Int

  • Word8

  • Word16

  • Word32

  • Word64

  • Int8

  • Int16

  • Int32

  • Int64

  • Float

  • Double

  • ByteString

  • Text

  • Object

  • Furthermore there are instances for

    • lists [a], if the type a is an instance of FromMsgPack resp. ToMsgPack.

    • maps Map k v if the types k and v are instances of FromMsgPack resp. ToMsgPack.

Usage

For example, to serialize a number into a MessagePack encoded ByteString, use:

let n = 2342 :: Int
size <- msgPackSize n
let bytes = runPacking size (toMsgPack n)

To deserialize a ByteString you can use fromMsgPack specialized to fromMsgPack :: Unpacking Object in case the type of the next MessagePack object is not known. For example:

let obj = runUnpacking fromMsgPack bytes :: Object

On the other hand, if a specific type is expected, fromMsgPack can be used specialized to the respective type as follows:

let n' = runUnpacking fromMsgPack bytes :: Int

Note that a MessagePack signed (resp. unsigned) integer can be as big as an Int64 (resp. Word64). Therefore, if you want to make sure that there are no overflow problems, use Int64 (resp. Word64) during deserialization. In case of overflows exceptions will be thrown. For example:

let n = (2^62) :: Int64
size <- msgPackSize n
let bytes = runPacking size (toMsgPack n)
    n' = runUnpacking fromMsgPack bytes :: Int32

Because the number 2^62 exceeds the boundaries of Int32, n' will denote a pure exception:

MsgPackDeserializationFailure "Integer Overflow"

Stackage

Currently, Packer is not included in Stackage yet. Therefore, if you would like to use this package together with Stackage, you could pull them in via extra-deps. For example:

extra-deps: [packer-VERSION, packer-messagepack-VERSION]