Data.ProtoLens.Message

Datatypes for reflection of protocol buffer messages.

Reflection of Messages

class Message msg where

Every protocol buffer is an instance of Message. This class enables serialization by providing reflection of all of the fields that may be used by this type.

Minimal complete definition

messageName, packedMessageDescriptor, packedFileDescriptor, defMessage, fieldsByTag, unknownFields, parseMessage, buildMessage

Methods

messageName :: Proxy msg -> Text

A unique identifier for this type, of the format "packagename.messagename".

packedMessageDescriptor :: Proxy msg -> ByteString

The serialized protobuffer message descriptor for this type.

For a friendlier version which returns the actual descriptor type, use Data.ProtoLens.Descriptor.messageDescriptor from the proto-lens-protobuf-types package.

packedFileDescriptor :: Proxy msg -> ByteString

The serialized protobuffer file message descriptor containing this type.

For a friendlier version which returns the actual file descriptor type, use Data.ProtoLens.Descriptor.fileDescriptor from the proto-lens-protobuf-types package.

defMessage :: msg

A message with all fields set to their default values.

Satisfies encodeMessage defMessage == "" and decodeMessage "" == Right defMessage.

fieldsByTag :: Map Tag (FieldDescriptor msg)

The fields of the proto, indexed by their (integer) tag.

fieldsByTextFormatName :: Map String (FieldDescriptor msg)

This map is keyed by the name of the field used for text format protos. This is just the field name for every field except for group fields, which use their Message type name in text protos instead of their field name. For example, "optional group Foo" has the field name "foo" but in this map it is stored with the key Foo.

unknownFields :: Lens' msg FieldSet

Access the unknown fields of a Message.

parseMessage :: Parser msg

Decode a message value.

See also the functions in Data.ProtoLens.Encoding.

buildMessage :: msg -> Builder

Encode a message value.

See also the functions in Data.ProtoLens.Encoding.

newtype Tag

A tag that identifies a particular field of the message when converting to/from the wire format.

Constructors

Tag

Fields

• unTag :: Int

Instances

Num Tag

Defined in Data.ProtoLens.Encoding.Wire

Methods

(+) :: Tag -> Tag -> Tag

(-) :: Tag -> Tag -> Tag

(*) :: Tag -> Tag -> Tag

negate :: Tag -> Tag

abs :: Tag -> Tag

signum :: Tag -> Tag

fromInteger :: Integer -> Tag

Show Tag

Defined in Data.ProtoLens.Encoding.Wire

Methods

showsPrec :: Int -> Tag -> ShowS

show :: Tag -> String

showList :: [Tag] -> ShowS

NFData Tag

Defined in Data.ProtoLens.Encoding.Wire

Methods

rnf :: Tag -> ()

Eq Tag

Defined in Data.ProtoLens.Encoding.Wire

Methods

(==) :: Tag -> Tag -> Bool

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

Ord Tag

Defined in Data.ProtoLens.Encoding.Wire

Methods

compare :: Tag -> Tag -> Ordering

(<) :: Tag -> Tag -> Bool

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

(>) :: Tag -> Tag -> Bool

(>=) :: Tag -> Tag -> Bool

max :: Tag -> Tag -> Tag

min :: Tag -> Tag -> Tag

allFields :: Message msg => [FieldDescriptor msg]

data FieldDescriptor msg where

A description of a specific field of a protocol buffer.

