-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Binary serialization with version control.
--   
--   An extension to Data.Serialize with built-in version control.
@package safecopy
@version 0.9.3.1

module Data.SafeCopy.Internal

-- | The central mechanism for dealing with version control.
--   
--   This type class specifies what data migrations can happen and how they
--   happen.
class SafeCopy (MigrateFrom a) => Migrate a where type MigrateFrom a where {
    type family MigrateFrom 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.
migrate :: Migrate a => MigrateFrom a -> a

-- | This is a wrapper type used migrating backwards in the chain of
--   compatible types.
newtype Reverse a
Reverse :: a -> Reverse a
[unReverse] :: Reverse a -> a

-- | The kind of a data type determines how it is tagged (if at all).
--   
--   Primitives kinds (see <a>primitive</a>) are not tagged with a version
--   id and hence cannot be extended later.
--   
--   Extensions (see <a>extension</a>) 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.
data Kind a
[Primitive] :: Kind a
[Base] :: Kind a
[Extends] :: (Migrate a) => Proxy (MigrateFrom a) -> Kind a
[Extended] :: (Migrate (Reverse a)) => Kind a -> Kind a
isPrimitive :: Kind a -> Bool

-- | Wrapper for data that was saved without a version tag.
newtype Prim a
Prim :: a -> Prim a
[getPrimitive] :: Prim a -> a

-- | 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 <a>SafeCopy</a> for their types even
--   though <a>getCopy</a> and <a>putCopy</a> can't be used directly. To
--   serialize/parse a data type using <a>SafeCopy</a>, see <a>safeGet</a>
--   and <a>safePut</a>.
class SafeCopy a where version = Version 0 kind = Base internalConsistency = computeConsistency Proxy objectProfile = mkProfile Proxy errorTypeName _ = "<unkown type>" getCopy = contain get putCopy = contain . put

-- | 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'.
version :: SafeCopy a => Version 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
--   <a>extension</a> and the much less used <a>primitive</a>.
kind :: SafeCopy a => Kind 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 <a>safeGet</a>, instead.
getCopy :: SafeCopy a => Contained (Get a)

-- | 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 <a>safeGet</a>, instead.
putCopy :: SafeCopy a => a -> Contained Put

-- | Internal function that should not be overrided. <tt>Consistent</tt>
--   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
--   <a>safeGet</a> or <a>safePut</a> is used.
internalConsistency :: SafeCopy a => Consistency a

-- | Version profile.
objectProfile :: SafeCopy a => Profile a

-- | The name of the type. This is only used in error message strings. Feel
--   free to leave undefined in your instances.
errorTypeName :: SafeCopy a => Proxy a -> String

-- | 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 <a>safeGet</a>, instead.
getCopy :: (SafeCopy a, Serialize a) => Contained (Get a)

-- | 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 <a>safeGet</a>, instead.
putCopy :: (SafeCopy a, Serialize a) => a -> Contained Put
constructGetterFromVersion :: SafeCopy a => Version a -> Kind a -> Either String (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.
safeGet :: SafeCopy a => 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 <a>getSafePut</a>.
getSafeGet :: forall a. SafeCopy a => Get (Get a)

-- | Serialize a data type by first writing out its version tag. This is
--   much simpler than the corresponding <a>safeGet</a> since previous
--   versions don't come into play.
safePut :: SafeCopy a => a -> Put

-- | Serialize the version tag and return the associated putter. This is
--   useful when serializing multiple values with the same version. See
--   <a>getSafeGet</a>.
getSafePut :: forall a. SafeCopy a => PutM (a -> Put)

-- | The extended_base kind lets the system know that there is at least one
--   future version of this type.
extended_extension :: (SafeCopy a, Migrate a, Migrate (Reverse a)) => Kind a

-- | The extended_base kind lets the system know that there is at least one
--   future version of this type.
extended_base :: (Migrate (Reverse 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.
extension :: (SafeCopy a, Migrate a) => Kind a

-- | The default kind. Does not extend any type.
base :: Kind a

-- | Primitive kinds aren't version tagged. This kind is used for small or
--   built-in types that won't change such as <a>Int</a> or <a>Bool</a>.
primitive :: Kind a

-- | A simple numeric version id.
newtype Version a
Version :: Int32 -> Version a
[unVersion] :: Version a -> Int32
castVersion :: Version a -> Version b

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

-- | Place a value in an unbreakable container.
contain :: a -> Contained a
data Profile a
PrimitiveProfile :: Profile a
InvalidProfile :: String -> Profile a
Profile :: Int32 -> [Int32] -> Profile a
[profileCurrentVersion] :: Profile a -> Int32
[profileSupportedVersions] :: Profile a -> [Int32]
mkProfile :: SafeCopy a => Proxy a -> Profile a
data Consistency a
Consistent :: Consistency a
NotConsistent :: String -> Consistency a
availableVersions :: SafeCopy a => Proxy a -> [Int32]
getForwardKind :: (Migrate (Reverse a)) => Kind a -> Kind (MigrateFrom (Reverse a))
validChain :: SafeCopy a => Proxy a -> Bool
checkConsistency :: (SafeCopy a, Monad m) => Proxy a -> m b -> m b
computeConsistency :: SafeCopy a => Proxy a -> Consistency a
isObviouslyConsistent :: Kind a -> Bool
proxyFromConsistency :: Consistency a -> Proxy a
proxyFromKind :: Kind a -> Proxy a
consistentFromProxy :: SafeCopy a => Proxy a -> Consistency a
versionFromProxy :: SafeCopy a => Proxy a -> Version a
versionFromKind :: (SafeCopy a) => Kind a -> Version a
versionFromReverseKind :: (SafeCopy a, SafeCopy (MigrateFrom (Reverse a))) => Kind a -> Version (MigrateFrom (Reverse a))
kindFromProxy :: SafeCopy a => Proxy a -> Kind a
data Proxy a
Proxy :: Proxy a
mkProxy :: a -> Proxy a
asProxyType :: a -> Proxy a -> a

-- | Derive an instance of <a>SafeCopy</a>.
--   
--   When serializing, we put a <tt>Word8</tt> describing the constructor
--   (if the data type has more than one constructor). For each type used
--   in the constructor, we call <a>getSafePut</a> (which immediately
--   serializes the version of the type). Then, for each field in the
--   constructor, we use one of the put functions obtained in the last
--   step.
--   
--   For example, given the data type and the declaration below
--   
--   <pre>
--   data T0 b = T0 b Int
--   deriveSafeCopy 1 'base ''T0
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T0 b) where
--       putCopy (T0 arg1 arg2) = contain $ do put_b   &lt;- getSafePut
--                                             put_Int &lt;- getSafePut
--                                             put_b   arg1
--                                             put_Int arg2
--                                             return ()
--       getCopy = contain $ do get_b   &lt;- getSafeGet
--                              get_Int &lt;- getSafeGet
--                              return T0 &lt;*&gt; get_b &lt;*&gt; get_Int
--       version = 1
--       kind = base
--      
--   </pre>
--   
--   And, should we create another data type as a newer version of
--   <tt>T0</tt>, such as
--   
--   <pre>
--   data T a b = C a a | D b Int
--   deriveSafeCopy 2 'extension ''T
--   
--   instance SafeCopy b =&gt; Migrate (T a b) where
--     type MigrateFrom (T a b) = T0 b
--     migrate (T0 b i) = D b i
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T a b) where
--       putCopy (C arg1 arg2) = contain $ do putWord8 0
--                                            put_a &lt;- getSafePut
--                                            put_a arg1
--                                            put_a arg2
--                                            return ()
--       putCopy (D arg1 arg2) = contain $ do putWord8 1
--                                            put_b   &lt;- getSafePut
--                                            put_Int &lt;- getSafePut
--                                            put_b   arg1
--                                            put_Int arg2
--                                            return ()
--       getCopy = contain $ do tag &lt;- getWord8
--                              case tag of
--                                0 -&gt; do get_a &lt;- getSafeGet
--                                        return C &lt;*&gt; get_a &lt;*&gt; get_a
--                                1 -&gt; do get_b   &lt;- getSafeGet
--                                        get_Int &lt;- getSafeGet
--                                        return D &lt;*&gt; get_b &lt;*&gt; get_Int
--                                _ -&gt; fail $ "Could not identify tag \"" ++
--                                            show tag ++ "\" for type Main.T " ++
--                                            "that has only 2 constructors.  " ++
--                                            "Maybe your data is corrupted?"
--       version = 2
--       kind = extension
--      
--   </pre>
--   
--   Note that by using getSafePut, we saved 4 bytes in the case of the
--   <tt>C</tt> constructor. For <tt>D</tt> and <tt>T0</tt>, we didn't save
--   anything. The instance derived by this function always use at most the
--   same space as those generated by <a>deriveSafeCopySimple</a>, but
--   never more (as we don't call 'getSafePut'/'getSafeGet' for types that
--   aren't needed).
--   
--   Note that you may use <a>deriveSafeCopySimple</a> with one version of
--   your data type and <a>deriveSafeCopy</a> in another version without
--   any problems.
deriveSafeCopy :: Version a -> Name -> Name -> Q [Dec]
deriveSafeCopyIndexedType :: Version a -> Name -> Name -> [Name] -> Q [Dec]

-- | Derive an instance of <a>SafeCopy</a>. The instance derived by this
--   function is simpler than the one derived by <a>deriveSafeCopy</a> in
--   that we always use <a>safePut</a> and <a>safeGet</a> (instead of
--   <a>getSafePut</a> and <a>getSafeGet</a>).
--   
--   When serializing, we put a <tt>Word8</tt> describing the constructor
--   (if the data type has more than one constructor) and, for each field
--   of the constructor, we use <a>safePut</a>.
--   
--   For example, given the data type and the declaration below
--   
--   <pre>
--   data T a b = C a a | D b Int
--   deriveSafeCopySimple 1 'base ''T
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T a b) where
--       putCopy (C arg1 arg2) = contain $ do putWord8 0
--                                            safePut arg1
--                                            safePut arg2
--                                            return ()
--       putCopy (D arg1 arg2) = contain $ do putWord8 1
--                                            safePut arg1
--                                            safePut arg2
--                                            return ()
--       getCopy = contain $ do tag &lt;- getWord8
--                              case tag of
--                                0 -&gt; do return C &lt;*&gt; safeGet &lt;*&gt; safeGet
--                                1 -&gt; do return D &lt;*&gt; safeGet &lt;*&gt; safeGet
--                                _ -&gt; fail $ "Could not identify tag \"" ++
--                                            show tag ++ "\" for type Main.T " ++
--                                            "that has only 2 constructors.  " ++
--                                            "Maybe your data is corrupted?"
--       version = 1
--       kind = base
--      
--   </pre>
--   
--   Using this simpler instance means that you may spend more bytes when
--   serializing data. On the other hand, it is more straightforward and
--   may match any other format you used in the past.
--   
--   Note that you may use <a>deriveSafeCopy</a> with one version of your
--   data type and <a>deriveSafeCopySimple</a> in another version without
--   any problems.
deriveSafeCopySimple :: Version a -> Name -> Name -> Q [Dec]
deriveSafeCopySimpleIndexedType :: Version a -> Name -> Name -> [Name] -> Q [Dec]

-- | Derive an instance of <a>SafeCopy</a>. The instance derived by this
--   function should be compatible with the instance derived by the module
--   <tt>Happstack.Data.SerializeTH</tt> of the <tt>happstack-data</tt>
--   package. The instances use only <a>safePut</a> and <a>safeGet</a> (as
--   do the instances created by <a>deriveSafeCopySimple</a>), but we also
--   always write a <tt>Word8</tt> tag, even if the data type isn't a sum
--   type.
--   
--   For example, given the data type and the declaration below
--   
--   <pre>
--   data T0 b = T0 b Int
--   deriveSafeCopy 1 'base ''T0
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T0 b) where
--       putCopy (T0 arg1 arg2) = contain $ do putWord8 0
--                                             safePut arg1
--                                             safePut arg2
--                                             return ()
--       getCopy = contain $ do tag &lt;- getWord8
--                              case tag of
--                                0 -&gt; do return T0 &lt;*&gt; safeGet &lt;*&gt; safeGet
--                                _ -&gt; fail $ "Could not identify tag \"" ++
--                                            show tag ++ "\" for type Main.T0 " ++
--                                            "that has only 1 constructors.  " ++
--                                            "Maybe your data is corrupted?"
--       version = 1
--       kind = base
--      
--   </pre>
--   
--   This instance always consumes at least the same space as
--   <a>deriveSafeCopy</a> or <a>deriveSafeCopySimple</a>, but may use more
--   because of the useless tag. So we recomend using it only if you really
--   need to read a previous version in this format, and not for newer
--   versions.
--   
--   Note that you may use <a>deriveSafeCopy</a> with one version of your
--   data type and <a>deriveSafeCopyHappstackData</a> in another version
--   without any problems.
deriveSafeCopyHappstackData :: Version a -> Name -> Name -> Q [Dec]
deriveSafeCopyHappstackDataIndexedType :: Version a -> Name -> Name -> [Name] -> Q [Dec]
data DeriveType
Normal :: DeriveType
Simple :: DeriveType
HappstackData :: DeriveType
forceTag :: DeriveType -> Bool
tyVarName :: TyVarBndr -> Name
internalDeriveSafeCopy :: DeriveType -> Version a -> Name -> Name -> Q [Dec]
internalDeriveSafeCopy' :: DeriveType -> Version a -> Name -> Name -> Info -> Q [Dec]
internalDeriveSafeCopyIndexedType :: DeriveType -> Version a -> Name -> Name -> [Name] -> Q [Dec]
internalDeriveSafeCopyIndexedType' :: DeriveType -> Version a -> Name -> Name -> [Name] -> Info -> Q [Dec]
mkPutCopy :: DeriveType -> [(Integer, Con)] -> DecQ
mkGetCopy :: DeriveType -> String -> [(Integer, Con)] -> DecQ
mkSafeFunctions :: String -> Name -> Con -> Q ([StmtQ], Type -> Name)

-- | Follow type synonyms. This allows us to see, for example, that
--   <tt>[Char]</tt> and <tt>String</tt> are the same type and we just need
--   to call <a>getSafePut</a> or <a>getSafeGet</a> once for both.
followSynonyms :: Type -> Q Type
conSize :: Con -> Int
conName :: Con -> Name
conTypes :: Con -> [Type]
typeName :: Type -> String


-- | SafeCopy extends the parsing and serialization capabilities of
--   Data.Serialize to include nested version control. Nested version
--   control means that you can change the definition 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:
--   
--   <pre>
--   type Name     = String
--   type Address  = String
--   data Contacts = Contacts [(Name, Address)]
--   instance SafeCopy Contacts where
--        putCopy (Contacts list) = contain $ safePut list
--        getCopy = contain $ Contacts &lt;$&gt; safeGet
--    
--   </pre>
--   
--   At this point, everything is fine. You get the awesome speed of
--   Data.Serialize together with Haskell's ease of use. However, things
--   quickly take a U-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:
--   
--   <pre>
--   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 &lt;$&gt; 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 &lt;$&gt; safeGet &lt;*&gt; safeGet &lt;*&gt; safeGet
--   
--   data Contacts = Contacts [Contact]
--   instance SafeCopy Contacts where
--        version = 2
--        kind = extension
--        putCopy (Contacts contacts) = contain $ safePut contacts
--        getCopy = contain $ Contacts &lt;$&gt; 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) &lt;- contacts ]
--    
--   </pre>
--   
--   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
--   <tt>Contacts_v0</tt> once you no longer wish to support that legacy
--   format.
module Data.SafeCopy

