diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,29 @@ +0.2.0.0 +------- + + +* Removed `Default` instance on `TagFingerprint` in favor of just a normal + `emptyTagFP` function. This is a breaking change, and is the reason for + the "major" version bump. +* Fixed bug on decoding badly formatted binary due to unexpected laziness. +* Removed dependency on *data-default* and *spoon* packages. +* Removed upper version bounds for all dependencies except for *base*. + +0.1.2.0 +------- + + +* Tagged `ByteStrings` now lead with a "TagLead" byte sequence that + signifies that a `Tagged` is coming. For now, it is statically 0xfe 0xff, + which are two bytes that are never found in any valid UTF-8 encoded + string. +* So that all `TagFingerprint`s should be of the same length, + `TagFingerprint`s contain an `MD5Digest`, generated from the name of the + type. Its `Default` instance is the `MD5Digest` of an empty string. + +0.1.0.0 +------- + + +* Initial version. + diff --git a/Data/Binary/Tagged.hs b/Data/Binary/Tagged.hs --- a/Data/Binary/Tagged.hs +++ b/Data/Binary/Tagged.hs @@ -57,7 +57,6 @@ , typeFingerprint -- :: Typeable a => a -> TagFingerprint ) where -import Control.Spoon (teaspoon) import Data.Binary import Data.Binary.Tagged.Internal import Data.ByteString.Lazy @@ -84,5 +83,6 @@ -- 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 -decodeTagged bs = teaspoon =<< getTagged (decode bs) - +decodeTagged bs = case decodeOrFail bs of + Left _ -> Nothing + Right (_,_,x) -> getTagged x diff --git a/Data/Binary/Tagged/Internal.hs b/Data/Binary/Tagged/Internal.hs --- a/Data/Binary/Tagged/Internal.hs +++ b/Data/Binary/Tagged/Internal.hs @@ -28,14 +28,14 @@ , typeFingerprint -- :: Typeable a => a -> TagFingerprint , tagFingerprint -- :: Tagged a -> TagFingerprint , bsFingerprint -- :: ByteString -> Maybe TagFingerprint + , emptyTagFP -- :: TagFingerprint ) where import Control.Applicative ((<$>),(<*>)) import Control.Monad (guard, forM_) import Data.Binary -import Data.ByteString.Lazy.Char8 as LC import Data.Binary.Get -import Data.Default +import Data.ByteString.Lazy.Char8 as LC import Data.Digest.Pure.MD5 import Data.Maybe (isJust) import Data.Typeable.Internal @@ -51,7 +51,7 @@ -- 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 = Tagged !TagFingerprint a +data Tagged a = Tagged !TagFingerprint !a deriving (Show, Eq, Generic, Typeable) instance Binary a => Binary (Tagged a) where @@ -77,18 +77,19 @@ -- This type is mostly used for the ability to categorized Tagged items -- by their type. -- --- There is a 'Default' instance, because the constructor is hidden. For --- now, it is just an empty 'ByteString', but when fingerprinting works for --- real, think of it as a way to generate a fingerprint that will most --- likely not be matched by any type, in case the need ever comes up. +-- '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. newtype TagFingerprint = TagFP MD5Digest deriving (Show, Typeable, Generic, Eq, Ord) instance Binary TagFingerprint --- | 'MD5Digest' of an empty string: d41d8cd98f00b204e9800998ecf8427e -instance Default TagFingerprint where - def = TagFP (md5 "") +-- | 'TagFingerprint' that is meant to never be matched by any actual +-- normal type's 'TagFingerprint'. +emptyTagFP :: TagFingerprint +emptyTagFP = TagFP (md5 "") -- | Put at the start of a 'Tagged' to signify that it is a 'Tagged'. data TagLead = TagLead diff --git a/README.md b/README.md new file mode 100644 --- /dev/null +++ b/README.md @@ -0,0 +1,30 @@ +tagged-binary +============= + +Very minimal (Haskell) 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 and decoding, 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 + +Copyright +--------- + +Copyright (c) 2014 Justin Le diff --git a/changelog.md b/changelog.md deleted file mode 100644 --- a/changelog.md +++ /dev/null @@ -1,14 +0,0 @@ -Changelog -========= - -## 0.1.2.0 - -* Tagged `ByteStrings` now lead with a "TagLead" byte sequence that - signifies that a `Tagged` is coming. For now, it is statically 0xfe 0xff, - which are two bytes that are never found in any valid UTF-8 encoded - string. - -* So that all `TagFingerprint`s should be of the same length, - `TagFingerprint`s contain an `MD5Digest`, generated from the name of the - type. Its `Default` instance is the `MD5Digest` of an empty string. - diff --git a/tagged-binary.cabal b/tagged-binary.cabal --- a/tagged-binary.cabal +++ b/tagged-binary.cabal @@ -1,5 +1,5 @@ name: tagged-binary -version: 0.1.2.0 +version: 0.2.0.0 synopsis: Provides tools for serializing data tagged with type information. description: Very minimal library providing tools for serializing and @@ -37,7 +37,8 @@ copyright: Copyright (c) Justin Le 2014 category: Data, Serialization build-type: Simple -extra-source-files: changelog.md +extra-source-files: CHANGELOG.md + , README.md cabal-version: >=1.10 source-repository head @@ -49,12 +50,10 @@ , Data.Binary.Tagged.Internal -- other-modules: -- other-extensions: - build-depends: base >=4.6 && <5 - , binary >=0.7.1.0 && <0.8 - , bytestring >=0.10.4.0 && <0.11 - , data-default >=0.5.3 && <0.6 - , spoon >=0.3.1 && <0.4 - , pureMD5 >=2.1.2.1 && <3 + build-depends: base >= 4.6 && <5 + , binary >= 0.7.1 + , bytestring >= 0.10.4 + , pureMD5 >= 2.1 -- hs-source-dirs: default-language: Haskell2010 ghc-options: -Wall