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


-- | Prevent serialization backwards compatibility problems using golden tests
--   
--   Tests the serialization backwards compatibility of data types by
--   storing serialized representations in .test files to be checked into
--   your project's version control.
@package armor
@version 0.2

module Armor

-- | Version numbers are simple monotonically increasing positive integers.
newtype Version a
Version :: Word -> Version a
[unVersion] :: Version a -> Word

-- | Core type class for armoring types. Includes a version and all the
--   type's serializations that you want to armor.
class Armored a

-- | Current version number for the data type.
version :: Armored a => Version a

-- | Map of serializations keyed by a unique ID used to refer to each
--   serialization. A serialization is a tuple of <tt>(a -&gt;
--   ByteString)</tt> and <tt>(ByteString -&gt; Maybe a)</tt>. Represented
--   here as a prism.
serializations :: Armored a => Map String (APrism' ByteString a)

-- | The mode of operation for armor test cases.
data ArmorMode

-- | Write test files for serializations that don't have them, but don't do
--   any tests to verify that existing files are deserialized properly.
SaveOnly :: ArmorMode

-- | Run tests to verify that existing files are deserialized properly, but
--   don't write any missing files.
TestOnly :: ArmorMode

-- | Do both the save and test phases.
SaveAndTest :: ArmorMode

-- | Config data for armor tests.
data ArmorConfig
ArmorConfig :: ArmorMode -> FilePath -> Maybe Word -> ArmorConfig
[acArmorMode] :: ArmorConfig -> ArmorMode

-- | Directory where all the test serializations are stored.
[acStoreDir] :: ArmorConfig -> FilePath

-- | How many versions back to test for backwards compatibility. A value of
--   <tt>Just 0</tt> means that it only tests that the current version
--   satisfies <tt>parse . render == id</tt>. <tt>Just 1</tt> means that it
--   will verify that the previous version can still be parse. <tt>Just
--   2</tt> the previous two versions, etc. Nothing means that all versions
--   will be tested.
[acNumVersions] :: ArmorConfig -> Maybe Word

-- | Default value for ArmorConfig.
defArmorConfig :: ArmorConfig

-- | Tests the serialization backwards compatibility of a data type by
--   storing serialized representations in .test files to be checked into
--   your project's version control.
--   
--   First, this function checks the directory <a>acStoreDir</a> for the
--   existence of a file <tt>foo-000.test</tt>. If it doesn't exist, it
--   creates it for each serialization with the serialized representation
--   of the val parameter.
--   
--   Next, it checks that the serialized formats in the most recent
--   <a>acNumVersions</a> of the stored <tt>.test</tt> files are parsable
--   by the current version of the serialization.
testArmor :: (Eq a, Show a, Typeable a, Armored a) => ArmorConfig -> String -> a -> Test

-- | Same as <a>testArmor</a>, but more convenient for testing several
--   values of the same type.
testArmorMany :: (Eq a, Show a, Typeable a, Armored a) => ArmorConfig -> Map String a -> Test

-- | Lower level assertion function that works for a wider array of test
--   frameworks.
testSerialization :: forall a. (Eq a, Show a, Typeable a, Armored a) => ArmorConfig -> (GoldenTest a -> FilePath) -> String -> (String, APrism' ByteString a) -> a -> Assertion

-- | Data structure that holds all the values needed for a golden test
data GoldenTest a
GoldenTest :: a -> String -> String -> APrism' ByteString a -> Version a -> GoldenTest a
[gtTestVal] :: GoldenTest a -> a
[gtValName] :: GoldenTest a -> String
[gtSerializationName] :: GoldenTest a -> String
[gtPrism] :: GoldenTest a -> APrism' ByteString a
[gtVersion] :: GoldenTest a -> Version a

-- | Constructs the FilePath where the serialization will be stored
--   (relative to the base directory defined in ArmorConfig).
--   
--   This function uses typeOf as a part of the directory hierarchy to
--   disambiguate tests for different data types. typeOf can contain single
--   quotes, spaces, and parenthesis in the case of type constructors that
--   have type variables so we only take the first alphanumeric characters
--   so that the paths will be meaningful to humans and then add four
--   characters of the type's hash for disambiguation.
goldenFilePath :: Typeable a => GoldenTest a -> FilePath
instance GHC.Read.Read (Armor.Version a)
instance GHC.Show.Show (Armor.Version a)
instance GHC.Classes.Ord (Armor.Version a)
instance GHC.Classes.Eq (Armor.Version a)
instance GHC.Enum.Bounded Armor.ArmorMode
instance GHC.Enum.Enum Armor.ArmorMode
instance GHC.Read.Read Armor.ArmorMode
instance GHC.Show.Show Armor.ArmorMode
instance GHC.Classes.Ord Armor.ArmorMode
instance GHC.Classes.Eq Armor.ArmorMode