-- | 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.
safeGet :: SafeCopy a => Get a

-- | Serialize a data type by first writing out its version tag. This is
--   much simpler than the corresponding <a>safeGet</a> since previous
--   versions don't come into play.
safePut :: SafeCopy a => a -> Put

-- | 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 <a>SafeCopy</a> for their types even
--   though <a>getCopy</a> and <a>putCopy</a> can't be used directly. To
--   serialize/parse a data type using <a>SafeCopy</a>, see <a>safeGet</a>
--   and <a>safePut</a>.
class SafeCopy a where version = Version 0 kind = Base internalConsistency = computeConsistency Proxy objectProfile = mkProfile Proxy errorTypeName _ = "<unkown type>" getCopy = contain get putCopy = contain . put

-- | 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'.
version :: SafeCopy a => Version 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
--   <a>extension</a> and the much less used <a>primitive</a>.
kind :: SafeCopy a => Kind 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 <a>safeGet</a>, instead.
getCopy :: SafeCopy a => Contained (Get a)

-- | 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 <a>safeGet</a>, instead.
putCopy :: SafeCopy a => a -> Contained Put

-- | Version profile.
objectProfile :: SafeCopy a => Profile a

-- | The name of the type. This is only used in error message strings. Feel
--   free to leave undefined in your instances.
errorTypeName :: SafeCopy a => Proxy a -> String

