-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An alternative implementation of Thrift for Haskell.
--   
--   This library provides machinery for types to specify how they can be
--   serialized and deserialized into/from Thrift payloads. It makes no
--   assumptions on how these payloads are sent or received and performs no
--   code generation. Types may specify how to be serialized and
--   deserialized by defining instances of the <tt>Pinchable</tt> typeclass
--   by hand, or with automatically derived instances by using generics.
--   Check the documentation in the <a>Pinch</a> module for more
--   information.
--   
--   <i>What is Thrift?</i> Apache Thrift provides an interface description
--   language, a set of communication protocols, and a code generator and
--   libraries for various programming languages to interact with the
--   generated code. Pinch aims to provide an alternative implementation of
--   Thrift for Haskell.
@package pinch
@version 0.3.2.0


-- | This module implements a ByteString builder very similar to
--   <a>Builder</a> except that it keeps track of its final serialized
--   length. This allows it to allocate the target ByteString in one
--   <tt>malloc</tt> and simply write the bytes to it.
module Pinch.Internal.Builder

-- | A ByteString Builder that knows its final size.
data Builder

-- | Build a ByteString from the given ByteString builder.
runBuilder :: Builder -> ByteString

-- | Append two Builders into one.
append :: Builder -> Builder -> Builder

-- | Serialize a single signed byte.
int8 :: Int8 -> Builder

-- | Serialize a single unsigned byte.
word8 :: Word8 -> Builder

-- | Serialize a signed 16-bit integer in big endian format.
int16BE :: Int16 -> Builder

-- | Serialize a signed 32-bit integer in big endian format.
int32BE :: Int32 -> Builder

-- | Serialize a signed 64-bit integer in big endian format.
int64BE :: Int64 -> Builder

-- | Serialize a signed 64-bit integer in little endian format.
int64LE :: Int64 -> Builder

-- | Serialize a signed 64-bit floating point number in big endian format.
doubleBE :: Double -> Builder

-- | Serialize a signed 64-bit floating point number in little endian
--   format.
doubleLE :: Double -> Builder

-- | Inlcude the given ByteString as-is in the builder.
--   
--   Note that because this operation is applied lazily, we will maintain a
--   reference to the ByteString until the builder is executed.
byteString :: ByteString -> Builder
instance GHC.Base.Monoid Pinch.Internal.Builder.Builder


-- | Implements a representation of a list as a fold over it.
module Pinch.Internal.FoldList

-- | FoldList represents a list as a <tt>foldl'</tt> traversal over it.
--   
--   This allows us to avoid allocating new collections for an intermediate
--   representation of various data types that users provide.
data FoldList a

-- | Applies the given function to all elements in the FoldList.
--   
--   Note that the function is applied lazily when the results are
--   requested. If the results of the same FoldList are requested multiple
--   times, the function will be called multiple times on the same
--   elements.
map :: (a -> b) -> FoldList a -> FoldList b

-- | Returns a FoldList with the given item repeated <tt>n</tt> times.
replicate :: Int -> a -> FoldList a

-- | Executes the given monadic action the given number of times and
--   returns a FoldList of the results.
replicateM :: Monad m => Int -> m a -> m (FoldList a)

-- | Left-associative fold of a structure but with strict application of
--   the operator.
--   
--   This ensures that each step of the fold is forced to weak head normal
--   form before being applied, avoiding the collection of thunks that
--   would otherwise occur. This is often what you want to strictly reduce
--   a finite list to a single, monolithic result (e.g. <a>length</a>).
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldl f z = <a>foldl'</a> f z . <a>toList</a>
--   </pre>
foldl' :: Foldable t => forall b a. () => (b -> a -> b) -> b -> t a -> b

-- | Right-associative fold of a structure.
--   
--   In the case of lists, <a>foldr</a>, when applied to a binary operator,
--   a starting value (typically the right-identity of the operator), and a
--   list, reduces the list using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--   </pre>
--   
--   Note that, since the head of the resulting expression is produced by
--   an application of the operator to the first element of the list,
--   <a>foldr</a> can produce a terminating expression from an infinite
--   list.
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldr f z = <a>foldr</a> f z . <a>toList</a>
--   </pre>
foldr :: Foldable t => forall a b. () => (a -> b -> b) -> b -> t a -> b

-- | List of elements of a structure, from left to right.
toList :: Foldable t => forall a. () => t a -> [a]

-- | Builds a FoldList from a Foldable.
fromFoldable :: Foldable f => f a -> FoldList a

-- | Builds a FoldList over pairs of items of a map.
fromMap :: (forall r. (r -> k -> v -> r) -> r -> m k v -> r) -> m k v -> FoldList (k, v)

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: Traversable t => forall (m :: * -> *) a b. Monad m => (a -> m b) -> t a -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: Traversable t => forall (m :: * -> *) a. Monad m => t m a -> m t a
instance GHC.Show.Show a => GHC.Show.Show (Pinch.Internal.FoldList.FoldList a)
instance GHC.Base.Functor Pinch.Internal.FoldList.FoldList
instance Data.Foldable.Foldable Pinch.Internal.FoldList.FoldList
instance Data.Traversable.Traversable Pinch.Internal.FoldList.FoldList
instance GHC.Classes.Eq a => GHC.Classes.Eq (Pinch.Internal.FoldList.FoldList a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Pinch.Internal.FoldList.FoldList a)
instance Data.Hashable.Class.Hashable a => Data.Hashable.Class.Hashable (Pinch.Internal.FoldList.FoldList a)
instance GHC.Base.Monoid (Pinch.Internal.FoldList.FoldList a)


