Safe Haskell	None
Language	Haskell2010

Text.ProtocolBuffers.WireMessage

Contents

Description

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. The main functions are messageGet and messagePut (and messageSize). There are then several 'message*' variants which allow for finer control and for making delimited messages.

Synopsis

messageSize :: (ReflectDescriptor msg, Wire msg) => msg -> WireSize
messagePut :: (ReflectDescriptor msg, Wire msg) => msg -> ByteString
messageGet :: (ReflectDescriptor msg, Wire msg) => ByteString -> Either String (msg, ByteString)
messagePutM :: (ReflectDescriptor msg, Wire msg) => msg -> Put
messageGetM :: (ReflectDescriptor msg, Wire msg) => Get msg
messageWithLengthSize :: (ReflectDescriptor msg, Wire msg) => msg -> WireSize
messageWithLengthPut :: (ReflectDescriptor msg, Wire msg) => msg -> ByteString
messageWithLengthGet :: (ReflectDescriptor msg, Wire msg) => ByteString -> Either String (msg, ByteString)
messageWithLengthPutM :: (ReflectDescriptor msg, Wire msg) => msg -> Put
messageWithLengthGetM :: (ReflectDescriptor msg, Wire msg) => Get msg
messageAsFieldSize :: (ReflectDescriptor msg, Wire msg) => FieldId -> msg -> WireSize
messageAsFieldPutM :: (ReflectDescriptor msg, Wire msg) => FieldId -> msg -> Put
messageAsFieldGetM :: (ReflectDescriptor msg, Wire msg) => Get (FieldId, msg)
type Put = PutM ()
data PutM a
data Get a
runPut :: Put -> ByteString
runPutM :: PutM a -> (a, ByteString)
runGet :: Get a -> ByteString -> Result a
runGetOnLazy :: Get r -> ByteString -> Either String (r, ByteString)
getFromBS :: Get r -> ByteString -> r
class Wire b where
- wireSize :: FieldType -> b -> WireSize
- wirePut :: FieldType -> b -> Put
- wirePutWithSize :: FieldType -> b -> PutM WireSize
- wireGet :: FieldType -> Get b
- wireGetPacked :: FieldType -> Get (Seq b)
size'WireTag :: WireTag -> Int64
size'WireSize :: Int64 -> Int64
toWireType :: FieldType -> WireType
toWireTag :: FieldId -> FieldType -> WireTag
toPackedWireTag :: FieldId -> WireTag
mkWireTag :: FieldId -> WireType -> WireTag
prependMessageSize :: WireSize -> WireSize
putSize :: WireSize -> Put
putVarUInt :: (Integral a, Bits a) => a -> Put
getVarInt :: (Show a, Integral a, Bits a) => Get a
putLazyByteString :: ByteString -> Put
splitWireTag :: WireTag -> (FieldId, WireType)
fieldIdOf :: WireTag -> FieldId
wireSizeReq :: Wire v => Int64 -> FieldType -> v -> Int64
wireSizeOpt :: Wire v => Int64 -> FieldType -> Maybe v -> Int64
wireSizeRep :: Wire v => Int64 -> FieldType -> Seq v -> Int64
wireSizePacked :: Wire v => Int64 -> FieldType -> Seq v -> Int64
wirePutReq :: Wire v => WireTag -> FieldType -> v -> Put
wirePutOpt :: Wire v => WireTag -> FieldType -> Maybe v -> Put
wirePutRep :: Wire v => WireTag -> FieldType -> Seq v -> Put
wirePutPacked :: Wire v => WireTag -> FieldType -> Seq v -> Put
wirePutReqWithSize :: Wire v => WireTag -> FieldType -> v -> PutM WireSize
wirePutOptWithSize :: Wire v => WireTag -> FieldType -> Maybe v -> PutM WireSize
wirePutRepWithSize :: Wire v => WireTag -> FieldType -> Seq v -> PutM WireSize
wirePutPackedWithSize :: Wire v => WireTag -> FieldType -> Seq v -> PutM WireSize
sequencePutWithSize :: Foldable f => f (PutM WireSize) -> PutM WireSize
wireSizeErr :: Typeable a => FieldType -> a -> WireSize
wirePutErr :: Typeable a => FieldType -> a -> PutM b
wireGetErr :: Typeable a => FieldType -> Get a
getMessageWith :: (Default message, ReflectDescriptor message) => (WireTag -> message -> Get message) -> Get message
getBareMessageWith :: (Default message, ReflectDescriptor message) => (WireTag -> message -> Get message) -> Get message
wireGetEnum :: (Typeable e, Enum e) => (Int -> Maybe e) -> Get e
wireGetPackedEnum :: (Typeable e, Enum e) => (Int -> Maybe e) -> Get (Seq e)
unknownField :: Typeable a => a -> FieldId -> Get a
unknown :: (Typeable a, ReflectDescriptor a) => FieldId -> WireType -> a -> Get a
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

