Data.SafeCopy

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.

Consider this scenario. You want to store your contact list on disk and so write the following code:

type Name     = String
type Address  = String
data Contacts = Contacts [(Name, Address)]
instance SafeCopy Contacts where
     putCopy (Contacts list) = contain $ safePut list
     getCopy = contain $ Contacts <$> safeGet

At this point, everything is fine. You get the awesome speed of Data.Binary together with Haskell's easy of use. However, things quickly takes a turn for the worse when you realize that you want to keep phone numbers as well as names and addresses. Being the experienced coder that you are, you see that using a 3-tuple isn't very pretty and you'd rather use a record. At first you fear that this change in structure will invalidate all your old data. Those fears are quickly quelled, though, when you remember how nifty SafeCopy is. With renewed enthusiasm, you set out and write the following code:

type Name = String
type Address = String
type Phone = String

{- We rename our old Contacts structure -}
data Contacts_v0 = Contacts_v0 [(Name, Address)]
instance SafeCopy Contacts_v0 where
     putCopy (Contacts_v0 list) = contain $ safePut list
     getCopy = contain $ Contacts_v0 <$> safeGet

data Contact = Contact { name    :: Name
                        , address :: Address
                        , phone   :: Phone }
instance SafeCopy Contact where
    putCopy Contact{..} = contain $ do safePut name; safePut address; safePut phone
    getCopy = contain $ Contact <$> safeGet <*> safeGet <*> safeGet

data Contacts = Contacts [Contact]
instance SafeCopy Contacts where
     version = 2
     kind = extension
     putCopy (Contacts contacts) = contain $ safePut contacts
     getCopy = contain $ Contacts <$> safeGet

{- Here the magic happens: -}
instance Migrate Contacts where
     type MigrateFrom Contacts = Contacts_v0
     migrate (Contacts_v0 contacts) = Contacts [ Contact{ name    = name
                                                        , address = address
                                                        , phone   = "" }
                                               | (name, address) <- contacts ]

With this, you reflect on your code and you are happy. You feel confident in the safety of your data and you know you can remove Contacts_v0 once you no longer wish to support that legacy format.

Documentation

safeGet :: SafeCopy a => Get a

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.

safePut :: SafeCopy a => a -> Put

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.

class SafeCopy a where

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 through getCopy and putCopy can't be used directly. To serialize/parse a data type using SafeCopy, see safeGet and safePut.

Methods

version :: Version a

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 a

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)

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 Put

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.

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 a => SafeCopy [a]

SafeCopy a => SafeCopy (Maybe a)

SafeCopy a => SafeCopy (IntMap a)

(SafeCopy a, Ord a) => SafeCopy (Set a)

(SafeCopy a, SafeCopy b) => SafeCopy (Either a b)

(SafeCopy a, SafeCopy b) => SafeCopy (a, b)

(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)

class SafeCopy (MigrateFrom a) => Migrate a where

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

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

Methods

migrate :: MigrateFrom a -> a

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

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.

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

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.

data Contained a

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.

contain :: a -> Contained a

Place a value in an unbreakable container.

data Version a

A simple numeric version id.

Instances

Eq (Version a)

Num (Version a)

Read (Version a)

Show (Version a)

Binary (Version a)

Rarely used functions

getSafeGet :: SafeCopy a => Get (Get a)

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.

getSafePut :: SafeCopy a => PutM (a -> Put)

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

primitive :: Kind a

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.