packer-messagepack: MessagePack Serialization an Deserialization for Packer

[ bsd3, data, library ] [ Propose Tags ]

This package implements MessagePack on top of the Packer package.


[Skip to Readme]
Versions 0.1.0.0, 0.2.0.0
Dependencies base (>=4.7 && <5), bytestring, containers, packer (>=0.1.9 && <0.2), safe-exceptions, text, unliftio [details]
License BSD-3-Clause
Copyright (c) 2017 Moritz Schulte
Author Moritz Schulte
Maintainer mtesseract@silverratio.net
Category Data
Home page https://github.com/mtesseract/packer-messagepack#readme
Uploaded by mtesseract at Sun Oct 22 15:50:51 UTC 2017
Distributions NixOS:0.2.0.0
Downloads 351 total (9 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-10-22 [all 1 reports]
Hackage Matrix CI

Modules

[Index]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for packer-messagepack-0.2.0.0

[back to package description]

packer-messagepack Hackage version Build Status

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]