-- | Implements a basic parser for binary data. The parser does not do any
--   extra book-keeping besides keeping track of the current position in
--   the ByteString.
module Pinch.Internal.Parser

-- | A simple ByteString parser.
data Parser a

-- | Run the parser on the given ByteString. Return either the failure
--   message or the result.
runParser :: Parser a -> ByteString -> Either String a

-- | Run the parser on the given ByteString. Return either the failure
--   message or the result and any left-over content.
runParser' :: Parser a -> ByteString -> Either String (ByteString, a)

-- | Produces the next byte and advances the parser.
int8 :: Parser Int8

-- | Produces the next byte and advances the parser.
word8 :: Parser Word8

-- | Produces a signed 16-bit integer and advances the parser.
int16 :: Parser Int16

-- | Produces a signed 32-bit integer and advances the parser.
int32 :: Parser Int32

-- | Produces a signed 64-bit integer and advances the parser.
int64 :: Parser Int64

-- | Produces a signed 64-bit integer (parsed in little endian byte
--   ordering) and advances the parser.
int64LE :: Parser Int64

-- | Produces a 64-bit floating point number and advances the parser.
double :: Parser Double

-- | Produces a 64-bit floating point number (parsed in little endian byte
--   ordering) and advances the parser.
doubleLE :: Parser Double

-- | <tt>take n</tt> gets exactly <tt>n</tt> bytes or fails the parse.
take :: Int -> Parser ByteString
instance GHC.Base.Functor Pinch.Internal.Parser.Parser
instance GHC.Base.Applicative Pinch.Internal.Parser.Parser
instance GHC.Base.Monad Pinch.Internal.Parser.Parser


-- | Defines the different types Thrift supports at the protocol level.
module Pinch.Internal.TType

-- | Represents the type of a Thrift value.
--   
--   Objects of this type are tagged with one of the TType tags, so this
--   type also acts as a singleton on the TTypes. It allows writing code
--   that can enforce properties about the TType of values at compile time.
data TType a
[TBool] :: TType TBool
[TByte] :: TType TByte
[TDouble] :: TType TDouble
[TInt16] :: TType TInt16
[TInt32] :: TType TInt32
[TInt64] :: TType TInt64
[TBinary] :: TType TBinary
[TStruct] :: TType TStruct
[TMap] :: TType TMap
[TSet] :: TType TSet
[TList] :: TType TList

-- | Typeclass used to map type-leve TTypes into <a>TType</a> objects. All
--   TType tags are instances of this class.
class Typeable a => IsTType a

-- | Based on the context in which this is used, it will automatically
--   return the corresponding <a>TType</a> object.
ttype :: IsTType a => TType a

-- | Used when the <a>TType</a> for something is not known at compile time.
--   Typically, this will be pattern matched inside a case statement and
--   code that depends on the TType will be go there.
data SomeTType
[SomeTType] :: forall a. IsTType a => TType a -> SomeTType

-- | Witness the equality of two ttypes.
ttypeEquality :: TType a -> TType b -> Maybe (a :~: b)

-- | Witness the equality of two TTypes.
--   
--   Implicit version of <tt>ttypeEquality</tt>.
ttypeEqT :: forall a b. (IsTType a, IsTType b) => Maybe (a :~: b)

-- | <pre>
--   bool
--   </pre>
data TBool

-- | <pre>
--   byte
--   </pre>
data TByte

-- | <pre>
--   double
--   </pre>
data TDouble

-- | <pre>
--   i16
--   </pre>
data TInt16

-- | <pre>
--   i32
--   </pre>
data TInt32

-- | <pre>
--   enum
--   </pre>
type TEnum = TInt32

-- | <pre>
--   i64
--   </pre>
data TInt64

-- | <pre>
--   binary
--   </pre>
data TBinary

-- | <pre>
--   string
--   </pre>
type TText = TBinary

-- | <pre>
--   struct
--   </pre>
data TStruct

-- | <pre>
--   union
--   </pre>
type TUnion = TStruct

-- | <pre>
--   exception
--   </pre>
type TException = TStruct

-- | <pre>
--   map&lt;k, v&gt;
--   </pre>
data TMap

-- | <pre>
--   set&lt;x&gt;
--   </pre>
data TSet

-- | <pre>
--   list&lt;x&gt;
--   </pre>
data TList
instance GHC.Show.Show (Pinch.Internal.TType.TType a)
instance GHC.Classes.Eq (Pinch.Internal.TType.TType a)
instance GHC.Show.Show Pinch.Internal.TType.SomeTType
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TBool
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TByte
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TDouble
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TInt16
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TInt32
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TInt64
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TBinary
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TStruct
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TMap
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TSet
instance Pinch.Internal.TType.IsTType Pinch.Internal.TType.TList
instance Data.Hashable.Class.Hashable (Pinch.Internal.TType.TType a)


-- | This module defines an intermediate representation for Thrift values
--   and functions to work with the intermediate representation.
module Pinch.Internal.Value

