protocol-buffers-2.0.17: Parse Google Protocol Buffer specifications

Safe HaskellNone
LanguageHaskell98

Text.ProtocolBuffers.Basic

Contents

Description

Text.ProtocolBuffers.Basic defines or re-exports most of the basic field types; Maybe,Bool, Double, and Float come from the Prelude instead. This module also defined the Mergeable and Default classes. The Wire class is not defined here to avoid orphans.

Synopsis

Basic types for protocol buffer fields in Haskell

data Double :: *

Double-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE double-precision type.

data Float :: *

Single-precision floating point numbers. It is desirable that this type be at least equal in range and precision to the IEEE single-precision type.

data Maybe a :: * -> *

The Maybe type encapsulates an optional value. A value of type Maybe a either contains a value of type a (represented as Just a), or it is empty (represented as Nothing). Using Maybe is a good way to deal with errors or exceptional cases without resorting to drastic measures such as error.

The Maybe type is also a monad. It is a simple kind of error monad, where all errors are represented by Nothing. A richer error monad can be built using the Either type.

Instances

Alternative Maybe 
Monad Maybe 
Functor Maybe 
MonadPlus Maybe 
Applicative Maybe 
Foldable Maybe 
Traversable Maybe 
Eq1 Maybe 
Ord1 Maybe 
Read1 Maybe 
Show1 Maybe 
ExtKey Maybe 
(Default msg, Default a) => MessageAPI msg (msg -> Maybe a) a 
Default v => MessageAPI msg (Key Maybe msg v) v 
Eq a => Eq (Maybe a) 
Data a => Data (Maybe a) 
Ord a => Ord (Maybe a) 
Read a => Read (Maybe a) 
Show a => Show (Maybe a) 
Monoid a => Monoid (Maybe a)

Lift a semigroup into Maybe forming a Monoid according to http://en.wikipedia.org/wiki/Monoid: "Any semigroup S may be turned into a monoid simply by adjoining an element e not in S and defining e*e = e and e*s = s = s*e for all s ∈ S." Since there is no "Semigroup" typeclass providing just mappend, we use Monoid instead.

Default (Maybe a) 
Mergeable a => Mergeable (Maybe a) 
TextType a => TextType (Maybe a) 
Typeable (* -> *) Maybe 
type (==) (Maybe k) a b = EqMaybe k a b 

data Seq a :: * -> *

General-purpose finite sequences.

Instances

Alternative Seq 
Monad Seq 
Functor Seq 
MonadPlus Seq 
Applicative Seq 
Foldable Seq 
Traversable Seq 
ExtKey Seq 
MessageAPI msg (msg -> Seq a) (Seq a) 
Default v => MessageAPI msg (Key Seq msg v) (Seq v) 
Eq a => Eq (Seq a) 
Data a => Data (Seq a) 
Ord a => Ord (Seq a) 
Read a => Read (Seq a) 
Show a => Show (Seq a) 
Monoid (Seq a) 
NFData a => NFData (Seq a) 
Default (Seq a) 
Mergeable (Seq a) 
TextType a => TextType (Seq a) 
Typeable (* -> *) Seq 

newtype Utf8 Source

Utf8 is used to mark ByteString values that (should) contain valud utf8 encoded strings. This type is used to represent TYPE_STRING values.

Constructors

Utf8 ByteString 

data ByteString :: *

A space-efficient representation of a Word8 vector, supporting many efficient operations.

A lazy ByteString contains 8-bit bytes, or by using the operations from Data.ByteString.Lazy.Char8 it can be interpreted as containing 8-bit characters.

Haskell types that act in the place of DescritorProto values

newtype WireTag Source

WireTag is the 32 bit value with the upper 29 bits being the FieldId and the lower 3 bits being the WireType

Constructors

WireTag 

Fields

getWireTag :: Word32
 

newtype FieldId Source

FieldId is the field number which can be in the range 1 to 2^29-1 but the value from 19000 to 19999 are forbidden (so sayeth Google).

Constructors

