pb
is an OCaml library for describing and serializing Protocol buffers
(Protobuf) messages.
Message descriptions can be written by hand, or generated from .proto
files
using the pb-plugin
protoc compiler plugin.
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
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