-- | <tt>Value</tt> maps directly to serialized representation of Thrift
--   types. It contains about as much information as what gets sent over
--   the wire. <tt>Value</tt> objects are tagged with different
--   <a>TType</a> values to indicate the type of the value.
--   
--   Typical usage will not involve accessing the constructors for this
--   type. <a>Pinchable</a> must be used to construct <a>Value</a> objects
--   or convert them back to original types.
data Value a
[VBool] :: !Bool -> Value TBool
[VByte] :: !Int8 -> Value TByte
[VDouble] :: !Double -> Value TDouble
[VInt16] :: !Int16 -> Value TInt16
[VInt32] :: !Int32 -> Value TInt32
[VInt64] :: !Int64 -> Value TInt64
[VBinary] :: !ByteString -> Value TBinary
[VStruct] :: !(HashMap Int16 SomeValue) -> Value TStruct
[VMap] :: forall k v. (IsTType k, IsTType v) => !(FoldList (MapItem k v)) -> Value TMap
[VNullMap] :: Value TMap
[VSet] :: forall a. IsTType a => !(FoldList (Value a)) -> Value TSet
[VList] :: forall a. IsTType a => !(FoldList (Value a)) -> Value TList

-- | A single item in a map
data MapItem k v
MapItem :: !(Value k) -> !(Value v) -> MapItem k v

-- | <a>SomeValue</a> holds any value, regardless of type. This may be used
--   when the type of the value is not necessarily known at compile time.
--   Typically, this will be pattern matched on and code that depends on
--   the value's <a>TType</a> will go inside the scope of the match.
data SomeValue
[SomeValue] :: (IsTType a) => !(Value a) -> SomeValue

-- | Safely attempt to cast a Value into another.
castValue :: forall a b. (IsTType a, IsTType b) => Value a -> Maybe (Value b)

-- | Get the <a>TType</a> of a <a>Value</a>.
valueTType :: IsTType a => Value a -> TType a
instance GHC.Classes.Eq (Pinch.Internal.Value.MapItem k v)
instance GHC.Show.Show Pinch.Internal.Value.SomeValue
instance Control.DeepSeq.NFData (Pinch.Internal.Value.MapItem k v)
instance Data.Hashable.Class.Hashable (Pinch.Internal.Value.MapItem k v)
instance GHC.Show.Show (Pinch.Internal.Value.MapItem k v)
instance GHC.Show.Show (Pinch.Internal.Value.Value a)
instance GHC.Classes.Eq (Pinch.Internal.Value.Value a)
instance Control.DeepSeq.NFData (Pinch.Internal.Value.Value a)
instance GHC.Classes.Eq Pinch.Internal.Value.SomeValue
instance Control.DeepSeq.NFData Pinch.Internal.Value.SomeValue
instance Data.Hashable.Class.Hashable (Pinch.Internal.Value.Value a)
instance Data.Hashable.Class.Hashable Pinch.Internal.Value.SomeValue


-- | Provides the core <tt>Pinchable</tt> typeclass and the
--   <tt>GPinchable</tt> typeclass used to derive instances automatically.
module Pinch.Internal.Pinchable

-- | The Pinchable type class is implemented by types that can be sent or
--   received over the wire as Thrift payloads.
class IsTType (Tag a) => Pinchable a where {
    type family Tag a;
    type Tag a = GTag (Rep a);
}

-- | Convert an <tt>a</tt> into a <a>Value</a>.
--   
--   For structs, <a>struct</a>, <a>.=</a>, and <a>?=</a> may be used to
--   construct <a>Value</a> objects tagged with <a>TStruct</a>.
pinch :: Pinchable a => a -> Value (Tag a)

-- | Read a <a>Value</a> back into an <tt>a</tt>.
--   
--   For structs, <a>.:</a> and <a>.:?</a> may be used to retrieve field
--   values.
unpinch :: Pinchable a => Value (Tag a) -> Parser a

-- | Convert an <tt>a</tt> into a <a>Value</a>.
--   
--   For structs, <a>struct</a>, <a>.=</a>, and <a>?=</a> may be used to
--   construct <a>Value</a> objects tagged with <a>TStruct</a>.
pinch :: (Pinchable a, Generic a, Tag a ~ GTag (Rep a), GPinchable (Rep a)) => a -> Value (Tag a)

-- | Read a <a>Value</a> back into an <tt>a</tt>.
--   
--   For structs, <a>.:</a> and <a>.:?</a> may be used to retrieve field
--   values.
unpinch :: (Pinchable a, Generic a, Tag a ~ GTag (Rep a), GPinchable (Rep a)) => Value (Tag a) -> Parser a

-- | Construct a <a>FieldPair</a> from a field identifier and a
--   <a>Pinchable</a> value.
(.=) :: Pinchable a => Int16 -> a -> FieldPair

-- | Construct a <a>FieldPair</a> from a field identifier and an optional
--   <a>Pinchable</a> value.
(?=) :: Pinchable a => Int16 -> Maybe a -> FieldPair

-- | Construct a <a>Value</a> tagged with a <a>TStruct</a> from the given
--   key-value pairs. Optional fields whose values were omitted will be
--   ignored.
--   
--   <pre>
--   struct [1 .= ("Hello" :: Text), 2 .= (42 :: Int16)]
--   </pre>
struct :: [FieldPair] -> Value TStruct

-- | Constructs a <a>Value</a> tagged with <a>TUnion</a>.
--   
--   <pre>
--   union 1 ("foo" :: ByteString)
--   </pre>
union :: Pinchable a => Int16 -> a -> Value TUnion

-- | A pair of field identifier and maybe a value stored in the field. If
--   the value is absent, the field will be ignored.
type FieldPair = (Int16, Maybe SomeValue)

