safecopy-0.6.1: Binary serialization with version control.

Portabilitynon-portable (uses GHC extensions)
Maintainerlemmih@gmail.com
Safe HaskellSafe-Infered

Data.SafeCopy.SafeCopy

Description

SafeCopy extends the parsing and serialization capabilities of Data.Binary to include nested version control. Nested version control means that you can change the defintion and binary format of a type nested deep within other types without problems.

Synopsis

Documentation

class SafeCopy (MigrateFrom a) => Migrate a whereSource

The central mechanism for dealing with version control.

This type class specifies what data migrations can happen and how they happen.

Associated Types

type MigrateFrom a Source

This is the type we're extending. Each type capable of migration can only extend one other type.

Methods

migrate :: MigrateFrom a -> aSource

This method specifies how to migrate from the older type to the newer one. It will never be necessary to use this function manually as it all taken care of internally in the library.

data Kind a whereSource

The kind of a data type determines how it is tagged (if at all).

Primitives kinds (see primitive) are not tagged with a version id and hence cannot be extended later.

Extensions (see extension) tells the system that there exists a previous version of the data type which should be migrated if needed.

There is also a default kind which is neither primitive nor is an extension of a previous type.

Constructors

Primitive :: Kind a 
Base :: Kind a 
Extends :: Migrate a => Proxy (MigrateFrom a) -> Kind a 

newtype Prim a Source

Wrapper for data that was saved without a version tag.

Constructors

Prim 

Fields

getPrimitive :: a
 

Instances

class SafeCopy a whereSource

The centerpiece of this library. Defines a version for a data type together with how it should be serialized/parsed.

Users should define instances of SafeCopy for their types even though getCopy and putCopy can't be used directly. To serialize/parse a data type using SafeCopy, see safeGet and safePut.

Methods

version :: Version aSource

The version of the type.

Only used as a key so it must be unique (this is checked at run-time) but doesn't have to be sequential or continuous.

The default version is '0'.

kind :: Kind aSource

The kind specifies how versions are dealt with. By default, values are tagged with their version id and don't have any previous versions. See extension and the much less used primitive.

getCopy :: Contained (Get a)Source

This method defines how a value should be parsed without also worrying about writing out the version tag. This function cannot be used directly. One should use safeGet, instead.

putCopy :: a -> Contained PutSource

This method defines how a value should be parsed without worrying about previous versions or migrations. This function cannot be used directly. One should use safeGet, instead.

internalConsistency :: Consistency aSource

Internal function that should not be overrided. Consistent iff the version history is consistent (i.e. there are no duplicate version numbers) and the chain of migrations is valid.

This function is in the typeclass so that this information is calculated only once during the program lifetime, instead of everytime safeGet or safePut is used.

errorTypeName :: Proxy a -> StringSource

The name of the type. This is only used in error message strings. Feel free to leave undefined in your instances.

Instances

SafeCopy Bool 
SafeCopy Char 
SafeCopy Double 
SafeCopy Float 
SafeCopy Int 
SafeCopy Int8 
SafeCopy Int16 
SafeCopy Int32 
SafeCopy Int64 
SafeCopy Integer 
SafeCopy Ordering 
SafeCopy Word8 
SafeCopy Word16 
SafeCopy Word32 
SafeCopy Word64 
SafeCopy () 
SafeCopy ByteString 
SafeCopy ByteString 
SafeCopy IntSet 
SafeCopy Month 
SafeCopy Day 
SafeCopy ClockTime 
SafeCopy CalendarTime 
SafeCopy TimeDiff 
SafeCopy Text 
SafeCopy Text 
SafeCopy AbsoluteTime 
SafeCopy LocalTime 
SafeCopy ZonedTime 
SafeCopy TimeOfDay 
SafeCopy TimeZone 
SafeCopy UTCTime 
SafeCopy NominalDiffTime 
SafeCopy Day 
SafeCopy UniversalTime 
SafeCopy DiffTime 
SafeCopy a => SafeCopy [a] 
(Integral a, SafeCopy a) => SafeCopy (Ratio a) 
(HasResolution a, Fractional (Fixed a)) => SafeCopy (Fixed a) 
SafeCopy a => SafeCopy (Maybe a) 
SafeCopy a => SafeCopy (Tree a) 
SafeCopy a => SafeCopy (Seq a) 
SafeCopy a => SafeCopy (IntMap a) 
(SafeCopy a, Ord a) => SafeCopy (Set a) 
SafeCopy a => SafeCopy (Prim a) 
(SafeCopy a, SafeCopy b) => SafeCopy (Either a b) 
(SafeCopy a, SafeCopy b) => SafeCopy (a, b) 
(IArray UArray e, Ix i, SafeCopy e, SafeCopy i) => SafeCopy (UArray i e) 
(Ix i, SafeCopy e, SafeCopy i) => SafeCopy (Array i e) 
(SafeCopy a, SafeCopy b, Ord a) => SafeCopy (Map a b) 
(SafeCopy a, SafeCopy b, SafeCopy c) => SafeCopy (a, b, c) 
(SafeCopy a, SafeCopy b, SafeCopy c, SafeCopy d) => SafeCopy (a, b, c, d) 
(SafeCopy a, SafeCopy b, SafeCopy c, SafeCopy d, SafeCopy e) => SafeCopy (a, b, c, d, e) 
(SafeCopy a, SafeCopy b, SafeCopy c, SafeCopy d, SafeCopy e, SafeCopy f) => SafeCopy (a, b, c, d, e, f) 
(SafeCopy a, SafeCopy b, SafeCopy c, SafeCopy d, SafeCopy e, SafeCopy f, SafeCopy g) => SafeCopy (a, b, c, d, e, f, g) 

safeGet :: SafeCopy a => Get aSource

Parse a version tagged data type and then migrate it to the desired type. Any serialized value has been extended by the return type can be parsed.

getSafeGet :: forall a. SafeCopy a => Get (Get a)Source

Parse a version tag and return the corresponding migrated parser. This is useful when you can prove that multiple values have the same version. See getSafePut.

safePut :: SafeCopy a => a -> PutSource

Serialize a data type by first writing out its version tag. This is much simpler than the corresponding safeGet since previous versions don't come into play.

getSafePut :: forall a. SafeCopy a => PutM (a -> Put)Source

Serialize the version tag and return the associated putter. This is useful when serializing multiple values with the same version. See getSafeGet.

extension :: (SafeCopy a, Migrate a) => Kind aSource

The extension kind lets the system know that there is at least one previous version of this type. A given data type can only extend a single other data type. However, it is perfectly fine to build chains of extensions. The migrations between each step is handled automatically.

base :: Kind aSource

The default kind. Does not extend any type.

primitive :: Kind aSource

Primitive kinds aren't version tagged. This kind is used for small or built-in types that won't change such as Int or Bool.

newtype Version a Source

A simple numeric version id.

Constructors

Version 

Fields

unVersion :: Int32
 

Instances

newtype Contained a Source

To ensure that no-one reads or writes values without handling versions correct, it is necessary to restrict access to getCopy and putCopy. This is where Contained enters the picture. It allows you to put values in to a container but not to take them out again.

Constructors

Contained 

Fields

unsafeUnPack :: a
 

contain :: a -> Contained aSource

Place a value in an unbreakable container.

checkConsistency :: (SafeCopy a, Monad m) => Proxy a -> m b -> m bSource

data Proxy a Source

Constructors

Proxy 

asProxyType :: a -> Proxy a -> aSource