bytes-0.15.2: Sharing code for serialization between binary and cereal

Copyright(c) Edward Kmett 2013-2015
LicenseBSD3
MaintainerEdward Kmett <ekmett@gmail.com>
Stabilityexperimental
Portabilitynon-portable
Safe HaskellTrustworthy
LanguageHaskell98

Data.Bytes.Serial

Contents

Description

This module contains two main classes, each providing methods to serialize and deserialize types. Serial is the primary class, to be used for the canonical way to serialize a specific type. SerialEndian is used to provide endian-specific methods for serializing a type.

Synopsis

Serialization

class Serial a where #

Methods to serialize and deserialize type a to a binary representation

Instances provided here for fixed-with Integers and Words are big endian. Instances for strict and lazy bytestrings store also the length of bytestring big endian. Instances for Word and Int are host endian as they are machine-specific types.

Methods

serialize :: MonadPut m => a -> m () #

serialize :: (MonadPut m, GSerial (Rep a), Generic a) => a -> m () #

deserialize :: MonadGet m => m a #

deserialize :: (MonadGet m, GSerial (Rep a), Generic a) => m a #

Instances

Serial Bool # 

Methods

serialize :: MonadPut m => Bool -> m () #

deserialize :: MonadGet m => m Bool #

Serial Char # 

Methods

serialize :: MonadPut m => Char -> m () #

deserialize :: MonadGet m => m Char #

Serial Double # 

Methods

serialize :: MonadPut m => Double -> m () #

deserialize :: MonadGet m => m Double #

Serial Float # 

Methods

serialize :: MonadPut m => Float -> m () #

deserialize :: MonadGet m => m Float #

Serial Int # 

Methods

serialize :: MonadPut m => Int -> m () #

deserialize :: MonadGet m => m Int #

Serial Int8 # 

Methods

serialize :: MonadPut m => Int8 -> m () #

deserialize :: MonadGet m => m Int8 #

Serial Int16 # 

Methods

serialize :: MonadPut m => Int16 -> m () #

deserialize :: MonadGet m => m Int16 #

Serial Int32 # 

Methods

serialize :: MonadPut m => Int32 -> m () #

deserialize :: MonadGet m => m Int32 #

Serial Int64 # 

Methods

serialize :: MonadPut m => Int64 -> m () #

deserialize :: MonadGet m => m Int64 #

Serial Integer #
>>> (runGetL deserialize $ runPutL $ serialize (1822304234^100::Integer))::Integer
115368812579128172803867366576339947332796540054052185472042218522037227934707037623902492207671987696439966697503243972076991940820348847422930433939639982092916577692754723458548819441583937289395076910527534916776189405228720063994377687015476947534961767053653973945346259230972683338173842343243493433367681264359887291905132383269175086733345253389374961758293922003996035662362278340494093804835649459223465051596978792130073960666112508481814461273829244289795707398202762289955919352549768394583446336873179280924584333491364188425976869717125645749497258775598562132278030402205794994603544837805140410310712693778605743100915046769381631247123664460203591228745772887977959388457679427407639421147498028487544882346912935398848298806021505673449774474457435816552278997100556732447852816961683577731381792363312695347606768120122976105200574809419685234274705929886121600174028733812771637390342332436695318974693376

Methods

serialize :: MonadPut m => Integer -> m () #

deserialize :: MonadGet m => m Integer #

Serial Ordering #
>>> runGetL deserialize $ runPutL $ serialize LT::Ordering
LT
>>> runGetL deserialize $ runPutL $ serialize EQ::Ordering
EQ
>>> runGetL deserialize $ runPutL $ serialize GT::Ordering
GT

Methods

serialize :: MonadPut m => Ordering -> m () #

deserialize :: MonadGet m => m Ordering #

Serial Word # 

Methods

serialize :: MonadPut m => Word -> m () #

deserialize :: MonadGet m => m Word #

Serial Word8 # 

Methods

serialize :: MonadPut m => Word8 -> m () #

deserialize :: MonadGet m => m Word8 #

Serial Word16 # 

Methods

