-- 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 <tt>Optional</tt> <tt>Enumeration</tt> fields fail
--   to encode. This module contains orphan instances required to make
--   these functional.
--   
--   For more information reference the associated ticket:
--   <a>https://github.com/alphaHeavy/protobuf/issues/3</a>
module Data.ProtocolBuffers.Orphans

module Data.ProtocolBuffers.Internal

-- | Field identifiers
type Tag = Word32

-- | A representation of the wire format as described in
--   <a>https://developers.google.com/protocol-buffers/docs/encoding#structure</a>
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
--   <a>Tagged</a>
newtype Field (n :: Nat) a
Field :: a -> Field (n :: Nat) a
[runField] :: Field (n :: Nat) a -> a

-- | <a>Value</a> 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 <a>Traversable</a>
--   <a>Functor</a> is needed to make <a>Required</a> fields have the same
--   shape as <a>Optional</a>, <a>Repeated</a> and <a>Packed</a>.
--   
--   This is the <a>Identity</a> <a>Functor</a> with a <a>Show</a>
--   instance.
newtype Always a
Always :: a -> Always a
[runAlways] :: Always a -> a

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

-- | <a>RequiredField</a> 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

-- | <a>OptionalField</a> 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

-- | <a>RepeatedField</a> 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 <a>Traversable</a> <a>Functor</a> 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:
--   
--   <pre>
--   data Inner = Inner
--      { innerField :: <a>Required</a> '1' (<a>Value</a> <a>Int64</a>)
--      } deriving (<a>Generic</a>, <a>Show</a>)
--   
--    instance <a>Encode</a> Inner
--   instance <a>Decode</a> Inner
--   
--    data Outer = Outer
--      { outerField :: <a>Required</a> '1' (<a>Message</a> Inner)
--      } deriving (<a>Generic</a>, <a>Show</a>)
--   
--    instance <a>Encode</a> Outer
--   instance <a>Decode</a> Outer
--    
--   </pre>
--   
--   It's worth noting that <tt> <a>Message</a> a </tt> is a <a>Monoid</a>
--   and <a>NFData</a> instance. The <a>Monoid</a> behavior models that of
--   the Protocol Buffers documentation, effectively <a>Last</a>. 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 <a>Message</a> types:
--   
--   <pre>
--   data Inner = Inner{inner :: <a>Required</a> '2' (<a>Value</a> <a>Float</a>)} deriving (<a>Generic</a>, <a>Show</a>)
--   instance <a>Encode</a> Inner
--   instance <a>Decode</a> Inner
--   
--   data Outer a = Outer{outer :: <a>Required</a> '3' (<a>Message</a> a)} deriving (<a>Generic</a>, <a>Show</a>)
--   instance <a>Encode</a> a =&gt; <a>Encode</a> (Outer a)
--   instance <a>Decode</a> a =&gt; <a>Decode</a> (Outer a)
--    
--   </pre>
--   
--   This fails because <a>Decode</a> needs to know that the message can be
--   merged. The resulting error implies that you may want to add a
--   constraint to the internal <a>GMessageMonoid</a> class:
--   
--   <pre>
--   /tmp/tst.hs:18:10:
--     Could not deduce (protobuf-0.1:<a>GMessageMonoid</a> (<a>Rep</a> a))
--       arising from a use of `protobuf-0.1: <a>Decode</a> .$gdmdecode'
--     from the context (<a>Decode</a> a)
--       bound by the instance declaration at /tmp/tst.hs:18:10-39
--     Possible fix:
--       add an instance declaration for
--       (protobuf-0.1:<a>GMessageMonoid</a> (<a>Rep</a> a))
--     In the expression:
--       (protobuf-0.1:<a>Decode</a>.$gdmdecode)
--     In an equation for <tt>decode</tt>:
--         decode = (protobuf-0.1:<a>Decode</a> .$gdmdecode)
--     In the instance declaration for `<a>Decode</a> (Outer a)'
--   </pre>
--   
--   The correct fix is to add the <a>Monoid</a> constraint for the
--   message:
--   
--   <pre>
--   - instance (<a>Encode</a> a) =&gt; <a>Decode</a> (Outer a)
--   + instance (<a>Monoid</a> (<a>Message</a> a), <a>Decode</a> a) =&gt; <a>Decode</a> (Outer a)
--   </pre>
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
--   <a>https://developers.google.com/protocol-buffers/docs/overview</a>
--   and Google's reference implementation can be found at
--   <a>http://code.google.com/p/protobuf/</a>.
--   
--   It is intended to be used via <a>GHC.Generics</a> and does not require
--   <tt> .proto </tt> files to function. Tools are being developed that
--   will convert a Haskell Protobuf definition into a <tt> .proto </tt>
--   and vice versa.
--   
--   Given a message definition:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   {-# LANGUAGE DataKinds     #-}
--   
--   import <a>Data.Int</a>
--   import <a>Data.ProtocolBuffers</a>
--   import <a>Data.Text</a>
--   import <a>GHC.Generics</a> (<a>Generic</a>)
--   import <a>GHC.TypeLits</a>
--   import <a>Data.Monoid</a>
--   import <a>Data.Serialize</a>
--   import <a>Data.Hex</a>  -- cabal install hex (for testing)
--   
--    data Foo = Foo
--      { field1 :: <a>Required</a> 1 (<a>Value</a> <a>Int64</a>) -- ^ The last field with tag = 1
--      , field2 :: <a>Optional</a> 2 (<a>Value</a> <a>Text</a>) -- ^ The last field with tag = 2
--      , field3 :: <a>Repeated</a> 3 (<a>Value</a> <a>Bool</a>)   -- ^ All fields with tag = 3, ordering is preserved
--      } deriving (<a>Generic</a>, <a>Show</a>)
--   
--   instance <a>Encode</a> Foo
--   instance <a>Decode</a> Foo
--    
--   </pre>
--   
--   It can then be used for encoding and decoding. The <a>Encode</a> and
--   <a>Decode</a> instances are derived automatically using DeriveGeneric
--   and DefaultSignatures as outlined here:
--   <a>http://www.haskell.org/haskellwiki/GHC.Generics#More_general_default_methods</a>.
--   
--   To construct a message, use <a>putField</a> to set each field value.
--   <a>Optional</a>, <a>Repeated</a> and <a>Packed</a> fields can be set
--   to their empty value by using <a>mempty</a>. An example using record
--   syntax for clarity:
--   
--   <pre>
--   &gt;&gt;&gt; let msg = Foo{field1 = putField 42, field2 = mempty, field3 = putField [True, False]}
--   </pre>
--   
--   To serialize a message first convert it into a <a>Put</a> by way of
--   <a>encodeMessage</a> and then to a <a>ByteString</a> by using
--   <a>runPut</a>. Lazy <a>ByteString</a> serialization is done with
--   <a>runPutLazy</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fmap hex runPut $ encodeMessage msg
--   "082A18011800"
--   </pre>
--   
--   Decoding is done with the inverse functions: <a>decodeMessage</a> and
--   <a>runGet</a>, or <a>runGetLazy</a>.
--   
--   <pre>
--   &gt;&gt;&gt; runGet decodeMessage =&lt;&lt; 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}]}}
--       }
--     )
--   </pre>
--   
--   Use <a>getField</a> to read fields from a message:
--   
--   <pre>
--   &gt;&gt;&gt; let Right msg = runGet decodeMessage =&lt;&lt; unhex "082A18011800" :: Either String Foo
--   
--   &gt;&gt;&gt; getField $ field1 msg
--   42
--   
--   &gt;&gt;&gt; getField $ field2 msg
--   Nothing
--   
--   &gt;&gt;&gt; getField $ field3 msg
--   [True,False]
--   </pre>
--   
--   Some Protocol Buffers features are not currently implemented:
--   
--   <ul>
--   <li>Default values for <a>Optional</a> fields</li>
--   <li>Extension fields</li>
--   <li>Storing unknown fields, those without a mapped field tag in
--   message record</li>
--   <li>Tag-delimited Groups, deprecated in lieu of <a>Message</a></li>
--   </ul>
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 <a>empty</a> if a <a>Required</a>
--   value is not found while decoding.
type family Required (n :: Nat) a

