2.1 .proto file to Lisp conversion
2.2 CLOS classes to .proto conversion
2.3 Using .proto files directly
+ 2.3.1 A note on Lisp packages
2.4 Using the Protobufs macros
2.4.1 Protobufs types
2.4.2 Protobufs service stubs
system.)
+A note on Lisp packages
+~~~~~~~~~~~~~~~~~~~~~~~
+
+When using an existing .proto file directly, it will likely contain a
+``package`` line, but not a ``lisp_package`` line. CL-Protobufs needs
+to choose some package to use. Here is what it does:
+
+ - The package name from the ``package`` line is converted to a more
+ Lisp-like name, e.g., ``fortune_teller`` becomes ``fortune-teller``.
+ - If the Lisp package exists (i.e., you have previously used
+ ``defpackage`` to define the packaged), then CL-Protobufs just
+ uses it.
+ - If the Lisp package does not exist, CL-Protobufs creates a new
+ package of the given name that uses no other packages, not even
+ the ``common-lisp`` package. In addition, the symbols naming all
+ of the enum types, message types, field name and service method
+ names are exported from the new package.
+
+
Using the Protobufs macros
--------------------------
(color :type color))
(proto:define-service color-wheel ()
(get-color (get-color-request color)
- :options ("deadline" "1.0"))
+ :options (:deadline 1.0))
(add-color (add-color-request color)
- :options ("deadline" "1.0"))))
+ :options (:deadline 1.0))))
This will create the Protobufs model objects, Lisp classes and enum
types that correspond to the model. The .proto file of the same schema
service ColorWheel {
rpc GetColor (GetColorRequest) returns (Color) {
- option deadline = "1.0";
+ option deadline = 1.0;
}
rpc AddColor (AddColorRequest) returns (Color) {
- option deadline = "1.0";
+ option deadline = 1.0;
}
}
in the .proto file.
*body* consists of the enum values, each of which is either a symbol
-or a list of the form ``(name index)``. By default, the indexes start
-at 0 and are incremented by 1 for each new enum value. For schema
-forward and backward compatibility, you should always use the
-``(name index)`` form.
+or a list either of the form ``(name index)`` or ``(name &key index)``.
+By default, and if you have not explicitly given an index, the indexes
+start at 0 and are incremented by 1 for each new enum value. For
+schema forward and backward compatibility, you should always use the
+explicit form, either ``(name index)`` or ``(name &key index)``.
``proto:define-enum`` can be used only within ``proto:define-schema``
or ``proto:define-message``.
The body *fields* consists of fields, ``proto:define-enum``,
``proto:define-message`` or ``proto:define-extension`` forms.
-Fields take the form ``(slot &key type name default reader writer)``.
+Fields take the form ``(slot &key index type name default reader writer)``.
*slot* can be either a symbol giving the slot name or a list of the
form ``(slot index)``. By default, the field indexes start at 1 and
are incremented by 1 for each new field value. *type* is the type of
the slot. For schema forward and backward compatibility, you should
-always use the ``(slot index)`` form.
+always use either the ``(slot index)`` form or supply ``:index``.
*name* can be used to override the defaultly generated Protobufs field
name (for example, a Lisp field called ``color-name``, by default,
in the .proto file.
The body is a set of method specs of the form
-``(name (input-type output-type) &key options documentation)``.
-*name* is a symbol naming the RPC method. *input-type* and
-*output-type* may either be symbols or a list of the form ``(type &key name)``.
+``(name (input-type [=>] output-type &key streams) &key options documentation)``.
+
+For each method spec, *name* is a symbol naming the RPC method.
+*input-type* and *output-type* give the input and output types of the method;
+they may either be symbols or a list of the form ``(type &key name)``.
+You can optionally include the symbol ``=>`` between the input and
+output types; this seems to improve readability.
+
+*streams* is also the name of a type, and provides a hook to RPC
+implementations that implement "streaming".
``proto:define-service`` can only be used within ``proto:define-schema``.
Protobufs types
----------------
+~~~~~~~~~~~~~~~
The following types are defined in the ``protobufs`` package:
Protobufs service stubs
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
When you use the ``proto:define-service`` macro to define a service
with some methods, the macro defines "stubs" (CLOS generic functions)
for each of the methods in the service. Each method named ``foo`` gets
a client stub and a server stub whose signatures are, respectively::
- foo (rpc-channel request &key callback) => response
- do-foo (rpc-channel request) => response
+ call-foo (rpc-channel request &key callback) => response
+ foo-impl (rpc-channel request) => response
+
+These methods are interned in a different lisp package, ``XXX-RPC``,
+where ``XXX`` is the name of the lisp package into which the rest of
+the schema's symbols are interned. This is done so that message field
+accessors methods can't collide with the stubs.
The type of *rpc-channel* is unspecified, but is meant to be a
"channel" over which the RPC call will be done. The types of *request*
(get-color (get-color-request color))
(add-color (add-color-request color)))
-The client stubs are ``get-color`` and ``add-color``, the server stubs
-are ``do-get-color`` and ``do-add-color``. An RPC library will implement
-a method for the client stub. You must fill in the server stub yourself;
-it will implement the desired functionality.
+The client stubs are ``call-get-color`` and ``call-add-color``, the
+server stubs are ``get-color-impl`` and ``add-color-impl``. An RPC
+library will implement a method for the client stub. You must fill in
+the server stub yourself; it will implement the desired functionality.
The client stub also gets a single method defined for it that looks like
something like this::
- (defmethod foo (rpc-channel (request input-type) &key callback)
+ (defmethod call-foo (rpc-channel (request input-type) &key callback)
(let ((call (and *rpc-package* *rpc-call-function*)))
(funcall call rpc-channel method request :callback callback)))
counterpart in Protobufs, but which "ground out" to compatible
Protobufs code.
+
Type aliases
------------
projects / cl-protobufs.git / blobdiff