User API functions

Main encoding and decoding operations (non-delimited message encoding)

messageSize :: (ReflectDescriptor msg, Wire msg) => msg -> WireSize Source #

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.

messagePut :: (ReflectDescriptor msg, Wire msg) => msg -> ByteString Source #

This is runPut applied to messagePutM. It result in a ByteString with a length of messageSize bytes.

messageGet :: (ReflectDescriptor msg, Wire msg) => ByteString -> Either String (msg, ByteString) Source #

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.

messagePutM :: (ReflectDescriptor msg, Wire msg) => msg -> Put Source #

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

messageGetM :: (ReflectDescriptor msg, Wire msg) => Get msg Source #

This reads the tagged message fields until the stop tag or the end of input is reached.

This is actually wireGet 10 msg

These should agree with the length delimited message format of protobuf-2.10, where the message size preceeds the data.

messageWithLengthSize :: (ReflectDescriptor msg, Wire msg) => msg -> WireSize Source #

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.

messageWithLengthPut :: (ReflectDescriptor msg, Wire msg) => msg -> ByteString Source #

This is runPut applied to messageWithLengthPutM. It results in a ByteString with a length of messageWithLengthSize bytes.

messageWithLengthGet :: (ReflectDescriptor msg, Wire msg) => ByteString -> Either String (msg, ByteString) Source #

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.

messageWithLengthPutM :: (ReflectDescriptor msg, Wire msg) => msg -> Put Source #

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

messageWithLengthGetM :: (ReflectDescriptor msg, Wire msg) => Get msg Source #

This reads the encoded message length and then the message.

This is actually wireGet 11 msg

Encoding to write or read a single message field (good for delimited messages or incremental use)

messageAsFieldSize :: (ReflectDescriptor msg, Wire msg) => FieldId -> msg -> WireSize Source #

This computes the size of the messageWithLengthSize and then adds the length an initial tag with the given FieldId.

messageAsFieldPutM :: (ReflectDescriptor msg, Wire msg) => FieldId -> msg -> Put Source #

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.

messageAsFieldGetM :: (ReflectDescriptor msg, Wire msg) => Get (FieldId, msg) Source #

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.

The Put monad from the binary package, and a custom binary Get monad (Text.ProtocolBuffers.Get)

type Put = PutM () #

Put merely lifts Builder into a Writer monad, applied to ().

data PutM a #

The PutM type. A Writer monad over the efficient Builder monoid.

Instances

Instances details