-- | Optional fields. Values that are not found will return <a>Nothing</a>.
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:
--   
--   <pre>
--   <a>getField</a> :: <a>Required</a> '1' (<a>Value</a> <a>Text</a>) -&gt; <a>Text</a>
--   <a>putField</a> :: <a>Text</a> -&gt; <a>Required</a> '1' (<a>Value</a> <a>Text</a>)
--   
--   <a>getField</a> :: <a>Optional</a> '2' (<a>Value</a> <a>Int32</a>) -&gt; <a>Maybe</a> <a>Int32</a>
--   <a>putField</a> :: <a>Maybe</a> <a>Int32</a> -&gt; <a>Optional</a> '2' (<a>Value</a> <a>Int32</a>)
--   
--   <a>getField</a> :: <a>Repeated</a> '3' (<a>Value</a> <a>Double</a>) -&gt; [<a>Double</a>]
--   <a>putField</a> :: [<a>Double</a>] -&gt; <a>Repeated</a> '3' (<a>Value</a> <a>Double</a>)
--   
--   <a>getField</a> :: <a>Packed</a> '4' (<a>Value</a> <a>Word64</a>) -&gt; [<a>Word64</a>]
--   <a>putField</a> :: [<a>Word64</a>] -&gt; <a>Packed</a> '4' (<a>Value</a> <a>Word64</a>)
--    
--   </pre>
class HasField a where {
    type FieldType a;
}

