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

-- | Google Protocol Buffers via GHC.Generics
--   
--   Google Protocol Buffers via GHC.Generics.
--   
--   Protocol Buffers are a way of encoding structured data in an efficient
--   yet extensible format. Google uses Protocol Buffers for almost all of
--   its internal RPC protocols and file formats.
--   
--   This library supports a useful subset of Google Protocol Buffers
--   message specifications in a Haskell. No preprocessor or additional
--   build steps are required for message encoding and decoding.
--   
--   Record specifications are built by defining records with specially
--   defined fields that capture most of the Protocol Buffers specification
--   language.
@package protobuf
@version 0.2.1.3

-- | Messages containing Optional Enumeration fields fail
--   to encode. This module contains orphan instances required to make
--   these functional.
--   
--   For more information reference the associated ticket:
--   https://github.com/alphaHeavy/protobuf/issues/3
module Data.ProtocolBuffers.Orphans

module Data.ProtocolBuffers.Internal

-- | Field identifiers
type Tag = Word32

-- | A representation of the wire format as described in
--   https://developers.google.com/protocol-buffers/docs/encoding#structure
data WireField

-- | For: int32, int64, uint32, uint64, sint32, sint64, bool, enum
VarintField :: {-# UNPACK #-} !Tag -> {-# UNPACK #-} !Word64 -> WireField

-- | For: fixed64, sfixed64, double
Fixed64Field :: {-# UNPACK #-} !Tag -> {-# UNPACK #-} !Word64 -> WireField

-- | For: string, bytes, embedded messages, packed repeated fields
DelimitedField :: {-# UNPACK #-} !Tag -> !ByteString -> WireField

-- | For: groups (deprecated)
StartField :: {-# UNPACK #-} !Tag -> WireField

-- | For: groups (deprecated)
EndField :: {-# UNPACK #-} !Tag -> WireField

-- | For: fixed32, sfixed32, float
Fixed32Field :: {-# UNPACK #-} !Tag -> {-# UNPACK #-} !Word32 -> WireField
wireFieldTag :: WireField -> Tag
getWireField :: Get WireField
class EncodeWire a
encodeWire :: EncodeWire a => Tag -> a -> Put
class DecodeWire a
decodeWire :: DecodeWire a => WireField -> Get a
zzEncode32 :: Int32 -> Word32
zzEncode64 :: Int64 -> Word64
zzDecode32 :: Word32 -> Int32
zzDecode64 :: Word64 -> Int64
getVarintPrefixedBS :: Get ByteString
getVarInt :: (Integral a, Bits a) => Get a
putVarintPrefixedBS :: ByteString -> Put

-- | This can be used on any Integral type and is needed for signed types;
--   unsigned can use putVarUInt below. This has been changed to handle
--   only up to 64 bit integral values (to match documentation).
putVarSInt :: (Integral a, Bits a) => a -> Put

-- | This should be used on unsigned Integral types only (not checked)
putVarUInt :: (Integral a, Bits a) => a -> Put

-- | Fields are merely a way to hold a field tag along with its type, this
--   shouldn't normally be referenced directly.
--   
--   This provides better error messages than older versions which used
--   Tagged
newtype Field (n :: Nat) a
Field :: a -> Field (n :: Nat) a
[runField] :: Field (n :: Nat) a -> a

-- | Value selects the normal/typical way for encoding scalar
--   (primitive) values.
newtype Value a
Value :: a -> Value a
[runValue] :: Value a -> a

-- | To provide consistent instances for serialization a Traversable
--   Functor is needed to make Required fields have the same
--   shape as Optional, Repeated and Packed.
--   
--   This is the Identity Functor with a Show
--   instance.
newtype Always a
Always :: a -> Always a
[runAlways] :: Always a -> a

-- | Enumeration fields use fromEnum and toEnum when
--   encoding and decoding messages.
newtype Enumeration a
Enumeration :: a -> Enumeration a
[runEnumeration] :: Enumeration a -> a

-- | RequiredField is a newtype wrapped used to break overlapping
--   instances for encoding and decoding values
newtype RequiredField a
Required :: a -> RequiredField a
[runRequired] :: RequiredField a -> a

-- | OptionalField is a newtype wrapped used to break overlapping
--   instances for encoding and decoding values
newtype OptionalField a
Optional :: a -> OptionalField a
[runOptional] :: OptionalField a -> a

-- | RepeatedField is a newtype wrapped used to break overlapping
--   instances for encoding and decoding values
newtype RepeatedField a
Repeated :: a -> RepeatedField a
[runRepeated] :: RepeatedField a -> a

-- | A Traversable Functor used to select packed sequence
--   encoding/decoding.
newtype PackedField a
PackedField :: a -> PackedField a
[runPackedField] :: PackedField a -> a

-- | A list that is stored in a packed format.
newtype PackedList a
PackedList :: [a] -> PackedList a
[unPackedList] :: PackedList a -> [a]

-- | The way to embed a message within another message. These embedded
--   messages are stored as length-delimited fields.
--   
--   For example:
--   
--   
--   data Inner = Inner
--      { innerField :: Required '1' (Value Int64)
--      } deriving (Generic, Show)
--   
--    instance Encode Inner
--   instance Decode Inner
--   
--    data Outer = Outer
--      { outerField :: Required '1' (Message Inner)
--      } deriving (Generic, Show)
--   
--    instance Encode Outer
--   instance Decode Outer
--    
--   
--   
--   It's worth noting that  Message a  is a Monoid
--   and NFData instance. The Monoid behavior models that of
--   the Protocol Buffers documentation, effectively Last. It's done
--   with a fairly big hammer and it isn't possible to override this
--   behavior. This can cause some less-obvious compile errors for
--   paramterized Message types:
--   
--   
--   data Inner = Inner{inner :: Required '2' (Value Float)} deriving (Generic, Show)
--   instance Encode Inner
--   instance Decode Inner
--   
--   data Outer a = Outer{outer :: Required '3' (Message a)} deriving (Generic, Show)
--   instance Encode a => Encode (Outer a)
--   instance Decode a => Decode (Outer a)
--    
--   
--   
--   This fails because Decode needs to know that the message can be
--   merged. The resulting error implies that you may want to add a
--   constraint to the internal GMessageMonoid class:
--   
--   
--   /tmp/tst.hs:18:10:
--     Could not deduce (protobuf-0.1:GMessageMonoid (Rep a))
--       arising from a use of `protobuf-0.1: Decode .$gdmdecode'
--     from the context (Decode a)
--       bound by the instance declaration at /tmp/tst.hs:18:10-39
--     Possible fix:
--       add an instance declaration for
--       (protobuf-0.1:GMessageMonoid (Rep a))
--     In the expression:
--       (protobuf-0.1:Decode.$gdmdecode)
--     In an equation for decode:
--         decode = (protobuf-0.1:Decode .$gdmdecode)
--     In the instance declaration for `Decode (Outer a)'
--   
--   
--   The correct fix is to add the Monoid constraint for the
--   message:
--   
--   
--   - instance (Encode a) => Decode (Outer a)
--   + instance (Monoid (Message a), Decode a) => Decode (Outer a)
--   
newtype Message m
Message :: m -> Message m
[runMessage] :: Message m -> m
class GDecode (f :: Type -> Type)
class GEncode (f :: Type -> Type)
class GMessageMonoid (f :: Type -> Type)

-- | An implementation of Protocol Buffers in pure Haskell.
--   
--   Extensive documentation is available at
--   https://developers.google.com/protocol-buffers/docs/overview
--   and Google's reference implementation can be found at
--   http://code.google.com/p/protobuf/.
--   
--   It is intended to be used via GHC.Generics and does not require
--    .proto  files to function. Tools are being developed that
--   will convert a Haskell Protobuf definition into a  .proto 
--   and vice versa.
--   
--   Given a message definition:
--   
--   
--   {-# LANGUAGE DeriveGeneric #-}
--   {-# LANGUAGE DataKinds     #-}
--   
--   import Data.Int
--   import Data.ProtocolBuffers
--   import Data.Text
--   import GHC.Generics (Generic)
--   import GHC.TypeLits
--   import Data.Monoid
--   import Data.Serialize
--   import Data.Hex  -- cabal install hex (for testing)
--   
--    data Foo = Foo
--      { field1 :: Required 1 (Value Int64) -- ^ The last field with tag = 1
--      , field2 :: Optional 2 (Value Text) -- ^ The last field with tag = 2
--      , field3 :: Repeated 3 (Value Bool)   -- ^ All fields with tag = 3, ordering is preserved
--      } deriving (Generic, Show)
--   
--   instance Encode Foo
--   instance Decode Foo
--    
--   
--   
--   It can then be used for encoding and decoding. The Encode and
--   Decode instances are derived automatically using DeriveGeneric
--   and DefaultSignatures as outlined here:
--   http://www.haskell.org/haskellwiki/GHC.Generics#More_general_default_methods.
--   
--   To construct a message, use putField to set each field value.
--   Optional, Repeated and Packed fields can be set
--   to their empty value by using mempty. An example using record
--   syntax for clarity:
--   
--   
--   >>> let msg = Foo{field1 = putField 42, field2 = mempty, field3 = putField [True, False]}
--   
--   
--   To serialize a message first convert it into a Put by way of
--   encodeMessage and then to a ByteString by using
--   runPut. Lazy ByteString serialization is done with
--   runPutLazy.
--   
--   
--   >>> fmap hex runPut $ encodeMessage msg
--   "082A18011800"
--   
--   
--   Decoding is done with the inverse functions: decodeMessage and
--   runGet, or runGetLazy.
--   
--   
--   >>> runGet decodeMessage =<< unhex "082A18011800" :: Either String Foo
--   Right
--     (Foo
--       { field1 = Field {runField = Required {runRequired = Always {runAlways = Value {runValue = 42}}}}
--       , field2 = Field {runField = Optional {runOptional = Last {getLast = Nothing}}}
--       , field3 = Field {runField = Repeated {runRepeated = [Value {runValue = True},Value {runValue = False}]}}
--       }
--     )
--   
--   
--   Use getField to read fields from a message:
--   
--   
--   >>> let Right msg = runGet decodeMessage =<< unhex "082A18011800" :: Either String Foo
--   
--   >>> getField $ field1 msg
--   42
--   
--   >>> getField $ field2 msg
--   Nothing
--   
--   >>> getField $ field3 msg
--   [True,False]
--   
--   
--   Some Protocol Buffers features are not currently implemented:
--   
--   
--   
- Default values for Optional fields
--   
- Extension fields
--   
- Storing unknown fields, those without a mapped field tag in
--   message record
--   
- Tag-delimited Groups, deprecated in lieu of Message
--   
module Data.ProtocolBuffers
class Encode a
encode :: Encode a => a -> Put
($dmencode) :: (Encode a, Generic a, GEncode (Rep a)) => a -> Put

-- | Encode a Protocol Buffers message.
encodeMessage :: Encode a => a -> Put

-- | Encode a Protocol Buffers message prefixed with a varint encoded
--   32-bit integer describing its length.
encodeLengthPrefixedMessage :: Encode a => a -> Put
class Decode a
decode :: Decode a => HashMap Tag [WireField] -> Get a
($dmdecode) :: (Decode a, Generic a, GDecode (Rep a)) => HashMap Tag [WireField] -> Get a

-- | Decode a Protocol Buffers message.
decodeMessage :: Decode a => Get a

-- | Decode a Protocol Buffers message prefixed with a varint encoded
--   32-bit integer describing its length.
decodeLengthPrefixedMessage :: Decode a => Get a

-- | Required fields. Parsing will return empty if a Required
--   value is not found while decoding.
type family Required (n :: Nat) a

-- | Optional fields. Values that are not found will return Nothing.
type family Optional (n :: Nat) a

-- | Lists of values.
type Repeated (n :: Nat) a = Field n RepeatedField [a]

-- | Packed values.
type Packed (n :: Nat) a = Field n PackedField PackedList a

-- | Functions for wrapping and unwrapping record fields. When applied they
--   will have types similar to these:
--   
--   
--   getField :: Required '1' (Value Text) -> Text
--   putField :: Text -> Required '1' (Value Text)
--   
--   getField :: Optional '2' (Value Int32) -> Maybe Int32
--   putField :: Maybe Int32 -> Optional '2' (Value Int32)
--   
--   getField :: Repeated '3' (Value Double) -> [Double]
--   putField :: [Double] -> Repeated '3' (Value Double)
--   
--   getField :: Packed '4' (Value Word64) -> [Word64]
--   putField :: [Word64] -> Packed '4' (Value Word64)
--    
--   
class HasField a where {
    type FieldType a;
}

-- | Extract a value from it's Field representation.
getField :: HasField a => a -> FieldType a

-- | Wrap it back up again.
putField :: HasField a => FieldType a -> a

-- | An isomorphism lens compatible with the lens package
field :: (HasField a, Functor f) => (FieldType a -> f (FieldType a)) -> a -> f a

-- | Fields are merely a way to hold a field tag along with its type, this
--   shouldn't normally be referenced directly.
--   
--   This provides better error messages than older versions which used
--   Tagged
data Field (n :: Nat) a

-- | Value selects the normal/typical way for encoding scalar
--   (primitive) values.
data Value a

-- | Enumeration fields use fromEnum and toEnum when
--   encoding and decoding messages.
data Enumeration a

-- | The way to embed a message within another message. These embedded
--   messages are stored as length-delimited fields.
--   
--   For example:
--   
--   
--   data Inner = Inner
--      { innerField :: Required '1' (Value Int64)
--      } deriving (Generic, Show)
--   
--    instance Encode Inner
--   instance Decode Inner
--   
--    data Outer = Outer
--      { outerField :: Required '1' (Message Inner)
--      } deriving (Generic, Show)
--   
--    instance Encode Outer
--   instance Decode Outer
--    
--   
--   
--   It's worth noting that  Message a  is a Monoid
--   and NFData instance. The Monoid behavior models that of
--   the Protocol Buffers documentation, effectively Last. It's done
--   with a fairly big hammer and it isn't possible to override this
--   behavior. This can cause some less-obvious compile errors for
--   paramterized Message types:
--   
--   
--   data Inner = Inner{inner :: Required '2' (Value Float)} deriving (Generic, Show)
--   instance Encode Inner
--   instance Decode Inner
--   
--   data Outer a = Outer{outer :: Required '3' (Message a)} deriving (Generic, Show)
--   instance Encode a => Encode (Outer a)
--   instance Decode a => Decode (Outer a)
--    
--   
--   
--   This fails because Decode needs to know that the message can be
--   merged. The resulting error implies that you may want to add a
--   constraint to the internal GMessageMonoid class:
--   
--   
--   /tmp/tst.hs:18:10:
--     Could not deduce (protobuf-0.1:GMessageMonoid (Rep a))
--       arising from a use of `protobuf-0.1: Decode .$gdmdecode'
--     from the context (Decode a)
--       bound by the instance declaration at /tmp/tst.hs:18:10-39
--     Possible fix:
--       add an instance declaration for
--       (protobuf-0.1:GMessageMonoid (Rep a))
--     In the expression:
--       (protobuf-0.1:Decode.$gdmdecode)
--     In an equation for decode:
--         decode = (protobuf-0.1:Decode .$gdmdecode)
--     In the instance declaration for `Decode (Outer a)'
--   
--   
--   The correct fix is to add the Monoid constraint for the
--   message:
--   
--   
--   - instance (Encode a) => Decode (Outer a)
--   + instance (Monoid (Message a), Decode a) => Decode (Outer a)
--   
data Message m

-- | Signed integers are stored in a zz-encoded form.
newtype Signed a
Signed :: a -> Signed a

-- | Fixed integers are stored in little-endian form without additional
--   encoding.
newtype Fixed a
Fixed :: a -> Fixed a
