Hackage :: [Package]

flat: Principled and efficient bit-oriented binary serialization.

[ bsd3, data, library, parsing, serialization ] [ Propose Tags ] [ Report a vulnerability ]
Versions [RSS] 0.2, 0.2.2, 0.3, 0.3.2, 0.3.4, 0.4, 0.4.2, 0.4.4, 0.5, 0.5.2, 0.6
Change log CHANGELOG
Dependencies array (>=0.5.1.0), base, bytestring (>=0.10.6), containers, deepseq (>=1.4), dlist, filepath (==1.4.1.1), ghc-prim, hashable (>=1.2.4.0 && <=1.2.7.0 || >=1.4.0.1), HUnit (==1.6.0.0), list-t (>1), memory (>=0.14.10 && <=0.14.14), mono-traversable, pretty (>=1.1.2), primitive, QuickCheck (==2.10), semigroups (<0.19), tasty (==1.1.0.3), text, unordered-containers, vector [details]
Tested with ghc ==7.10.3 || ==8.0.2 || ==8.2.2 || ==8.4.4 || ==8.6.5 || ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.4 || ==9.4.3
License BSD-3-Clause
Copyright Copyright: (c) 2016-2022 Pasqualino `Titto` Assini
Author Pasqualino `Titto` Assini
Maintainer tittoassini@gmail.com
Category Data, Parsing, Serialization
Home page http://quid2.org
Source repo head: git clone https://github.com/Quid2/flat
Uploaded by PasqualinoAssini at 2022-11-07T15:58:46Z
Distributions LTSHaskell:0.6, NixOS:0.6, Stackage:0.6
Reverse Dependencies 5 direct, 1 indirect [details]
Downloads 8354 total (147 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2022-11-07 [all 1 reports]

Readme for flat-0.6

[back to package description]

Build Status

Hackage version

Stackage LTS 16 Stackage LTS 18 Stackage LTS 19 Stackage Nightly

Haskell implementation of Flat, a principled, portable and compact binary data format (specs).

How To Use It For Fun and Profit

{-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}

import Flat

data Direction = North | South | Center | East | West deriving (Show,Generic,Flat)

Use flat to encode:

flat [North,South]
-> "\149"

and unflat to decode:

unflat (flat [North,South]) :: Decoded [Direction]
-> Right [ North , South ]

And thanks to Flat's bit-encoding, this list fits in 1 byte (rather than the 5 bytes that would be required by a traditional byte encoding):

flatBits [North,South]
-> "10010101"

Performance

For some hard data, see this comparison of the major haskell serialisation libraries.

Briefly:

  • Size: flat produces significantly smaller binaries than all other libraries (3/4 times usually)
  • Serialization time: store, persist and flat are faster
  • Deserialization time: store, flat, persist and cereal are faster
  • Transfer time (serialisation time + transport time on the network + deserialisation at the receiving end): flat is usually faster for all but the highest network speeds

Documentation

Installation

Get the latest stable version from hackage.

Compatibility

Tested with:

  • GHC 7.10.3 to 9.4.3 (x64)

  • GHCJS version 8.6.0.1 (GHC 8.6.2)

Known Bugs and Infelicities

  • Data types with more than 512 constructors are currently unsupported (but support could be easily added if necessary)

  • Longish compilation times

    • To improve performance, flat relies on extensive inlining. This unfortunately leads to longer compilation times.

      If you have many data types or very large ones, you might want to:

      • During development, turn optimisations off (stack --fast or -O0 in the cabal file).

      • Keep your serialisation code in separate modules.

  • See also the full list of open issues.

Ports for other languages

Rust and TypeScript-JavaScript ports are under development.

Get in touch if you would like to help porting flat to other languages.

Acknowledgements

flat reuses ideas and readapts code from various packages, mainly: store, binary-bits and binary and includes bug fixes from a number of contributors.

Other Stuff You Might Like

To decode flat encoded data you need to know the type of the serialised data.

This is ok for applications that do not require long-term storage and that do not operate in open distributed systems.

For those who do, you might want to supplement flat with ZM - Language independent, reproducible, absolute types.