diff --git a/binary-typed.cabal b/binary-typed.cabal --- a/binary-typed.cabal +++ b/binary-typed.cabal @@ -1,5 +1,5 @@ name: binary-typed -version: 0.2.0.0 +version: 0.2.0.1 synopsis: Type-safe binary serialization Description: `Binary` serialization tagged with type information, allowing for diff --git a/src/Data/Binary/Typed.hs b/src/Data/Binary/Typed.hs --- a/src/Data/Binary/Typed.hs +++ b/src/Data/Binary/Typed.hs @@ -47,24 +47,24 @@ -- | 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. +-- representation. In other words, calling 'mapTyped' on something that is +-- typed using 'Hashed' will yield a 'Hashed' value again. -- --- Note: this destroys 'precache'd information, so that values have to be --- 'precache'd again if desired. As a consequence, @'mapTyped' 'id'@ --- can be used to un-'precache' values. +-- Note: this destroys 'precache'd information, so that values have to be +-- 'precache'd again if desired. As a consequence, @'mapTyped' 'id'@ +-- can be used to un-'precache' values. mapTyped :: Typeable b => (a -> b) -> Typed a -> Typed b mapTyped f (Typed ty x) = typed (getFormat ty) (f x) -- | 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. +-- 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@). +-- 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 reValue f (Typed ty x) = Typed ty (f x) @@ -113,7 +113,7 @@ -- | Decode a typed value, throwing an error at runtime on failure. --- Typed cousin of 'Data.Binary.decode'. +-- Typed cousin of 'Data.Binary.decode'. -- -- @ -- encoded = 'encodeTyped' 'Full' ("hello", 1 :: 'Int', 2.34 :: 'Double') @@ -132,10 +132,11 @@ -- | Safely decode data, yielding 'Either' an error 'String' or the value, --- along with meta-information of the consumed binary data. +-- along with meta-information of the consumed binary data. -- --- * Typed cousin of 'Data.Binary.decodeOrFail'. --- * Like 'decodeTyped', but with additional data. +-- * Typed cousin of 'Data.Binary.decodeOrFail'. +-- +-- * Like 'decodeTyped', but with additional data. decodeTypedOrFail :: (Typeable a, Binary a) => BSL.ByteString -> Either (BSL.ByteString, ByteOffset, String) @@ -147,7 +148,7 @@ -- | Safely decode data, yielding 'Either' an error 'String' or the value. --- Equivalent to 'decodeTypedOrFail' stripped of the non-essential data. +-- Equivalent to 'decodeTypedOrFail' stripped of the non-essential data. -- -- @ -- encoded = 'encodeTyped' 'Full' ("hello", 1 :: 'Int', 2.34 :: 'Double') diff --git a/src/Data/Binary/Typed/Internal.hs b/src/Data/Binary/Typed/Internal.hs --- a/src/Data/Binary/Typed/Internal.hs +++ b/src/Data/Binary/Typed/Internal.hs @@ -53,8 +53,8 @@ -- ^ 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. +-- recipient can do consistency checks. See 'TypeFormat' for more detailed +-- information on the fields. data TypeInformation = Untyped' | Hashed32' Hash32 | Hashed64' Hash64 @@ -83,7 +83,7 @@ -- | A hash value of a 'TypeRep'. Currently a 32-bit value created using --- the MurmurHash2 algorithm. +-- the MurmurHash2 algorithm. newtype Hash32 = Hash32 Word32 deriving (Eq, Ord, Show, Generic) instance Binary Hash32 @@ -91,7 +91,7 @@ -- | A hash value of a 'TypeRep'. Currently a 64-bit value created using --- the MurmurHash2 algorithm. +-- the MurmurHash2 algorithm. newtype Hash64 = Hash64 Word64 deriving (Eq, Ord, Show, Generic) instance Binary Hash64 @@ -99,7 +99,7 @@ -- | A value suitable to be typechecked using the contained extra type --- information. +-- information. data Typed a = Typed TypeInformation a -- ^ Using this data constructor directly is unsafe, as it allows -- construction of ill-typed 'Typed' data. Use the 'typed' smart @@ -112,8 +112,8 @@ (show x) -- | Ensures data is decoded as the appropriate type with high or total --- confidence (depending on with what 'TypeFormat' the 'Typed' was --- constructed). +-- confidence (depending on with what 'TypeFormat' the 'Typed' was +-- constructed). instance (Binary a, Typeable a) => Binary (Typed a) where get = do (ty, value) <- get either fail return (typecheck (Typed ty value)) @@ -123,19 +123,19 @@ -- | 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 'BSL.ByteString'requires its length to --- be included in the final serialization, yielding a 8-byte overhead for the --- required 'Data.Int.Int64', and one for the tag of what was serialized --- ("shown or full?"). +-- 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 'BSL.ByteString' requires its length to +-- be included in the final serialization, yielding a 8-byte overhead for the +-- required 'Data.Int.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 8 bytes are negligible (determined by an --- arbitrary threshold, currently 10*9 bytes). +-- 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 'Data.Binary.Typed.encodeTyped' more efficient; the source --- there also makes a good usage example. +-- Used to make 'Data.Binary.Typed.encodeTyped' more efficient; the source +-- there also makes a good usage example. preserialize :: TypeInformation -> TypeInformation preserialize x@(Cached' _) = x preserialize x@(Untyped' ) = x @@ -150,9 +150,9 @@ -- | Preserializes type information if its encoded byte length is larger than --- an arbitrary threshold. Less efficient than 'preserialize' since it --- always preserializes and always calculates the encoded version no matter --- what. +-- an arbitrary threshold. Less efficient than 'preserialize' since it +-- always preserializes and always calculates the encoded version no matter +-- what. preserialize' :: TypeInformation -> TypeInformation preserialize' x | BSL.length encoded > 10*9 = Cached' encoded | otherwise = x @@ -171,52 +171,57 @@ Untyped -- | Compare types by their hash values (using the MurmurHash2 - -- algorithm). + -- algorithm). -- - -- * Requires five bytes more compared to using 'Binary' directly for - -- the type information (one to tag as 'Hashed32', four for the - -- hash value) - -- * 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") + -- * Requires five bytes more compared to using 'Binary' directly for + -- the type information (one to tag as 'Hashed32', four for the + -- hash value) + -- + -- * 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") | Hashed32 -- | Like 'Hashed32', but uses a 64-bit hash value. -- - -- * Requires nine bytes more compared to using 'Binary'. - -- * Hash collisions are even less likely to occur than with - -- 'Hashed32'. + -- * Requires nine bytes more compared to using 'Binary'. + -- + -- * Hash collisions are even less likely to occur than with + -- 'Hashed32'. | Hashed64 -- | 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. + -- '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. -- - -- * Data size larger than 'Hashed32', 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. Remember this when you get a - -- seemingly silly error "expected Foo, but given Foo". + -- * Data size larger than 'Hashed32', 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. Remember this when you get a + -- seemingly silly error "expected Foo, but given Foo". | Shown -- | 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. Remember this when you get a - -- seemingly silly error "expected Foo, but given Foo". + -- * 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. Remember this when you get a + -- seemingly silly error "expected Foo, but given Foo". | Full deriving (Eq, Ord, Show)