-- | Extract a value from it's <a>Field</a> 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
--   <a>Tagged</a>
data Field (n :: Nat) a

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

-- | <a>Enumeration</a> fields use <a>fromEnum</a> and <a>toEnum</a> 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:
--   
--   <pre>
--   data Inner = Inner
--      { innerField :: <a>Required</a> '1' (<a>Value</a> <a>Int64</a>)
--      } deriving (<a>Generic</a>, <a>Show</a>)
--   
--    instance <a>Encode</a> Inner
--   instance <a>Decode</a> Inner
--   
--    data Outer = Outer
--      { outerField :: <a>Required</a> '1' (<a>Message</a> Inner)
--      } deriving (<a>Generic</a>, <a>Show</a>)
--   
--    instance <a>Encode</a> Outer
--   instance <a>Decode</a> Outer
--    
--   </pre>
--   
--   It's worth noting that <tt> <a>Message</a> a </tt> is a <a>Monoid</a>
--   and <a>NFData</a> instance. The <a>Monoid</a> behavior models that of
--   the Protocol Buffers documentation, effectively <a>Last</a>. 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 <a>Message</a> types:
--   
--   <pre>
--   data Inner = Inner{inner :: <a>Required</a> '2' (<a>Value</a> <a>Float</a>)} deriving (<a>Generic</a>, <a>Show</a>)
--   instance <a>Encode</a> Inner
--   instance <a>Decode</a> Inner
--   
--   data Outer a = Outer{outer :: <a>Required</a> '3' (<a>Message</a> a)} deriving (<a>Generic</a>, <a>Show</a>)
--   instance <a>Encode</a> a =&gt; <a>Encode</a> (Outer a)
--   instance <a>Decode</a> a =&gt; <a>Decode</a> (Outer a)
--    
--   </pre>
--   
--   This fails because <a>Decode</a> needs to know that the message can be
--   merged. The resulting error implies that you may want to add a
--   constraint to the internal <a>GMessageMonoid</a> class:
--   
--   <pre>
--   /tmp/tst.hs:18:10:
--     Could not deduce (protobuf-0.1:<a>GMessageMonoid</a> (<a>Rep</a> a))
--       arising from a use of `protobuf-0.1: <a>Decode</a> .$gdmdecode'
--     from the context (<a>Decode</a> a)
--       bound by the instance declaration at /tmp/tst.hs:18:10-39
--     Possible fix:
--       add an instance declaration for
--       (protobuf-0.1:<a>GMessageMonoid</a> (<a>Rep</a> a))
--     In the expression:
--       (protobuf-0.1:<a>Decode</a>.$gdmdecode)
--     In an equation for <tt>decode</tt>:
--         decode = (protobuf-0.1:<a>Decode</a> .$gdmdecode)
--     In the instance declaration for `<a>Decode</a> (Outer a)'
--   </pre>
--   
--   The correct fix is to add the <a>Monoid</a> constraint for the
--   message:
--   
--   <pre>
--   - instance (<a>Encode</a> a) =&gt; <a>Decode</a> (Outer a)
--   + instance (<a>Monoid</a> (<a>Message</a> a), <a>Decode</a> a) =&gt; <a>Decode</a> (Outer a)
--   </pre>
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