The String parameter is the name of the field from the .proto file, as used in TextFormat, with the same behavior for groups as fieldsByTextFormatName. (Haddock doesn't support per-argument docs for GADTs.)

Constructors

FieldDescriptor :: String -> FieldTypeDescriptor value -> FieldAccessor msg value -> FieldDescriptor msg

fieldDescriptorName :: FieldDescriptor msg -> String

The original name of the field in the .proto file.

isRequired :: FieldDescriptor msg -> Bool

Whether the given field is required. Specifically, if its FieldAccessor is a Required PlainField.

data FieldAccessor msg value where

A Lens for accessing the value of an individual field in a protocol buffer message.

Constructors

PlainField :: WireDefault value -> Lens' msg value -> FieldAccessor msg value

OptionalField :: Lens' msg (Maybe value) -> FieldAccessor msg value

RepeatedField :: Packing -> Lens' msg [value] -> FieldAccessor msg value

MapField :: (Ord key, Message entry) => Lens' entry key -> Lens' entry value -> Lens' msg (Map key value) -> FieldAccessor msg entry

data WireDefault value where

The default value (if any) for a PlainField on the wire.

Constructors

Required :: WireDefault value

Optional :: (FieldDefault value, Eq value) => WireDefault value

data Packing

How a given repeated field is transmitted on the wire format.

Constructors

Packed

Unpacked

data FieldTypeDescriptor value where

A description of the type of a given field value.

Constructors

MessageField :: Message value => MessageOrGroup -> FieldTypeDescriptor value

ScalarField :: ScalarField value -> FieldTypeDescriptor value

Instances

Show (FieldTypeDescriptor value)

Defined in Data.ProtoLens.Message

Methods

showsPrec :: Int -> FieldTypeDescriptor value -> ShowS

show :: FieldTypeDescriptor value -> String

showList :: [FieldTypeDescriptor value] -> ShowS

data ScalarField t where

Constructors

EnumField :: MessageEnum value => ScalarField value

Int32Field :: ScalarField Int32

Int64Field :: ScalarField Int64

UInt32Field :: ScalarField Word32

UInt64Field :: ScalarField Word64

SInt32Field :: ScalarField Int32

SInt64Field :: ScalarField Int64

Fixed32Field :: ScalarField Word32

Fixed64Field :: ScalarField Word64

SFixed32Field :: ScalarField Int32

SFixed64Field :: ScalarField Int64

FloatField :: ScalarField Float

DoubleField :: ScalarField Double

BoolField :: ScalarField Bool

StringField :: ScalarField Text

BytesField :: ScalarField ByteString

Instances

Show (ScalarField value)

Defined in Data.ProtoLens.Message

Methods

showsPrec :: Int -> ScalarField value -> ShowS

show :: ScalarField value -> String

showList :: [ScalarField value] -> ShowS

data MessageOrGroup

Constructors

MessageType

GroupType

Instances

Show MessageOrGroup

Defined in Data.ProtoLens.Message

Methods

showsPrec :: Int -> MessageOrGroup -> ShowS

show :: MessageOrGroup -> String

showList :: [MessageOrGroup] -> ShowS

class FieldDefault value where

A proto3 field type with an implicit default value.

This is distinct from, say, Default to avoid orphan instances, and because Bool doesn't necessarily have a good Default instance for general usage.

Methods

fieldDefault :: value

Instances

FieldDefault Int32

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Int32

FieldDefault Int64

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Int64

FieldDefault Word32

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Word32

FieldDefault Word64

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Word64

FieldDefault ByteString

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: ByteString

FieldDefault Text

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Text

FieldDefault Bool

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Bool

FieldDefault Double

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Double

FieldDefault Float

Defined in Data.ProtoLens.Message

Methods

fieldDefault :: Float

class (Enum a, Bounded a) => MessageEnum a where

A class for protocol buffer enums that enables safe decoding.

Methods

maybeToEnum :: Int -> Maybe a

Convert the given Int to an enum value. Returns Nothing if no corresponding value was defined in the .proto file.

showEnum :: a -> String

Get the name of this enum as defined in the .proto file. Used for the human-readable output in Data.ProtoLens.TextFormat.

readEnum :: String -> Maybe a

Convert the given String to an enum value. Returns Nothing if no corresponding value was defined in the .proto file.

Constructing protocol buffers

build :: Message a => (a -> a) -> a

Utility function for building a message from a default value. For example:

instance Default A where ...
x, y :: Lens' A Int
m :: A
m = build ((x .~ 5) . (y .~ 7))

Proto registries

data Registry

A set of known message types. Can help encode/decode protobufs containing Data.ProtoLens.Any values in a more human-readable text format.

Registries can be combined using their Monoid instance.

See the withRegistry functions in TextFormat

Instances

Monoid Registry

Defined in Data.ProtoLens.Message

Methods

mempty :: Registry

mappend :: Registry -> Registry -> Registry

mconcat :: [Registry] -> Registry

Semigroup Registry

Defined in Data.ProtoLens.Message

Methods

(<>) :: Registry -> Registry -> Registry

sconcat :: NonEmpty Registry -> Registry

stimes :: Integral b => b -> Registry -> Registry

register :: forall msg. Message msg => Proxy msg -> Registry

Build a Registry containing a single proto type.

Example: > register (Proxy :: Proxy Proto.My.Proto.Type)

lookupRegistered :: Text -> Registry -> Maybe SomeMessageType

Look up a message type by name (e.g., "type.googleapis.com/google.protobuf.FloatValue"). The URL corresponds to the field google.protobuf.Any.type_url.

data SomeMessageType where

Constructors

SomeMessageType :: Message msg => Proxy msg -> SomeMessageType

Any messages

matchAnyMessage :: forall value. FieldTypeDescriptor value -> Maybe (AnyMessageDescriptor value)

data AnyMessageDescriptor msg

Constructors

AnyMessageDescriptor

Fields

• anyTypeUrlLens :: Lens' msg Text
• anyValueLens :: Lens' msg ByteString

Utilities for constructing protocol buffer lenses

maybeLens :: b -> Lens' (Maybe b) b

A helper lens for accessing optional fields. This is used as part of code generation, and should generally not be needed explicitly.

Note that maybeLens does not satisfy the lens laws, which expect that set l (view l x) == x. For example,

set (maybeLens 'a') (view (maybeLens 'a') Nothing) == Just 'a'

However, this is the behavior generally expected by users, and only matters if we're explicitly checking whether a field is set.

Internal utilities for parsing protocol buffers

reverseRepeatedFields :: Map k (FieldDescriptor msg) -> msg -> msg

Reverse every repeated (list) field in the message.

During parsing, we store fields temporarily in reverse order, and then un-reverse them at the end. This helps avoid the quadratic blowup from repeatedly appending to lists. TODO: Benchmark how much of a problem this is in practice, and whether it's still a net win for small protobufs. If we decide on it more permanently, consider moving it to a more internal module.

Unknown fields

type FieldSet = [TaggedValue]

data TaggedValue

A pair of an encoded field and a value.

Constructors

TaggedValue !Tag !WireValue

Instances

NFData TaggedValue

Defined in Data.ProtoLens.Encoding.Wire

Methods

rnf :: TaggedValue -> ()

Eq TaggedValue

Defined in Data.ProtoLens.Encoding.Wire

Methods

(==) :: TaggedValue -> TaggedValue -> Bool

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

Ord TaggedValue

Defined in Data.ProtoLens.Encoding.Wire

Methods

compare :: TaggedValue -> TaggedValue -> Ordering

(<) :: TaggedValue -> TaggedValue -> Bool

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

(>) :: TaggedValue -> TaggedValue -> Bool

(>=) :: TaggedValue -> TaggedValue -> Bool

max :: TaggedValue -> TaggedValue -> TaggedValue

min :: TaggedValue -> TaggedValue -> TaggedValue

discardUnknownFields :: Message msg => msg -> msg