| Copyright | (C) 2015-2020 Oleg Grenrus |
|---|---|
| License | BSD3 |
| Maintainer | Oleg Grenrus <oleg.grenrus@iki.fi> |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
Data.Binary.Tagged
Description
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
structuredEncoderecord :: LBS.ByteStringstructuredDecodelbs :: Either String Record
If structure of Record changes in between, deserialisation will fail early.
Synopsis
- structuredEncode :: forall a. (Binary a, Structured a) => a -> ByteString
- structuredEncodeFile :: (Binary a, Structured a) => FilePath -> a -> IO ()
- structuredDecode :: forall a. (Binary a, Structured a) => ByteString -> a
- structuredDecodeOrFailIO :: (Binary a, Structured a) => ByteString -> IO (Either String a)
- structuredDecodeFileOrFail :: (Binary a, Structured a) => FilePath -> IO (Either String a)
- class Typeable a => Structured a where
- structureHash :: Structured a => Proxy a -> MD5
- structureBuilder :: Structure -> Builder
- genericStructure :: (Typeable a, Generic a, GStructured (Rep a)) => Proxy a -> Structure
- class GStructured (f :: Type -> Type)
- nominalStructure :: Typeable a => Proxy a -> Structure
- containerStructure :: (Typeable f, Structured a) => Proxy (f a) -> Structure
- data Structure
- type TypeName = String
- type ConstructorName = String
- type TypeVersion = Word32
- type SopStructure = [(ConstructorName, [Structure])]
- hashStructure :: Structure -> MD5
- typeVersion :: Functor f => (TypeVersion -> f TypeVersion) -> Structure -> f Structure
- typeName :: Functor f => (TypeName -> f TypeName) -> Structure -> f Structure
- type MD5 = Fingerprint
- showMD5 :: MD5 -> String
- md5 :: ByteString -> MD5
- md5FromInteger :: Integer -> MD5
- binaryPutMD5 :: MD5 -> Put
- binaryGetMD5 :: Get MD5
Encoding and decoding
These functions operate like binary's counterparts,
but the serialised version has a structure hash in front.
structuredEncode :: forall a. (Binary a, Structured a) => a -> ByteString Source #
Structured encode.
Encode a value to using binary serialisation to a lazy ByteString.
Encoding starts with 16 byte large structure hash.
structuredEncodeFile :: (Binary a, Structured a) => FilePath -> a -> IO () Source #
Lazily serialise a value to a file
structuredDecode :: forall a. (Binary a, Structured a) => ByteString -> a Source #
Structured decode.
Decode a value from a lazy ByteString, reconstructing the original structure.
Throws pure exception on invalid inputs.
structuredDecodeOrFailIO :: (Binary a, Structured a) => ByteString -> IO (Either String a) Source #
structuredDecodeFileOrFail :: (Binary a, Structured a) => FilePath -> IO (Either String a) Source #
Lazily reconstruct a value previously written to a file.
Structured class
class Typeable a => Structured a where #
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
Since: structured-3.2.0.0
Minimal complete definition
Nothing
Instances
structureHash :: Structured a => Proxy a -> MD5 #
Semantically hashStructure . structure
structureBuilder :: Structure -> Builder #
genericStructure :: (Typeable a, Generic a, GStructured (Rep a)) => Proxy a -> Structure #
Derive structure genrically.
class GStructured (f :: Type -> Type) #
Used to implement genericStructure.
Minimal complete definition
Instances
| (i ~ D, Datatype c, GStructuredSum f) => GStructured (M1 i c f) | |
Defined in Data.Structured.Internal Methods gstructured :: TypeRep -> Proxy (M1 i c f) -> TypeVersion -> Structure # | |
containerStructure :: (Typeable f, Structured a) => Proxy (f a) -> Structure #
Structure type
Structure of a datatype.
It can be infinite, as far as TypeReps involved are finite.
(e.g. polymorphic recursion might cause troubles).
Constructors
| Nominal !TypeRep !TypeVersion TypeName [Structure] | nominal, yet can be parametrised by other structures. |
| Newtype !TypeRep !TypeVersion TypeName Structure | a newtype wrapper |
| Structure !TypeRep !TypeVersion TypeName SopStructure | sum-of-products structure |
Instances
type ConstructorName = String #
type TypeVersion = Word32 #
A sematic version of a data type. Usually 0.
type SopStructure = [(ConstructorName, [Structure])] #
hashStructure :: Structure -> MD5 #
A MD5 hash digest of Structure.
typeVersion :: Functor f => (TypeVersion -> f TypeVersion) -> Structure -> f Structure #
A van-Laarhoven lens into TypeVersion of Structure
typeVersion:: Lens'StructureTypeVersion
MD5
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
md5 :: ByteString -> MD5 #
@since 3.2.0.0
md5FromInteger :: Integer -> 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"
Since: structured-3.4.0.0
binaryPutMD5 :: MD5 -> Put Source #
binaryGetMD5 :: Get MD5 Source #