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


-- | A lens-based implementation of protocol buffers in Haskell.
--   
--   The proto-lens library provides to protocol buffers using modern
--   Haskell language and library patterns. Specifically, it provides:
--   
--   <ul>
--   <li>Composable field accessors via lenses</li>
--   <li>Simple field name resolution/overloading via type-level
--   literals</li>
--   <li>Type-safe reflection and encoding/decoding of messages via
--   GADTs</li>
--   </ul>
@package proto-lens
@version 0.2.2.0


-- | Datatypes for reflection of protocol buffer messages.
module Data.ProtoLens.Message

-- | Every protocol buffer is an instance of <a>Message</a>. This class
--   enables serialization by providing reflection of all of the fields
--   that may be used by this type.
class Default msg => Message msg
descriptor :: Message msg => MessageDescriptor msg

-- | A tag that identifies a particular field of the message when
--   converting to/from the wire format.
newtype Tag
Tag :: Int -> Tag
[unTag] :: Tag -> Int

-- | The description of a particular protocol buffer message type.
data MessageDescriptor msg
MessageDescriptor :: Text -> Map Tag (FieldDescriptor msg) -> Map String (FieldDescriptor msg) -> MessageDescriptor msg

-- | A unique identifier for this type, of the format
--   <tt>"packagename.messagename"</tt>.
[messageName] :: MessageDescriptor msg -> Text

-- | The fields of the proto, indexed by their (integer) tag.
[fieldsByTag] :: MessageDescriptor msg -> Map Tag (FieldDescriptor msg)

-- | This map is keyed by the name of the field used for text format
--   protos. This is just the field name for every field except for group
--   fields, which use their Message type name in text protos instead of
--   their field name. For example, "optional group Foo" has the field name
--   "foo" but in this map it is stored with the key <a>Foo</a>.
[fieldsByTextFormatName] :: MessageDescriptor msg -> Map String (FieldDescriptor msg)

-- | A description of a specific field of a protocol buffer.
--   
--   The <a>String</a> parameter is the name of the field from the .proto
--   file, as used in TextFormat, with the same behavior for groups as
--   <a>fieldsByTextFormatName</a>. (Haddock doesn't support per-argument
--   docs for GADTs.)
data FieldDescriptor msg
[FieldDescriptor] :: String -> FieldTypeDescriptor value -> FieldAccessor msg value -> FieldDescriptor msg

-- | The original name of the field in the .proto file.
fieldDescriptorName :: FieldDescriptor msg -> String

-- | Whether the given field is required. Specifically, if its
--   <a>FieldAccessor</a> is a <a>Required</a> <a>PlainField</a>.
isRequired :: FieldDescriptor msg -> Bool

-- | A Lens for accessing the value of an individual field in a protocol
--   buffer message.
data FieldAccessor msg value
[PlainField] :: WireDefault value -> Lens' msg value -> FieldAccessor msg value
[OptionalField] :: Lens' msg (Maybe value) -> FieldAccessor msg value
[RepeatedField] :: Packing -> Lens' msg [value] -> FieldAccessor msg value
[MapField] :: (Ord key, Message entry) => Lens' entry key -> Lens' entry value -> Lens' msg (Map key value) -> FieldAccessor msg entry

-- | The default value (if any) for a <a>PlainField</a> on the wire.
data WireDefault value
[Required] :: WireDefault value
[Optional] :: (FieldDefault value, Eq value) => WireDefault value

-- | How a given repeated field is transmitted on the wire format.
data Packing
Packed :: Packing
Unpacked :: Packing

-- | A description of the type of a given field value.
data FieldTypeDescriptor value
[MessageField] :: Message value => FieldTypeDescriptor value
[GroupField] :: Message value => FieldTypeDescriptor value
[EnumField] :: MessageEnum value => FieldTypeDescriptor value
[Int32Field] :: FieldTypeDescriptor Int32
[Int64Field] :: FieldTypeDescriptor Int64
[UInt32Field] :: FieldTypeDescriptor Word32
[UInt64Field] :: FieldTypeDescriptor Word64
[SInt32Field] :: FieldTypeDescriptor Int32
[SInt64Field] :: FieldTypeDescriptor Int64
[Fixed32Field] :: FieldTypeDescriptor Word32
[Fixed64Field] :: FieldTypeDescriptor Word64
[SFixed32Field] :: FieldTypeDescriptor Int32
[SFixed64Field] :: FieldTypeDescriptor Int64
[FloatField] :: FieldTypeDescriptor Float
[DoubleField] :: FieldTypeDescriptor Double
[BoolField] :: FieldTypeDescriptor Bool
[StringField] :: FieldTypeDescriptor Text
[BytesField] :: FieldTypeDescriptor ByteString

