pinch

An alternative implementation of Thrift for Haskell.

https://github.com/abhinav/pinch#readme

Version on this page:0.3.3.0
LTS Haskell 22.40:0.5.2.0
Stackage Nightly 2024-11-09:0.5.2.0
Latest on Hackage:0.5.2.0

See all snapshots pinch appears in

BSD-3-Clause licensed by Abhinav Gupta
Maintained by [email protected]
This version can be pinned in stack with:pinch-0.3.3.0@sha256:31cfdeeff163de5a444aee9e3d5fc6db86b441dd87ae60f8a51ec53c38aff915,3869

build-status

pinch aims to provide an alternative implementation of Apache Thrift for Haskell. The pinch library itself acts only as a serialization library. Types specify their Thrift encoding by defining instances of the Pinchable typeclass, which may be done by hand or automatically with the use of Generics.

Haddock documentation for this package is avilable on Hackage and here.

Overview

Types which can be encoded into Thrift payloads implement the Pinchable typeclass.

Given the Thrift struct,

struct Person {
    1: required string name
    2: optional i64 dateOfBirth
}

You can write a Pinchable instance like so,

data Person = Person { name :: Text, dateOfBirth :: Maybe Int64 }
    deriving (Eq)

instance Pinchable Person where
    type Tag Person = TStruct
    -- The Tag tells the system that this represents a struct.

    pinch (Person name dateOfBirth) =
        struct [1 .= name, 2 ?= dateOfBirth]

    unpinch value =
        Person <$> value .:  1
               <*> value .:? 2

Better yet, you can drive an instance automatically.

{-# LANGUAGE DeriveGeneric, DataKinds #-}
import GHC.Generics (Generic)

data Person = Person
    { name        :: Field 1 Text
    , dateOfBirth :: Field 2 (Maybe Int64)
    } deriving (Eq, Generic)

instance Pinchable Person

Objects can be serialized and deserialized using the encode and decode methods. These methods accept a Protocol as an argument.

decode binaryProtocol (encode binaryProtocol person) == person

For more information, check the documentation and the examples.

Supported Protocols

The following Thrift protocols are supported:

  • Binary
  • Compact

Caveats

  • There is no code generation or template haskell support yet so types from the Thrift file will have to be translated by hand.

Changes

0.3.3.0 (2018-06-15)

  • Add Semigroup instances for some internal types. This improves GHC 8.4 compatibility.

0.3.2.0 (2017-06-03)

  • Compact: Fixed bug which caused incorrect encoding of doubles.

0.3.1.0 (2017-05-13)

  • Support GHC 8.2 (#14).

0.3.0.2 (2017-01-12)

  • Bump upper bound for vector (#11).

0.3.0.1 (2016-07-12)

  • Compile on 32-bit systems.

0.3.0.0 (2016-06-02)

  • Add support for the Thrift Compact Protocol (#2).
  • Add support for returning the leftover ByteString when parsing Thrift payloads (#3).

0.2.0.2 (2016-07-12)

  • Compile on 32-bit systems.

0.2.0.1 (2016-05-23)

  • Build with GHC 8.

0.2.0.0 (2015-12-27)

Breaking changes:

  • unpinch no longer returns Either String a. Instead it returns a Parser a.
  • Protocol.serialize* methods no longer produce a ByteString.Builder and the serialized length. Instead, they produce a custom Builder type.

Other changes:

  • Improve deserialization performance significantly by getting rid of unnecessary calls to Data.Typeable.{eqT, cast}.
  • Improve serialization performance by allocating the output buffer in one go rather than using ByteString.Builder.
  • Improve serialization and deserialization performance further by changing the intermediate representation of lists, sets, and maps.

0.1.0.2 (2015-12-27)

  • Loosen vector version constraint.

0.1.0.1 (2015-11-15)

  • Fixed recursion in C pre-processor expansion. This can break the build on some systems.

0.1.0.0 (2015-11-15)

  • Initial release.