serialize :: MonadPut m => Word16 -> m () #

deserialize :: MonadGet m => m Word16 #

Serial Word32 # 

Methods

serialize :: MonadPut m => Word32 -> m () #

deserialize :: MonadGet m => m Word32 #

Serial Word64 # 

Methods

serialize :: MonadPut m => Word64 -> m () #

deserialize :: MonadGet m => m Word64 #

Serial () # 

Methods

serialize :: MonadPut m => () -> m () #

deserialize :: MonadGet m => m () #

Serial Natural #
>>> runGetL deserialize (runPutL (serialize (10^10::Natural))) :: Natural
10000000000

Methods

serialize :: MonadPut m => Natural -> m () #

deserialize :: MonadGet m => m Natural #

Serial Void # 

Methods

serialize :: MonadPut m => Void -> m () #

deserialize :: MonadGet m => m Void #

Serial Version # 

Methods

serialize :: MonadPut m => Version -> m () #

deserialize :: MonadGet m => m Version #

Serial All # 

Methods

serialize :: MonadPut m => All -> m () #

deserialize :: MonadGet m => m All #

Serial Any # 

Methods

serialize :: MonadPut m => Any -> m () #

deserialize :: MonadGet m => m Any #

Serial ByteString # 

Methods

serialize :: MonadPut m => ByteString -> m () #

deserialize :: MonadGet m => m ByteString #

Serial ByteString # 

Methods

serialize :: MonadPut m => ByteString -> m () #

deserialize :: MonadGet m => m ByteString #

Serial IntSet # 

Methods

serialize :: MonadPut m => IntSet -> m () #

deserialize :: MonadGet m => m IntSet #

Serial Scientific # 

Methods

serialize :: MonadPut m => Scientific -> m () #

deserialize :: MonadGet m => m Scientific #

Serial Text # 

Methods

serialize :: MonadPut m => Text -> m () #

deserialize :: MonadGet m => m Text #

Serial Text # 

Methods

serialize :: MonadPut m => Text -> m () #

deserialize :: MonadGet m => m Text #

Serial AbsoluteTime #
>>> (runGetL deserialize $ runPutL $ serialize (addAbsoluteTime 18.2 taiEpoch))::AbsoluteTime
1858-11-17 00:00:18.2 TAI
Serial LocalTime # 

Methods

serialize :: MonadPut m => LocalTime -> m () #

deserialize :: MonadGet m => m LocalTime #

Serial ZonedTime # 

Methods

serialize :: MonadPut m => ZonedTime -> m () #

deserialize :: MonadGet m => m ZonedTime #

Serial TimeOfDay # 

Methods

serialize :: MonadPut m => TimeOfDay -> m () #

deserialize :: MonadGet m => m TimeOfDay #

Serial TimeZone # 

Methods

serialize :: MonadPut m => TimeZone -> m () #

deserialize :: MonadGet m => m TimeZone #

Serial UTCTime #
>>> (runGetL deserialize $ runPutL $ serialize (read "2014-01-01 10:54:42.478031 UTC"::UTCTime))::UTCTime
2014-01-01 10:54:42.478031 UTC

Methods

serialize :: MonadPut m => UTCTime -> m () #

deserialize :: MonadGet m => m UTCTime #

Serial NominalDiffTime #
>>> (runGetL deserialize $ runPutL $ serialize (1.82::DiffTime))::DiffTime
1.82s
Serial Day #
>>> (runGetL deserialize $ runPutL $ serialize (ModifiedJulianDay 1))::Day
1858-11-18

Methods

serialize :: MonadPut m => Day -> m () #

deserialize :: MonadGet m => m Day #

Serial UniversalTime #
>>> getModJulianDate $ (runGetL deserialize $ runPutL $ serialize (ModJulianDate $ 5 % 11)::UniversalTime)
5 % 11
Serial DiffTime #
>>> (runGetL deserialize $ runPutL $ serialize (1.82::DiffTime))::DiffTime
1.82s

Methods

serialize :: MonadPut m => DiffTime -> m () #

deserialize :: MonadGet m => m DiffTime #