-- | 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 <a>safeGet</a>, instead.
getCopy :: (SafeCopy a, Serialize a) => Contained (Get a)

-- | 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 <a>safeGet</a>, instead.
putCopy :: (SafeCopy a, Serialize a) => a -> Contained Put
data Profile a
PrimitiveProfile :: Profile a
InvalidProfile :: String -> Profile a
Profile :: Int32 -> [Int32] -> Profile a
[profileCurrentVersion] :: Profile a -> Int32
[profileSupportedVersions] :: Profile a -> [Int32]

-- | Wrapper for data that was saved without a version tag.
newtype Prim a
Prim :: a -> Prim a
[getPrimitive] :: Prim a -> a

-- | The central mechanism for dealing with version control.
--   
--   This type class specifies what data migrations can happen and how they
--   happen.
class SafeCopy (MigrateFrom a) => Migrate a where type MigrateFrom a where {
    type family MigrateFrom 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.
migrate :: Migrate a => MigrateFrom a -> a

-- | This is a wrapper type used migrating backwards in the chain of
--   compatible types.
newtype Reverse a
Reverse :: a -> Reverse a
[unReverse] :: Reverse a -> a

-- | The kind of a data type determines how it is tagged (if at all).
--   
--   Primitives kinds (see <a>primitive</a>) are not tagged with a version
--   id and hence cannot be extended later.
--   
--   Extensions (see <a>extension</a>) 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.
data 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.
extension :: (SafeCopy a, Migrate a) => Kind a

-- | The extended_base kind lets the system know that there is at least one
--   future version of this type.
extended_extension :: (SafeCopy a, Migrate a, Migrate (Reverse a)) => Kind a

-- | The extended_base kind lets the system know that there is at least one
--   future version of this type.
extended_base :: (Migrate (Reverse a)) => Kind a

-- | The default kind. Does not extend any type.
base :: Kind a

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

-- | Place a value in an unbreakable container.
contain :: a -> Contained a

-- | A simple numeric version id.
data Version a

-- | Derive an instance of <a>SafeCopy</a>.
--   
--   When serializing, we put a <tt>Word8</tt> describing the constructor
--   (if the data type has more than one constructor). For each type used
--   in the constructor, we call <a>getSafePut</a> (which immediately
--   serializes the version of the type). Then, for each field in the
--   constructor, we use one of the put functions obtained in the last
--   step.
--   
--   For example, given the data type and the declaration below
--   
--   <pre>
--   data T0 b = T0 b Int
--   deriveSafeCopy 1 'base ''T0
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T0 b) where
--       putCopy (T0 arg1 arg2) = contain $ do put_b   &lt;- getSafePut
--                                             put_Int &lt;- getSafePut
--                                             put_b   arg1
--                                             put_Int arg2
--                                             return ()
--       getCopy = contain $ do get_b   &lt;- getSafeGet
--                              get_Int &lt;- getSafeGet
--                              return T0 &lt;*&gt; get_b &lt;*&gt; get_Int
--       version = 1
--       kind = base
--      
--   </pre>
--   
--   And, should we create another data type as a newer version of
--   <tt>T0</tt>, such as
--   
--   <pre>
--   data T a b = C a a | D b Int
--   deriveSafeCopy 2 'extension ''T
--   
--   instance SafeCopy b =&gt; Migrate (T a b) where
--     type MigrateFrom (T a b) = T0 b
--     migrate (T0 b i) = D b i
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T a b) where
--       putCopy (C arg1 arg2) = contain $ do putWord8 0
--                                            put_a &lt;- getSafePut
--                                            put_a arg1
--                                            put_a arg2
--                                            return ()
--       putCopy (D arg1 arg2) = contain $ do putWord8 1
--                                            put_b   &lt;- getSafePut
--                                            put_Int &lt;- getSafePut
--                                            put_b   arg1
--                                            put_Int arg2
--                                            return ()
--       getCopy = contain $ do tag &lt;- getWord8
--                              case tag of
--                                0 -&gt; do get_a &lt;- getSafeGet
--                                        return C &lt;*&gt; get_a &lt;*&gt; get_a
--                                1 -&gt; do get_b   &lt;- getSafeGet
--                                        get_Int &lt;- getSafeGet
--                                        return D &lt;*&gt; get_b &lt;*&gt; get_Int
--                                _ -&gt; fail $ "Could not identify tag \"" ++
--                                            show tag ++ "\" for type Main.T " ++
--                                            "that has only 2 constructors.  " ++
--                                            "Maybe your data is corrupted?"
--       version = 2
--       kind = extension
--      
--   </pre>
--   
--   Note that by using getSafePut, we saved 4 bytes in the case of the
--   <tt>C</tt> constructor. For <tt>D</tt> and <tt>T0</tt>, we didn't save
--   anything. The instance derived by this function always use at most the
--   same space as those generated by <a>deriveSafeCopySimple</a>, but
--   never more (as we don't call 'getSafePut'/'getSafeGet' for types that
--   aren't needed).
--   
--   Note that you may use <a>deriveSafeCopySimple</a> with one version of
--   your data type and <a>deriveSafeCopy</a> in another version without
--   any problems.
deriveSafeCopy :: Version a -> Name -> Name -> Q [Dec]
deriveSafeCopyIndexedType :: Version a -> Name -> Name -> [Name] -> Q [Dec]

-- | Derive an instance of <a>SafeCopy</a>. The instance derived by this
--   function is simpler than the one derived by <a>deriveSafeCopy</a> in
--   that we always use <a>safePut</a> and <a>safeGet</a> (instead of
--   <a>getSafePut</a> and <a>getSafeGet</a>).
--   
--   When serializing, we put a <tt>Word8</tt> describing the constructor
--   (if the data type has more than one constructor) and, for each field
--   of the constructor, we use <a>safePut</a>.
--   
--   For example, given the data type and the declaration below
--   
--   <pre>
--   data T a b = C a a | D b Int
--   deriveSafeCopySimple 1 'base ''T
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T a b) where
--       putCopy (C arg1 arg2) = contain $ do putWord8 0
--                                            safePut arg1
--                                            safePut arg2
--                                            return ()
--       putCopy (D arg1 arg2) = contain $ do putWord8 1
--                                            safePut arg1
--                                            safePut arg2
--                                            return ()
--       getCopy = contain $ do tag &lt;- getWord8
--                              case tag of
--                                0 -&gt; do return C &lt;*&gt; safeGet &lt;*&gt; safeGet
--                                1 -&gt; do return D &lt;*&gt; safeGet &lt;*&gt; safeGet
--                                _ -&gt; fail $ "Could not identify tag \"" ++
--                                            show tag ++ "\" for type Main.T " ++
--                                            "that has only 2 constructors.  " ++
--                                            "Maybe your data is corrupted?"
--       version = 1
--       kind = base
--      
--   </pre>
--   
--   Using this simpler instance means that you may spend more bytes when
--   serializing data. On the other hand, it is more straightforward and
--   may match any other format you used in the past.
--   
--   Note that you may use <a>deriveSafeCopy</a> with one version of your
--   data type and <a>deriveSafeCopySimple</a> in another version without
--   any problems.
deriveSafeCopySimple :: Version a -> Name -> Name -> Q [Dec]
deriveSafeCopySimpleIndexedType :: Version a -> Name -> Name -> [Name] -> Q [Dec]

