-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Type-safe binary serialization -- -- Binary serialization tagged with type information, allowing for -- typechecking and useful error messages at the receiving site. -- -- This package serves the same purpose as tagged-binary, with a couple -- of key differences: -- -- -- -- For information about usage, see the Data.Binary.Typed.Tutorial -- module. -- -- Performance-wise, here is a value Right (Left <100 chars -- lipsum>) of type Either (Char, Int) (Either String (Maybe -- Integer)) benchmarked using the Hashed64 type -- representation: -- -- -- (local copy) @package binary-typed @version 1.0 -- | Internals, exposed mostly for potential use by testsuites and -- benchmarks. -- -- Not recommended to be used from within other independent -- libraries. module Data.Binary.Typed.Internal -- | A value suitable to be typechecked using the contained extra type -- information. data Typed a -- | Using this data constructor directly is unsafe, as it allows -- construction of ill-typed Typed data. Use the typed -- smart constructor unless you really need Typed. Typed :: TypeInformation -> a -> Typed a -- | Like Typed, but the type information is not checked. Useful to -- read type and value, and do the typechecking externally, as required -- by the caching of decodeTyped. Using typecheck', this -- can be promoted to a proper Typed value. data Typed' a Typed' :: TypeInformation -> a -> Typed' a -- | Type information stored alongside a value to be serialized, so that -- the recipient can do consistency checks. See TypeFormat for -- more detailed information on the fields. data TypeInformation Untyped' :: TypeInformation Hashed5' :: Hash5 -> TypeInformation Hashed32' :: Hash32 -> TypeInformation Hashed64' :: Hash64 -> TypeInformation Shown' :: Hash32 -> String -> TypeInformation Full' :: TypeRep -> TypeInformation -- | Pre-serialized representation of one of the other fields. Cached' :: ByteString -> TypeInformation -- | A 5-bit hash value. -- -- Since TypeInformation needs 3 bit to store the sort of the -- TypeInformation, the remaining 5 bit per Word8 can be -- used to store a hash value at no additional space cost. For this -- reason, it is important that the three rightmost bits of any -- Hashed5 are set to zero, i.e. (.&. 7) is -- id on the contained Word8. -- -- This type intentionally doesn't have a Binary instance, since -- its serialization is part of the TypeInformation Binary -- instance exclusively. newtype Hash5 Hash5 :: Word8 -> Hash5 -- | Smart constructor for Hash5 values. Makes sure the rightmost -- three bits are not set by applying a bit mask to the input. mkHash5 :: Integral a => a -> Hash5 -- | A 32-bit hash value. newtype Hash32 Hash32 :: Word32 -> Hash32 -- | A 64-bit hash value. newtype Hash64 Hash64 :: Word64 -> Hash64 -- | Construct a Typed value using the chosen type format. -- -- Example: -- -- 
--   value = typed Full ("hello", 1 :: Int, 2.34 :: Double)
--   encoded = encode value
--
-- -- The decode site can now verify whether decoding happens with the right -- type. typed :: Typeable a => TypeFormat -> a -> Typed a -- | Create the TypeInformation to be stored inside a Typed -- value from a TypeRep. makeTypeInformation :: TypeFormat -> TypeRep -> TypeInformation -- | Different ways of including/verifying type information of serialized -- messages. data TypeFormat -- | Include no type information. -- -- Untyped :: TypeFormat -- | Like Hashed32, but uses a 5-bit hash value. -- -- Hashed5 :: TypeFormat -- | Compare types by their hash values (using the MurmurHash2 algorithm). -- -- Hashed32 :: TypeFormat -- | Like Hashed32, but uses a 64-bit hash value. -- -- Hashed64 :: TypeFormat -- | Compare String representation of types, obtained by calling -- show on the TypeRep, and also include a hash value (like -- Hashed32). The former is mostly for readable error messages, -- the latter provides better collision resistance. -- -- Shown :: TypeFormat -- | Compare the full representation of a data type. -- -- Full :: TypeFormat -- | Extract which TypeFormat was used to create a certain -- TypeInformation. -- -- If the type is Cached', then the contained information is -- assumed well-formed. In the public API, this is safe to do, since only -- well-typed Typed values can be created in the first place. getFormat :: TypeInformation -> TypeFormat -- | Typecheck a Typed. Returns the (well-typed) input, or an error -- message if the types don't work out. typecheck :: Typeable a => Typed a -> Either String (Typed a) -- | Typecheck a 'Typed\'' value so it can be used as a safe Typed -- value. typecheck' :: Typeable a => Typed' a -> Either String (Typed a) -- | Extract the value of a Typed, i.e. strip off the explicit type -- information. -- -- This function is safe to use for all Typed values created by -- the public API, since all construction sites ensure the actual type -- matches the contained type description. -- -- 
--   erase (typed format x) == x
--
erase :: Typed a -> a -- | Sometimes it can be beneficial to serialize the type information in -- advance, so that the maybe costly serialization step does not have to -- be repeated on every invocation of encode. Preserialization -- comes at a price though, as the directly contained ByteString -- requires its length to be included in the final serialization, -- yielding a 8-byte overhead for the required Int64, and one for -- the tag of what was serialized ("shown or full?"). -- -- This function calculates the serialized version of -- TypeInformation in cases where the required 9 bytes are -- negligible (determined by an arbitrary threshold, currently 10*9 -- bytes). -- -- Used to make encodeTyped more efficient; the source there also -- makes a good usage example. preserialize :: TypeInformation -> TypeInformation -- | TypeRep without the (internal) fingerprint. data TypeRep TypeRep :: TyCon -> [TypeRep] -> TypeRep -- | Strip a TypeRep off the fingerprint. Inverse of -- unStripTypeRep. stripTypeRep :: TypeRep -> TypeRep -- | Add a fingerprint to a TypeRep. Inverse of stripTypeRep. unStripTypeRep :: TypeRep -> TypeRep -- | Hash a TypeRep to a 5-bit digest. hashType5 :: TypeRep -> Hash5 -- | Split a Word8 into the last 3 bit (used to tag the constructor) -- and the first 5 (data payload). Used by the Binary instance of -- TypeInformation. hashed5Split :: Word8 -> (Word8, Hash5) -- | Hash a TypeRep to a 32-bit digest. hashType32 :: TypeRep -> Hash32 -- | Hash a TypeRep to a 64-bit digest. hashType64 :: TypeRep -> Hash64 -- | TyCon without the (internal) fingerprint. data TyCon -- | Package, module, constructor name TyCon :: String -> String -> String -> TyCon -- | Strip a TyCon off the fingerprint. Inverse of -- unStripTyCon. stripTyCon :: TyCon -> TyCon -- | Add a fingerprint to a TyCon. Inverse of stripTyCon. unStripTyCon :: TyCon -> TyCon instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_6TypeInformation instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_5TypeInformation instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_4TypeInformation instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_3TypeInformation instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_2TypeInformation instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_1TypeInformation instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_0TypeInformation instance GHC.Generics.Datatype Data.Binary.Typed.Internal.D1TypeInformation instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_0TypeRep instance GHC.Generics.Datatype Data.Binary.Typed.Internal.D1TypeRep instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_0TyCon instance GHC.Generics.Datatype Data.Binary.Typed.Internal.D1TyCon instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_0Hash64 instance GHC.Generics.Datatype Data.Binary.Typed.Internal.D1Hash64 instance GHC.Generics.Constructor Data.Binary.Typed.Internal.C1_0Hash32 instance GHC.Generics.Datatype Data.Binary.Typed.Internal.D1Hash32 instance GHC.Generics.Generic Data.Binary.Typed.Internal.TypeInformation instance GHC.Show.Show Data.Binary.Typed.Internal.TypeInformation instance GHC.Classes.Ord Data.Binary.Typed.Internal.TypeInformation instance GHC.Classes.Eq Data.Binary.Typed.Internal.TypeInformation instance GHC.Generics.Generic Data.Binary.Typed.Internal.TypeRep instance GHC.Classes.Ord Data.Binary.Typed.Internal.TypeRep instance GHC.Classes.Eq Data.Binary.Typed.Internal.TypeRep instance GHC.Generics.Generic Data.Binary.Typed.Internal.TyCon instance GHC.Classes.Ord Data.Binary.Typed.Internal.TyCon instance GHC.Classes.Eq Data.Binary.Typed.Internal.TyCon instance GHC.Show.Show Data.Binary.Typed.Internal.TypeFormat instance GHC.Classes.Ord Data.Binary.Typed.Internal.TypeFormat instance GHC.Classes.Eq Data.Binary.Typed.Internal.TypeFormat instance GHC.Generics.Generic Data.Binary.Typed.Internal.Hash64 instance GHC.Show.Show Data.Binary.Typed.Internal.Hash64 instance GHC.Classes.Ord Data.Binary.Typed.Internal.Hash64 instance GHC.Classes.Eq Data.Binary.Typed.Internal.Hash64 instance GHC.Generics.Generic Data.Binary.Typed.Internal.Hash32 instance GHC.Show.Show Data.Binary.Typed.Internal.Hash32 instance GHC.Classes.Ord Data.Binary.Typed.Internal.Hash32 instance GHC.Classes.Eq Data.Binary.Typed.Internal.Hash32 instance GHC.Show.Show Data.Binary.Typed.Internal.Hash5 instance GHC.Classes.Ord Data.Binary.Typed.Internal.Hash5 instance GHC.Classes.Eq Data.Binary.Typed.Internal.Hash5 instance Data.Binary.Class.Binary Data.Binary.Typed.Internal.TypeInformation instance Data.Binary.Class.Binary Data.Binary.Typed.Internal.Hash32 instance Data.Binary.Class.Binary Data.Binary.Typed.Internal.Hash64 instance GHC.Show.Show a => GHC.Show.Show (Data.Binary.Typed.Internal.Typed a) instance (Data.Binary.Class.Binary a, Data.Typeable.Internal.Typeable a) => Data.Binary.Class.Binary (Data.Binary.Typed.Internal.Typed a) instance GHC.Show.Show a => GHC.Show.Show (Data.Binary.Typed.Internal.Typed' a) instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Data.Binary.Typed.Internal.Typed' a) instance Data.Binary.Class.Binary Data.Binary.Typed.Internal.TypeRep instance GHC.Show.Show Data.Binary.Typed.Internal.TypeRep instance Data.Digest.Murmur32.Hashable32 Data.Binary.Typed.Internal.TypeRep instance Data.Digest.Murmur64.Hashable64 Data.Binary.Typed.Internal.TypeRep instance Data.Binary.Class.Binary Data.Binary.Typed.Internal.TyCon instance GHC.Show.Show Data.Binary.Typed.Internal.TyCon instance Data.Digest.Murmur32.Hashable32 Data.Binary.Typed.Internal.TyCon instance Data.Digest.Murmur64.Hashable64 Data.Binary.Typed.Internal.TyCon -- | Defines a type-safe Binary instance to ensure data is ecoded -- with the type it was serialized from. -- -- module Data.Binary.Typed -- | A value suitable to be typechecked using the contained extra type -- information. data Typed a -- | Construct a Typed value using the chosen type format. -- -- Example: -- -- 
--   value = typed Full ("hello", 1 :: Int, 2.34 :: Double)
--   encoded = encode value
--
-- -- The decode site can now verify whether decoding happens with the right -- type. typed :: Typeable a => TypeFormat -> a -> Typed a -- | Different ways of including/verifying type information of serialized -- messages. data TypeFormat -- | Include no type information. -- -- Untyped :: TypeFormat -- | Like Hashed32, but uses a 5-bit hash value. -- -- Hashed5 :: TypeFormat -- | Compare types by their hash values (using the MurmurHash2 algorithm). -- -- Hashed32 :: TypeFormat -- | Like Hashed32, but uses a 64-bit hash value. -- -- Hashed64 :: TypeFormat -- | Compare String representation of types, obtained by calling -- show on the TypeRep, and also include a hash value (like -- Hashed32). The former is mostly for readable error messages, -- the latter provides better collision resistance. -- -- Shown :: TypeFormat -- | Compare the full representation of a data type. -- -- Full :: TypeFormat -- | Extract the value of a Typed, i.e. strip off the explicit type -- information. -- -- This function is safe to use for all Typed values created by -- the public API, since all construction sites ensure the actual type -- matches the contained type description. -- -- 
--   erase (typed format x) == x
--
erase :: Typed a -> a -- | Modify the value contained in a Typed, keeping the same sort of -- type representation. In other words, calling mapTyped on -- something that is typed using Hashed will yield a -- Hashed value again. -- -- Note: this destroys preserialized information, so that values -- have to be preserialized again if desired. As a consequence, -- mapTyped id can be used to -- un-preserialize values. mapTyped :: Typeable b => (a -> b) -> Typed a -> Typed b -- | Change the value contained in a Typed, leaving the type -- representation unchanged. This can be useful to avoid recomputation of -- the included type information, and can improve performance -- significantly if many individual messages are serialized. -- -- Can be seen as a more efficient mapTyped in case f is -- an endomorphism (i.e. has type a -> a). reValue :: (a -> a) -> Typed a -> Typed a -- | Change the way a type is represented inside a Typed value. -- -- 
--   reType format x = typed format (erase x)
--
reType :: Typeable a => TypeFormat -> Typed a -> Typed a -- | Sometimes it can be beneficial to serialize the type information in -- advance, so that the maybe costly serialization step does not have to -- be repeated on every invocation of encode. Preserialization -- comes at a price though, as the directly contained ByteString -- requires its length to be included in the final serialization, -- yielding a 8-byte overhead for the required Int64, and one for -- the tag of what was serialized ("shown or full?"). -- -- This function calculates the serialized version of -- TypeInformation in cases where the required 9 bytes are -- negligible (determined by an arbitrary threshold, currently 10*9 -- bytes). -- -- Used to make encodeTyped more efficient; the source there also -- makes a good usage example. preserialize :: TypeInformation -> TypeInformation -- | Encode a Typeable value to ByteString that includes type -- information. This function is useful to create specialized typed -- encoding functions, because the type information is cached and does -- not need to be recalculated on every serialization. -- -- Observationally, encodeTyped format value is -- equivalent to encode (typed format value). -- However, encodeTyped does the type information related -- calculations in advance and shares the results between future -- invocations of it, making it much more efficient to serialize many -- values of the same type. encodeTyped :: (Typeable a, Binary a) => TypeFormat -> a -> ByteString -- | Safely decode data, yielding Either an error String or -- the value. Equivalent to decodeTypedOrFail stripped of the -- non-essential data. Based on decodeTypedOrFail. -- -- 
--   encoded = encodeTyped Full ("hello", 1 :: Int, 2.34 :: Double)
--   
--   -- Right <value>:
--   decodeTyped encoded :: Either String (String, Int, Double)
--   
--   -- Left "Type error: expected (Char, Int, Double), got (String, Int, Double)"
--   decodeTyped encoded :: Either String (Char, Int, Double)
--
decodeTyped :: (Typeable a, Binary a) => ByteString -> Either String a -- | Safely decode data, yielding Either an error String or -- the value, along with meta-information of the consumed binary data. -- -- decodeTypedOrFail :: (Typeable a, Binary a) => ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) -- | Decode a typed value, throwing a descriptive error at runtime -- on failure. Typed cousin of decode. Based on -- decodeTypedOrFail. -- -- 
--   encoded = encodeTyped Full ("hello", 1 :: Int, 2.34 :: Double)
--   
--   -- <value>
--   unsafeDecodeTyped encoded :: (String, Int, Double)
--   
--   -- (Descriptive) runtime error
--   unsafeDecodeTyped encoded :: (Char, Int, Double)
--
unsafeDecodeTyped :: (Typeable a, Binary a) => ByteString -> a -- | This module has the same interface as Data.Binary.Typed, but -- emits debugging messages via Debug.Trace whenever a -- TypeInformation is calculated. This is useful to determine -- whether caching works properly, i.e. if a single serialization point -- emits a lot of caching messages it's worth having a look at. -- -- A simple example to check sharing is to evaluate -- -- 
--   map (encodeTyped Hashed5) "hello world!"
--
-- -- This should print only one debug message "TypeRep/Hashed5 calculated", -- since the encoding function is shared between all invocations. module Data.Binary.Typed.Debug -- | A value suitable to be typechecked using the contained extra type -- information. data Typed a -- | Construct a Typed value using the chosen type format. -- -- Example: -- -- 
--   value = typed Full ("hello", 1 :: Int, 2.34 :: Double)
--   encoded = encode value
--
-- -- The decode site can now verify whether decoding happens with the right -- type. typed :: Typeable a => TypeFormat -> a -> Typed a -- | Different ways of including/verifying type information of serialized -- messages. data TypeFormat -- | Include no type information. -- -- Untyped :: TypeFormat -- | Like Hashed32, but uses a 5-bit hash value. -- -- Hashed5 :: TypeFormat -- | Compare types by their hash values (using the MurmurHash2 algorithm). -- -- Hashed32 :: TypeFormat -- | Like Hashed32, but uses a 64-bit hash value. -- -- Hashed64 :: TypeFormat -- | Compare String representation of types, obtained by calling -- show on the TypeRep, and also include a hash value (like -- Hashed32). The former is mostly for readable error messages, -- the latter provides better collision resistance. -- -- Shown :: TypeFormat -- | Compare the full representation of a data type. -- -- Full :: TypeFormat -- | Extract the value of a Typed, i.e. strip off the explicit type -- information. -- -- This function is safe to use for all Typed values created by -- the public API, since all construction sites ensure the actual type -- matches the contained type description. -- -- 
--   erase (typed format x) == x
--
erase :: Typed a -> a -- | Modify the value contained in a Typed, keeping the same sort of -- type representation. In other words, calling mapTyped on -- something that is typed using Hashed will yield a -- Hashed value again. -- -- Note: this destroys preserialized information, so that values -- have to be preserialized again if desired. As a consequence, -- mapTyped id can be used to -- un-preserialize values. mapTyped :: Typeable b => (a -> b) -> Typed a -> Typed b -- | Change the value contained in a Typed, leaving the type -- representation unchanged. This can be useful to avoid recomputation of -- the included type information, and can improve performance -- significantly if many individual messages are serialized. -- -- Can be seen as a more efficient mapTyped in case f is -- an endomorphism (i.e. has type a -> a). reValue :: (a -> a) -> Typed a -> Typed a -- | Change the way a type is represented inside a Typed value. -- -- 
--   reType format x = typed format (erase x)
--
reType :: Typeable a => TypeFormat -> Typed a -> Typed a -- | Sometimes it can be beneficial to serialize the type information in -- advance, so that the maybe costly serialization step does not have to -- be repeated on every invocation of encode. Preserialization -- comes at a price though, as the directly contained ByteString -- requires its length to be included in the final serialization, -- yielding a 8-byte overhead for the required Int64, and one for -- the tag of what was serialized ("shown or full?"). -- -- This function calculates the serialized version of -- TypeInformation in cases where the required 9 bytes are -- negligible (determined by an arbitrary threshold, currently 10*9 -- bytes). -- -- Used to make encodeTyped more efficient; the source there also -- makes a good usage example. preserialize :: TypeInformation -> TypeInformation -- | Encode a Typeable value to ByteString that includes type -- information. This function is useful to create specialized typed -- encoding functions, because the type information is cached and does -- not need to be recalculated on every serialization. -- -- Observationally, encodeTyped format value is -- equivalent to encode (typed format value). -- However, encodeTyped does the type information related -- calculations in advance and shares the results between future -- invocations of it, making it much more efficient to serialize many -- values of the same type. encodeTyped :: (Typeable a, Binary a) => TypeFormat -> a -> ByteString -- | Safely decode data, yielding Either an error String or -- the value. Equivalent to decodeTypedOrFail stripped of the -- non-essential data. Based on decodeTypedOrFail. -- -- 
--   encoded = encodeTyped Full ("hello", 1 :: Int, 2.34 :: Double)
--   
--   -- Right <value>:
--   decodeTyped encoded :: Either String (String, Int, Double)
--   
--   -- Left "Type error: expected (Char, Int, Double), got (String, Int, Double)"
--   decodeTyped encoded :: Either String (Char, Int, Double)
--
decodeTyped :: (Typeable a, Binary a) => ByteString -> Either String a -- | Safely decode data, yielding Either an error String or -- the value, along with meta-information of the consumed binary data. -- -- decodeTypedOrFail :: (Typeable a, Binary a) => ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) -- | Decode a typed value, throwing a descriptive error at runtime -- on failure. Typed cousin of decode. Based on -- decodeTypedOrFail. -- -- 
--   encoded = encodeTyped Full ("hello", 1 :: Int, 2.34 :: Double)
--   
--   -- <value>
--   unsafeDecodeTyped encoded :: (String, Int, Double)
--   
--   -- (Descriptive) runtime error
--   unsafeDecodeTyped encoded :: (Char, Int, Double)
--
unsafeDecodeTyped :: (Typeable a, Binary a) => ByteString -> a -- | This meta-module exists only for documentational purposes; the library -- functionality is found in Data.Binary.Typed. module Data.Binary.Typed.Tutorial