-- | Given a field ID and a <tt>Value TStruct</tt>, get the value stored in
--   the struct under that field ID. The lookup fails if the field is
--   absent or if it's not the same type as expected by this call's
--   context.
(.:) :: forall a. Pinchable a => Value TStruct -> Int16 -> Parser a

-- | Given a field ID and a <tt>Value TStruct</tt>, get the optional value
--   stored in the struct under the given field ID. The value returned is
--   <tt>Nothing</tt> if it was absent or the wrong type. The lookup fails
--   only if the value retrieved fails to <a>unpinch</a>.
(.:?) :: forall a. Pinchable a => Value TStruct -> Int16 -> Parser (Maybe a)

-- | GPinchable is used to impelment support for automatically deriving
--   instances of Pinchable via generics.
class IsTType (GTag f) => GPinchable (f :: * -> *) where {
    type family GTag f;
}

-- | Converts a generic representation of a value into a <a>Value</a>.
gPinch :: GPinchable f => f a -> Value (GTag f)

-- | Converts a <a>Value</a> back into the generic representation of the
--   object.
gUnpinch :: GPinchable f => Value (GTag f) -> Parser (f a)

-- | Implementation of <a>pinch</a> based on <a>GPinchable</a>.
genericPinch :: (Generic a, GPinchable (Rep a)) => a -> Value (GTag (Rep a))

-- | Implementation of <a>unpinch</a> based on <a>GPinchable</a>.
genericUnpinch :: (Generic a, GPinchable (Rep a)) => Value (GTag (Rep a)) -> Parser a

-- | A simple continuation-based parser.
--   
--   This is just <tt>Either e a</tt> in continuation-passing style.
data Parser a

-- | Run a <tt>Parser</tt> and return the result inside an <tt>Either</tt>.
runParser :: Parser a -> Either String a

-- | Allows handling parse errors.
parserCatch :: Parser a -> (String -> Parser b) -> (a -> Parser b) -> Parser b
instance Pinch.Internal.TType.IsTType a => Pinch.Internal.Pinchable.Pinchable (Pinch.Internal.Value.Value a)
instance Pinch.Internal.Pinchable.Pinchable Data.ByteString.Internal.ByteString
instance Pinch.Internal.Pinchable.Pinchable Data.ByteString.Lazy.Internal.ByteString
instance Pinch.Internal.Pinchable.Pinchable Data.Text.Internal.Text
instance Pinch.Internal.Pinchable.Pinchable Data.Text.Internal.Lazy.Text
instance Pinch.Internal.Pinchable.Pinchable GHC.Types.Bool
instance Pinch.Internal.Pinchable.Pinchable GHC.Int.Int8
instance Pinch.Internal.Pinchable.Pinchable GHC.Types.Double
instance Pinch.Internal.Pinchable.Pinchable GHC.Int.Int16
instance Pinch.Internal.Pinchable.Pinchable GHC.Int.Int32
instance Pinch.Internal.Pinchable.Pinchable GHC.Int.Int64
instance Pinch.Internal.Pinchable.Pinchable a => Pinch.Internal.Pinchable.Pinchable (Data.Vector.Vector a)
instance Pinch.Internal.Pinchable.Pinchable a => Pinch.Internal.Pinchable.Pinchable [a]
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k, Pinch.Internal.Pinchable.Pinchable k, Pinch.Internal.Pinchable.Pinchable v) => Pinch.Internal.Pinchable.Pinchable (Data.HashMap.Base.HashMap k v)
instance (GHC.Classes.Ord k, Pinch.Internal.Pinchable.Pinchable k, Pinch.Internal.Pinchable.Pinchable v) => Pinch.Internal.Pinchable.Pinchable (Data.Map.Internal.Map k v)
instance (GHC.Classes.Eq a, Data.Hashable.Class.Hashable a, Pinch.Internal.Pinchable.Pinchable a) => Pinch.Internal.Pinchable.Pinchable (Data.HashSet.HashSet a)
instance (GHC.Classes.Ord a, Pinch.Internal.Pinchable.Pinchable a) => Pinch.Internal.Pinchable.Pinchable (Data.Set.Internal.Set a)


-- | Message wrapper for Thrift payloads. Normal Thrift requests sent over
--   the wire are wrapped inside a message envelope that contains
--   information about the method being called, the type of message, etc.
--   This information is essential for the RPC system to function.
module Pinch.Internal.Message

-- | Message envelope for Thrift payloads.
data Message
Message :: !Text -> !MessageType -> !Int32 -> !(Value TStruct) -> Message

-- | Name of the method to which this message is targeted.
[messageName] :: Message -> !Text

-- | Type of the message.
[messageType] :: Message -> !MessageType

-- | Sequence ID of the message.
--   
--   If the clients expect to receive out-of-order responses, they may use
--   the message ID to map responses back to their corresponding requests.
--   If the client does not expect out-of-order responses, they are free to
--   use the same message ID for all messages.
--   
--   The server's contract regarding message IDs is that all responses must
--   have the same message ID as their corresponding requests.
[messageId] :: Message -> !Int32

-- | Contents of the message.
[messagePayload] :: Message -> !(Value TStruct)

-- | Type of message being sent.
data MessageType

-- | A call to a specific method.
--   
--   The message body is the request arguments struct.
Call :: MessageType

-- | Response to a call.
--   
--   The message body is the response union.
Reply :: MessageType