-- | A proto3 field type with an implicit default value.
--   
--   This is distinct from <a>Default</a> to avoid orphan instances, and
--   because <a>Bool</a> doesn't necessarily have a good Default instance
--   for general usage.
class FieldDefault value
fieldDefault :: FieldDefault value => value

-- | A class for protocol buffer enums that enables safe decoding.
class (Enum a, Bounded a) => MessageEnum a

-- | Convert the given <a>Int</a> to an enum value. Returns <a>Nothing</a>
--   if no corresponding value was defined in the .proto file.
maybeToEnum :: MessageEnum a => Int -> Maybe a

-- | Get the name of this enum as defined in the .proto file.
showEnum :: MessageEnum a => a -> String

-- | Convert the given <a>String</a> to an enum value. Returns
--   <a>Nothing</a> if no corresponding value was defined in the .proto
--   file.
readEnum :: MessageEnum a => String -> Maybe a

-- | A class for types with a default value.
class Default a

-- | The default value for this type.
def :: Default a => a

-- | Utility function for building a message from a default value. For
--   example:
--   
--   <pre>
--   instance Default A where ...
--   x, y :: Lens' A Int
--   m :: A
--   m = build ((x .~ 5) . (y .~ 7))
--   </pre>
build :: Default a => (a -> a) -> a

-- | A helper lens for accessing optional fields. This is used as part of
--   code generation, and should generally not be needed explicitly.
--   
--   Note that <a>maybeLens</a> does not satisfy the lens laws, which
--   expect that <tt>set l (view l x) == x</tt>. For example,
--   
--   <pre>
--   set (maybeLens 'a') (view (maybeLens 'a') Nothing) == Just 'a'
--   </pre>
--   
--   However, this is the behavior generally expected by users, and only
--   matters if we're explicitly checking whether a field is set.
maybeLens :: b -> Lens' (Maybe b) b

-- | Reverse every repeated (list) field in the message.
--   
--   During parsing, we store fields temporarily in reverse order, and then
--   un-reverse them at the end. This helps avoid the quadratic blowup from
--   repeatedly appending to lists. TODO: Benchmark how much of a problem
--   this is in practice, and whether it's still a net win for small
--   protobufs. If we decide on it more permanently, consider moving it to
--   a more internal module.
reverseRepeatedFields :: Map k (FieldDescriptor msg) -> msg -> msg
instance GHC.Num.Num Data.ProtoLens.Message.Tag
instance GHC.Classes.Ord Data.ProtoLens.Message.Tag
instance GHC.Classes.Eq Data.ProtoLens.Message.Tag
instance GHC.Show.Show Data.ProtoLens.Message.Tag
instance GHC.Show.Show (Data.ProtoLens.Message.FieldTypeDescriptor value)
instance Data.ProtoLens.Message.FieldDefault GHC.Types.Bool
instance Data.ProtoLens.Message.FieldDefault GHC.Int.Int32
instance Data.ProtoLens.Message.FieldDefault GHC.Int.Int64
instance Data.ProtoLens.Message.FieldDefault GHC.Word.Word32
instance Data.ProtoLens.Message.FieldDefault GHC.Word.Word64
instance Data.ProtoLens.Message.FieldDefault GHC.Types.Float
instance Data.ProtoLens.Message.FieldDefault GHC.Types.Double
instance Data.ProtoLens.Message.FieldDefault Data.ByteString.Internal.ByteString
instance Data.ProtoLens.Message.FieldDefault Data.Text.Internal.Text


-- | Functions for encoding and decoding protocol buffer Messages.
--   
--   TODO: Currently all operations are on strict ByteStrings; we should
--   try to generalize to lazy Bytestrings as well.
module Data.ProtoLens.Encoding

