-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Parse Google Protocol Buffer specifications -- -- Parse proto files and generate Haskell code. @package protocol-buffers @version 0.3.1 -- | By Chris Kuklewicz, drawing heavily from binary and binary-strict, but -- all the bugs are my own. -- -- This file is under the usual BSD3 licence, copyright 2008. -- -- This started out as an improvement to -- Data.Binary.Strict.IncrementalGet with slightly better -- internals. The simplified Get, runGet, Result -- trio with the Data.Binary.Strict.Class.BinaryParser instance -- are an _untested_ upgrade from IncrementalGet. Especially untested are -- the strictness properties. -- -- Get usefully implements Applicative and Monad, MonadError, -- Alternative and MonadPlus. Unhandled errors are reported along with -- the number of bytes successfully consumed. Effects of suspend -- and putAvailable are visible after failthrowErrormzero. -- -- Each time the parser reaches the end of the input it will return a -- Partial wrapped continuation which requests a (Maybe Lazy.ByteString). -- Passing (Just bs) will append bs to the input so far and continue -- processing. If you pass Nothing to the continuation then you are -- declaring that there will never be more input and that the parser -- should never again return a partial contination; it should return -- failure or finished. -- -- suspendUntilComplete repeatedly uses a partial continuation to -- ask for more input until Nothing is passed and then it proceeds -- with parsing. -- -- The getAvailable command returns the lazy byte string the -- parser has remaining before calling suspend. The -- putAvailable replaces this input and is a bit fancy: it also -- replaces the input at the current offset for all the potential -- catchError/mplus handlers. This change is _not_ reverted by -- failthrowErrormzero. -- -- The three lookAhead and lookAheadM and lookAheadE -- functions are very similar to the ones in binary's Data.Binary.Get. module Text.ProtocolBuffers.Get data Get a -- | runGet is the simple executor runGet :: Get a -> ByteString -> Result a data Result a Failed :: !!Int64 -> String -> Result a Finished :: !!ByteString -> !!Int64 -> a -> Result a Partial :: (Maybe ByteString -> Result a) -> Result a -- | check that there are at least n bytes available in the input. -- This will suspend if there is to little data. ensureBytes :: Int64 -> Get () getStorable :: (Storable a) => Get a -- | Pull n bytes from the unput, as a lazy ByteString. This will -- suspend if there is too little data. getLazyByteString :: Int64 -> Get ByteString -- | Keep calling suspend until Nothing is passed to the -- Partial continuation. This ensures all the data has been loaded -- into the state of the parser. suspendUntilComplete :: Get () -- | Get the input currently available to the parser. getAvailable :: Get ByteString -- | putAvailable replaces the bytestream past the current # of read -- bytes. This will also affect pending MonadError handler and MonadPlus -- branches. I think all pending branches have to have fewer bytesRead -- than the current one. If this is wrong then an error will be thrown. -- -- WARNING : putAvailable is still untested. putAvailable :: ByteString -> Get () -- | lookAhead runs the todo action and then rewinds only -- the BinaryParser state. Any new input from suspend or changes -- from putAvailable are kept. Changes to the user state -- (MonadState) are kept. The MonadWriter output is retained. -- -- If an error is thrown then the entire monad state is reset to last -- catchError as usual. lookAhead :: Get a -> Get a -- | lookAheadM runs the todo action. If the action returns -- Nothing then the BinaryParser state is rewound (as in -- lookAhead). If the action return Just then the -- BinaryParser is not rewound, and lookAheadM acts as an identity. -- -- If an error is thrown then the entire monad state is reset to last -- catchError as usual. lookAheadM :: Get (Maybe a) -> Get (Maybe a) -- | lookAheadE runs the todo action. If the action returns -- Left then the BinaryParser state is rewound (as in -- lookAhead). If the action return Right then the -- BinaryParser is not rewound, and lookAheadE acts as an identity. -- -- If an error is thrown then the entire monad state is reset to last -- catchError as usual. lookAheadE :: Get (Either a b) -> Get (Either a b) -- | Discard the next m bytes skip :: Int64 -> Get () -- | Return the number of bytesRead so far. Initially 0, never -- negative. bytesRead :: Get Int64 -- | Return True if the number of bytes remaining is 0. Any futher -- attempts to read an empty parser will call suspend which might -- result in more input to consume. -- -- Compare with isReallyEmpty isEmpty :: Get Bool -- | Return True if the input is exhausted and will never be added to. -- Returns False if there is input left to consume. -- -- Compare with isEmpty isReallyEmpty :: Get Bool -- | Return the number of bytes remaining before the current input -- runs out and suspend might be called. remaining :: Get Int64 spanOf :: (Word8 -> Bool) -> Get (ByteString) getWord8 :: Get Word8 -- | Pull n bytes from the input, as a strict ByteString. This -- will suspend if there is too little data. If the result spans multiple -- lazy chunks then the result occupies a freshly allocated strict -- bytestring, otherwise it fits in a single chunk and refers to the same -- immutable memory block as the whole chunk. getByteString :: Int -> Get ByteString getWord16be :: Get Word16 getWord32be :: Get Word32 getWord64be :: Get Word64 getWord16le :: Get Word16 getWord32le :: Get Word32 getWord64le :: Get Word64 getWordhost :: Get Word getWord16host :: Get Word16 getWord32host :: Get Word32 getWord64host :: Get Word64 instance Show S instance Alternative Get instance Applicative Get instance MonadPlus Get instance MonadError String Get instance Monad Get instance Functor Get instance MonadSuspend Get instance Show (FrameStack b) instance (Show a) => Show (Result a) -- | Text.ProtocolBuffers.Basic defines or re-exports most of the -- basic field types; Maybe,Bool, Double, and -- Float come from the Prelude instead. This module also defined -- the Mergeable, Default, and Wire classes. module Text.ProtocolBuffers.Basic -- | General-purpose finite sequences. data Seq a :: * -> * -- | Utf8 is used to mark ByteString values that (should) -- contain valud utf8 encoded strings. This type is used to represent -- TYPE_STRING values. newtype Utf8 Utf8 :: ByteString -> Utf8 utf8 :: Utf8 -> ByteString -- | A space-efficient representation of a Word8 vector, supporting many -- efficient operations. A ByteString contains 8-bit characters -- only. -- -- Instances of Eq, Ord, Read, Show, Data, Typeable data ByteString :: * -- | 32-bit signed integer type data Int32 :: * -- | 64-bit signed integer type data Int64 :: * -- | 32-bit unsigned integer type data Word32 :: * -- | 64-bit unsigned integer type data Word64 :: * -- | WireTag is the 32 bit value with the upper 29 bits being the -- FieldId and the lower 3 bits being the WireType newtype WireTag WireTag :: Word32 -> WireTag getWireTag :: WireTag -> Word32 -- | FieldId is the field number which can be in the range 1 to -- 2^29-1 but the value from 19000 to 19999 are forbidden (so sayeth -- Google). newtype FieldId FieldId :: Int32 -> FieldId getFieldId :: FieldId -> Int32 -- | WireType is the 3 bit wire encoding value, and is currently in -- the range 0 to 5, leaving 6 and 7 currently invalid. -- -- newtype WireType WireType :: Word32 -> WireType getWireType :: WireType -> Word32 -- | FieldType is the integer associated with the -- FieldDescriptorProto's Type. The allowed range is currently 1 to 18, -- as shown below (excerpt from descritor.proto) -- -- 
--   // 0 is reserved for errors.
--   // Order is weird for historical reasons.
--   TYPE_DOUBLE         = 1;
--   TYPE_FLOAT          = 2;
--   TYPE_INT64          = 3;   // Not ZigZag encoded.  Negative numbers
--                              // take 10 bytes.  Use TYPE_SINT64 if negative
--                              // values are likely.
--   TYPE_UINT64         = 4;
--   TYPE_INT32          = 5;   // Not ZigZag encoded.  Negative numbers
--                              // take 10 bytes.  Use TYPE_SINT32 if negative
--                              // values are likely.
--   TYPE_FIXED64        = 6;
--   TYPE_FIXED32        = 7;
--   TYPE_BOOL           = 8;
--   TYPE_STRING         = 9;
--   TYPE_GROUP          = 10;  // Tag-delimited aggregate.
--   TYPE_MESSAGE        = 11;  // Length-delimited aggregate.
--   
--   // New in version 2.
--   TYPE_BYTES          = 12;
--   TYPE_UINT32         = 13;
--   TYPE_ENUM           = 14;
--   TYPE_SFIXED32       = 15;
--   TYPE_SFIXED64       = 16;
--   TYPE_SINT32         = 17;  // Uses ZigZag encoding.
--   TYPE_SINT64         = 18;  // Uses ZigZag encoding.
--
newtype FieldType FieldType :: Int -> FieldType getFieldType :: FieldType -> Int -- | EnumCode is the Int32 assoicated with a -- EnumValueDescriptorProto and is in the range 0 to 2^31-1. newtype EnumCode EnumCode :: Int32 -> EnumCode getEnumCode :: EnumCode -> Int32 -- | WireSize is the Int64 size type associate with the lazy -- bytestrings used in the Put and Get monads. type WireSize = Int64 -- | The Mergeable class is not a Monoid, mergeEmpty -- is not a left or right unit like mempty. The default -- mergeAppend is to take the second parameter and discard the -- first one. The mergeConcat defaults to foldl -- associativity. class Mergeable a mergeEmpty :: (Mergeable a) => a mergeAppend :: (Mergeable a) => a -> a -> a mergeConcat :: (Mergeable a, Foldable t) => t a -> a -- | The Default class has the default-default values of types. See -- http://code.google.com/apis/protocolbuffers/docs/proto.html#optional -- and also note that Enum types have a defaultValue that -- is the first one in the .proto file (there is always at least -- one value). Instances of this for messages hold any default value -- defined in the .proto file. defaultValue is where the -- MessageAPI function getVal looks when an optional -- field is not set. class Default a defaultValue :: (Default a) => a -- | The Wire class is for internal use, and may change. If there is -- a mis-match between the FieldType and the type of b -- then you will get a failure at runtime. -- -- Users should stick to the message functions defined in -- Text.ProtocolBuffers.WireMessage and exported to use user by -- Text.ProtocolBuffers. These are less likely to change. class Wire b wireSize :: (Wire b) => FieldType -> b -> WireSize wirePut :: (Wire b) => FieldType -> b -> Put wireGet :: (Wire b) => FieldType -> Get b instance Typeable EnumCode instance Typeable FieldType instance Typeable WireType instance Typeable FieldId instance Typeable WireTag instance Typeable Utf8 instance Eq EnumCode instance Ord EnumCode instance Read EnumCode instance Show EnumCode instance Num EnumCode instance Data EnumCode instance Eq FieldType instance Ord FieldType instance Read FieldType instance Show FieldType instance Num FieldType instance Data FieldType instance Eq WireType instance Ord WireType instance Read WireType instance Show WireType instance Num WireType instance Data WireType instance Eq FieldId instance Ord FieldId instance Read FieldId instance Show FieldId instance Num FieldId instance Data FieldId instance Ix FieldId instance Eq WireTag instance Ord WireTag instance Read WireTag instance Show WireTag instance Num WireTag instance Bits WireTag instance Bounded WireTag instance Data WireTag instance Read Utf8 instance Show Utf8 instance Data Utf8 instance Eq Utf8 instance Ord Utf8 instance Bounded EnumCode instance Bounded FieldType instance Bounded WireType instance Bounded FieldId -- | A strong feature of the protocol-buffers package is that it does not -- contain any structures defined by descriptor.proto! This prevents me -- hitting any annoying circular dependencies. The structures defined -- here are included in each module created by hprotoc. They are -- optimized for use in code generation. -- -- These values can be inspected at runtime by the user's code, but I -- have yet to write much documentation. Luckily the record field names -- are somewhat descriptive. module Text.ProtocolBuffers.Reflections -- | This is fully qualified name data type for code generation. The -- haskellPrefix was possibly specified on the hprotoc -- command line. The parentModule is a combination of the module -- prefix from the '.proto' file and any nested levels of definition. -- -- The name components are likely to have been mangled to ensure the -- baseName started with an uppercase letter, in ['A'..'Z'] -- . data ProtoName ProtoName :: String -> String -> String -> ProtoName -- | Haskell specific prefix to module hierarchy (e.g. Text.Foo) haskellPrefix :: ProtoName -> String -- | Proto specified namespace (like Com.Google.Bar) parentModule :: ProtoName -> String -- | unqualfied name of this thing (with no periods) baseName :: ProtoName -> String data ProtoInfo ProtoInfo :: ProtoName -> [FilePath] -> String -> Seq KeyInfo -> [DescriptorInfo] -> [EnumInfo] -> Map ProtoName (Seq FieldInfo) -> ProtoInfo protoMod :: ProtoInfo -> ProtoName protoFilePath :: ProtoInfo -> [FilePath] protoSource :: ProtoInfo -> String extensionKeys :: ProtoInfo -> Seq KeyInfo messages :: ProtoInfo -> [DescriptorInfo] enums :: ProtoInfo -> [EnumInfo] knownKeyMap :: ProtoInfo -> Map ProtoName (Seq FieldInfo) data DescriptorInfo DescriptorInfo :: ProtoName -> [FilePath] -> Bool -> Seq FieldInfo -> Seq KeyInfo -> [(FieldId, FieldId)] -> Seq FieldInfo -> Bool -> DescriptorInfo descName :: DescriptorInfo -> ProtoName descFilePath :: DescriptorInfo -> [FilePath] isGroup :: DescriptorInfo -> Bool fields :: DescriptorInfo -> Seq FieldInfo keys :: DescriptorInfo -> Seq KeyInfo extRanges :: DescriptorInfo -> [(FieldId, FieldId)] knownKeys :: DescriptorInfo -> Seq FieldInfo storeUnknown :: DescriptorInfo -> Bool data FieldInfo FieldInfo :: ProtoName -> FieldId -> WireTag -> WireSize -> Bool -> Bool -> FieldType -> Maybe ProtoName -> Maybe ByteString -> Maybe HsDefault -> FieldInfo fieldName :: FieldInfo -> ProtoName fieldNumber :: FieldInfo -> FieldId wireTag :: FieldInfo -> WireTag -- | Bytes required in the Varint formatted wireTag wireTagLength :: FieldInfo -> WireSize isRequired :: FieldInfo -> Bool canRepeat :: FieldInfo -> Bool -- | fromEnum of Text.DescriptorProtos.FieldDescriptorProto.Type typeCode :: FieldInfo -> FieldType -- | Set for Messages,Groups,and Enums typeName :: FieldInfo -> Maybe ProtoName -- | crappy, but not escaped, thing hsRawDefault :: FieldInfo -> Maybe ByteString -- | nice parsed thing hsDefault :: FieldInfo -> Maybe HsDefault type KeyInfo = (ProtoName, FieldInfo) -- | HsDefault stores the parsed default from the proto file in a -- form that will make a nice literal in the -- Language.Haskell.Exts.Syntax code generation by -- hprotoc. -- -- Note that Utf8 labeled byte sequences have been stripped to just -- ByteString here as this is sufficient for code generation. data HsDefault HsDef'Bool :: Bool -> HsDefault HsDef'ByteString :: ByteString -> HsDefault HsDef'Rational :: Rational -> HsDefault HsDef'Integer :: Integer -> HsDefault HsDef'Enum :: String -> HsDefault data EnumInfo EnumInfo :: ProtoName -> [FilePath] -> [(EnumCode, String)] -> EnumInfo enumName :: EnumInfo -> ProtoName enumFilePath :: EnumInfo -> [FilePath] enumValues :: EnumInfo -> [(EnumCode, String)] type EnumInfoApp e = [(EnumCode, String, e)] class ReflectDescriptor m getMessageInfo :: (ReflectDescriptor m) => m -> GetMessageInfo reflectDescriptorInfo :: (ReflectDescriptor m) => m -> DescriptorInfo class ReflectEnum e reflectEnum :: (ReflectEnum e) => EnumInfoApp e reflectEnumInfo :: (ReflectEnum e) => e -> EnumInfo parentOfEnum :: (ReflectEnum e) => e -> Maybe DescriptorInfo -- | GetMessageInfo is used in getting messages from the wire. It -- supplies the Set of precomposed wire tags that must be found in -- the message as well as a Set of all allowed tags (including -- known extension fields and all required wire tags). -- -- Extension fields not in the allowedTags set are still loaded, but only -- as ByteString blobs that will have to interpreted later. data GetMessageInfo GetMessageInfo :: Set WireTag -> Set WireTag -> GetMessageInfo requiredTags :: GetMessageInfo -> Set WireTag allowedTags :: GetMessageInfo -> Set WireTag instance Typeable EnumInfo instance Typeable HsDefault instance Typeable FieldInfo instance Typeable GetMessageInfo instance Typeable DescriptorInfo instance Typeable ProtoInfo instance Typeable ProtoName instance Show EnumInfo instance Read EnumInfo instance Eq EnumInfo instance Ord EnumInfo instance Data EnumInfo instance Show HsDefault instance Read HsDefault instance Eq HsDefault instance Ord HsDefault instance Data HsDefault instance Show FieldInfo instance Read FieldInfo instance Eq FieldInfo instance Ord FieldInfo instance Data FieldInfo instance Show GetMessageInfo instance Read GetMessageInfo instance Eq GetMessageInfo instance Ord GetMessageInfo instance Data GetMessageInfo instance Show DescriptorInfo instance Read DescriptorInfo instance Eq DescriptorInfo instance Ord DescriptorInfo instance Data DescriptorInfo instance Show ProtoInfo instance Read ProtoInfo instance Eq ProtoInfo instance Ord ProtoInfo instance Data ProtoInfo instance Show ProtoName instance Read ProtoName instance Eq ProtoName instance Ord ProtoName instance Data ProtoName -- | This only defined instances now. The class definition was moved to -- Basic.hs module Text.ProtocolBuffers.Default instance Default Word64 instance Default Word32 instance Default Int64 instance Default Int32 instance Default Float instance Default Double instance Default Utf8 instance Default ByteString instance Default Bool instance Default (Seq a) instance (Default a) => Default (Maybe a) -- | This provides instance of Mergeable for the basic field types. module Text.ProtocolBuffers.Mergeable instance Mergeable Word64 instance Mergeable Word32 instance Mergeable Int64 instance Mergeable Int32 instance Mergeable Float instance Mergeable Double instance Mergeable ByteString instance Mergeable Utf8 instance Mergeable Bool instance Mergeable (Seq a) instance (Mergeable a) => Mergeable (Maybe a) -- | Here are the serialization and deserialization functions. -- -- This module cooperates with the generated code to implement the Wire -- instances. The encoding is mostly documented at -- http://code.google.com/apis/protocolbuffers/docs/encoding.html. -- -- The user API functions are grouped into sections and documented. The -- rest are for internal use. module Text.ProtocolBuffers.WireMessage -- | This computes the size of the message's fields with tags on the wire -- with no initial tag or length (in bytes). This is also the length of -- the message as placed between group start and stop tags. messageSize :: (ReflectDescriptor msg, Wire msg) => msg -> WireSize -- | This is runPut applied to messagePutM. It result in a -- ByteString with a length of messageSize bytes. messagePut :: (ReflectDescriptor msg, Wire msg) => msg -> ByteString -- | This consumes the ByteString to decode a message. It assumes -- the ByteString is merely a sequence of the tagged fields of the -- message, and consumes until a group stop tag is detected or the entire -- input is consumed. Any ByteString past the end of the stop tag -- is returned as well. -- -- This is runGetOnLazy applied to messageGetM. messageGet :: (ReflectDescriptor msg, Wire msg) => ByteString -> Either String (msg, ByteString) -- | This writes just the message's fields with tags to the wire. This -- Put monad can be composed and eventually executed with -- runPut. -- -- This is actually wirePut 10 msg messagePutM :: (ReflectDescriptor msg, Wire msg) => msg -> Put -- | This reads the tagged message fields until the stop tag or the end of -- input is reached. -- -- This is actually wireGet 10 msg messageGetM :: (ReflectDescriptor msg, Wire msg) => Get msg -- | This computes the size of the message fields as in messageSize -- and add the length of the encoded size to the total. Thus this is the -- the length of the message including the encoded length header, but -- without any leading tag. messageWithLengthSize :: (ReflectDescriptor msg, Wire msg) => msg -> WireSize -- | This is runPut applied to messageWithLengthPutM. It -- results in a ByteString with a length of -- messageWithLengthSize bytes. messageWithLengthPut :: (ReflectDescriptor msg, Wire msg) => msg -> ByteString -- | This runGetOnLazy applied to messageWithLengthGetM. -- -- This first reads the encoded length of the message and will then -- succeed when it has consumed precisely this many additional bytes. The -- ByteString after this point will be returned. messageWithLengthGet :: (ReflectDescriptor msg, Wire msg) => ByteString -> Either String (msg, ByteString) -- | This writes the encoded length of the message's fields and then the -- message's fields with tags to the wire. This Put monad can be -- composed and eventually executed with runPut. -- -- This is actually wirePut 11 msg messageWithLengthPutM :: (ReflectDescriptor msg, Wire msg) => msg -> Put -- | This reads the encoded message length and then the message. -- -- This is actually wireGet 11 msg messageWithLengthGetM :: (ReflectDescriptor msg, Wire msg) => Get msg -- | This computes the size of the messageWithLengthSize and then -- adds the length an initial tag with the given FieldId. messageAsFieldSize :: (ReflectDescriptor msg, Wire msg) => FieldId -> msg -> WireSize -- | This writes an encoded wire tag with the given FieldId and then -- the encoded length of the message's fields and then the message's -- fields with tags to the wire. This Put monad can be composed -- and eventually executed with runPut. messageAsFieldPutM :: (ReflectDescriptor msg, Wire msg) => FieldId -> msg -> Put -- | This reads a wire tag (must be of type '2') to get the FieldId. -- Then the encoded message length is read, followed by the message -- itself. Both the FieldId and the message are returned. -- -- This allows for incremental reading and processing. messageAsFieldGetM :: (ReflectDescriptor msg, Wire msg) => Get (FieldId, msg) -- | Put merely lifts Builder into a Writer monad, applied to (). type Put = PutM () data Get a -- | Run the Put monad with a serialiser runPut :: Put -> ByteString -- | runGet is the simple executor runGet :: Get a -> ByteString -> Result a runGetOnLazy :: Get r -> ByteString -> Either String (r, ByteString) -- | This is runGetOnLazy with the Left results converted to -- error calls and the trailing ByteString discarded. This -- use of runtime errors is discouraged, but may be convenient. getFromBS :: Get r -> ByteString -> r -- | The Wire class is for internal use, and may change. If there is -- a mis-match between the FieldType and the type of b -- then you will get a failure at runtime. -- -- Users should stick to the message functions defined in -- Text.ProtocolBuffers.WireMessage and exported to use user by -- Text.ProtocolBuffers. These are less likely to change. class Wire b wireSize :: (Wire b) => FieldType -> b -> WireSize wirePut :: (Wire b) => FieldType -> b -> Put wireGet :: (Wire b) => FieldType -> Get b size'Varint :: (Bits a, Integral a) => a -> Int64 toWireType :: FieldType -> WireType toWireTag :: FieldId -> FieldType -> WireTag mkWireTag :: FieldId -> WireType -> WireTag -- | Used in generated code. prependMessageSize :: WireSize -> WireSize -- | Used in generated code. putSize :: WireSize -> Put putVarUInt :: (Integral a, Bits a) => a -> Put getVarInt :: (Integral a, Bits a) => Get a -- | Write a lazy ByteString efficiently, simply appending the lazy -- ByteString chunks to the output buffer putLazyByteString :: ByteString -> Put splitWireTag :: WireTag -> (FieldId, WireType) -- | Used in generated code. wireSizeReq :: (Wire b) => Int64 -> FieldType -> b -> Int64 -- | Used in generated code. wireSizeOpt :: (Wire b) => Int64 -> FieldType -> Maybe b -> Int64 -- | Used in generated code. wireSizeRep :: (Wire b) => Int64 -> FieldType -> Seq b -> Int64 -- | Used in generated code. wirePutReq :: (Wire b) => WireTag -> FieldType -> b -> Put -- | Used in generated code. wirePutOpt :: (Wire b) => WireTag -> FieldType -> Maybe b -> Put -- | Used in generated code. wirePutRep :: (Wire b) => WireTag -> FieldType -> Seq b -> Put wireSizeErr :: (Typeable a) => FieldType -> a -> WireSize wirePutErr :: (Typeable a) => FieldType -> a -> Put wireGetErr :: (Typeable a) => FieldType -> Get a -- | Used by generated code getMessage :: (Mergeable message, ReflectDescriptor message, Typeable message) => (FieldId -> message -> Get message) -> Get message -- | Used by generated code getBareMessage assumes the wireTag for the -- message, if it existed, has already been read. getBareMessage assumes -- that it does needs to read the Varint encoded length of the message. -- getBareMessage will consume the entire ByteString it is operating on, -- or until it finds any STOP_GROUP tag getBareMessage :: (Typeable message, Mergeable message, ReflectDescriptor message) => (FieldId -> message -> Get message) -> Get message getMessageWith :: (Mergeable message, ReflectDescriptor message) => (FieldId -> WireType -> message -> Get message) -> (FieldId -> message -> Get message) -> Get message getBareMessageWith :: (Mergeable message, ReflectDescriptor message) => (FieldId -> WireType -> message -> Get message) -> (FieldId -> message -> Get message) -> Get message unknownField :: FieldId -> Get a unknown :: (Typeable a, ReflectDescriptor a) => FieldId -> WireType -> a -> Get a -- | This reads in the raw bytestring corresponding to an field known only -- through the wiretag's FieldId and WireType. wireGetFromWire :: FieldId -> WireType -> Get ByteString castWord64ToDouble :: Word64 -> Double castWord32ToFloat :: Word32 -> Float castDoubleToWord64 :: Double -> Word64 castFloatToWord32 :: Float -> Word32 zzEncode64 :: Int64 -> Word64 zzEncode32 :: Int32 -> Word32 zzDecode64 :: Word64 -> Int64 zzDecode32 :: Word32 -> Int32 instance Wire Int instance Wire ByteString instance Wire Utf8 instance Wire Bool instance Wire Word32 instance Wire Word64 instance Wire Int32 instance Wire Int64 instance Wire Float instance Wire Double -- | The Extensions module contributes two main things. The first is -- the definition and implementation of extensible message features. This -- means that the ExtField data type is exported but its -- constructor is (in an ideal world) hidden. -- -- This first part also includes the keys for the extension fields: the -- Key data type. These are typically defined in code generated by -- hprotoc from '.proto' file definitions. -- -- The second main part is the MessageAPI class which defines -- getVal and isSet. These allow uniform access to normal -- and extension fields for users. -- -- Access to extension fields is strictly though keys. There is not -- currently any way to query or change or clear any other extension -- field data. -- -- This module is likely to get broken up into pieces. module Text.ProtocolBuffers.Extensions -- | This allows reflection, in this case it gives the numerical -- FieldId of the key, from 1 to 2^29-1 (excluding 19,000 through -- 19,999). getKeyFieldId :: Key c msg v -> FieldId -- | This allows reflection, in this case it gives the FieldType -- enumeration value (1 to 18) of the -- Text.DescriptorProtos.FieldDescriptorProto.Type of the field. getKeyFieldType :: Key c msg v -> FieldType -- | This will return the default value for a given Key, which is -- set in the '.proto' file, or if unset it is the defaultValue of -- that type. getKeyDefaultValue :: Key c msg v -> v -- | The Key data type is used with the ExtKey class to put, -- get, and clear external fields of messages. The Key can also be -- used with the MessagesAPI to get a possibly default value and -- to check whether a key has been set in a message. -- -- The Key type (opaque to the user) has a phantom type of Maybe -- or Seq that corresponds to Optional or Repeated fields. And a second -- phantom type that matches the message type it must be used with. The -- third type parameter corresonds to the Haskell value type. -- -- The Key is a GADT that puts all the needed class instances into -- scope. The actual content is the FieldId ( numeric key), the -- FieldType (for sanity checks), and Maybe v (a -- non-standard default value). -- -- When code is generated all of the known keys are taken into account in -- the deserialization from the wire. Unknown extension fields are read -- as a collection of raw byte sequences. If a key is then presented it -- will be used to parse the bytes. -- -- There is no guarantee for what happens if two Keys disagree about the -- type of a field; in particular there may be undefined values and -- runtime errors. The data constructor for Key has to be exported -- to the generated code, but is not exposed to the user by -- Text.ProtocolBuffers. data Key c msg v Key :: FieldId -> FieldType -> (Maybe v) -> Key c msg v -- | The ExtKey class has three functions for user of the API: -- putExt, getExt, and clearExt. The -- wireGetKey is used in generated code. -- -- There are two instances of this class, Maybe for optional -- message fields and Seq for repeated message fields. This class -- allows for uniform treatment of these two kinds of extension fields. class ExtKey c putExt :: (ExtKey c) => Key c msg v -> c v -> msg -> msg getExt :: (ExtKey c) => Key c msg v -> msg -> Either String (c v) clearExt :: (ExtKey c) => Key c msg v -> msg -> msg wireGetKey :: (ExtKey c) => Key c msg v -> msg -> Get msg class MessageAPI msg a b | msg a -> b getVal :: (MessageAPI msg a b) => msg -> a -> b isSet :: (MessageAPI msg a b) => msg -> a -> Bool -- | This is used by the generated code wireSizeExtField :: ExtField -> WireSize -- | This is used by the generated code. The data is serialized in order of -- increasing field number. wirePutExtField :: ExtField -> Put -- | This is used by the generated code to get messages that have -- extensions getMessageExt :: (Mergeable message, ReflectDescriptor message, Typeable message, ExtendMessage message) => (FieldId -> message -> Get message) -> Get message -- | This is used by the generated code to get messages that have -- extensions getBareMessageExt :: (Mergeable message, ReflectDescriptor message, Typeable message, ExtendMessage message) => (FieldId -> message -> Get message) -> Get message -- | get a value from the wire into the message's ExtField. This is used by -- getMessageExt and getBareMessageExt above. loadExtension :: (ReflectDescriptor a, ExtendMessage a) => FieldId -> WireType -> a -> Get a -- | The Key and GPWitness GADTs use GPB as a -- shorthand for many classes. class (Mergeable a, Default a, Wire a, Show a, Typeable a, Eq a, Ord a) => GPB a -- | ExtField is a newtype'd map from the numeric FieldId key to the -- ExtFieldValue. This allows for the needed class instances. newtype ExtField ExtField :: (Map FieldId ExtFieldValue) -> ExtField -- | ExtendMessage abstracts the operations of storing and -- retrieving the ExtField from the message, and provides the -- reflection needed to know the valid field numbers. -- -- This only used internally. class (Typeable msg) => ExtendMessage msg getExtField :: (ExtendMessage msg) => msg -> ExtField putExtField :: (ExtendMessage msg) => ExtField -> msg -> msg validExtRanges :: (ExtendMessage msg) => msg -> [(FieldId, FieldId)] instance Typeable ExtField instance Typeable DummyMessageType instance Typeable ExtFieldValue instance Typeable GPDynSeq instance Typeable GPDyn instance Typeable1 GPWitness instance Eq ExtField instance Ord ExtField instance Show ExtField instance Ord ExtFieldValue instance Show ExtFieldValue instance MessageAPI msg (msg -> Word64) Word64 instance MessageAPI msg (msg -> Word32) Word32 instance MessageAPI msg (msg -> Int64) Int64 instance MessageAPI msg (msg -> Int32) Int32 instance MessageAPI msg (msg -> Float) Float instance MessageAPI msg (msg -> Double) Double instance MessageAPI msg (msg -> Utf8) Utf8 instance MessageAPI msg (msg -> ByteString) ByteString instance (Default v) => MessageAPI msg (Key Seq msg v) (Seq v) instance (Default v) => MessageAPI msg (Key Maybe msg v) v instance MessageAPI msg (msg -> Seq a) (Seq a) instance (Default msg, Default a) => MessageAPI msg (msg -> Maybe a) a instance ExtKey Seq instance ExtKey Maybe instance Show GPDynSeq instance Ord GPDynSeq instance Eq GPDynSeq instance Show GPDyn instance Ord GPDyn instance Eq GPDyn instance (GPB a) => Data (GPWitness a) instance Ord (GPWitness a) instance Eq (GPWitness a) instance Show (GPWitness a) instance Default ExtField instance Mergeable ExtField instance GPB Word64 instance GPB Word32 instance GPB Int64 instance GPB Int32 instance GPB Float instance GPB Double instance GPB Utf8 instance GPB ByteString instance GPB Bool instance Eq ExtFieldValue instance ExtendMessage DummyMessageType instance (Typeable1 c, Typeable msg, Typeable v) => Show (Key c msg v) instance (Typeable1 c) => Typeable2 (Key c) -- | This module add unknown field supprt to the library -- -- This should support 1) Storing unknown bytestrings in messages a) -- Mergeable b) Default c) Show 2) loading the unknown bytestrings into a -- (Map FieldId) from wire a) If wiretypes differ this is an error so -- report it b) Take extra care to ensure a _copy_ of the input is kept -- (?) 3) save unknown bytestring back to the wire 4) API ? a) Provide -- ability to wireGet the data as a real type b) clear the data c) -- has any unkown data ? 5) Extend reflection to indicate presence of -- support for unkown data 6) Extend Options and command line to flag -- this 7) Extend hprotoc to add in this field module Text.ProtocolBuffers.Unknown newtype UnknownField UnknownField :: (Map FieldId UnknownFieldValue) -> UnknownField class UnknownMessage msg getUnknownField :: (UnknownMessage msg) => msg -> UnknownField putUnknownField :: (UnknownMessage msg) => UnknownField -> msg -> msg data UnknownFieldValue UFV :: !WireType -> !Seq ByteString -> UnknownFieldValue -- | This is used by the generated code wireSizeUnknownField :: UnknownField -> WireSize -- | This is used by the generated code wirePutUnknownField :: UnknownField -> Put loadUnknown :: (Typeable a, UnknownMessage a) => FieldId -> WireType -> a -> Get a instance Typeable UnknownFieldValue instance Typeable UnknownField instance Eq UnknownFieldValue instance Ord UnknownFieldValue instance Show UnknownFieldValue instance Read UnknownFieldValue instance Data UnknownFieldValue instance Eq UnknownField instance Ord UnknownField instance Show UnknownField instance Read UnknownField instance Data UnknownField instance Default UnknownField instance Mergeable UnknownField -- | This provides much that is needed for the output of hprotoc -- to compile. It will be imported qualified as P', the prime ensuring no -- name conflicts are possible. module Text.ProtocolBuffers.Header emptyBS :: ByteString -- | O(n) Convert a String into a ByteString. pack :: [Char] -> ByteString append :: Seq a -> a -> Seq a -- | Text.ProtocolBuffers exposes the client API. This merely -- re-exports parts of the other modules in protocol-buffers. The exposed -- parts are: -- -- 
--   import Text.ProtocolBuffers.Basic
--     ( Seq,Utf8(..),ByteString,Int32,Int64,Word32,Word64
--     , WireTag,FieldId,WireType,FieldType,EnumCode,WireSize
--     , Mergeable(..),Default(..),Wire)
--   import Text.ProtocolBuffers.Default()
--   import Text.ProtocolBuffers.Extensions
--     ( Key,ExtKey(getExt,putExt,clearExt),MessageAPI(..)
--     , getKeyFieldId,getKeyFieldType,getKeyDefaultValue)
--   import Text.ProtocolBuffers.Mergeable()
--   import Text.ProtocolBuffers.Reflections
--     ( ReflectDescriptor(..),ReflectEnum(..),ProtoName(..),HsDefault(..),EnumInfoApp
--     , KeyInfo,FieldInfo(..),DescriptorInfo(..),EnumInfo(..),ProtoInfo(..))
--   import Text.ProtocolBuffers.WireMessage
--     ( Put,Get,runPut,runGet,runGetOnLazy
--     , messageSize,messagePut,messageGet,messagePutM,messageGetM
--     , messageWithLengthSize,messageWithLengthPut,messageWithLengthGet,messageWithLengthPutM,messageWithLengthGetM
--     , messageAsFieldSize,messageAsFieldPutM,messageAsFieldGetM)
--
module Text.ProtocolBuffers