Serial a => Serial [a] # 

Methods

serialize :: MonadPut m => [a] -> m () #

deserialize :: MonadGet m => m [a] #

Serial a => Serial (Maybe a) # 

Methods

serialize :: MonadPut m => Maybe a -> m () #

deserialize :: MonadGet m => m (Maybe a) #

(Serial a, Integral a) => Serial (Ratio a) #
>>> (runGetL deserialize $ runPutL $ serialize (5 % 11::Ratio Int))::Ratio Int
5 % 11

Methods

serialize :: MonadPut m => Ratio a -> m () #

deserialize :: MonadGet m => m (Ratio a) #

Serial a => Serial (Identity a) # 

Methods

serialize :: MonadPut m => Identity a -> m () #

deserialize :: MonadGet m => m (Identity a) #

HasResolution a => Serial (Fixed a) #
>>> (runGetL deserialize $ runPutL $ serialize (1.82::Fixed E2))::Fixed E2
1.82

Methods

serialize :: MonadPut m => Fixed a -> m () #

deserialize :: MonadGet m => m (Fixed a) #

Serial a => Serial (ZipList a) # 

Methods

serialize :: MonadPut m => ZipList a -> m () #

deserialize :: MonadGet m => m (ZipList a) #

Serial a => Serial (Dual a) # 

Methods

serialize :: MonadPut m => Dual a -> m () #

deserialize :: MonadGet m => m (Dual a) #

Serial a => Serial (Sum a) # 

Methods

serialize :: MonadPut m => Sum a -> m () #

deserialize :: MonadGet m => m (Sum a) #

Serial a => Serial (Product a) # 

Methods

serialize :: MonadPut m => Product a -> m () #

deserialize :: MonadGet m => m (Product a) #

Serial a => Serial (First a) # 

Methods

serialize :: MonadPut m => First a -> m () #

deserialize :: MonadGet m => m (First a) #

Serial a => Serial (Last a) # 

Methods

serialize :: MonadPut m => Last a -> m () #

deserialize :: MonadGet m => m (Last a) #

Serial a => Serial (Down a) # 

Methods

serialize :: MonadPut m => Down a -> m () #

deserialize :: MonadGet m => m (Down a) #

Serial v => Serial (IntMap v) # 

Methods

serialize :: MonadPut m => IntMap v -> m () #

deserialize :: MonadGet m => m (IntMap v) #

Serial a => Serial (Seq a) # 

Methods

serialize :: MonadPut m => Seq a -> m () #

deserialize :: MonadGet m => m (Seq a) #

(Serial a, Ord a) => Serial (Set a) # 

Methods

serialize :: MonadPut m => Set a -> m () #

deserialize :: MonadGet m => m (Set a) #

(Serial v, Hashable v, Eq v) => Serial (HashSet v) # 

Methods

serialize :: MonadPut m => HashSet v -> m () #

deserialize :: MonadGet m => m (HashSet v) #

(Bits n, Integral n, Bits (Unsigned n), Integral (Unsigned n)) => Serial (VarInt n) #

Integer/Word types serialized to base-128 variable-width ints.

>>> import Data.Monoid (mconcat)
>>> import qualified Data.ByteString.Lazy as BSL
>>> mconcat $ BSL.toChunks $ runPutL $ serialize (97 :: Word64)
"\NUL\NUL\NUL\NUL\NUL\NUL\NULa"
>>> mconcat $ BSL.toChunks $ runPutL $ serialize (97 :: VarInt Word64)
"a"

Methods

serialize :: MonadPut m => VarInt n -> m () #

deserialize :: MonadGet m => m (VarInt n) #

(Serial a, Serial b) => Serial (Either a b) # 

Methods

serialize :: MonadPut m => Either a b -> m () #

deserialize :: MonadGet m => m (Either a b) #

(Serial a, Serial b) => Serial (a, b) # 

Methods

serialize :: MonadPut m => (a, b) -> m () #

deserialize :: MonadGet m => m (a, b) #

(Serial k, Serial v, Ord k) => Serial (Map k v) # 