-- | Encode a message to the wire format as a strict <tt>ByteString</tt>.
encodeMessage :: Message msg => msg -> ByteString

-- | Encode a message to the wire format, as part of a <a>Builder</a>.
buildMessage :: Message msg => msg -> Builder

-- | Decode a message from its wire format. Returns <a>Left</a> if the
--   decoding fails.
decodeMessage :: Message msg => ByteString -> Either String msg

-- | Decode a message from its wire format. Throws an error if the decoding
--   fails.
decodeMessageOrDie :: Message msg => ByteString -> msg


-- | This internal module provides functions used to define the various
--   <tt>enumFrom*</tt> functions of <a>Enum</a>.
--   
--   We expect <a>fromEnum</a> to be an ordering homomorphism, that is:
--   
--   <pre>
--   forall a b. Enum a b
--   succ a == b =&gt; fromEnum a &lt; fromEnum b
--   </pre>
--   
--   Note that this homomorphism is most likely not surjective. Note
--   further that one cannot assume:
--   
--   <pre>
--   CANNOT BE ASSUMED !
--   succ a == b =&gt; fromEnum a + 1 == fromEnum b
--   </pre>
--   
--   The <a>succ</a> essor of a given message enum value <tt>A</tt> that's
--   not <a>maxBound</a> is the enum value <tt>B</tt> whose <a>fromEnum</a>
--   value is the one immediately after <tt>A</tt>'s <a>fromEnum</a> value.
--   That is, <a>fromEnum</a> determines order, but not distance.
--   
--   As an example, consider the enum in the test suite:
--   
--   <pre>
--   enum Baz {
--       BAZ1 = 1; BAZ2 = 2; BAZ3 = 4; BAZ4 = 6;
--       BAZ5 = 7; BAZ6 = 9; BAZ7 = 10; BAZ8 = 12;
--   }
--   </pre>
--   
--   In this case, <tt>succ BAZ2</tt> is <tt>BAZ3</tt> despite their
--   fromEnum values differing by 2. Further, <tt>[BAZ2, BAZ4 ..]</tt> or
--   equivalently <tt>messageEnumFromThen BAZ2 BAZ4</tt> is every other
--   enum (i.e. a distance of 2) when taken as a list, i.e. <tt>[BAZ2,
--   BAZ4, BAZ6, BAZ8]</tt> despite the <a>fromEnum</a> distances being
--   <tt>[4, 3, 3]</tt>.
--   
--   That said, it is highly unwise to use any of the <tt>[a,b ..*]</tt>
--   patterns or <tt>enumFromThen*</tt> functions since adding or removing
--   enums values can cause previously functioning code to fail. I.e.
--   removing <tt>BAZ3</tt> in the above example makes the result
--   equivalent <tt>fromEnum BAZ2</tt> and the sequence now includes every
--   enum value save <tt>BAZ1</tt>. This is all despite the fact that
--   <tt>BAZ3</tt> was never referenced.
module Data.ProtoLens.Message.Enum
messageEnumFrom :: (Enum a, Bounded a) => a -> [a]
messageEnumFromTo :: Enum a => a -> a -> [a]
messageEnumFromThen :: (Enum a, Bounded a) => a -> a -> [a]
messageEnumFromThenTo :: forall a. Enum a => a -> a -> a -> [a]


-- | Functions for converting protocol buffers to a human-readable text
--   format.
module Data.ProtoLens.TextFormat

-- | Convert the given message into a human-readable <a>String</a>.
showMessage :: Message msg => msg -> String

-- | Serializes a proto as a string on a single line. Useful for debugging
--   and error messages like <tt>.DebugString()</tt> in other languages.
showMessageShort :: Message msg => msg -> String

-- | Pretty-print the given message into a human-readable form.
pprintMessage :: Message msg => msg -> Doc

-- | Parse a <a>Message</a> from the human-readable protocol buffer text
--   format.
readMessage :: Message msg => Text -> Either String msg

-- | Parse a <a>Message</a> from the human-readable protocol buffer text
--   format. Throws an error if the parse was not successful.
readMessageOrDie :: Message msg => Text -> msg


-- | The proto-lens package is a new implementation of protocol buffers in
--   Haskell.
module Data.ProtoLens