-- | Derive an instance of <a>SafeCopy</a>. The instance derived by this
--   function should be compatible with the instance derived by the module
--   <tt>Happstack.Data.SerializeTH</tt> of the <tt>happstack-data</tt>
--   package. The instances use only <a>safePut</a> and <a>safeGet</a> (as
--   do the instances created by <a>deriveSafeCopySimple</a>), but we also
--   always write a <tt>Word8</tt> tag, even if the data type isn't a sum
--   type.
--   
--   For example, given the data type and the declaration below
--   
--   <pre>
--   data T0 b = T0 b Int
--   deriveSafeCopy 1 'base ''T0
--      
--   </pre>
--   
--   we generate
--   
--   <pre>
--   instance (SafeCopy a, SafeCopy b) =&gt;
--            SafeCopy (T0 b) where
--       putCopy (T0 arg1 arg2) = contain $ do putWord8 0
--                                             safePut arg1
--                                             safePut arg2
--                                             return ()
--       getCopy = contain $ do tag &lt;- getWord8
--                              case tag of
--                                0 -&gt; do return T0 &lt;*&gt; safeGet &lt;*&gt; safeGet
--                                _ -&gt; fail $ "Could not identify tag \"" ++
--                                            show tag ++ "\" for type Main.T0 " ++
--                                            "that has only 1 constructors.  " ++
--                                            "Maybe your data is corrupted?"
--       version = 1
--       kind = base
--      
--   </pre>
--   
--   This instance always consumes at least the same space as
--   <a>deriveSafeCopy</a> or <a>deriveSafeCopySimple</a>, but may use more
--   because of the useless tag. So we recomend using it only if you really
--   need to read a previous version in this format, and not for newer
--   versions.
--   
--   Note that you may use <a>deriveSafeCopy</a> with one version of your
--   data type and <a>deriveSafeCopyHappstackData</a> in another version
--   without any problems.
deriveSafeCopyHappstackData :: Version a -> Name -> Name -> Q [Dec]
deriveSafeCopyHappstackDataIndexedType :: Version a -> Name -> Name -> [Name] -> Q [Dec]

-- | 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 <a>getSafePut</a>.
getSafeGet :: forall a. SafeCopy a => Get (Get a)

-- | Serialize the version tag and return the associated putter. This is
--   useful when serializing multiple values with the same version. See
--   <a>getSafeGet</a>.
getSafePut :: forall a. SafeCopy a => PutM (a -> Put)

-- | Primitive kinds aren't version tagged. This kind is used for small or
--   built-in types that won't change such as <a>Int</a> or <a>Bool</a>.
primitive :: Kind a
