1. Overview
  2. Docs
Library for describing Protobuf messages







pb, a library for describing Protobuf messages

pb is an OCaml library for describing and serializing Protocol buffers

Message descriptions can be written by hand, or generated from .proto files
using the pb-plugin protoc compiler plugin.

Describing messages

Protocol buffers provide both a file format for describing messages and a
serialization (wire) format. The pb library supports only the wire format, but
there is a straightforward mapping from the file format into pb code. Here is
a description of a Protobuf message with two fields, a
number field with the tag 1, and a PhoneType field with
the tag 2 and default value HOME:

message PhoneNumber {
  required string number = 1;
  optional PhoneType type = 2 [default = HOME];

And here is the equivalent pb code that defines the PhoneNumber message:

module PhoneNumber = (val message "PhoneNumber")
let number = PhoneNumber.required string "number" 1
let type_  = PhoneNumber.optional "type" 2 ~default:home

The type field of the PhoneNumber message has the type PhoneType, an
enumeration value. Here is a description of the PhoneType
enumeration with its three values:

enum PhoneType {
  MOBILE = 0;
  HOME = 1;
  WORK = 2;

And here is the equivalent pb code that defines the PhoneType enumeration:

module PhoneType = (val enum "PhoneType")
let mobile = PhoneType.constant "MOBILE" 0l
let home   = PhoneType.constant "HOME" 1l
let work   = PhoneType.constant "WORK" 2l

Serializing and deserializing

Messages described by pb can be serialized using the Faraday
serialization library. The following code creates a PhoneNumber message,
assigns values to its two fields, and writes it to a Faraday serializer:

let pn = create PhoneNumber.t in
  setf pn number ("+1-541-754-3010");
  setf pn type_ work;
  write pn

Messages can be deserialized (parsed) using the Angstrom
parser-combinator library. The following code reads a message using Angstrom and
retrieves the values of its fields:

let pn = match Angstrom.parse_string (read PhoneNumber.t) s) with
         | Ok m -> m
         | Error s -> failwith s
  in (getf pn number, getf pn type_)


Messages can also be pretty-printed:

pp_msg PhoneNumber.t Format.std_formatter pn