proto3-wire-1.2.0: A low-level implementation of the Protocol Buffers (version 3) wire format

Proto3.Wire.Decode

Description

Low level functions for reading data in the protobufs wire format.

This module exports a function decodeWire which parses data in the raw wire format into an untyped Map representation.

This module also provides Parser types and functions for reading messages from the untyped Map representation obtained from decodeWire.

Synopsis

# Untyped Representation

One field in a protobuf message.

We don't know what's inside some of these fields until we know what type we're deserializing to, so we leave them as ByteString until a later step in the process.

Instances
 Source # Instance detailsDefined in Proto3.Wire.Decode Methods Source # Instance detailsDefined in Proto3.Wire.Decode MethodsshowList :: [ParsedField] -> ShowS #

Parses data in the raw wire format into an untyped Map representation.

# Parser Types

newtype Parser input a Source #

A parsing function type synonym, to tidy up type signatures.

This synonym is used in three ways:

• Applied to RawPrimitive, to parse primitive fields.
• Applied to RawField, to parse fields which correspond to a single FieldNumber.
• Applied to RawMessage, to parse entire messages.

Many of the combinators in this module are used to combine and convert between these three parser types.

Parsers can be combined using the Applicative, Monad and Alternative instances.

Constructors

 Parser FieldsrunParser :: input -> Either ParseError a
Instances
 Monad (Parser input) Source # Instance detailsDefined in Proto3.Wire.Decode Methods(>>=) :: Parser input a -> (a -> Parser input b) -> Parser input b #(>>) :: Parser input a -> Parser input b -> Parser input b #return :: a -> Parser input a #fail :: String -> Parser input a # Functor (Parser input) Source # Instance detailsDefined in Proto3.Wire.Decode Methodsfmap :: (a -> b) -> Parser input a -> Parser input b #(<\$) :: a -> Parser input b -> Parser input a # Applicative (Parser input) Source # Instance detailsDefined in Proto3.Wire.Decode Methodspure :: a -> Parser input a #(<*>) :: Parser input (a -> b) -> Parser input a -> Parser input b #liftA2 :: (a -> b -> c) -> Parser input a -> Parser input b -> Parser input c #(*>) :: Parser input a -> Parser input b -> Parser input b #(<*) :: Parser input a -> Parser input b -> Parser input a #

Raw data corresponding to a single encoded key/value pair.

type RawField = [RawPrimitive] Source #

Raw data corresponding to a single FieldNumber.

Raw data corresponding to an entire message.

A Map from FieldNumbers to the those values associated with that FieldNumber.

Type describing possible errors that can be encountered while parsing.

Constructors

 WireTypeError Text A WireTypeError occurs when the type of the data in the protobuf binary format does not match the type encountered by the parser. This can indicate that the type of a field has changed or is incorrect. BinaryError Text A BinaryError occurs when we can't successfully parse the contents of the field. EmbeddedError Text (Maybe ParseError) An EmbeddedError occurs when we encounter an error while parsing an embedded message.
Instances
 Source # Instance detailsDefined in Proto3.Wire.Decode Methods Source # Instance detailsDefined in Proto3.Wire.Decode Methods Source # Instance detailsDefined in Proto3.Wire.Decode MethodsshowList :: [ParseError] -> ShowS # Source # This library does not use this instance, but it is provided for convenience, so that ParseError may be used with functions like throwIO Instance detailsDefined in Proto3.Wire.Decode Methods

foldFields :: IntMap (Parser RawPrimitive a, a -> acc -> acc) -> acc -> [(FieldNumber, ParsedField)] -> Either ParseError acc Source #

Fold over a list of parsed fields accumulating a result

Parse a message (encoded in the raw wire format) using the specified Parser.

# Primitives

Parse a Boolean value.

Parse a primitive with the int32 wire type.

Parse a primitive with the int64 wire type.

Parse a primitive with the uint32 wire type.

Parse a primitive with the uint64 wire type.

Parse a primitive with the sint32 wire type.

Parse a primitive with the sint64 wire type.

enum :: forall e. ProtoEnum e => Parser RawPrimitive (Either Int32 e) Source #

Parse a primitive with an enumerated type.

This parser will return Left if the encoded integer value is not a code for a known enumerator.

Parse a primitive with the bytes wire type as a ByteString.

Parse a primitive with the bytes wire type as a lazy ByteString.

Parse a primitive with the bytes wire type as Text.

Parse a packed collection of variable-width integer values (any of int32, int64, sint32, sint64, uint32, uint64 or enumerations).

Parse a packed collection of fixed32 values.

Parse a packed collection of fixed64 values.

Parse a packed collection of float values.

Parse a packed collection of double values.

Parse an integer primitive with the fixed32 wire type.

Parse an integer primitive with the fixed64 wire type.

Parse a signed integer primitive with the fixed32 wire type.

Parse a signed integer primitive with the fixed64 wire type.

Parse a float.

Parse a double.

# Decoding Messages

Turn a field parser into a message parser, by specifying the FieldNumber.

This parser will fail if the specified FieldNumber is not present.

For example:

one float at fieldNumber 1 :: Parser RawMessage (Maybe Float)

Arguments

 :: a The value to produce when no field numbers belonging to the oneof are present in the input -> [(FieldNumber, Parser RawField a)] Left-biased oneof field parsers, one per field number belonging to the oneof -> Parser RawMessage a

Try to parse different field numbers with their respective parsers. This is used to express alternative between possible fields of a oneof.

TODO: contrary to the protobuf spec, in the case of multiple fields number matching the oneof content, the choice of field is biased to the order of the list, instead of being biased to the last field of group of field number in the oneof. This is related to the Map used for input that preserve order across multiple invocation of the same field, but not across a group of field.

one :: Parser RawPrimitive a -> a -> Parser RawField a Source #

This turns a primitive parser into a field parser by keeping the last received value, or return a default value if the field number is missing.

Used to ensure that we return the last value with the given field number in the message, in compliance with the protobuf standard.

The protocol buffers specification specifies default values for primitive types.

For example:

one float 0 :: Parser RawField Float

Parse a repeated field, or an unpacked collection of primitives.

Each value with the identified FieldNumber will be passed to the parser in the first argument, to be converted into a value of the correct type.

For example, to parse a packed collection of uint32 values:

repeated uint32 :: Parser RawField ([Word32])

or to parse a collection of embedded messages:

repeated . embedded' :: Parser RawMessage a -> Parser RawField ([a])

Create a field parser for an embedded message, from a message parser.

The protobuf spec requires that embedded messages be mergeable, so that protobuf encoding has the flexibility to transmit embedded messages in pieces. This function reassembles the pieces, and must be used to parse all embedded non-repeated messages.

If the embedded message is not found in the outer message, this function returns Nothing.

Create a primitive parser for an embedded message from a message parser.

This parser does no merging of fields if multiple message fragments are sent separately.

# Exported For Doctest Only

toMap :: [(FieldNumber, v)] -> IntMap [v] Source #

Convert key-value pairs to a map of keys to a sequence of values with that key, in their reverse occurrence order.

>>> toMap ([(FieldNumber 1, 3),(FieldNumber 2, 4),(FieldNumber 1, 6)] :: [(FieldNumber,Int)])
fromList [(1,[6,3]),(2,[4])]