Monad PutM
Instance details Defined in Data.Binary.Put Methods (>>=) :: PutM a -> (a -> PutM b) -> PutM b # (>>) :: PutM a -> PutM b -> PutM b # return :: a -> PutM a #
Functor PutM
Instance details Defined in Data.Binary.Put Methods fmap :: (a -> b) -> PutM a -> PutM b # (<$) :: a -> PutM b -> PutM a #
Applicative PutM
Instance details Defined in Data.Binary.Put Methods pure :: a -> PutM a # (<>) :: PutM (a -> b) -> PutM a -> PutM b # liftA2 :: (a -> b -> c) -> PutM a -> PutM b -> PutM c # (>) :: PutM a -> PutM b -> PutM b # (<*) :: PutM a -> PutM b -> PutM a #
Semigroup (PutM ())
Instance details Defined in Data.Binary.Put Methods (<>) :: PutM () -> PutM () -> PutM () # sconcat :: NonEmpty (PutM ()) -> PutM () # stimes :: Integral b => b -> PutM () -> PutM () #
Monoid (PutM ())
Instance details Defined in Data.Binary.Put Methods mempty :: PutM () # mappend :: PutM () -> PutM () -> PutM () # mconcat :: [PutM ()] -> PutM () #

data Get a Source #

Instances

Instances details

Monad Get Source #
Instance details Defined in Text.ProtocolBuffers.Get Methods (>>=) :: Get a -> (a -> Get b) -> Get b # (>>) :: Get a -> Get b -> Get b # return :: a -> Get a #
Functor Get Source #
Instance details Defined in Text.ProtocolBuffers.Get Methods fmap :: (a -> b) -> Get a -> Get b # (<$) :: a -> Get b -> Get a #
MonadFail Get Source #
Instance details Defined in Text.ProtocolBuffers.Get Methods fail :: String -> Get a #
Applicative Get Source #
Instance details Defined in Text.ProtocolBuffers.Get Methods pure :: a -> Get a # (<>) :: Get (a -> b) -> Get a -> Get b # liftA2 :: (a -> b -> c) -> Get a -> Get b -> Get c # (>) :: Get a -> Get b -> Get b # (<*) :: Get a -> Get b -> Get a #
Alternative Get Source #
Instance details Defined in Text.ProtocolBuffers.Get Methods empty :: Get a # (<\|>) :: Get a -> Get a -> Get a # some :: Get a -> Get [a] # many :: Get a -> Get [a] #
MonadPlus Get Source #
Instance details Defined in Text.ProtocolBuffers.Get Methods mzero :: Get a # mplus :: Get a -> Get a -> Get a #
MonadError String Get Source #
Instance details Defined in Text.ProtocolBuffers.Get Methods throwError :: String -> Get a # catchError :: Get a -> (String -> Get a) -> Get a #

runPut :: Put -> ByteString #

Run the Put monad with a serialiser

runPutM :: PutM a -> (a, ByteString) #

Run the Put monad with a serialiser and get its result

runGet :: Get a -> ByteString -> Result a Source #

runGet is the simple executor

runGetOnLazy :: Get r -> ByteString -> Either String (r, ByteString) Source #

This is like runGet, without the ability to pass in more input beyond the initial ByteString. Thus the ByteString argument is taken to be the entire input. To be able to incrementally feed in more input you should use runGet and respond to Partial differently.

getFromBS :: Get r -> ByteString -> r Source #

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.

The Wire monad itself. Users should beware that passing an incompatible `FieldType` is a runtime error or fail

class Wire b where Source #

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.

Minimal complete definition

wireGet, wireSize, (wirePut | wirePutWithSize)

Methods

wireSize :: FieldType -> b -> WireSize Source #

wirePut :: FieldType -> b -> Put Source #

wirePutWithSize :: FieldType -> b -> PutM WireSize Source #

wireGet :: FieldType -> Get b Source #

wireGetPacked :: FieldType -> Get (Seq b) Source #

Instances

Instances details