Methods

serialize :: MonadPut m => Map k v -> m () #

deserialize :: MonadGet m => m (Map k v) #

(Serial k, Serial v, Hashable k, Eq k) => Serial (HashMap k v) # 

Methods

serialize :: MonadPut m => HashMap k v -> m () #

deserialize :: MonadGet m => m (HashMap k v) #

(Serial a, Serial b, Serial c) => Serial (a, b, c) # 

Methods

serialize :: MonadPut m => (a, b, c) -> m () #

deserialize :: MonadGet m => m (a, b, c) #

Serial (f a) => Serial (Reverse * f a) # 

Methods

serialize :: MonadPut m => Reverse * f a -> m () #

deserialize :: MonadGet m => m (Reverse * f a) #

Serial a => Serial (Constant * a b) # 

Methods

serialize :: MonadPut m => Constant * a b -> m () #

deserialize :: MonadGet m => m (Constant * a b) #

(Serial a, Serial b, Serial c, Serial d) => Serial (a, b, c, d) # 

Methods

serialize :: MonadPut m => (a, b, c, d) -> m () #

deserialize :: MonadGet m => m (a, b, c, d) #

(Serial (f a), Serial (g a)) => Serial (Product * f g a) # 

Methods

serialize :: MonadPut m => Product * f g a -> m () #

deserialize :: MonadGet m => m (Product * f g a) #

(Serial a, Serial b, Serial c, Serial d, Serial e) => Serial (a, b, c, d, e) # 

Methods

serialize :: MonadPut m => (a, b, c, d, e) -> m () #

deserialize :: MonadGet m => m (a, b, c, d, e) #

Specifying endianness

class SerialEndian a where #

Methods to serialize and deserialize type a to a big and little endian binary representations. Methods suffixed with "host" are automatically defined to use equal the methods corresponding to the current machine's native endianness, but they can be overridden.

Methods

serializeBE :: MonadPut m => a -> m () #

serializeBE :: (MonadPut m, GSerialEndian (Rep a), Generic a) => a -> m () #

deserializeBE :: MonadGet m => m a #

deserializeBE :: (MonadGet m, GSerialEndian (Rep a), Generic a) => m a #

serializeLE :: MonadPut m => a -> m () #

serializeLE :: (MonadPut m, GSerialEndian (Rep a), Generic a) => a -> m () #

deserializeLE :: MonadGet m => m a #

deserializeLE :: (MonadGet m, GSerialEndian (Rep a), Generic a) => m a #

serializeHost :: MonadPut m => a -> m () #

deserializeHost :: MonadGet m => m a #

Instances

SerialEndian Char # 

Methods

serializeBE :: MonadPut m => Char -> m () #

deserializeBE :: MonadGet m => m Char #

serializeLE :: MonadPut m => Char -> m () #

deserializeLE :: MonadGet m => m Char #

serializeHost :: MonadPut m => Char -> m () #

deserializeHost :: MonadGet m => m Char #

SerialEndian Double # 
SerialEndian Float # 
SerialEndian Int16 # 
SerialEndian Int32 # 
SerialEndian Int64 # 
SerialEndian Word16 # 
SerialEndian Word32 # 
SerialEndian Word64 # 

Higher-order

These classes provide us with the ability to serialize containers that need polymorphic recursion.

class Serial1 f where #

Methods

serializeWith :: MonadPut m => (a -> m ()) -> f a -> m () #

serializeWith :: (MonadPut m, GSerial1 (Rep1 f), Generic1 f) => (a -> m ()) -> f a -> m () #

deserializeWith :: MonadGet m => m a -> m (f a) #

deserializeWith :: (MonadGet m, GSerial1 (Rep1 f), Generic1 f) => m a -> m (f a) #

Instances

Serial1 [] # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> [a] -> m () #

deserializeWith :: MonadGet m => m a -> m [a] #

Serial1 Maybe # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> Maybe a -> m () #

deserializeWith :: MonadGet m => m a -> m (Maybe a) #

Serial1 IntMap # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> IntMap a -> m () #

