Proto3.Suite.Tutorial

Tutorial

This module contains a worked example of encoding and decoding messages, and exporting a corresponding .proto file from Haskell types.

Setup

If you are using GHC.Generics, you should enable the generic deriving extension, and import the main module:

{-# LANGUAGE DeriveGeneric #-}

import Proto3.Suite
import GHC.Generics

Documentation

>>> :set -XOverloadedStrings

data Foo

Defining Message Types

Define messages using Haskell record types. You can use any MessageField types in your records, and the correct serializer and deserializer will be generated for you.

Make sure to derive a Generic instance for your type, and then derive instances for Message and Named using the default (empty) instances:

instance Message Foo
instance Named Foo

Encoding Messages

Now we can encode a value of type Foo using toLazyByteString.

For example:

>>> Proto3.Suite.toLazyByteString (Foo 42 (Proto3.Suite.PackedVec (pure 123)))
"\b*\DC2\SOH{"

We can also decode messages using fromByteString:

>>> Proto3.Suite.fromByteString "\b*\DC2\SOH{" :: Either Proto3.Wire.Decode.ParseError Foo
Right (Foo {fooX = 42, fooY = PackedVec {packedvec = [123]}})

Constructors

Foo

Fields

• fooX :: Word32
• fooY :: PackedVec Int32

Instances

Eq Foo

Defined in Proto3.Suite.Tutorial

Methods

(==) :: Foo -> Foo -> Bool

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

Show Foo

Defined in Proto3.Suite.Tutorial

Methods

showsPrec :: Int -> Foo -> ShowS

show :: Foo -> String

showList :: [Foo] -> ShowS

Generic Foo

Defined in Proto3.Suite.Tutorial

Associated Types

type Rep Foo :: Type -> Type

Methods

from :: Foo -> Rep Foo x

to :: Rep Foo x -> Foo

Message Foo

Defined in Proto3.Suite.Tutorial

Methods

encodeMessage :: FieldNumber -> Foo -> MessageBuilder

decodeMessage :: FieldNumber -> Parser RawMessage Foo

dotProto :: Proxy# Foo -> [DotProtoField]

Named Foo

Defined in Proto3.Suite.Tutorial

Methods

nameOf :: IsString string => Proxy# Foo -> string

type Rep Foo

Defined in Proto3.Suite.Tutorial

type Rep Foo = D1 ('MetaData "Foo" "Proto3.Suite.Tutorial" "proto3-suite-0.7.0-inplace" 'False) (C1 ('MetaCons "Foo" 'PrefixI 'True) (S1 ('MetaSel ('Just "fooX") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word32) :*: S1 ('MetaSel ('Just "fooY") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (PackedVec Int32))))

data Bar

Nested Messages

Messages can contain other messages, by using the Nested constructor, and lists of nested messages using the 'NestedVec constructor'.

Constructors

Bar

Fields

• barShape :: Enumerated Shape
• barFoo :: Nested Foo
• foos :: NestedVec Foo

Instances

Eq Bar

Defined in Proto3.Suite.Tutorial

Methods

(==) :: Bar -> Bar -> Bool

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

Generic Bar

Defined in Proto3.Suite.Tutorial

Associated Types

type Rep Bar :: Type -> Type

Methods

from :: Bar -> Rep Bar x

to :: Rep Bar x -> Bar

Message Bar

Defined in Proto3.Suite.Tutorial

Methods

encodeMessage :: FieldNumber -> Bar -> MessageBuilder

decodeMessage :: FieldNumber -> Parser RawMessage Bar

dotProto :: Proxy# Bar -> [DotProtoField]

Named Bar

Defined in Proto3.Suite.Tutorial

Methods

nameOf :: IsString string => Proxy# Bar -> string

type Rep Bar

Defined in Proto3.Suite.Tutorial

type Rep Bar = D1 ('MetaData "Bar" "Proto3.Suite.Tutorial" "proto3-suite-0.7.0-inplace" 'False) (C1 ('MetaCons "Bar" 'PrefixI 'True) (S1 ('MetaSel ('Just "barShape") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Enumerated Shape)) :*: (S1 ('MetaSel ('Just "barFoo") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Nested Foo)) :*: S1 ('MetaSel ('Just "foos") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (NestedVec Foo)))))

data Shape

Enumerations

Enumerated types can be used by deriving the Bounded, Enum, ProtoEnum, Finite, and Named classes. Each of these instances are implied by a Generic instance, so can be derived as follows:

data Shape
  = Circle
  | Square
  | Triangle
  deriving (Bounded, Eq, Enum, Finite, Generic, Named, Ord, ProtoEnum)

Constructors

Circle

Square

Triangle

Instances

Bounded Shape

Defined in Proto3.Suite.Tutorial

Methods

minBound :: Shape

maxBound :: Shape

Enum Shape

Defined in Proto3.Suite.Tutorial

Methods

succ :: Shape -> Shape

pred :: Shape -> Shape

toEnum :: Int -> Shape

fromEnum :: Shape -> Int

enumFrom :: Shape -> [Shape]

enumFromThen :: Shape -> Shape -> [Shape]

enumFromTo :: Shape -> Shape -> [Shape]

enumFromThenTo :: Shape -> Shape -> Shape -> [Shape]

Eq Shape

Defined in Proto3.Suite.Tutorial

Methods

(==) :: Shape -> Shape -> Bool

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

Ord Shape

Defined in Proto3.Suite.Tutorial

Methods

compare :: Shape -> Shape -> Ordering

(<) :: Shape -> Shape -> Bool

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

(>) :: Shape -> Shape -> Bool

(>=) :: Shape -> Shape -> Bool

max :: Shape -> Shape -> Shape

min :: Shape -> Shape -> Shape

Generic Shape

Defined in Proto3.Suite.Tutorial

Associated Types

type Rep Shape :: Type -> Type

Methods

from :: Shape -> Rep Shape x

to :: Rep Shape x -> Shape

ProtoEnum Shape

Defined in Proto3.Suite.Tutorial

Methods

toProtoEnumMay :: Int32 -> Maybe Shape

fromProtoEnum :: Shape -> Int32

Finite Shape

Defined in Proto3.Suite.Tutorial

Methods

enumerate :: IsString string => Proxy# Shape -> [(string, Int32)]

Named Shape

Defined in Proto3.Suite.Tutorial

Methods

nameOf :: IsString string => Proxy# Shape -> string

type Rep Shape

Defined in Proto3.Suite.Tutorial

type Rep Shape = D1 ('MetaData "Shape" "Proto3.Suite.Tutorial" "proto3-suite-0.7.0-inplace" 'False) (C1 ('MetaCons "Circle" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "Square" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Triangle" 'PrefixI 'False) (U1 :: Type -> Type)))

protoFile :: String

Generating a .proto file

We can generate a .proto file for the Foo and Bar data types by using the toProtoFileDef function. We have to provide a package name, and explicitly list the message and enumeration types as a DotProto value.

>>> putStrLn protoFile
syntax = "proto3";
package examplePackageName;
enum Shape {
  Circle = 0;
  Square = 1;
  Triangle = 2;
}
message Foo {
  uint32 fooX = 1;
  repeated int32 fooY = 2 [packed = true];
}
message Bar {
  Shape barShape = 1;
  Foo barFoo = 2;
  repeated Foo foos = 3;
}