Wire Bool Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Bool -> WireSize Source # wirePut :: FieldType -> Bool -> Put Source # wirePutWithSize :: FieldType -> Bool -> PutM WireSize Source # wireGet :: FieldType -> Get Bool Source # wireGetPacked :: FieldType -> Get (Seq Bool) Source #
Wire Double Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Double -> WireSize Source # wirePut :: FieldType -> Double -> Put Source # wirePutWithSize :: FieldType -> Double -> PutM WireSize Source # wireGet :: FieldType -> Get Double Source # wireGetPacked :: FieldType -> Get (Seq Double) Source #
Wire Float Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Float -> WireSize Source # wirePut :: FieldType -> Float -> Put Source # wirePutWithSize :: FieldType -> Float -> PutM WireSize Source # wireGet :: FieldType -> Get Float Source # wireGetPacked :: FieldType -> Get (Seq Float) Source #
Wire Int Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Int -> WireSize Source # wirePut :: FieldType -> Int -> Put Source # wirePutWithSize :: FieldType -> Int -> PutM WireSize Source # wireGet :: FieldType -> Get Int Source # wireGetPacked :: FieldType -> Get (Seq Int) Source #
Wire Int32 Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Int32 -> WireSize Source # wirePut :: FieldType -> Int32 -> Put Source # wirePutWithSize :: FieldType -> Int32 -> PutM WireSize Source # wireGet :: FieldType -> Get Int32 Source # wireGetPacked :: FieldType -> Get (Seq Int32) Source #
Wire Int64 Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Int64 -> WireSize Source # wirePut :: FieldType -> Int64 -> Put Source # wirePutWithSize :: FieldType -> Int64 -> PutM WireSize Source # wireGet :: FieldType -> Get Int64 Source # wireGetPacked :: FieldType -> Get (Seq Int64) Source #
Wire Word32 Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Word32 -> WireSize Source # wirePut :: FieldType -> Word32 -> Put Source # wirePutWithSize :: FieldType -> Word32 -> PutM WireSize Source # wireGet :: FieldType -> Get Word32 Source # wireGetPacked :: FieldType -> Get (Seq Word32) Source #
Wire Word64 Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Word64 -> WireSize Source # wirePut :: FieldType -> Word64 -> Put Source # wirePutWithSize :: FieldType -> Word64 -> PutM WireSize Source # wireGet :: FieldType -> Get Word64 Source # wireGetPacked :: FieldType -> Get (Seq Word64) Source #
Wire ByteString Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> ByteString -> WireSize Source # wirePut :: FieldType -> ByteString -> Put Source # wirePutWithSize :: FieldType -> ByteString -> PutM WireSize Source # wireGet :: FieldType -> Get ByteString Source # wireGetPacked :: FieldType -> Get (Seq ByteString) Source #
Wire Utf8 Source #
Instance details Defined in Text.ProtocolBuffers.WireMessage Methods wireSize :: FieldType -> Utf8 -> WireSize Source # wirePut :: FieldType -> Utf8 -> Put Source # wirePutWithSize :: FieldType -> Utf8 -> PutM WireSize Source # wireGet :: FieldType -> Get Utf8 Source # wireGetPacked :: FieldType -> Get (Seq Utf8) Source #

The internal exports, for use by generated code and the Text.ProtcolBuffer.Extensions module

size'WireTag :: WireTag -> Int64 Source #

size'WireSize :: Int64 -> Int64 Source #

toWireType :: FieldType -> WireType Source #

toWireTag :: FieldId -> FieldType -> WireTag Source #

toPackedWireTag :: FieldId -> WireTag Source #

mkWireTag :: FieldId -> WireType -> WireTag Source #

prependMessageSize :: WireSize -> WireSize Source #

Used in generated code.

putSize :: WireSize -> Put Source #

Used in generated code.

putVarUInt :: (Integral a, Bits a) => a -> Put Source #

getVarInt :: (Show a, Integral a, Bits a) => Get a Source #

putLazyByteString :: ByteString -> Put #

Write a lazy ByteString efficiently, simply appending the lazy ByteString chunks to the output buffer

splitWireTag :: WireTag -> (FieldId, WireType) Source #

fieldIdOf :: WireTag -> FieldId Source #

wireSizeReq :: Wire v => Int64 -> FieldType -> v -> Int64 Source #

Used in generated code.

