| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Data.ProtoLens.Message
Contents
Description
Datatypes for reflection of protocol buffer messages.
Synopsis
- class Message msg where
- messageName :: Proxy msg -> Text
- defMessage :: msg
- fieldsByTag :: Map Tag (FieldDescriptor msg)
- fieldsByTextFormatName :: Map String (FieldDescriptor msg)
- unknownFields :: Lens' msg FieldSet
- newtype Tag = Tag {}
- allFields :: Message msg => [FieldDescriptor msg]
- data FieldDescriptor msg where
- FieldDescriptor :: String -> FieldTypeDescriptor value -> FieldAccessor msg value -> FieldDescriptor msg
- fieldDescriptorName :: FieldDescriptor msg -> String
- isRequired :: FieldDescriptor msg -> Bool
- data FieldAccessor msg value where
- 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
- Required :: WireDefault value
- Optional :: (FieldDefault value, Eq value) => WireDefault value
- data Packing
- data FieldTypeDescriptor value where
- MessageField :: Message value => MessageOrGroup -> FieldTypeDescriptor value
- ScalarField :: ScalarField value -> FieldTypeDescriptor value
- data ScalarField t where
- 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
- data MessageOrGroup
- class FieldDefault value where
- fieldDefault :: value
- class (Enum a, Bounded a) => MessageEnum a where
- build :: Message a => (a -> a) -> a
- data Registry
- register :: forall msg. Message msg => Proxy msg -> Registry
- lookupRegistered :: Text -> Registry -> Maybe SomeMessageType
- data SomeMessageType where
- SomeMessageType :: Message msg => Proxy msg -> SomeMessageType
- matchAnyMessage :: forall value. FieldTypeDescriptor value -> Maybe (AnyMessageDescriptor value)
- data AnyMessageDescriptor msg = AnyMessageDescriptor {
- anyTypeUrlLens :: Lens' msg Text
- anyValueLens :: Lens' msg ByteString
- maybeLens :: b -> Lens' (Maybe b) b
- reverseRepeatedFields :: Map k (FieldDescriptor msg) -> msg -> msg
- type FieldSet = [TaggedValue]
- data TaggedValue = TaggedValue !Tag !WireValue
- discardUnknownFields :: Message msg => msg -> msg
Reflection of Messages
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
Methods
messageName :: Proxy msg -> Text #
A unique identifier for this type, of the format
"packagename.messagename".
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.
Instances
A tag that identifies a particular field of the message when converting to/from the wire format.
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 |
How a given repeated field is transmitted on the wire format.
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
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
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.
Get the name of this enum as defined in the .proto file. Used
for the human-readable output in Data.ProtoLens.TextFormat.
Instances
| MessageEnum MethodOptions'IdempotencyLevel # | |
Defined in Proto.Google.Protobuf.Descriptor | |
| MessageEnum FileOptions'OptimizeMode # | |
Defined in Proto.Google.Protobuf.Descriptor Methods maybeToEnum :: Int -> Maybe FileOptions'OptimizeMode # | |
| MessageEnum FieldOptions'JSType # | |
Defined in Proto.Google.Protobuf.Descriptor Methods maybeToEnum :: Int -> Maybe FieldOptions'JSType # showEnum :: FieldOptions'JSType -> String # readEnum :: String -> Maybe FieldOptions'JSType # | |
| MessageEnum FieldOptions'CType # | |
Defined in Proto.Google.Protobuf.Descriptor Methods maybeToEnum :: Int -> Maybe FieldOptions'CType # showEnum :: FieldOptions'CType -> String # readEnum :: String -> Maybe FieldOptions'CType # | |
| MessageEnum FieldDescriptorProto'Type # | |
Defined in Proto.Google.Protobuf.Descriptor Methods maybeToEnum :: Int -> Maybe FieldDescriptorProto'Type # | |
| MessageEnum FieldDescriptorProto'Label # | |
Defined in Proto.Google.Protobuf.Descriptor Methods maybeToEnum :: Int -> Maybe FieldDescriptorProto'Label # | |
Building 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
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
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
| |
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 #
Constructors
| TaggedValue !Tag !WireValue |
Instances
| Eq TaggedValue # | |
Defined in Data.ProtoLens.Encoding.Wire | |
| 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 # | |
| Show TaggedValue # | |
Defined in Data.ProtoLens.Encoding.Wire Methods showsPrec :: Int -> TaggedValue -> ShowS # show :: TaggedValue -> String # showList :: [TaggedValue] -> ShowS # | |
| NFData TaggedValue # | |
Defined in Data.ProtoLens.Encoding.Wire Methods rnf :: TaggedValue -> () # | |
discardUnknownFields :: Message msg => msg -> msg #