-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Provides tools for serializing data tagged with type
-- information.
--
-- Very minimal library providing tools for serializing and decoding data
-- into ByteString tagged with information about its type,
-- inspired by Cloud Haskell and distributed-process.
--
-- Intended for use by libraries and frameworks in distributed contexts,
-- such as distributed computation between native servers and
-- communication between native servers and ghcjs/various front-ends, for
-- behavior similar to the polymorphic communication channels of Cloud
-- Haskell and distributed-process; servers can send tagged data, and
-- clients can choose to selectively accept, ignore or queue incoming
-- messages depending on their types.
--
-- For basic encoding, decoding and categorization, only
-- Data.Binary.Tagged should be necessary.
-- Data.Binary.Tagged.Internal is exported in case you need it.
--
-- Quick example:
--
--
-- > let x = encodeTagged (1 :: Int)
-- > decodeTagged x :: Maybe Bool
-- Nothing
-- > decodeTagged x :: Maybe Int
-- Just 1
--
@package tagged-binary
@version 0.2.0.1
-- | Internals for the library, exported in case you should need it.
-- Usually, the parts you would need should be re-exported in
-- Data.Binary.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 GHC.Generics.Generic (Data.Binary.Tagged.Internal.Tagged a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Data.Binary.Tagged.Internal.Tagged a)
instance GHC.Show.Show a => GHC.Show.Show (Data.Binary.Tagged.Internal.Tagged a)
instance GHC.Classes.Ord Data.Binary.Tagged.Internal.TagFingerprint
instance GHC.Classes.Eq Data.Binary.Tagged.Internal.TagFingerprint
instance GHC.Generics.Generic Data.Binary.Tagged.Internal.TagFingerprint
instance GHC.Show.Show Data.Binary.Tagged.Internal.TagFingerprint
instance Data.Binary.Class.Binary a => Data.Binary.Class.Binary (Data.Binary.Tagged.Internal.Tagged a)
instance Data.Binary.Class.Binary Data.Binary.Tagged.Internal.TagFingerprint
instance Data.Binary.Class.Binary Data.Binary.Tagged.Internal.TagLead
-- | 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 Data.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 (Data.Text.Text or Data.Text.Lazy.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.
--
--
-- - If the data is not decoded, Nothing is returned.
-- - If successfully decoded data is tagged with a Fingerprint
-- not matching the desired type, Nothing is also returned.
-- - If the data is successfully decoded *and* the tagged
-- Fingerprint matches the desired type, Just x is
-- returned, where x is the originally encoded data (with its
-- tag stripped).
--
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