binary-tagged

Tagged binary serialisation.

https://github.com/phadej/binary-tagged#readme

Version on this page:0.2@rev:1
LTS Haskell 23.25:0.3.1@rev:4
Stackage Nightly 2024-12-09:0.3.1@rev:4
Latest on Hackage:0.3.1@rev:4

See all snapshots binary-tagged appears in

BSD-3-Clause licensed and maintained by Oleg Grenrus
This version can be pinned in stack with:binary-tagged-0.2@sha256:403aeaade390a7eca554d203d90f650f9e2bb29be8eb808461a722fa0b421b32,4235

Module documentation for 0.2

Structurally tag binary serialisation stream.

Say you have:

data Record = Record
  { _recordFields  :: HM.HashMap Text (Integer, ByteString)
  , _recordEnabled :: Bool
  }
  deriving (Eq, Show, Generic)

instance Binary Record
instance HasStructuralInfo Record
instance HasSemanticVersion Record

then you can serialise and deserialise Record values with a structure tag by simply

encodeTaggedFile "cachefile" record
decodeTaggedFile "cachefile" :: IO Record

If structure of Record changes in between, deserialisation will fail early.

The overhead is next to non-observable, see a simple benchmark.

benchmarking encode/Binary
time                 362.6 μs   (361.2 μs .. 363.8 μs)

benchmarking encode/Tagged
time                 379.2 μs   (375.5 μs .. 382.2 μs)

benchmarking decode/Binary
time                 366.3 μs   (365.1 μs .. 368.1 μs)

benchmarking decode/Tagged
time                 367.6 μs   (367.0 μs .. 368.2 μs)

Changes

  • 0.2 (2019-05-14)
    • use cryptohash-sha1, types of structuralInfoSha1Digest and structuralInfoSha1Digest are changed.
    • Use binary-instances in tests
  • 0.1.5.2 (2019-05-10)
    • generics-sop-0.5
  • 0.1.5.1 (2018-09-24)
    • GHC-8.6.1
  • 0.1.5 (2018-05-20)
    • GHC-8.4.2
    • Don’t depend on nats and semigroups on newer GHC
  • 0.1.4.2 (2016-12-05)
    • Fix compilation with generics-sop-0.2.3.0
  • 0.1.4.1 (2016-09-20)
    • Print mismatching hashes in base16 encoding
  • 0.1.4.0 (2016-04-12)
    • Add semigroups types
    • Add Natural
  • 0.1.3.1 (2016-02-10)
    • Support GHC 8.0
  • 0.1.3.0 (2015-10-24)
    • Support generics-sop-0.2
  • 0.1.2.0 (2015-10-06)
    • Add tuple HasSemanticVersion instances
    • Add instances for
      • ()
      • Float
      • Double
      • Version`
      • Fixed
      • Ordering
    • Fix Interleave & SumUpTo, introduce Div2
  • 0.1.1.0
    • Add instances
      • Ratio
      • Word
      • HasSemanticVersion for primitive types