-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Type-safe binary serialization -- @package binary-typed @version 0.1.0.1 -- | 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 -- | 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 Hashed' :: Hash -> TypeInformation Shown' :: Hash -> String -> TypeInformation Full' :: TypeRep -> TypeInformation Cached' :: ByteString -> TypeInformation -- | A hash value of a TypeRep. Currently a 64-bit value created -- using the MurmurHash2 algorithm. newtype Hash Hash :: Word64 -> Hash -- | Construct a Typed value using the chosen type format. -- -- Example: -- --

--   value = typed Full ("hello", 1 :: Int, 2.34 :: Double)
--   encded = 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. -- --

Requires one byte more than using Binary directly (namely -- to tag the data as untyped, required for the decoding step).

Untyped :: TypeFormat -- | Compare types by their hash values (using the MurmurHash2 algorithm). -- --

Requires only 8 additional bytes for the type information.
Subject to false positive due to hash collisions, although in -- practice this should almost never happen.
Type errors cannot tell the provided type ("Expected X, received -- type with hash H")

Hashed :: TypeFormat -- | Compare String representation of types, obtained by calling -- show on the TypeRep, and also include a hash value (like -- Hashed). The former is mostly for readable error messages, the -- latter provides collision resistance. -- --

Data size larger than Hashed, but usually smaller than -- Full.
Both the hash and the shown type must match to satisfy the -- typechecker.
Useful type errors ("expected X, received Y"). All types are shown -- unqualified though, making Foo.X and Bar.X look -- identical in error messages.

Shown :: TypeFormat -- | Compare the full representation of a data type. -- --

More verbose than Hashed and Shown. As a rule of -- thumb, transmitted data is roughly the same as Shown, but all -- names are fully qualified (package, module, type name).
Correct comparison (no false positives). An semi-exception here is -- when types change between package versions: package-1.0 Foo.X -- and package-1.1 Foo.X count as the same type.
Useful type errors ("expected X, received Y"). All types are shown -- unqualified though, making Foo.X and Bar.X look -- identical in error messages.

Full :: TypeFormat -- | Extract which TypeFormat was used to create a certain -- TypeInformation. 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) -- | 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 -- | Calculate the serialization of a TypeInformation and store it -- in a Typed value so it does not have to be recalculated on -- every call to encode. -- -- This is typically applied to a dummy value created using typed -- and the desired TypeFormat; the actual data is then inserted -- using reValue, which is how encodeTyped works. precache :: Typed a -> Typed a -- | 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. hashType :: TypeRep -> Hash -- | 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 Eq Hash instance Ord Hash instance Show Hash instance Generic Hash instance Eq TypeFormat instance Ord TypeFormat instance Show TypeFormat instance Eq TyCon instance Ord TyCon instance Generic TyCon instance Eq TypeRep instance Ord TypeRep instance Generic TypeRep instance Eq TypeInformation instance Ord TypeInformation instance Show TypeInformation instance Generic TypeInformation instance Datatype D1Hash instance Constructor C1_0Hash instance Datatype D1TyCon instance Constructor C1_0TyCon instance Datatype D1TypeRep instance Constructor C1_0TypeRep instance Datatype D1TypeInformation instance Constructor C1_0TypeInformation instance Constructor C1_1TypeInformation instance Constructor C1_2TypeInformation instance Constructor C1_3TypeInformation instance Constructor C1_4TypeInformation instance Hashable64 TyCon instance Show TyCon instance Binary TyCon instance Hashable64 TypeRep instance Show TypeRep instance Binary TypeRep instance (Binary a, Typeable a) => Binary (Typed a) instance Show a => Show (Typed a) instance Binary Hash instance Binary TypeInformation -- | Defines a type-safe Binary instance to ensure data is decoded -- with the type it was serialized from. -- -- For usage information, see the Data.Binary.Typed.Tutorial -- module. 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)
--   encded = encode value
--

Requires one byte more than using Binary directly (namely -- to tag the data as untyped, required for the decoding step).

Untyped :: TypeFormat -- | Compare types by their hash values (using the MurmurHash2 algorithm). -- --

Requires only 8 additional bytes for the type information.
Subject to false positive due to hash collisions, although in -- practice this should almost never happen.
Type errors cannot tell the provided type ("Expected X, received -- type with hash H")

Data size larger than Hashed, but usually smaller than -- Full.
Both the hash and the shown type must match to satisfy the -- typechecker.
Useful type errors ("expected X, received Y"). All types are shown -- unqualified though, making Foo.X and Bar.X look -- identical in error messages.

Shown :: TypeFormat -- | Compare the full representation of a data type. -- --

More verbose than Hashed and Shown. As a rule of -- thumb, transmitted data is roughly the same as Shown, but all -- names are fully qualified (package, module, type name).
Correct comparison (no false positives). An semi-exception here is -- when types change between package versions: package-1.0 Foo.X -- and package-1.1 Foo.X count as the same type.
Useful type errors ("expected X, received Y"). All types are shown -- unqualified though, making Foo.X and Bar.X look -- identical in error messages.

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 precached information, so that values have -- to be precached again if desired. As a consequence, -- mapTyped id can be used to un-precache -- 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 -- | Calculate the serialization of a TypeInformation and store it -- in a Typed value so it does not have to be recalculated on -- every call to encode. -- -- This is typically applied to a dummy value created using typed -- and the desired TypeFormat; the actual data is then inserted -- using reValue, which is how encodeTyped works. precache :: Typed a -> Typed a -- | Encode a Typeable value to ByteString that includes type -- information. If at all possible, prefer the more efficient -- encodeTypedLike though. -- --

--   encodeTyped format value = encode (typed format value)
--

encodeTyped :: (Typeable a, Binary a) => TypeFormat -> a -> ByteString -- | Version of encodeTyped that avoids recomputing the type -- representation of the input by using the one already contained in the -- first parameter. This is usually much more efficient than using -- encode, having a computational cost similar to using -- Binary directly. -- --

--   encodeTypedLike ty x
--   -- is observationally identical to
--   encode (reValue (const x) ty)
--

-- -- This function is intended to generate new encoding functions like so: -- --

--   encodeInt :: Int -> ByteString
--   encodeInt = encodeTypedLike (typed Full 0)
--

encodeTypedLike :: (Typeable a, Binary a) => Typed a -> a -> ByteString -- | Safely decode data, yielding Either an error String or -- the value. Equivalent to decodeTypedOrFail stripped of the -- non-essential data. -- --

--   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. -- --

Typed cousin of decodeOrFail.
Like decodeTyped, but with additional data.

decodeTypedOrFail :: (Typeable a, Binary a) => ByteString -> Either (ByteString, ByteOffset, String) (ByteString, ByteOffset, a) -- | Decode a typed value, throwing an error at runtime on failure. Typed -- cousin of decode. -- --

--   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