deserializeWith :: MonadGet m => m a -> m (IntMap a) #

Serial1 Seq # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> Seq a -> m () #

deserializeWith :: MonadGet m => m a -> m (Seq a) #

Serial a => Serial1 (Either a) # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> Either a a -> m () #

deserializeWith :: MonadGet m => m a -> m (Either a a) #

Serial a => Serial1 ((,) a) # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> (a, a) -> m () #

deserializeWith :: MonadGet m => m a -> m (a, a) #

(Ord k, Serial k) => Serial1 (Map k) # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> Map k a -> m () #

deserializeWith :: MonadGet m => m a -> m (Map k a) #

(Hashable k, Eq k, Serial k) => Serial1 (HashMap k) # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> HashMap k a -> m () #

deserializeWith :: MonadGet m => m a -> m (HashMap k a) #

(Serial a, Serial b) => Serial1 ((,,) a b) # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> (a, b, a) -> m () #

deserializeWith :: MonadGet m => m a -> m (a, b, a) #

(Serial a, Serial b, Serial c) => Serial1 ((,,,) a b c) # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> (a, b, c, a) -> m () #

deserializeWith :: MonadGet m => m a -> m (a, b, c, a) #

(Serial a, Serial b, Serial c, Serial d) => Serial1 ((,,,,) a b c d) # 

Methods

serializeWith :: MonadPut m => (a -> m ()) -> (a, b, c, d, a) -> m () #

deserializeWith :: MonadGet m => m a -> m (a, b, c, d, a) #

serialize1 :: (MonadPut m, Serial1 f, Serial a) => f a -> m () #

deserialize1 :: (MonadGet m, Serial1 f, Serial a) => m (f a) #

class Serial2 f where #

Minimal complete definition

serializeWith2, deserializeWith2

Methods

serializeWith2 :: MonadPut m => (a -> m ()) -> (b -> m ()) -> f a b -> m () #

deserializeWith2 :: MonadGet m => m a -> m b -> m (f a b) #

Instances

Serial2 Either # 

Methods

serializeWith2 :: MonadPut m => (a -> m ()) -> (b -> m ()) -> Either a b -> m () #

deserializeWith2 :: MonadGet m => m a -> m b -> m (Either a b) #

Serial2 (,) # 

Methods

serializeWith2 :: MonadPut m => (a -> m ()) -> (b -> m ()) -> (a, b) -> m () #

deserializeWith2 :: MonadGet m => m a -> m b -> m (a, b) #

Serial a => Serial2 ((,,) a) # 

Methods

serializeWith2 :: MonadPut m => (a -> m ()) -> (b -> m ()) -> (a, a, b) -> m () #

deserializeWith2 :: MonadGet m => m a -> m b -> m (a, a, b) #

(Serial a, Serial b) => Serial2 ((,,,) a b) # 

Methods

serializeWith2 :: MonadPut m => (a -> m ()) -> (b -> m ()) -> (a, b, a, b) -> m () #

deserializeWith2 :: MonadGet m => m a -> m b -> m (a, b, a, b) #

(Serial a, Serial b, Serial c) => Serial2 ((,,,,) a b c) # 

Methods

serializeWith2 :: MonadPut m => (a -> m ()) -> (b -> m ()) -> (a, b, c, a, b) -> m () #

deserializeWith2 :: MonadGet m => m a -> m b -> m (a, b, c, a, b) #

serialize2 :: (MonadPut m, Serial2 f, Serial a, Serial b) => f a b -> m () #

deserialize2 :: (MonadGet m, Serial2 f, Serial a, Serial b) => m (f a b) #

Storable

store :: (MonadPut m, Storable a) => a -> m () #

serialize any Storable in a host-specific format.

restore :: forall m a. (MonadGet m, Storable a) => m a #

deserialize any Storable in a host-specific format.

Generics

You probably will never need to care that these exist except they provide us with default definitions for Serial and SerialEndian

class GSerial f where #

Used internally to provide generic serialization

Minimal complete definition

gserialize, gdeserialize

Methods

gserialize :: MonadPut m => f a -> m () #

