-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Provides tools for serializing data tagged with type information. -- @package tagged-binary @version 0.2.0.0 -- | Internals for the library, exported in case you should need it. -- Usually, the parts you would need should be re-exported in -- Tagged. module Data.Binary.Tagged.Internal -- | A data type tupling together data with a TagFingerprint, -- representing data tagged with its type. -- -- It's best to interface directly with data using encodeTagged, -- decodeTagged, etc, using tag to tag data and -- extractTagged to extract data from valid tagged data. This -- type is exported mostly when you want to specifically decode a -- ByteString into tagged data, and manually extract it yourself. -- If you are writing a framework, it is preferred to handle this for the -- end user. data Tagged a -- | A data type representing a fingerprint for a Typeable type. -- Ideally, this would be Internal's own Fingerprint types; -- however, for some reason, the fingerprints for the same data type from -- the same modules differ between different GHC backends. So for now, it -- is just a ByteString representation of the name of the type. -- This is literally a bad idea, and so two types with the same name but -- from different modules will share a non-unique TagFingerprint. -- Hopefully in the future when I find out a way to fix this or the GHC -- backend maintainers find a way to provide consistent type -- fingerprints, this will be fixed. -- -- This type is mostly used for the ability to categorized Tagged items -- by their type. -- -- emptyTagFP gives a TagFingerprint that will most likely -- never be matched by any actual tag from a real type, so can be used as -- a test if needed. This replaces functionality that used to come from -- the Default instance. data TagFingerprint -- | Wrap data inside a Tagged tuple. tag :: Typeable a => a -> Tagged a -- | Extract data out of a Tagged, but only the type of the data -- matches the type represented by the fingerprint. It is polymorphic on -- its output and meant to be used when decoding a Tagged item -- with a desired type. getTagged :: Typeable a => Tagged a -> Maybe a -- | Check if the type inside the Tagged matches the fingerprint. tagMatched :: Typeable a => Tagged a -> Bool -- | Compute the Fingerprint representing a type. It is non-strict -- on its parameter, so passing in undefined should work if you want to -- just get the Fingerprint of a specific type without having data -- of that type on hand: -- -- 
--   typeFingerprint (undefined :: Int)
--
typeFingerprint :: Typeable a => a -> TagFingerprint -- | Extract the Fingerprint out of a Tagged. Mostly used so -- that you can categorize and associate Tagged items; to check if a -- Tagged is of a desired typed, getTagged and -- tagMatched might be more useful. tagFingerprint :: Tagged a -> TagFingerprint -- | With a ByteString, expecting tagged data, returns the -- Fingerprint that the data is tagged with. Returns -- Nothing if the data is not decodable as tagged data. Might -- accidentally decode untagged data though! bsFingerprint :: ByteString -> Maybe TagFingerprint -- | TagFingerprint that is meant to never be matched by any actual -- normal type's TagFingerprint. emptyTagFP :: TagFingerprint instance Typeable TagFingerprint instance Typeable Tagged instance Show TagFingerprint instance Generic TagFingerprint instance Eq TagFingerprint instance Ord TagFingerprint instance Show a => Show (Tagged a) instance Eq a => Eq (Tagged a) instance Generic (Tagged a) instance Datatype D1TagFingerprint instance Constructor C1_0TagFingerprint instance Datatype D1Tagged instance Constructor C1_0Tagged instance Binary TagLead instance Binary TagFingerprint instance Binary a => Binary (Tagged a) -- | Provides tools for serializing and decoding data into -- ByteString tagged with information about its type. Really, most -- of this should be used by libraries and frameworks and abstracted -- over. Typical use cases are the polymorphic communication channels in -- distributed computing used by Cloud Haskell and distributed-process -- --- data of any type can come through the channel, and the framework -- can chose to ignore, queue, or accept data depending on the type the -- data is tagged with. Designed to work with cross-platform GHC backends -- like ghcjs. -- -- When decoding data, the result is polymorphic, and you should either -- allow GHC to infer what you want somehow somewhere, or specify it -- explicitly. -- -- Quick example: -- -- 
--   > let x = encodeTagged (1 :: Int)
--   > decodeTagged x :: Maybe Bool
--   Nothing
--   > decodeTagged x :: Maybe Int
--   Just 1
--
-- -- The interface is very similar to that of Dynamic. -- -- Also provided here is the internal TagFingerprint data type, so -- that you can categorize, sort, and queue Tagged or -- ByteString based on the types they represent. -- -- It might be significant to note that the current TagFingerprint -- implementation is a little shaky; it's a bit tricky getting all GHC -- platforms to agree on a meaningful TypeRep serialization, and -- we will have a better implementation eventually. For now, it just uses -- an MD5 hash of the string name of the type. So for now, don't -- encode/decode things with the same type name but exist in different -- modules (Text or Text, for example) through the same -- polymorphic channel! This is a bit limiting, admittedly, but until I -- or the backend maintainers find out a way to ensure that type -- fingerprints match up per backend, be aware of this limitation. module Data.Binary.Tagged -- | Encode data into a ByteString with its type data tagged. -- -- Remember that for now, types are distinguished by their string names, -- so two types of the same name in different modules will not have -- unique tags. encodeTagged :: (Binary a, Typeable a) => a -> ByteString -- | Decode tagged data from a ByteString. The return type is -- polymorphic, so it'll attempt to decode it by inferred or specified -- type. -- -- decodeTagged :: (Binary a, Typeable a) => ByteString -> Maybe a -- | With a ByteString, expecting tagged data, returns the -- Fingerprint that the data is tagged with. Returns -- Nothing if the data is not decodable as tagged data. Might -- accidentally decode untagged data though! bsFingerprint :: ByteString -> Maybe TagFingerprint -- | A data type tupling together data with a TagFingerprint, -- representing data tagged with its type. -- -- It's best to interface directly with data using encodeTagged, -- decodeTagged, etc, using tag to tag data and -- extractTagged to extract data from valid tagged data. This -- type is exported mostly when you want to specifically decode a -- ByteString into tagged data, and manually extract it yourself. -- If you are writing a framework, it is preferred to handle this for the -- end user. data Tagged a -- | A data type representing a fingerprint for a Typeable type. -- Ideally, this would be Internal's own Fingerprint types; -- however, for some reason, the fingerprints for the same data type from -- the same modules differ between different GHC backends. So for now, it -- is just a ByteString representation of the name of the type. -- This is literally a bad idea, and so two types with the same name but -- from different modules will share a non-unique TagFingerprint. -- Hopefully in the future when I find out a way to fix this or the GHC -- backend maintainers find a way to provide consistent type -- fingerprints, this will be fixed. -- -- This type is mostly used for the ability to categorized Tagged items -- by their type. -- -- emptyTagFP gives a TagFingerprint that will most likely -- never be matched by any actual tag from a real type, so can be used as -- a test if needed. This replaces functionality that used to come from -- the Default instance. data TagFingerprint -- | Compute the Fingerprint representing a type. It is non-strict -- on its parameter, so passing in undefined should work if you want to -- just get the Fingerprint of a specific type without having data -- of that type on hand: -- -- 
--   typeFingerprint (undefined :: Int)
--
typeFingerprint :: Typeable a => a -> TagFingerprint