wireSizeOpt :: Wire v => Int64 -> FieldType -> Maybe v -> Int64 Source #

Used in generated code.

wireSizeRep :: Wire v => Int64 -> FieldType -> Seq v -> Int64 Source #

Used in generated code.

wireSizePacked :: Wire v => Int64 -> FieldType -> Seq v -> Int64 Source #

Used in generated code.

wirePutReq :: Wire v => WireTag -> FieldType -> v -> Put Source #

Used in generated code.

wirePutOpt :: Wire v => WireTag -> FieldType -> Maybe v -> Put Source #

Used in generated code.

wirePutRep :: Wire v => WireTag -> FieldType -> Seq v -> Put Source #

Used in generated code.

wirePutPacked :: Wire v => WireTag -> FieldType -> Seq v -> Put Source #

Used in generated code.

wirePutReqWithSize :: Wire v => WireTag -> FieldType -> v -> PutM WireSize Source #

Used in generated code.

wirePutOptWithSize :: Wire v => WireTag -> FieldType -> Maybe v -> PutM WireSize Source #

Used in generated code.

wirePutRepWithSize :: Wire v => WireTag -> FieldType -> Seq v -> PutM WireSize Source #

Used in generated code.

wirePutPackedWithSize :: Wire v => WireTag -> FieldType -> Seq v -> PutM WireSize Source #

Used in generated code.

sequencePutWithSize :: Foldable f => f (PutM WireSize) -> PutM WireSize Source #

Used in generated code.

wireSizeErr :: Typeable a => FieldType -> a -> WireSize Source #

wirePutErr :: Typeable a => FieldType -> a -> PutM b Source #

wireGetErr :: Typeable a => FieldType -> Get a Source #

getMessageWith :: (Default message, ReflectDescriptor message) => (WireTag -> message -> Get message) -> Get message Source #

getBareMessageWith :: (Default message, ReflectDescriptor message) => (WireTag -> message -> Get message) -> Get message Source #

Used by generated code getBareMessageWith assumes the wireTag for the message, if it existed, has already been read. getBareMessageWith assumes that it does needs to read the Varint encoded length of the message. getBareMessageWith will consume the entire ByteString it is operating on, or until it finds any STOP_GROUP tag (wireType == 4)

wireGetEnum :: (Typeable e, Enum e) => (Int -> Maybe e) -> Get e Source #

wireGetPackedEnum :: (Typeable e, Enum e) => (Int -> Maybe e) -> Get (Seq e) Source #

unknownField :: Typeable a => a -> FieldId -> Get a Source #

unknown :: (Typeable a, ReflectDescriptor a) => FieldId -> WireType -> a -> Get a Source #

wireGetFromWire :: FieldId -> WireType -> Get ByteString Source #

This reads in the raw bytestring corresponding to an field known only through the wiretag's FieldId and WireType.

castWord64ToDouble :: Word64 -> Double Source #

castWord32ToFloat :: Word32 -> Float Source #

castDoubleToWord64 :: Double -> Word64 Source #

castFloatToWord32 :: Float -> Word32 Source #

zzEncode64 :: Int64 -> Word64 Source #

zzEncode32 :: Int32 -> Word32 Source #

zzDecode64 :: Word64 -> Int64 Source #

zzDecode32 :: Word32 -> Int32 Source #

User API functions

Main encoding and decoding operations (non-delimited message encoding)

These should agree with the length delimited message format of protobuf-2.10, where the message size preceeds the data.

Encoding to write or read a single message field (good for delimited messages or incremental use)

The Put monad from the binary package, and a custom binary Get monad (Text.ProtocolBuffers.Get)

Instances

Instances

The Wire monad itself. Users should beware that passing an incompatible FieldType is a runtime error or fail

Instances

The internal exports, for use by generated code and the Text.ProtcolBuffer.Extensions module

The Wire monad itself. Users should beware that passing an incompatible `FieldType` is a runtime error or fail