gdeserialize :: MonadGet m => m (f a) #

Instances

GSerial V1 # 

Methods

gserialize :: MonadPut m => V1 a -> m () #

gdeserialize :: MonadGet m => m (V1 a) #

GSerial U1 # 

Methods

gserialize :: MonadPut m => U1 a -> m () #

gdeserialize :: MonadGet m => m (U1 a) #

Serial a => GSerial (K1 i a) # 

Methods

gserialize :: MonadPut m => K1 i a a -> m () #

gdeserialize :: MonadGet m => m (K1 i a a) #

(GSerial f, GSerial g) => GSerial ((:+:) f g) # 

Methods

gserialize :: MonadPut m => (f :+: g) a -> m () #

gdeserialize :: MonadGet m => m ((f :+: g) a) #

(GSerial f, GSerial g) => GSerial ((:*:) f g) # 

Methods

gserialize :: MonadPut m => (f :*: g) a -> m () #

gdeserialize :: MonadGet m => m ((f :*: g) a) #

GSerial f => GSerial (M1 i c f) # 

Methods

gserialize :: MonadPut m => M1 i c f a -> m () #

gdeserialize :: MonadGet m => m (M1 i c f a) #

class GSerialEndian f where #

Used internally to provide generic big-endian serialization

Methods

gserializeBE :: MonadPut m => f a -> m () #

gserializeBE :: (MonadPut m, GSerial f) => f a -> m () #

gdeserializeBE :: MonadGet m => m (f a) #

gdeserializeBE :: (MonadGet m, GSerial f) => m (f a) #

gserializeLE :: MonadPut m => f a -> m () #

gserializeLE :: (MonadPut m, GSerial f) => f a -> m () #

gdeserializeLE :: MonadGet m => m (f a) #

gdeserializeLE :: (MonadGet m, GSerial f) => m (f a) #

Instances

SerialEndian a => GSerialEndian (K1 i a) # 

Methods

gserializeBE :: MonadPut m => K1 i a a -> m () #

gdeserializeBE :: MonadGet m => m (K1 i a a) #

gserializeLE :: MonadPut m => K1 i a a -> m () #

gdeserializeLE :: MonadGet m => m (K1 i a a) #

class GSerial1 f where #

Used internally to provide generic serialization

Minimal complete definition

gserializeWith, gdeserializeWith

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> f a -> m () #

gdeserializeWith :: MonadGet m => m a -> m (f a) #

Instances

GSerial1 V1 # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> V1 a -> m () #

gdeserializeWith :: MonadGet m => m a -> m (V1 a) #

GSerial1 U1 # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> U1 a -> m () #

gdeserializeWith :: MonadGet m => m a -> m (U1 a) #

GSerial1 Par1 # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> Par1 a -> m () #

gdeserializeWith :: MonadGet m => m a -> m (Par1 a) #

Serial1 f => GSerial1 (Rec1 f) # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> Rec1 f a -> m () #

gdeserializeWith :: MonadGet m => m a -> m (Rec1 f a) #

Serial a => GSerial1 (K1 i a) # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> K1 i a a -> m () #

gdeserializeWith :: MonadGet m => m a -> m (K1 i a a) #

(GSerial1 f, GSerial1 g) => GSerial1 ((:+:) f g) # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> (f :+: g) a -> m () #

gdeserializeWith :: MonadGet m => m a -> m ((f :+: g) a) #

(GSerial1 f, GSerial1 g) => GSerial1 ((:*:) f g) # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> (f :*: g) a -> m () #

gdeserializeWith :: MonadGet m => m a -> m ((f :*: g) a) #

(Serial1 f, GSerial1 g) => GSerial1 ((:.:) f g) # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> (f :.: g) a -> m () #

gdeserializeWith :: MonadGet m => m a -> m ((f :.: g) a) #

GSerial1 f => GSerial1 (M1 i c f) # 

Methods

gserializeWith :: MonadPut m => (a -> m ()) -> M1 i c f a -> m () #

gdeserializeWith :: MonadGet m => m a -> m (M1 i c f a) #