-- | Failure to make a call.
--   
--   Note: This message type is <i>not</i> used for exceptions that are
--   defined under the <tt>throws</tt> clause of a method. Those exceptions
--   are part of the response union of the method and are received in a
--   <tt>Reply</tt>. This message type is used for Thrift-level failures.
Exception :: MessageType

-- | One-way call that expects no response.
Oneway :: MessageType
instance GHC.Generics.Generic Pinch.Internal.Message.Message
instance GHC.Classes.Eq Pinch.Internal.Message.Message
instance GHC.Show.Show Pinch.Internal.Message.Message
instance GHC.Generics.Generic Pinch.Internal.Message.MessageType
instance Data.Data.Data Pinch.Internal.Message.MessageType
instance GHC.Classes.Eq Pinch.Internal.Message.MessageType
instance GHC.Show.Show Pinch.Internal.Message.MessageType
instance Control.DeepSeq.NFData Pinch.Internal.Message.Message
instance Control.DeepSeq.NFData Pinch.Internal.Message.MessageType


-- | Implements support for automatically deriving Pinchable instances for
--   types that implement <tt>Generic</tt> and follow a specific pattern.
module Pinch.Internal.Generic

-- | Fields of data types that represent structs, unions, and exceptions
--   should be wrapped inside <a>Field</a> and tagged with the field
--   identifier.
--   
--   <pre>
--   data Foo = Foo (Field 1 Text) (Field 2 (Maybe Int32)) deriving Generic
--   instance Pinchable Foo
--   </pre>
--   
--   <pre>
--   data A = A (Field 1 Int32) | B (Field 2 Text) deriving Generic
--   instance Pinchable Foo
--   </pre>
--   
--   Fields which hold <tt>Maybe</tt> values are treated as optional. All
--   fields values must be <a>Pinchable</a> to automatically derive a
--   <tt>Pinchable</tt> instance for the new data type.
newtype Field (n :: Nat) a
Field :: a -> Field a

-- | Gets the current value of a field.
--   
--   <pre>
--   let Foo a' _ = {- ... -}
--       a = getField a'
--   </pre>
getField :: Field n a -> a

-- | Puts a value inside a field.
--   
--   <pre>
--   Foo (putField "Hello") (putField (Just 42))
--   </pre>
putField :: a -> Field n a

-- | A lens on <tt>Field</tt> wrappers for use with the lens library.
--   
--   <pre>
--   person &amp; name . field .~ "new value"
--   </pre>
field :: Functor f => (a -> f b) -> Field n a -> f (Field n b)

-- | Data types that represent Thrift enums must have one constructor for
--   each enum item accepting an <a>Enumeration</a> object tagged with the
--   corresponding enum value.
--   
--   <pre>
--   data Role = RoleUser (Enumeration 1) | RoleAdmin (Enumeration 2)
--     deriving Generic
--   instance Pinchable Role
--   </pre>
data Enumeration (n :: Nat)
Enumeration :: Enumeration

-- | Convenience function to construct <a>Enumeration</a> objects.
--   
--   <pre>
--   let role = RoleUser enum
--   </pre>
enum :: Enumeration n

-- | Represents a <tt>void</tt> result for methods.
--   
--   This should be used as an element in a response union along with
--   <a>Field</a> tags.
--   
--   For a method,
--   
--   <pre>
--   void setValue(..) throws
--     (1: ValueAlreadyExists alreadyExists,
--      2: InternalError internalError)
--   </pre>
--   
--   Something similar to the following can be used.
--   
--   <pre>
--   data SetValueResponse
--     = SetValueAlreadyExists (Field 1 ValueAlreadyExists)
--     | SetValueInternalError (Field 2 InternalError)
--     | SetValueSuccess Void
--     deriving (Generic)
--   
--   instance Pinchable SetValueResponse
--   </pre>
data Void
Void :: Void
instance GHC.Show.Show Pinch.Internal.Generic.Void
instance GHC.Classes.Ord Pinch.Internal.Generic.Void
instance GHC.Generics.Generic Pinch.Internal.Generic.Void
instance GHC.Classes.Eq Pinch.Internal.Generic.Void
instance GHC.Show.Show (Pinch.Internal.Generic.Enumeration n)
instance GHC.Classes.Ord (Pinch.Internal.Generic.Enumeration n)
instance GHC.Generics.Generic (Pinch.Internal.Generic.Enumeration n)
instance GHC.Classes.Eq (Pinch.Internal.Generic.Enumeration n)
instance Data.Traversable.Traversable (Pinch.Internal.Generic.Field n)
instance GHC.Show.Show a => GHC.Show.Show (Pinch.Internal.Generic.Field n a)
instance GHC.Classes.Ord a => GHC.Classes.Ord (Pinch.Internal.Generic.Field n a)
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Pinch.Internal.Generic.Field n a)
instance GHC.Base.Monoid a => GHC.Base.Monoid (Pinch.Internal.Generic.Field n a)
instance GHC.Generics.Generic (Pinch.Internal.Generic.Field n a)
instance GHC.Base.Functor (Pinch.Internal.Generic.Field n)
instance Data.Foldable.Foldable (Pinch.Internal.Generic.Field n)
instance GHC.Enum.Enum a => GHC.Enum.Enum (Pinch.Internal.Generic.Field n a)
instance GHC.Classes.Eq a => GHC.Classes.Eq (Pinch.Internal.Generic.Field n a)
instance GHC.Enum.Bounded a => GHC.Enum.Bounded (Pinch.Internal.Generic.Field n a)
instance Pinch.Internal.Pinchable.GPinchable (GHC.Generics.K1 i Pinch.Internal.Generic.Void)
instance Control.DeepSeq.NFData (Pinch.Internal.Generic.Enumeration n)
instance GHC.TypeNats.KnownNat n => Pinch.Internal.Pinchable.GPinchable (GHC.Generics.K1 i (Pinch.Internal.Generic.Enumeration n))
instance (Pinch.Internal.Pinchable.Pinchable a, GHC.TypeNats.KnownNat n) => Pinch.Internal.Pinchable.GPinchable (GHC.Generics.K1 i (Pinch.Internal.Generic.Field n a))
instance (Pinch.Internal.Pinchable.Pinchable a, GHC.TypeNats.KnownNat n) => Pinch.Internal.Pinchable.GPinchable (GHC.Generics.K1 i (Pinch.Internal.Generic.Field n (GHC.Base.Maybe a)))
instance Pinch.Internal.Generic.Combinable Pinch.Internal.TType.TStruct
instance (Pinch.Internal.Pinchable.GPinchable a, Pinch.Internal.Pinchable.GPinchable b, Pinch.Internal.Pinchable.GTag a ~ Pinch.Internal.Pinchable.GTag b, Pinch.Internal.Generic.Combinable (Pinch.Internal.Pinchable.GTag a)) => Pinch.Internal.Pinchable.GPinchable (a GHC.Generics.:*: b)
instance Pinch.Internal.Pinchable.GPinchable a => Pinch.Internal.Pinchable.GPinchable (GHC.Generics.M1 i c a)
instance (GHC.Generics.Datatype d, Pinch.Internal.Pinchable.GPinchable a) => Pinch.Internal.Pinchable.GPinchable (GHC.Generics.D1 d a)
instance (Pinch.Internal.Pinchable.GPinchable a, Pinch.Internal.Pinchable.GPinchable b, Pinch.Internal.Pinchable.GTag a ~ Pinch.Internal.Pinchable.GTag b) => Pinch.Internal.Pinchable.GPinchable (a GHC.Generics.:+: b)