FieldId 

Fields

getFieldId :: Int32
 

newtype WireType Source

WireType is the 3 bit wire encoding value, and is currently in the range 0 to 5, leaving 6 and 7 currently invalid.

  • 0 Varint : int32, int64, uint32, uint64, sint32, sint64, bool, enum
  • 1 64-bit : fixed64, sfixed64, double
  • 2 Length-delimited : string, bytes, embedded messages
  • 3 Start group : groups (deprecated)
  • 4 End group : groups (deprecated)
  • 5 32-bit : fixed32, sfixed32, float

Constructors

WireType 

Fields

getWireType :: Word32
 

newtype FieldType Source

FieldType is the integer associated with the FieldDescriptorProto's Type. The allowed range is currently 1 to 18, as shown below (excerpt from descritor.proto)

   // 0 is reserved for errors.
   // Order is weird for historical reasons.
   TYPE_DOUBLE         = 1;
   TYPE_FLOAT          = 2;
   TYPE_INT64          = 3;   // Not ZigZag encoded.  Negative numbers
                              // take 10 bytes.  Use TYPE_SINT64 if negative
                              // values are likely.
   TYPE_UINT64         = 4;
   TYPE_INT32          = 5;   // Not ZigZag encoded.  Negative numbers
                              // take 10 bytes.  Use TYPE_SINT32 if negative
                              // values are likely.
   TYPE_FIXED64        = 6;
   TYPE_FIXED32        = 7;
   TYPE_BOOL           = 8;
   TYPE_STRING         = 9;
   TYPE_GROUP          = 10;  // Tag-delimited aggregate.
   TYPE_MESSAGE        = 11;  // Length-delimited aggregate.

   // New in version 2.
   TYPE_BYTES          = 12;
   TYPE_UINT32         = 13;
   TYPE_ENUM           = 14;
   TYPE_SFIXED32       = 15;
   TYPE_SFIXED64       = 16;
   TYPE_SINT32         = 17;  // Uses ZigZag encoding.
   TYPE_SINT64         = 18;  // Uses ZigZag encoding.

Constructors

FieldType 

Fields

getFieldType :: Int
 

newtype EnumCode Source

EnumCode is the Int32 assoicated with a EnumValueDescriptorProto and is in the range 0 to 2^31-1.

Constructors

EnumCode 

Fields

getEnumCode :: Int32
 

type WireSize = Int64 Source

WireSize is the Int64 size type associate with the lazy bytestrings used in the Put and Get monads.

Some of the type classes implemented messages and fields

class Default a => Mergeable a where Source

The Mergeable class is not a Monoid, mergeEmpty is not a left or right unit like mempty. The default mergeAppend is to take the second parameter and discard the first one. The mergeConcat defaults to foldl associativity.

NOTE: mergeEmpty has been removed in protocol buffers version 2. Use defaultValue instead. New strict fields would mean that required fields in messages will be automatic errors with mergeEmpty.

Minimal complete definition

Nothing

Methods

mergeAppend :: a -> a -> a Source

mergeAppend is the right-biased merge of two values. A message (or group) is merged recursively. Required field are always taken from the second message. Optional field values are taken from the most defined message or the second message if both are set. Repeated fields have the sequences concatenated. Note that strings and bytes are NOT concatenated.

mergeConcat :: Foldable t => t a -> a Source

mergeConcat is F.foldl mergeAppend defaultValue and this default definition is not overridden in any of the code except for the (Seq a) instance.

class Default a where Source

The Default class has the default-default values of types. See http://code.google.com/apis/protocolbuffers/docs/proto.html#optional and also note that Enum types have a defaultValue that is the first one in the .proto file (there is always at least one value). Instances of this for messages hold any default value defined in the .proto file. defaultValue is where the MessageAPI function getVal looks when an optional field is not set.

Methods

defaultValue :: a Source

The defaultValue is never undefined or an error to evalute. This makes it much more useful compared to mergeEmpty. In a default message all Optional field values are set to Nothing and Repeated field values are empty.