Copyright	(c) Edward Kmett 2013-2015
License	BSD3
Maintainer	Edward Kmett <ekmett@gmail.com>
Stability	experimental
Portability	non-portable
Safe Haskell	Trustworthy
Language	Haskell98

Data.Bytes.Serial

Contents

Serialization
Specifying endianness
Higher-order
Storable
Generics

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 Source

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.

Minimal complete definition

Nothing

Methods

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

deserialize :: MonadGet m => m a Source

Instances

Serial Bool
Serial Char
Serial Double
Serial Float
Serial Int
Serial Int8
Serial Int16
Serial Int32
Serial Int64
Serial Integer	`>>>` `(runGetL deserialize $ runPutL $ serialize (1822304234^100::Integer))::Integer`115368812579128172803867366576339947332796540054052185472042218522037227934707037623902492207671987696439966697503243972076991940820348847422930433939639982092916577692754723458548819441583937289395076910527534916776189405228720063994377687015476947534961767053653973945346259230972683338173842343243493433367681264359887291905132383269175086733345253389374961758293922003996035662362278340494093804835649459223465051596978792130073960666112508481814461273829244289795707398202762289955919352549768394583446336873179280924584333491364188425976869717125645749497258775598562132278030402205794994603544837805140410310712693778605743100915046769381631247123664460203591228745772887977959388457679427407639421147498028487544882346912935398848298806021505673449774474457435816552278997100556732447852816961683577731381792363312695347606768120122976105200574809419685234274705929886121600174028733812771637390342332436695318974693376
Serial Ordering	`>>>` `runGetL deserialize $ runPutL $ serialize LT::Ordering`LT `>>>` `runGetL deserialize $ runPutL $ serialize EQ::Ordering`EQ `>>>` `runGetL deserialize $ runPutL $ serialize GT::Ordering`GT
Serial Word
Serial Word8
Serial Word16
Serial Word32
Serial Word64
Serial ()
Serial Version
Serial All
Serial Any
Serial ByteString
Serial ByteString
Serial IntSet
Serial Text
Serial Text
Serial AbsoluteTime	`>>>` `(runGetL deserialize $ runPutL $ serialize (addAbsoluteTime 18.2 taiEpoch))::AbsoluteTime`1858-11-17 00:00:18.2 TAI
Serial LocalTime
Serial ZonedTime
Serial TimeOfDay
Serial 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
Serial NominalDiffTime	`>>>` `(runGetL deserialize $ runPutL $ serialize (1.82::DiffTime))::DiffTime`1.82s
Serial Day	`>>>` `(runGetL deserialize $ runPutL $ serialize (ModifiedJulianDay 1))::Day`1858-11-18
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
Serial Void
Serial a => Serial [a]
(Serial a, Integral a) => Serial (Ratio a)	`>>>` `(runGetL deserialize $ runPutL $ serialize (5 % 11::Ratio Int))::Ratio Int`5 % 11
HasResolution a => Serial (Fixed a)	`>>>` `(runGetL deserialize $ runPutL $ serialize (1.82::Fixed E2))::Fixed E2`1.82
Serial a => Serial (ZipList a)
Serial a => Serial (Dual a)
Serial a => Serial (Sum a)
Serial a => Serial (Product a)
Serial a => Serial (First a)
Serial a => Serial (Last a)
Serial a => Serial (Down a)
Serial a => Serial (Maybe a)
Serial v => Serial (IntMap v)
(Serial a, Ord a) => Serial (Set a)
Serial a => Serial (Seq a)
Serial a => Serial (Identity a)
(Bits n, Integral n, Bits (Unsigned n), Integral (Unsigned n)) => Serial (VarInt n)	$setup >>> import Data.Word >>> import Data.Fixed >>> import Data.Bytes.Serial 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"
(Serial a, Serial b) => Serial (Either a b)
(Serial a, Serial b) => Serial (a, b)
(Serial k, Serial v, Ord k) => Serial (Map k v)
Serial (f a) => Serial (Reverse f a)
Serial a => Serial (Constant a b)
(Serial a, Serial b, Serial c) => Serial (a, b, c)
(Serial (f a), Serial (g a)) => Serial (Product f g a)
(Serial a, Serial b, Serial c, Serial d) => Serial (a, b, c, d)
(Serial a, Serial b, Serial c, Serial d, Serial e) => Serial (a, b, c, d, e)

Specifying endianness

class SerialEndian a where Source

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.

Minimal complete definition

Nothing

Methods

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

deserializeBE :: MonadGet m => m a Source

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

deserializeLE :: MonadGet m => m a Source

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

deserializeHost :: MonadGet m => m a Source

Instances

SerialEndian 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 Source

Minimal complete definition

Nothing

Methods

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

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

Instances

Serial1 []
Serial1 Maybe
Serial1 IntMap
Serial1 Seq
Serial a => Serial1 (Either a)
Serial a => Serial1 ((,) a)
(Ord k, Serial k) => Serial1 (Map k)
(Serial a, Serial b) => Serial1 ((,,) a b)
(Serial a, Serial b, Serial c) => Serial1 ((,,,) a b c)
(Serial a, Serial b, Serial c, Serial d) => Serial1 ((,,,,) a b c d)

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

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

class Serial2 f where Source

Methods

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

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

Instances

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

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

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

Storable

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

serialize any Storable in a host-specific format.

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

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 Source

Used internally to provide generic serialization

Methods

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

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

Instances

GSerial V1
GSerial U1
Serial a => GSerial (K1 i a)
(GSerial f, GSerial g) => GSerial ((:+:) f g)
(GSerial f, GSerial g) => GSerial ((:*:) f g)
GSerial f => GSerial (M1 i c f)

class GSerialEndian f where Source

Used internally to provide generic big-endian serialization

Minimal complete definition

Nothing

Methods

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

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

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

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

Instances

SerialEndian a => GSerialEndian (K1 i a)

class GSerial1 f where Source

Used internally to provide generic serialization

Methods

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

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

Instances

GSerial1 V1
GSerial1 U1
GSerial1 Par1
Serial1 f => GSerial1 (Rec1 f)
Serial a => GSerial1 (K1 i a)
(GSerial1 f, GSerial1 g) => GSerial1 ((:+:) f g)
(GSerial1 f, GSerial1 g) => GSerial1 ((:*:) f g)
(Serial1 f, GSerial1 g) => GSerial1 ((:.:) f g)
GSerial1 f => GSerial1 (M1 i c f)