-- | Protocols in Pinch only need to know how to serialize and deserialize
--   <a>Value</a> objects. Types that want to be serialized into/from
--   Thrift payloads define how to convert them to/from <a>Value</a>
--   objects via <a>Pinchable</a>.
module Pinch.Protocol

-- | Protocols define a specific way to convert values into binary and
--   back.
data Protocol
Protocol :: (forall a. IsTType a => Value a -> Builder) -> (Message -> Builder) -> (forall a. IsTType a => ByteString -> Either String (ByteString, Value a)) -> (ByteString -> Either String Message) -> Protocol

-- | Serializes a <a>Value</a> into a ByteString builder.
--   
--   Returns a <tt>Builder</tt> and the total length of the serialized
--   content.
[serializeValue] :: Protocol -> forall a. IsTType a => Value a -> Builder

-- | Serializes a <a>Message</a> and its payload into a ByteString builder.
--   
--   Returns a <tt>Builder</tt> and the total length of the serialized
--   content.
[serializeMessage] :: Protocol -> Message -> Builder

-- | Reads a <a>Value</a> from a ByteString and returns leftovers from
--   parse.
[deserializeValue'] :: Protocol -> forall a. IsTType a => ByteString -> Either String (ByteString, Value a)

-- | Reads a <a>Message</a> and its payload from a ByteString.
[deserializeMessage] :: Protocol -> ByteString -> Either String Message

-- | Reads a <a>Value</a> from a ByteString.
deserializeValue :: forall a. IsTType a => Protocol -> ByteString -> Either String (Value a)


-- | Implements the Thrift Binary Protocol as a <a>Protocol</a>.
module Pinch.Protocol.Binary

-- | Provides an implementation of the Thrift Binary Protocol.
binaryProtocol :: Protocol


-- | Implements the Thrift Compact Protocol as a <a>Protocol</a>.
module Pinch.Protocol.Compact

-- | Provides an implementation of the Thrift Compact Protocol.
compactProtocol :: Protocol
instance Pinch.Internal.TType.IsTType Pinch.Protocol.Compact.TStop


-- | Pinch defines machinery to specify how types can be encoded into or
--   decoded from Thrift payloads.
module Pinch

-- | Encode the given <a>Pinchable</a> value using the given
--   <a>Protocol</a>.
--   
--   <pre>
--   &gt;&gt;&gt; unpack $ encode binaryProtocol ["a" :: ByteString, "b"]
--   [11,0,0,0,2,0,0,0,1,97,0,0,0,1,98]
--   </pre>
encode :: Pinchable a => Protocol -> a -> ByteString

-- | Decode a <a>Pinchable</a> value from the using the given
--   <a>Protocol</a>.
--   
--   <pre>
--   &gt;&gt;&gt; let s = pack [11,0,0,0,2,0,0,0,1,97,0,0,0,1,98]
--   
--   &gt;&gt;&gt; decode binaryProtocol s :: Either String [ByteString]
--   Right ["a","b"]
--   </pre>
decode :: Pinchable a => Protocol -> ByteString -> Either String a

-- | Encode the <a>Message</a> using the given <a>Protocol</a>.
--   
--   <pre>
--   let request = GetUserRequest (putField "jsmith") (putField [])
--       message = <a>mkMessage</a> "getUser" Call 42 request
--   in encodeMessage binaryProtocol message
--   </pre>
encodeMessage :: Protocol -> Message -> ByteString

-- | Decode a <a>Message</a> using the given <a>Protocol</a>.
--   
--   <pre>
--   &gt;&gt;&gt; decodeMessage binaryProtocol bs &gt;&gt;= getMessageBody :: Either String GetUserRequest
--   Right (GetUserRequest {userName = Field "jsmith", userAttributes = Field []})
--   </pre>
decodeMessage :: Protocol -> ByteString -> Either String Message

-- | The Pinchable type class is implemented by types that can be sent or
--   received over the wire as Thrift payloads.
class IsTType (Tag a) => Pinchable a where {
    type family Tag a;
    type Tag a = GTag (Rep a);
}

-- | Convert an <tt>a</tt> into a <a>Value</a>.
--   
--   For structs, <a>struct</a>, <a>.=</a>, and <a>?=</a> may be used to
--   construct <a>Value</a> objects tagged with <a>TStruct</a>.
pinch :: Pinchable a => a -> Value (Tag a)

-- | Read a <a>Value</a> back into an <tt>a</tt>.
--   
--   For structs, <a>.:</a> and <a>.:?</a> may be used to retrieve field
--   values.
unpinch :: Pinchable a => Value (Tag a) -> Parser a

-- | Convert an <tt>a</tt> into a <a>Value</a>.
--   
--   For structs, <a>struct</a>, <a>.=</a>, and <a>?=</a> may be used to
--   construct <a>Value</a> objects tagged with <a>TStruct</a>.
pinch :: (Pinchable a, Generic a, Tag a ~ GTag (Rep a), GPinchable (Rep a)) => a -> Value (Tag a)

-- | Read a <a>Value</a> back into an <tt>a</tt>.
--   
--   For structs, <a>.:</a> and <a>.:?</a> may be used to retrieve field
--   values.
unpinch :: (Pinchable a, Generic a, Tag a ~ GTag (Rep a), GPinchable (Rep a)) => Value (Tag a) -> Parser a

-- | A simple continuation-based parser.
--   
--   This is just <tt>Either e a</tt> in continuation-passing style.
data Parser a

-- | Run a <tt>Parser</tt> and return the result inside an <tt>Either</tt>.
runParser :: Parser a -> Either String a

-- | Fields of data types that represent structs, unions, and exceptions
--   should be wrapped inside <a>Field</a> and tagged with the field
--   identifier.
--   
--   <pre>
--   data Foo = Foo (Field 1 Text) (Field 2 (Maybe Int32)) deriving Generic
--   instance Pinchable Foo
--   </pre>
--   
--   <pre>
--   data A = A (Field 1 Int32) | B (Field 2 Text) deriving Generic
--   instance Pinchable Foo
--   </pre>
--   
--   Fields which hold <tt>Maybe</tt> values are treated as optional. All
--   fields values must be <a>Pinchable</a> to automatically derive a
--   <tt>Pinchable</tt> instance for the new data type.
newtype Field (n :: Nat) a
Field :: a -> Field a

-- | Gets the current value of a field.
--   
--   <pre>
--   let Foo a' _ = {- ... -}
--       a = getField a'
--   </pre>
getField :: Field n a -> a

-- | Puts a value inside a field.
--   
--   <pre>
--   Foo (putField "Hello") (putField (Just 42))
--   </pre>
putField :: a -> Field n a

-- | A lens on <tt>Field</tt> wrappers for use with the lens library.
--   
--   <pre>
--   person &amp; name . field .~ "new value"
--   </pre>
field :: Functor f => (a -> f b) -> Field n a -> f (Field n b)

-- | Represents a <tt>void</tt> result for methods.
--   
--   This should be used as an element in a response union along with
--   <a>Field</a> tags.
--   
--   For a method,
--   
--   <pre>
--   void setValue(..) throws
--     (1: ValueAlreadyExists alreadyExists,
--      2: InternalError internalError)
--   </pre>
--   
--   Something similar to the following can be used.
--   
--   <pre>
--   data SetValueResponse
--     = SetValueAlreadyExists (Field 1 ValueAlreadyExists)
--     | SetValueInternalError (Field 2 InternalError)
--     | SetValueSuccess Void
--     deriving (Generic)
--   
--   instance Pinchable SetValueResponse
--   </pre>
data Void
Void :: Void

-- | Data types that represent Thrift enums must have one constructor for
--   each enum item accepting an <a>Enumeration</a> object tagged with the
--   corresponding enum value.
--   
--   <pre>
--   data Role = RoleUser (Enumeration 1) | RoleAdmin (Enumeration 2)
--     deriving Generic
--   instance Pinchable Role
--   </pre>
data Enumeration (n :: Nat)
Enumeration :: Enumeration

-- | Convenience function to construct <a>Enumeration</a> objects.
--   
--   <pre>
--   let role = RoleUser enum
--   </pre>
enum :: Enumeration n

-- | Construct a <a>FieldPair</a> from a field identifier and a
--   <a>Pinchable</a> value.
(.=) :: Pinchable a => Int16 -> a -> FieldPair

-- | Construct a <a>FieldPair</a> from a field identifier and an optional
--   <a>Pinchable</a> value.
(?=) :: Pinchable a => Int16 -> Maybe a -> FieldPair

-- | Construct a <a>Value</a> tagged with a <a>TStruct</a> from the given
--   key-value pairs. Optional fields whose values were omitted will be
--   ignored.
--   
--   <pre>
--   struct [1 .= ("Hello" :: Text), 2 .= (42 :: Int16)]
--   </pre>
struct :: [FieldPair] -> Value TStruct

-- | Constructs a <a>Value</a> tagged with <a>TUnion</a>.
--   
--   <pre>
--   union 1 ("foo" :: ByteString)
--   </pre>
union :: Pinchable a => Int16 -> a -> Value TUnion

-- | A pair of field identifier and maybe a value stored in the field. If
--   the value is absent, the field will be ignored.
type FieldPair = (Int16, Maybe SomeValue)

-- | Given a field ID and a <tt>Value TStruct</tt>, get the value stored in
--   the struct under that field ID. The lookup fails if the field is
--   absent or if it's not the same type as expected by this call's
--   context.
(.:) :: forall a. Pinchable a => Value TStruct -> Int16 -> Parser a

-- | Given a field ID and a <tt>Value TStruct</tt>, get the optional value
--   stored in the struct under the given field ID. The value returned is
--   <tt>Nothing</tt> if it was absent or the wrong type. The lookup fails
--   only if the value retrieved fails to <a>unpinch</a>.
(.:?) :: forall a. Pinchable a => Value TStruct -> Int16 -> Parser (Maybe a)

-- | <tt>Value</tt> maps directly to serialized representation of Thrift
--   types. It contains about as much information as what gets sent over
--   the wire. <tt>Value</tt> objects are tagged with different
--   <a>TType</a> values to indicate the type of the value.
--   
--   Typical usage will not involve accessing the constructors for this
--   type. <a>Pinchable</a> must be used to construct <a>Value</a> objects
--   or convert them back to original types.
data Value a

-- | <a>SomeValue</a> holds any value, regardless of type. This may be used
--   when the type of the value is not necessarily known at compile time.
--   Typically, this will be pattern matched on and code that depends on
--   the value's <a>TType</a> will go inside the scope of the match.
data SomeValue
[SomeValue] :: (IsTType a) => !(Value a) -> SomeValue

-- | Message envelope for Thrift payloads.
data Message

-- | Build a <tt>Message</tt>.
mkMessage :: (Pinchable a, Tag a ~ TStruct) => Text -> MessageType -> Int32 -> a -> Message

-- | Name of the method to which this message is targeted.
messageName :: Message -> Text

-- | Type of the message.
messageType :: Message -> MessageType

-- | Sequence ID of the message.
--   
--   If the clients expect to receive out-of-order responses, they may use
--   the message ID to map responses back to their corresponding requests.
--   If the client does not expect out-of-order responses, they are free to
--   use the same message ID for all messages.
--   
--   The server's contract regarding message IDs is that all responses must
--   have the same message ID as their corresponding requests.
messageId :: Message -> Int32

-- | Read the message contents.
--   
--   This returns a <tt>Left</tt> result if the message contents do not
--   match the requested type.
getMessageBody :: (Pinchable a, Tag a ~ TStruct) => Message -> Either String a

-- | Type of message being sent.
data MessageType

-- | A call to a specific method.
--   
--   The message body is the request arguments struct.
Call :: MessageType

-- | Response to a call.
--   
--   The message body is the response union.
Reply :: MessageType

-- | Failure to make a call.
--   
--   Note: This message type is <i>not</i> used for exceptions that are
--   defined under the <tt>throws</tt> clause of a method. Those exceptions
--   are part of the response union of the method and are received in a
--   <tt>Reply</tt>. This message type is used for Thrift-level failures.
Exception :: MessageType

-- | One-way call that expects no response.
Oneway :: MessageType

-- | Protocols define a specific way to convert values into binary and
--   back.
data Protocol

-- | Provides an implementation of the Thrift Binary Protocol.
binaryProtocol :: Protocol

-- | Provides an implementation of the Thrift Compact Protocol.
compactProtocol :: Protocol

-- | Represents the type of a Thrift value.
--   
--   Objects of this type are tagged with one of the TType tags, so this
--   type also acts as a singleton on the TTypes. It allows writing code
--   that can enforce properties about the TType of values at compile time.
data TType a

-- | Typeclass used to map type-leve TTypes into <a>TType</a> objects. All
--   TType tags are instances of this class.
class Typeable a => IsTType a

-- | Based on the context in which this is used, it will automatically
--   return the corresponding <a>TType</a> object.
ttype :: IsTType a => TType a

-- | <pre>
--   bool
--   </pre>
data TBool

-- | <pre>
--   byte
--   </pre>
data TByte

-- | <pre>
--   double
--   </pre>
data TDouble

-- | <pre>
--   enum
--   </pre>
type TEnum = TInt32

-- | <pre>
--   i16
--   </pre>
data TInt16

-- | <pre>
--   i32
--   </pre>
data TInt32

-- | <pre>
--   i64
--   </pre>
data TInt64

-- | <pre>
--   binary
--   </pre>
data TBinary

-- | <pre>
--   struct
--   </pre>
data TStruct

-- | <pre>
--   union
--   </pre>
type TUnion = TStruct

-- | <pre>
--   exception
--   </pre>
type TException = TStruct

-- | <pre>
--   map&lt;k, v&gt;
--   </pre>
data TMap

-- | <pre>
--   set&lt;x&gt;
--   </pre>
data TSet

-- | <pre>
--   list&lt;x&gt;
--   </pre>
data TList
