Z-MessagePack-0.3.0.0: MessagePack
Copyright(c) Dong Han 2019
LicenseBSD
Maintainerwinterland1989@gmail.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Z.Data.MessagePack

Description

This module provides an interface similar to Z.Data.JSON, to work with MessagePack binary format.

  • Maybe a convert to Nil in Nothing case, and a in Just case.
  • Use Int64(signed) or Word64(unsigned) type to marshall int type format, smaller types will sliently truncate when overflow.
  • Use Double to marshall float type format, Float may lost precision.
  • Use Scientific to marshall Ext 0x00/0x01 type.
  • Use SystemTime to marshall Ext 0xFF type.
  • Record's field label are preserved.
  • We use MessagePack extension type -1 to encode/decode SystemTime and UTCTime:

    0xc712-1nanoseconds in 32-bit unsigned intseconds in 64-bit signed int
  • We deliberately use ext type 0x00(positive) and 0x01(negative) to represent large numbers(Integer, Scientific, Fixed, DiffTime...):

    0xc7XXXXXXXX0x00base10 exponent(MessagePack int format)coefficient(big endian 256-base limbs

    Use a MessagePack implementation supporting ext type to marshall it, result value is coefficient * (10 ^ exponent).

The easiest way to use the library is to define target data type, deriving Generic and MessagePack instances, e.g.


import GHC.Generics (Generic)
import qualified Z.Data.MessagePack as MessagePack
import qualified Z.Data.Text as T

data Person = Person {name :: T.Text, age :: Int}
    deriving (Show, Generic)
    deriving anyclass (MessagePack.MessagePack)

> MessagePack.encode Person{ name="Alice", age=16 }
> [130,164,110,97,109,101,165,65,108,105,99,101,163,97,103,101,16]

MessagePack is a schemaless format, which means the encoded data can be recovered into some form(Value in haskell case) without providing data definition, e.g. the data encoded above:

[130,   164,   110,   97,   109,   101,   165,   65,   108,   105,   99,   101,   163,   97,   103,   101,   16]
 0x82   0xA4   'n'    'a'   'm'    'e'    0xA5   'A'   'l'    'i'    'c'   'e'    0xA3   'a'   'g'    'e'    int
 map    str                               str                                     str                        16
 2kvs   4bytes                            5bytes                                  3bytes

This property makes it suitable for passing data across language boundary, e.g. from a static typed language to a dynamic one, at the cost of a lower space efficiency(i.e. type tag and field label).

Synopsis

MessagePack Class

class MessagePack a where Source #

Type class for encode & decode MessagePack.

Minimal complete definition

Nothing

Methods

fromValue :: Value -> Converter a Source #

default fromValue :: (Generic a, GFromValue (Rep a)) => Value -> Converter a Source #

toValue :: a -> Value Source #

default toValue :: (Generic a, GToValue (Rep a)) => a -> Value Source #

encodeMessagePack :: a -> Builder () Source #

default encodeMessagePack :: (Generic a, GEncodeMessagePack (Rep a)) => a -> Builder () Source #

Instances

Instances details
MessagePack Bool Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Char Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Double Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Float Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Int Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Int8 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Int16 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Int32 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Int64 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Integer Source #

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Integer and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Natural Source #

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Natural and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Ordering Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Word Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Word8 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Word16 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Word32 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Word64 Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack () Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack String Source #

This is an INCOHERENT instance, encode String with Str.

Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Version Source #

Only round trip versionBranch as MessagePack array.

Instance details

Defined in Z.Data.MessagePack

MessagePack NominalDiffTime Source #

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype NominalDiffTime and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Z.Data.MessagePack

MessagePack DiffTime Source #

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype DiffTime and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Z.Data.MessagePack

MessagePack Scientific Source #

Note this instance doesn't reject large input

Instance details

Defined in Z.Data.MessagePack.Base

MessagePack ZonedTime Source #
YYYY-MM-DDTHH:MM:SS.SSSZ
Instance details

Defined in Z.Data.MessagePack

MessagePack LocalTime Source #
YYYY-MM-DDTHH:MM:SS.SSSZ
Instance details

Defined in Z.Data.MessagePack

MessagePack UTCTime Source #

MessagePack extension type Ext 0xFF

Instance details

Defined in Z.Data.MessagePack

MessagePack ByteArray Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack CUIntMax Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CIntMax Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CUIntPtr Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CIntPtr Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CSUSeconds Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CUSeconds Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CTime Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CClock Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CSigAtomic Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CWchar Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CSize Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CPtrdiff Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CDouble Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CFloat Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CBool Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CULLong Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CLLong Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CULong Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CLong Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CUInt Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CInt Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CUShort Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CShort Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CUChar Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CSChar Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CChar Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack CBytes Source #

Write CBytes as Bin not Str.

Instance details

Defined in Z.Data.MessagePack.Base

MessagePack FlatIntSet Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Text Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack Bytes Source #

This is an INCOHERENT instance, write Bytes as Bin.

Instance details

Defined in Z.Data.MessagePack.Base

MessagePack SystemTime Source #

MessagePack extension type Ext 0xFF

Instance details

Defined in Z.Data.MessagePack

MessagePack ExitCode Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack IntSet Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack TimeOfDay Source #
HH:MM:SS.SSS
Instance details

Defined in Z.Data.MessagePack

MessagePack CalendarDiffTime Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack DayOfWeek Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack Day Source #
YYYY-MM-DD
Instance details

Defined in Z.Data.MessagePack

MessagePack CalendarDiffDays Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack Value Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack [a] Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (Maybe a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(MessagePack a, Integral a) => MessagePack (Ratio a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (FlatIntMap a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(Ord a, MessagePack a) => MessagePack (FlatSet a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (Vector a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(Prim a, MessagePack a) => MessagePack (PrimVector a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (Array a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (SmallArray a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(Prim a, MessagePack a) => MessagePack (PrimArray a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (Min a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (Max a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (First a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (Last a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (WrappedMonoid a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (Identity a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (First a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (Last a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (Dual a) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack a => MessagePack (NonEmpty a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (IntMap a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (Tree a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

MessagePack a => MessagePack (Seq a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(Ord a, MessagePack a) => MessagePack (Set a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(Eq a, Hashable a, MessagePack a) => MessagePack (HashSet a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(MessagePack a, MessagePack b) => MessagePack (Either a b) Source # 
Instance details

Defined in Z.Data.MessagePack

(MessagePack a, MessagePack b) => MessagePack (a, b) Source # 
Instance details

Defined in Z.Data.MessagePack

Methods

fromValue :: Value -> Converter (a, b) Source #

toValue :: (a, b) -> Value Source #

encodeMessagePack :: (a, b) -> Builder () Source #

(Ord a, MessagePack a, MessagePack b) => MessagePack (FlatMap a b) Source #

default instance prefer later key

Instance details

Defined in Z.Data.MessagePack.Base

(PrimUnlifted a, MessagePack a) => MessagePack (UnliftedArray a) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

HasResolution a => MessagePack (Fixed a) Source #

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Fixed and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Z.Data.MessagePack.Base

MessagePack (Proxy a) Source #

Use Nil as Proxy a

Instance details

Defined in Z.Data.MessagePack.Base

(Ord a, MessagePack a, MessagePack b) => MessagePack (Map a b) Source # 
Instance details

Defined in Z.Data.MessagePack.Base

(Eq a, Hashable a, MessagePack a, MessagePack b) => MessagePack (HashMap a b) Source #

default instance prefer later key

Instance details

Defined in Z.Data.MessagePack.Base

(MessagePack a, MessagePack b, MessagePack c) => MessagePack (a, b, c) Source # 
Instance details

Defined in Z.Data.MessagePack

Methods

fromValue :: Value -> Converter (a, b, c) Source #

toValue :: (a, b, c) -> Value Source #

encodeMessagePack :: (a, b, c) -> Builder () Source #

MessagePack a => MessagePack (Const a b) Source # 
Instance details

Defined in Z.Data.MessagePack

MessagePack b => MessagePack (Tagged a b) Source # 
Instance details

Defined in Z.Data.MessagePack

(MessagePack a, MessagePack b, MessagePack c, MessagePack d) => MessagePack (a, b, c, d) Source # 
Instance details

Defined in Z.Data.MessagePack

Methods

fromValue :: Value -> Converter (a, b, c, d) Source #

toValue :: (a, b, c, d) -> Value Source #

encodeMessagePack :: (a, b, c, d) -> Builder () Source #

(MessagePack (f a), MessagePack (g a)) => MessagePack (Product f g a) Source # 
Instance details

Defined in Z.Data.MessagePack

(MessagePack (f a), MessagePack (g a), MessagePack a) => MessagePack (Sum f g a) Source # 
Instance details

Defined in Z.Data.MessagePack

Methods

fromValue :: Value -> Converter (Sum f g a) Source #

toValue :: Sum f g a -> Value Source #

encodeMessagePack :: Sum f g a -> Builder () Source #

(MessagePack a, MessagePack b, MessagePack c, MessagePack d, MessagePack e) => MessagePack (a, b, c, d, e) Source # 
Instance details

Defined in Z.Data.MessagePack

Methods

fromValue :: Value -> Converter (a, b, c, d, e) Source #

toValue :: (a, b, c, d, e) -> Value Source #

encodeMessagePack :: (a, b, c, d, e) -> Builder () Source #

MessagePack (f (g a)) => MessagePack (Compose f g a) Source # 
Instance details

Defined in Z.Data.MessagePack

(MessagePack a, MessagePack b, MessagePack c, MessagePack d, MessagePack e, MessagePack f) => MessagePack (a, b, c, d, e, f) Source # 
Instance details

Defined in Z.Data.MessagePack

Methods

fromValue :: Value -> Converter (a, b, c, d, e, f) Source #

toValue :: (a, b, c, d, e, f) -> Value Source #

encodeMessagePack :: (a, b, c, d, e, f) -> Builder () Source #

(MessagePack a, MessagePack b, MessagePack c, MessagePack d, MessagePack e, MessagePack f, MessagePack g) => MessagePack (a, b, c, d, e, f, g) Source # 
Instance details

Defined in Z.Data.MessagePack

Methods

fromValue :: Value -> Converter (a, b, c, d, e, f, g) Source #

toValue :: (a, b, c, d, e, f, g) -> Value Source #

encodeMessagePack :: (a, b, c, d, e, f, g) -> Builder () Source #

data Value Source #

Representation of MessagePack data.

Constructors

Bool !Bool

true or false

Int !Int64

an integer

Float !Float

a floating point number

Double !Double

a floating point number

Str !Text

a UTF-8 string

Bin !Bytes

a byte array

Array !(Vector Value)

a sequence of objects

Map !(Vector (Value, Value))

key-value pairs of objects

Ext 

Fields

Nil

nil

Instances

Instances details
Eq Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

Methods

(==) :: Value -> Value -> Bool #

(/=) :: Value -> Value -> Bool #

Ord Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

Methods

compare :: Value -> Value -> Ordering #

(<) :: Value -> Value -> Bool #

(<=) :: Value -> Value -> Bool #

(>) :: Value -> Value -> Bool #

(>=) :: Value -> Value -> Bool #

max :: Value -> Value -> Value #

min :: Value -> Value -> Value #

Show Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

Methods

showsPrec :: Int -> Value -> ShowS #

show :: Value -> String #

showList :: [Value] -> ShowS #

Generic Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

Associated Types

type Rep Value :: Type -> Type #

Methods

from :: Value -> Rep Value x #

to :: Rep Value x -> Value #

Arbitrary Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

Methods

arbitrary :: Gen Value #

shrink :: Value -> [Value] #

Print Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

Methods

toUTF8BuilderP :: Int -> Value -> Builder () #

NFData Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

Methods

rnf :: Value -> () #

MessagePack Value Source # 
Instance details

Defined in Z.Data.MessagePack.Base

type Rep Value Source # 
Instance details

Defined in Z.Data.MessagePack.Value

type Rep Value = D1 ('MetaData "Value" "Z.Data.MessagePack.Value" "Z-MessagePack-0.3.0.0-7KvFiOecrsnKr7xFC1c8Fa" 'False) (((C1 ('MetaCons "Bool" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Bool)) :+: C1 ('MetaCons "Int" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int64))) :+: (C1 ('MetaCons "Float" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Float)) :+: (C1 ('MetaCons "Double" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Double)) :+: C1 ('MetaCons "Str" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Text))))) :+: ((C1 ('MetaCons "Bin" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Bytes)) :+: C1 ('MetaCons "Array" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 (Vector Value)))) :+: (C1 ('MetaCons "Map" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 (Vector (Value, Value)))) :+: (C1 ('MetaCons "Ext" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Word8) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Bytes)) :+: C1 ('MetaCons "Nil" 'PrefixI 'False) (U1 :: Type -> Type)))))

defaultSettings :: Settings Source #

Settings T.pack T.pack False

data Settings Source #

Generic encode/decode Settings

Constructors

Settings 

Fields

snakeCase :: String -> Text #

Snake casing a pascal cased constructor name or camel cased field name, words are always lower cased and separated by an underscore.

trainCase :: String -> Text #

Train casing a pascal cased constructor name or camel cased field name, words are always lower cased and separated by a hyphen.

Encode & Decode

readMessagePackFile :: (HasCallStack, MessagePack a) => CBytes -> IO a Source #

Decode a MessagePack instance from file.

writeMessagePackFile :: (HasCallStack, MessagePack a) => CBytes -> a -> IO () Source #

Encode a MessagePack instance to file.

decode :: MessagePack a => Bytes -> (Bytes, Either DecodeError a) Source #

Decode a MessagePack bytes, return any trailing bytes.

decode' :: MessagePack a => Bytes -> Either DecodeError a Source #

Decode a MessagePack doc, trailing bytes are not allowed.

decodeChunks :: (MessagePack a, Monad m) => m Bytes -> Bytes -> m (Bytes, Either DecodeError a) Source #

Decode MessagePack doc chunks, return trailing bytes.

encode :: MessagePack a => a -> Bytes Source #

Directly encode data to MessagePack bytes.

encodeChunks :: MessagePack a => a -> [Bytes] Source #

Encode data to MessagePack bytes chunks.

type ParseError = [Text] #

Type alias for error message

parse into MessagePack Value

parseValue :: Bytes -> (Bytes, Either ParseError Value) Source #

Parse Value without consuming trailing bytes.

parseValue' :: Bytes -> Either ParseError Value Source #

Parse Value, if there're bytes left, parsing will fail.

parseValueChunks :: Monad m => m Bytes -> Bytes -> m (Bytes, Either ParseError Value) Source #

Increamental parse Value without consuming trailing bytes.

parseValueChunks' :: Monad m => m Bytes -> Bytes -> m (Either ParseError Value) Source #

Increamental parse Value, if there're bytes left, parsing will fail.

Generic FromValue, ToValue & EncodeMessagePack

gToValue :: GToValue f => Settings -> f a -> Value Source #

gFromValue :: GFromValue f => Settings -> Value -> Converter (f a) Source #

gEncodeMessagePack :: GEncodeMessagePack f => Settings -> f a -> Builder () Source #

Convert Value to Haskell data

convertValue :: MessagePack a => Value -> Either ConvertError a Source #

Run a Converter with input value.

newtype Converter a #

Converter provides a monadic interface to convert protocol IR (e.g.Value) to Haskell ADT.

Constructors

Converter 

Fields

Instances

Instances details
Monad Converter 
Instance details

Defined in Z.Data.JSON.Converter

Methods

(>>=) :: Converter a -> (a -> Converter b) -> Converter b #

(>>) :: Converter a -> Converter b -> Converter b #

return :: a -> Converter a #

Functor Converter 
Instance details

Defined in Z.Data.JSON.Converter

Methods

fmap :: (a -> b) -> Converter a -> Converter b #

(<$) :: a -> Converter b -> Converter a #

MonadFail Converter 
Instance details

Defined in Z.Data.JSON.Converter

Methods

fail :: String -> Converter a #

Applicative Converter 
Instance details

Defined in Z.Data.JSON.Converter

Methods

pure :: a -> Converter a #

(<*>) :: Converter (a -> b) -> Converter a -> Converter b #

liftA2 :: (a -> b -> c) -> Converter a -> Converter b -> Converter c #

(*>) :: Converter a -> Converter b -> Converter b #

(<*) :: Converter a -> Converter b -> Converter a #

Alternative Converter 
Instance details

Defined in Z.Data.JSON.Converter

Methods

empty :: Converter a #

(<|>) :: Converter a -> Converter a -> Converter a #

some :: Converter a -> Converter [a] #

many :: Converter a -> Converter [a] #

MonadPlus Converter 
Instance details

Defined in Z.Data.JSON.Converter

Methods

mzero :: Converter a #

mplus :: Converter a -> Converter a -> Converter a #

fail' :: Text -> Converter a #

Text version of fail.

(<?>) :: Converter a -> PathElement -> Converter a infixl 9 #

Add (JSON) Path context to a converter

When converting a complex structure, it helps to annotate (sub)converters with context, so that if an error occurs, you can find its location.

withFlatMapR "Person" $ \o ->
  Person
    <$> o .: "name" <?> Key "name"
    <*> o .: "age" <?> Key "age"

(Standard methods like (.:) already do this.)

With such annotations, if an error occurs, you will get a (JSON) Path location of that error.

prependContext :: Text -> Converter a -> Converter a #

Add context to a failure message, indicating the name of the structure being converted.

prependContext "MyType" (fail "[error message]")
-- Error: "converting MyType failed, [error message]"

data PathElement #

Elements of a (JSON) Value path used to describe the location of an error.

Constructors

Key !Text

Path element of a key into an object, "object.key".

Index !Int

Path element of an index into an array, "array[index]".

Embedded

path of a embedded (JSON) String

Instances

Instances details
Eq PathElement 
Instance details

Defined in Z.Data.JSON.Converter

Ord PathElement 
Instance details

Defined in Z.Data.JSON.Converter

Show PathElement 
Instance details

Defined in Z.Data.JSON.Converter

Generic PathElement 
Instance details

Defined in Z.Data.JSON.Converter

Associated Types

type Rep PathElement :: Type -> Type #

NFData PathElement 
Instance details

Defined in Z.Data.JSON.Converter

Methods

rnf :: PathElement -> () #

type Rep PathElement 
Instance details

Defined in Z.Data.JSON.Converter

type Rep PathElement = D1 ('MetaData "PathElement" "Z.Data.JSON.Converter" "Z-Data-0.6.1.0-JeXatJjxwtL6zC0T0lLei4" 'False) (C1 ('MetaCons "Key" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Text)) :+: (C1 ('MetaCons "Index" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int)) :+: C1 ('MetaCons "Embedded" 'PrefixI 'False) (U1 :: Type -> Type)))

data ConvertError #

Error info with (JSON) Path info.

Constructors

ConvertError 

Fields

Instances

Instances details
Eq ConvertError 
Instance details

Defined in Z.Data.JSON.Converter

Ord ConvertError 
Instance details

Defined in Z.Data.JSON.Converter

Show ConvertError 
Instance details

Defined in Z.Data.JSON.Converter

Generic ConvertError 
Instance details

Defined in Z.Data.JSON.Converter

Associated Types

type Rep ConvertError :: Type -> Type #

Print ConvertError 
Instance details

Defined in Z.Data.JSON.Converter

NFData ConvertError 
Instance details

Defined in Z.Data.JSON.Converter

Methods

rnf :: ConvertError -> () #

type Rep ConvertError 
Instance details

Defined in Z.Data.JSON.Converter

type Rep ConvertError = D1 ('MetaData "ConvertError" "Z.Data.JSON.Converter" "Z-Data-0.6.1.0-JeXatJjxwtL6zC0T0lLei4" 'False) (C1 ('MetaCons "ConvertError" 'PrefixI 'True) (S1 ('MetaSel ('Just "errPath") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [PathElement]) :*: S1 ('MetaSel ('Just "errMsg") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Text)))

typeMismatch Source #

Arguments

:: Text

The name of the type you are trying to convert.

-> Text

The MessagePack value type you expecting to meet.

-> Value

The actual value encountered.

-> Converter a 

Produce an error message like converting XXX failed, expected XXX, encountered XXX.

withKeyValues :: Text -> (Vector (Value, Value) -> Converter a) -> Value -> Converter a Source #

Directly use Map as key-values for further converting.

withFlatMap :: Text -> (FlatMap Value Value -> Converter a) -> Value -> Converter a Source #

Take a Map as an 'FM.FlatMap Value Value', on key duplication prefer first one.

withFlatMapR :: Text -> (FlatMap Value Value -> Converter a) -> Value -> Converter a Source #

Take a Map as an 'FM.FlatMap Value Value', on key duplication prefer last one.

(.:) :: MessagePack a => FlatMap Value Value -> Text -> Converter a Source #

Retrieve the value associated with the given key of an Map. The result is empty if the key is not present or the value cannot be converted to the desired type.

This accessor is appropriate if the key and value must be present in an object for it to be valid. If the key and value are optional, use .:? instead.

(.:?) :: MessagePack a => FlatMap Value Value -> Text -> Converter (Maybe a) Source #

Retrieve the value associated with the given key of an Map. The result is Nothing if the key is not present or if its value is Nil, or fail if the value cannot be converted to the desired type.

This accessor is most useful if the key and value can be absent from an object without affecting its validity. If the key and value are mandatory, use .: instead.

(.:!) :: MessagePack a => FlatMap Value Value -> Text -> Converter (Maybe a) Source #

Retrieve the value associated with the given key of an Map. The result is Nothing if the key is not present or fail if the value cannot be converted to the desired type.

This differs from .:? by attempting to convert Nil the same as any other MessagePack value, instead of interpreting it as Nothing.

convertField Source #

Arguments

:: (Value -> Converter a)

the field converter (value part of a key value pair)

-> FlatMap Value Value 
-> Text 
-> Converter a 

convertFieldMaybe :: (Value -> Converter a) -> FlatMap Value Value -> Text -> Converter (Maybe a) Source #

Variant of .:? with explicit converter function.

convertFieldMaybe' :: (Value -> Converter a) -> FlatMap Value Value -> Text -> Converter (Maybe a) Source #

Variant of .:! with explicit converter function.

Helper for manually writing instance.

(.=) :: MessagePack v => Text -> v -> (Value, Value) infixr 8 Source #

Connect key and value to a tuple to be used with object.

object :: [(Value, Value)] -> Value Source #

Alias for Map . pack.

(.!) :: MessagePack v => Text -> v -> KVItem infixr 8 Source #

Connect key and value to a KVItem using colon, key will be escaped.

object' :: KVItem -> Builder () Source #

Write map header and KVItems.

data KVItem Source #

A newtype for Builder, whose semigroup's instance is to connect kv builder and sum kv length.

Instances

Instances details
Semigroup KVItem Source # 
Instance details

Defined in Z.Data.MessagePack.Base

Orphan instances

MessagePack Version Source #

Only round trip versionBranch as MessagePack array.

Instance details

MessagePack NominalDiffTime Source #

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype NominalDiffTime and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

MessagePack DiffTime Source #

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype DiffTime and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

MessagePack ZonedTime Source #
YYYY-MM-DDTHH:MM:SS.SSSZ
Instance details

MessagePack LocalTime Source #
YYYY-MM-DDTHH:MM:SS.SSSZ
Instance details

MessagePack UTCTime Source #

MessagePack extension type Ext 0xFF

Instance details

MessagePack CUIntMax Source # 
Instance details

MessagePack CIntMax Source # 
Instance details

MessagePack CUIntPtr Source # 
Instance details

MessagePack CIntPtr Source # 
Instance details

MessagePack CSUSeconds Source # 
Instance details

MessagePack CUSeconds Source # 
Instance details

MessagePack CTime Source # 
Instance details

MessagePack CClock Source # 
Instance details

MessagePack CSigAtomic Source # 
Instance details

MessagePack CWchar Source # 
Instance details

MessagePack CSize Source # 
Instance details

MessagePack CPtrdiff Source # 
Instance details

MessagePack CDouble Source # 
Instance details

MessagePack CFloat Source # 
Instance details

MessagePack CBool Source # 
Instance details

MessagePack CULLong Source # 
Instance details

MessagePack CLLong Source # 
Instance details

MessagePack CULong Source # 
Instance details

MessagePack CLong Source # 
Instance details

MessagePack CUInt Source # 
Instance details

MessagePack CInt Source # 
Instance details

MessagePack CUShort Source # 
Instance details

MessagePack CShort Source # 
Instance details

MessagePack CUChar Source # 
Instance details

MessagePack CSChar Source # 
Instance details

MessagePack CChar Source # 
Instance details

MessagePack SystemTime Source #

MessagePack extension type Ext 0xFF

Instance details

MessagePack ExitCode Source # 
Instance details

MessagePack TimeOfDay Source #
HH:MM:SS.SSS
Instance details

MessagePack CalendarDiffTime Source # 
Instance details

MessagePack DayOfWeek Source # 
Instance details

MessagePack Day Source #
YYYY-MM-DD
Instance details

MessagePack CalendarDiffDays Source # 
Instance details

MessagePack a => MessagePack (Min a) Source # 
Instance details

MessagePack a => MessagePack (Max a) Source # 
Instance details

MessagePack a => MessagePack (First a) Source # 
Instance details

MessagePack a => MessagePack (Last a) Source # 
Instance details

MessagePack a => MessagePack (WrappedMonoid a) Source # 
Instance details

MessagePack a => MessagePack (Identity a) Source # 
Instance details

MessagePack a => MessagePack (First a) Source # 
Instance details

MessagePack a => MessagePack (Last a) Source # 
Instance details

MessagePack a => MessagePack (Dual a) Source # 
Instance details

(MessagePack a, MessagePack b) => MessagePack (Either a b) Source # 
Instance details

(MessagePack a, MessagePack b) => MessagePack (a, b) Source # 
Instance details

Methods

fromValue :: Value -> Converter (a, b) Source #

toValue :: (a, b) -> Value Source #

encodeMessagePack :: (a, b) -> Builder () Source #

(MessagePack a, MessagePack b, MessagePack c) => MessagePack (a, b, c) Source # 
Instance details

Methods

fromValue :: Value -> Converter (a, b, c) Source #

toValue :: (a, b, c) -> Value Source #

encodeMessagePack :: (a, b, c) -> Builder () Source #

MessagePack a => MessagePack (Const a b) Source # 
Instance details

MessagePack b => MessagePack (Tagged a b) Source # 
Instance details

(MessagePack a, MessagePack b, MessagePack c, MessagePack d) => MessagePack (a, b, c, d) Source # 
Instance details

Methods

fromValue :: Value -> Converter (a, b, c, d) Source #

toValue :: (a, b, c, d) -> Value Source #

encodeMessagePack :: (a, b, c, d) -> Builder () Source #

(MessagePack (f a), MessagePack (g a)) => MessagePack (Product f g a) Source # 
Instance details

(MessagePack (f a), MessagePack (g a), MessagePack a) => MessagePack (Sum f g a) Source # 
Instance details

Methods

fromValue :: Value -> Converter (Sum f g a) Source #

toValue :: Sum f g a -> Value Source #

encodeMessagePack :: Sum f g a -> Builder () Source #

(MessagePack a, MessagePack b, MessagePack c, MessagePack d, MessagePack e) => MessagePack (a, b, c, d, e) Source # 
Instance details

Methods

fromValue :: Value -> Converter (a, b, c, d, e) Source #

toValue :: (a, b, c, d, e) -> Value Source #

encodeMessagePack :: (a, b, c, d, e) -> Builder () Source #

MessagePack (f (g a)) => MessagePack (Compose f g a) Source # 
Instance details

(MessagePack a, MessagePack b, MessagePack c, MessagePack d, MessagePack e, MessagePack f) => MessagePack (a, b, c, d, e, f) Source # 
Instance details

Methods

fromValue :: Value -> Converter (a, b, c, d, e, f) Source #

toValue :: (a, b, c, d, e, f) -> Value Source #

encodeMessagePack :: (a, b, c, d, e, f) -> Builder () Source #

(MessagePack a, MessagePack b, MessagePack c, MessagePack d, MessagePack e, MessagePack f, MessagePack g) => MessagePack (a, b, c, d, e, f, g) Source # 
Instance details

Methods

fromValue :: Value -> Converter (a, b, c, d, e, f, g) Source #

toValue :: (a, b, c, d, e, f, g) -> Value Source #

encodeMessagePack :: (a, b, c, d, e, f, g) -> Builder () Source #