package pb-plugin

  1. Overview
  2. Docs
Plugin for generating pb protobuf message descriptions

Install

Dune Dependency

Authors

Maintainers

Sources

pb-1.0.0.tbz
sha256=e670f11879ee5e44de396fda26ce18384093fd9d75b33727fe90db073e1e4d01
sha512=d6d5bd2991af3bb0121c6f9620510707e5b25332ff80224a1da482093ed53427b620e01294be4d52637dfedad8c30775ad228ac74a6d579d7c3a1de5887327cc

Description

Plugin for generating pb protobuf message descriptions

Published: 04 Dec 2019

README

pb, a library for describing Protobuf messages

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.

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_)

Pretty-printing

Messages can also be pretty-printed:

pp_msg PhoneNumber.t Format.std_formatter pn

Dependencies (7)

  1. faraday
  2. angstrom >= "0.10.0"
  3. batteries < "3.7"
  4. integers
  5. dune >= "1.11"
  6. pb
  7. ocaml >= "4.08"

Dev Dependencies (1)

  1. ounit with-test & >= "2.0"

Used by

None

Conflicts

None