Protocol Buffers

8.12

Protocol Buffers🔗ℹ

This package implements support for the Protocol Buffers serialization format. It implements a parser for the Protocol Buffers definition languages proto2 and proto3, and it does not have any external dependencies.

Examples:

> (require protocol-buffers
           racket/port
           racket/string)
> (define m
    (read-protobuf
      (open-input-string
       (string-join
        '("syntax = 'proto2';"
          ""
          "message Person {"
          "  required string name = 1;"
          "  required uint32 age = 2;"
          "  optional string favorite_food = 5;"
          "}")
        "\n"))))
> (define Person (mod-ref m 'Person))
> (define data (hasheq 'name "Bogdan" 'age 30))
> (define person-bs
   (call-with-output-bytes
    (lambda (out)
      (write-message Person data out))))
> (println person-bs)
#"\n\6Bogdan\20\36"
> (call-with-input-bytes person-bs
   (lambda (in)
     (read-message Person in)))
'#hasheq((age . 30) (favorite_food . "") (name . "Bogdan"))

1 Limitations🔗ℹ

The parser supports RPC and stream definitions, but modules ignore them. Likewise, message group fields are supported in the parser, but definitions that use them raise an error when read via read-protobuf. Message extensions also raise an error when read via read-protobuf.

2 Reference🔗ℹ

(require protocol-buffers)

package: protocol-buffers-lib

2.1 Modules🔗ℹ

A module is a runtime representation of a Protocol Buffers definition and any of its dependencies.

procedure
(read-protobuf [in]) → mod?
in : input-port? = (current-input-port)

Reads a protobuf definition into a module from in.

If the module contains any import statements, then the imported files will also be read relative to current-directory.

procedure
(mod? v) → boolean?
v : any/c

Returns #t when v is a module.

procedure
(mod-package m) → (or/c #f symbol?)
m : mod?

Returns m’s package, if any.

procedure
(mod-messages m) → (listof message?)
m : mod?

Returns the top-level messages in m, in definition order.

procedure
(mod-ref m id [default-proc]) → message?
  m : mod?
  id : symbol?
  default-proc : (-> any) = error

Returns the message named id from m. If m does not contain a message with that name, then the result of applying default-proc is returned instead.

2.2 Messages🔗ℹ

Messages correspond to message definitions within a Protocol Buffers file. They contain information about how data should be serialized and deserialized.

procedure
(message? v) → boolean?
v : any/c

Returns #t when v is a message.

procedure
(message-name m) → symbol?
m : message?

Returns the name of the message m.

procedure
(message-messages m) → (listof message?)
m : message?

Returns the child messages of m, in order of definition.

procedure
(read-message m [in]) → hash?
m : message?
in : input-port? = (current-input-port)

Reads data from in according to the format of m.

procedure
(write-message m v [out]) → void?
  m : message?
  v : hash?
  out : output-port? = (current-output-port)

Writes v to out according to the format of m.