-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Tagged binary serialisation.
--
-- Structurally tag binary serialisation stream.
--
-- Say you have:
--
-- Say you have a data type
--
--
-- data Record = Record
-- { _recordFields :: HM.HashMap Text (Integer, ByteString)
-- , _recordEnabled :: Bool
-- }
-- deriving (Eq, Show, Generic)
--
-- instance Binary Record
-- instance Structured Record
--
--
-- then you can serialise and deserialise Record values with a
-- structure tag by simply
--
--
-- structuredEncode record :: LBS.ByteString
-- structuredDecode lbs :: IO Record
--
--
-- If structure of Record changes in between, deserialisation
-- will fail early.
--
-- The overhead is next to non-observable.
--
--
-- benchmarking encode/Binary
-- time 352.8 μs (349.5 μs .. 355.9 μs)
--
-- benchmarking encode/Tagged
-- time 350.8 μs (349.0 μs .. 353.1 μs)
--
-- benchmarking decode/Binary
-- time 346.8 μs (344.7 μs .. 349.9 μs)
--
-- benchmarking decode/Tagged
-- time 353.8 μs (352.0 μs .. 355.8 μs)
--
@package binary-tagged
@version 0.3
-- | Structurally tag binary serialisation stream.
--
-- Say you have a data type
--
--
-- data Record = Record
-- { _recordFields :: HM.HashMap Text (Integer, ByteString)
-- , _recordEnabled :: Bool
-- }
-- deriving (Eq, Show, Generic)
--
-- instance Binary Record
-- instance Structured Record
--
--
-- then you can serialise and deserialise Record values with a
-- structure tag by simply
--
--
-- structuredEncode record :: LBS.ByteString
-- structuredDecode lbs :: Either String Record
--
--
-- If structure of Record changes in between, deserialisation
-- will fail early.
module Data.Binary.Tagged
-- | Structured encode. Encode a value to using binary serialisation
-- to a lazy ByteString. Encoding starts with 16 byte large
-- structure hash.
structuredEncode :: forall a. (Binary a, Structured a) => a -> ByteString
-- | Lazily serialise a value to a file
structuredEncodeFile :: (Binary a, Structured a) => FilePath -> a -> IO ()
-- | Structured decode. Decode a value from a lazy
-- ByteString, reconstructing the original structure. Throws pure
-- exception on invalid inputs.
structuredDecode :: forall a. (Binary a, Structured a) => ByteString -> a
structuredDecodeOrFailIO :: (Binary a, Structured a) => ByteString -> IO (Either String a)
-- | Lazily reconstruct a value previously written to a file.
structuredDecodeFileOrFail :: (Binary a, Structured a) => FilePath -> IO (Either String a)
-- | Class of types with a known Structure.
--
-- For regular data types Structured can be derived generically.
--
--
-- data Record = Record { a :: Int, b :: Bool, c :: [Char] } deriving (Generic)
-- instance Structured Record
--
class Typeable a => Structured a
structure :: Structured a => Proxy a -> Structure
-- | Semantically hashStructure . structure.
structureHash :: Structured a => Proxy a -> MD5
-- | Flatten Structure into something we can calculate hash of.
--
-- As Structure can be potentially infinite. For mutually
-- recursive types, we keep track of TypeReps, and put just
-- TypeRep name when it's occurred another time.
structureBuilder :: Structure -> Builder
-- | Derive structure genrically.
genericStructure :: (Typeable a, Generic a, GStructured (Rep a)) => Proxy a -> Structure
-- | Used to implement genericStructure.
class GStructured (f :: Type -> Type)
-- | Use Typeable to infer name
nominalStructure :: Typeable a => Proxy a -> Structure
containerStructure :: (Typeable f, Structured a) => Proxy (f a) -> Structure
-- | Structure of a datatype.
--
-- It can be infinite, as far as TypeReps involved are finite.
-- (e.g. polymorphic recursion might cause troubles).
data Structure
-- | nominal, yet can be parametrised by other structures.
Nominal :: !TypeRep -> !TypeVersion -> TypeName -> [Structure] -> Structure
-- | a newtype wrapper
Newtype :: !TypeRep -> !TypeVersion -> TypeName -> Structure -> Structure
-- | sum-of-products structure
Structure :: !TypeRep -> !TypeVersion -> TypeName -> SopStructure -> Structure
type TypeName = String
type ConstructorName = String
-- | A sematic version of a data type. Usually 0.
type TypeVersion = Word32
type SopStructure = [(ConstructorName, [Structure])]
-- | A MD5 hash digest of Structure.
hashStructure :: Structure -> MD5
-- | A van-Laarhoven lens into TypeVersion of Structure
--
--
-- typeVersion :: Lens' Structure TypeVersion
--
typeVersion :: Functor f => (TypeVersion -> f TypeVersion) -> Structure -> f Structure
-- | A van-Laarhoven lens into TypeName of Structure
--
--
-- typeName :: Lens' Structure TypeName
--
typeName :: Functor f => (TypeName -> f TypeName) -> Structure -> f Structure
type MD5 = Fingerprint
-- | Show MD5 in human readable form
--
--
-- >>> showMD5 (Fingerprint 123 456)
-- "000000000000007b00000000000001c8"
--
--
--
-- >>> showMD5 $ md5 $ BS.pack [0..127]
-- "37eff01866ba3f538421b30b7cbefcac"
--
--
-- @since 3.2.0.0
showMD5 :: MD5 -> String
-- | @since 3.2.0.0
md5 :: ByteString -> MD5
-- |
-- >>> showMD5 $ md5FromInteger 0x37eff01866ba3f538421b30b7cbefcac
-- "37eff01866ba3f538421b30b7cbefcac"
--
--
-- Note: the input is truncated:
--
--
-- >>> showMD5 $ md5FromInteger 0x1230000037eff01866ba3f538421b30b7cbefcac
-- "37eff01866ba3f538421b30b7cbefcac"
--
--
-- Yet, negative numbers are not a problem...
--
--
-- >>> showMD5 $ md5FromInteger (-1)
-- "ffffffffffffffffffffffffffffffff"
--
md5FromInteger :: Integer -> MD5
binaryPutMD5 :: MD5 -> Put
binaryGetMD5 :: Get MD5
instance Data.Structured.Internal.Structured a => Data.Binary.Class.Binary (Data.Binary.Tagged.Tag a)