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

Safe HaskellNone
LanguageHaskell2010

Proto3.Wire

Contents

Description

See the Proto3.Wire.Tutorial module.

Synopsis

Support Classes

class ProtoEnum a where Source #

Similar to Enum, but allows gaps in the sequence of numeric codes, and uses Int32 in order to match the proto3 specification.

Absent gaps, you can use an automatic derivation of Bounded and Enum, then use the default implementations for all methods of this class. But if gaps are involved, then you must instantiate this class directly and supply the specific numeric codes desired for each constructor.

Minimal complete definition

Nothing

Methods

toProtoEnumMay :: Int32 -> Maybe a Source #

Default implementation: toEnumMay.

toProtoEnumMay :: (Bounded a, Enum a) => Int32 -> Maybe a Source #

Default implementation: toEnumMay.

fromProtoEnum :: a -> Int32 Source #

Default implementation: fromEnum.

fromProtoEnum :: Enum a => a -> Int32 Source #

Default implementation: fromEnum.

Message Structure

newtype FieldNumber Source #

A FieldNumber identifies a field inside a protobufs message.

This library makes no attempt to generate these automatically, or even make sure that field numbers are provided in increasing order. Such things are left to other, higher-level libraries.

Constructors

FieldNumber 
Instances
Enum FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

Eq FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

Num FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

Ord FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

Show FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

Arbitrary FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

NFData FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

Methods

rnf :: FieldNumber -> () #

Hashable FieldNumber Source # 
Instance details

Defined in Proto3.Wire.Types

fieldNumber :: Word64 -> FieldNumber Source #

Create a FieldNumber given the (one-based) integer which would label the field in the corresponding .proto file.

Decoding Messages

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

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 Source #

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

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

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