Proto3.Wire.Decode

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.

Untyped Representation

data ParsedField

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.

Constructors

VarintField Word64

Fixed32Field ByteString

Fixed64Field ByteString

LengthDelimitedField ByteString

Instances

Eq ParsedField

Defined in Proto3.Wire.Decode

Methods

(==) :: ParsedField -> ParsedField -> Bool

(/=) :: ParsedField -> ParsedField -> Bool

Show ParsedField

Defined in Proto3.Wire.Decode

Methods

showsPrec :: Int -> ParsedField -> ShowS

show :: ParsedField -> String

showList :: [ParsedField] -> ShowS

decodeWire :: ByteString -> Either String [(FieldNumber, ParsedField)]

Parser Types

newtype Parser input a

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

Fields

• runParser :: input -> Either ParseError a

Instances

Monad (Parser input)

Defined 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)

Defined in Proto3.Wire.Decode

Methods

fmap :: (a -> b) -> Parser input a -> Parser input b

(<$) :: a -> Parser input b -> Parser input a

Applicative (Parser input)

Defined in Proto3.Wire.Decode

Methods

pure :: 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

type RawPrimitive = ParsedField

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

type RawField = [RawPrimitive]

Raw data corresponding to a single FieldNumber.

type RawMessage = IntMap RawField

Raw data corresponding to an entire message.

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

data ParseError

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

Eq ParseError

Defined in Proto3.Wire.Decode

Methods

(==) :: ParseError -> ParseError -> Bool

(/=) :: ParseError -> ParseError -> Bool

Ord ParseError

Defined in Proto3.Wire.Decode

Methods

compare :: ParseError -> ParseError -> Ordering

(<) :: ParseError -> ParseError -> Bool

(<=) :: ParseError -> ParseError -> Bool

(>) :: ParseError -> ParseError -> Bool

(>=) :: ParseError -> ParseError -> Bool

max :: ParseError -> ParseError -> ParseError

min :: ParseError -> ParseError -> ParseError

Show ParseError

Defined in Proto3.Wire.Decode

Methods

showsPrec :: Int -> ParseError -> ShowS

show :: ParseError -> String

showList :: [ParseError] -> ShowS

Exception ParseError

This library does not use this instance, but it is provided for convenience, so that ParseError may be used with functions like throwIO

Defined in Proto3.Wire.Decode

Methods

toException :: ParseError -> SomeException

fromException :: SomeException -> Maybe ParseError

displayException :: ParseError -> String

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

Fold over a list of parsed fields accumulating a result

parse :: Parser RawMessage a -> ByteString -> Either ParseError a

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

Primitives

bool :: Parser RawPrimitive Bool

Parse a Boolean value.

int32 :: Parser RawPrimitive Int32

Parse a primitive with the int32 wire type.

int64 :: Parser RawPrimitive Int64

Parse a primitive with the int64 wire type.

uint32 :: Parser RawPrimitive Word32

Parse a primitive with the uint32 wire type.

uint64 :: Parser RawPrimitive Word64

Parse a primitive with the uint64 wire type.

sint32 :: Parser RawPrimitive Int32

Parse a primitive with the sint32 wire type.

sint64 :: Parser RawPrimitive Int64

Parse a primitive with the sint64 wire type.

enum :: forall e. (Enum e, Bounded e) => Parser RawPrimitive (Either Int e)

Parse a primitive with an enumerated type.

This parser will return Left if the encoded integer value is outside the acceptable range of the Bounded instance.

byteString :: Parser RawPrimitive ByteString

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

lazyByteString :: Parser RawPrimitive ByteString

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

text :: Parser RawPrimitive Text

Parse a primitive with the bytes wire type as Text.

packedVarints :: Integral a => Parser RawPrimitive [a]

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

packedFixed32 :: Integral a => Parser RawPrimitive [a]

Parse a packed collection of fixed32 values.

packedFixed64 :: Integral a => Parser RawPrimitive [a]

Parse a packed collection of fixed64 values.

packedFloats :: Parser RawPrimitive [Float]

Parse a packed collection of float values.

packedDoubles :: Parser RawPrimitive [Double]

Parse a packed collection of double values.

fixed32 :: Parser RawPrimitive Word32

Parse an integer primitive with the fixed32 wire type.

fixed64 :: Parser RawPrimitive Word64

Parse an integer primitive with the fixed64 wire type.

sfixed32 :: Parser RawPrimitive Int32

Parse a signed integer primitive with the fixed32 wire type.

sfixed64 :: Parser RawPrimitive Int64

Parse a signed integer primitive with the fixed64 wire type.

float :: Parser RawPrimitive Float

Parse a float.

double :: Parser RawPrimitive Double

Parse a double.

Decoding Messages

at :: Parser RawField a -> FieldNumber -> Parser RawMessage a

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)

oneof

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

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

repeated :: Parser RawPrimitive a -> Parser RawField [a]

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])

embedded :: Parser RawMessage a -> Parser RawField (Maybe 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.

embedded' :: Parser RawMessage a -> Parser RawPrimitive a

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.