Common Lisp Package: PROTOBUFS

README:

FUNCTION

Public

DESERIALIZE-OBJECT-FROM-BYTES (TYPE BUFFER)

Deserializes an object of the given type 'type' from the given stream as a Protobuf object. 'type' is the Lisp name of a Protobufs message (usually the name of a Lisp class) or a 'protobuf-message'. The return value is the object.

DESERIALIZE-OBJECT-FROM-FILE (TYPE FILENAME)

Deserializes an object of the given type 'type' from the given file as a Protobuf object.

DESERIALIZE-OBJECT-FROM-STREAM (TYPE &KEY (STREAM *STANDARD-INPUT*))

Deserializes an object of the given type 'type' from the given stream as a Protobuf object.

GENERATE-SCHEMA-FOR-CLASSES (CLASSES &KEY NAME PACKAGE LISP-PACKAGE INSTALL SLOT-FILTER TYPE-FILTER ENUM-FILTER VALUE-FILTER (ALIAS-EXISTING-CLASSES *ALIAS-EXISTING-CLASSES*))

Given a set of CLOS classes, generates a Protobufs schema for the classes. The return value is the schema.

PARSE-SCHEMA-FROM-FILE (FILENAME &KEY NAME CLASS (CONC-NAME ))

Parses the named file as a .proto file, and returns the Protobufs schema.

PARSE-SCHEMA-FROM-STREAM (STREAM &KEY NAME CLASS (CONC-NAME ))

Parses a top-level .proto file from the stream 'stream'. Returns the protobuf schema that describes the .proto file.

SERIALIZE-OBJECT-TO-BYTES (OBJECT TYPE &KEY VISITED)

Serializes the object 'object' of type 'type' into a new byte vector using the wire format. 'type' is the Lisp name of a Protobufs message (usually the name of a Lisp class) or a 'protobuf-message'. 'visited' is a hash table used to cache object sizes. If it is supplied, it will be cleared before it is used; otherwise, a fresh table will be created if necessary. The return value is the buffer containing the serialized object. If the stream is nil, the buffer is not actually written to anywhere.

SERIALIZE-OBJECT-TO-FILE (FILENAME OBJECT TYPE &KEY VISITED)

Serializes the object 'object' of type 'type' into the file 'filename' using the wire format. 'object' and 'type' are the same as for 'serialize-object-to-bytes'.

SERIALIZE-OBJECT-TO-STREAM (OBJECT TYPE &KEY (STREAM *STANDARD-OUTPUT*) VISITED)

Serializes the object 'object' of type 'type' onto the stream 'stream' using the wire format. 'object' and 'type' are the same as for 'serialize-object-to-bytes'.

WRITE-SCHEMA (PROTOBUF &REST KEYS &KEY (STREAM *STANDARD-OUTPUT*) (TYPE PROTO) &ALLOW-OTHER-KEYS)

Writes the object 'protobuf' (schema, message, enum, etc) onto the stream 'stream' in the format given by 'type' (:proto, :text, etc).

WRITE-SCHEMA-FOR-CLASSES (CLASSES &KEY (STREAM *STANDARD-OUTPUT*) (TYPE PROTO) NAME PACKAGE LISP-PACKAGE INSTALL SLOT-FILTER TYPE-FILTER ENUM-FILTER VALUE-FILTER (ALIAS-EXISTING-CLASSES *ALIAS-EXISTING-CLASSES*))

Given a set of CLOS classes, generates a Protobufs schema for the classes and pretty prints the schema to the stream. The return value is the schema.

Undocumented

MAKE-BYTE-VECTOR (SIZE)

UNDEFINED-FIELD-TYPE (FORMAT-CONTROL OBJECT TYPE FIELD)

MACRO

Public

DEFINE-ENUM (TYPE (&KEY NAME CONC-NAME ALIAS-FOR OPTIONS DOCUMENTATION SOURCE-LOCATION) &BODY VALUES)

Define a Protobufs enum type and a Lisp 'deftype' named 'type'. 'name' can be used to override the defaultly generated Protobufs enum name. 'conc-name' will be used as the prefix to the Lisp enum names, if it's supplied. If 'alias-for' is given, no Lisp 'deftype' will be defined. Instead, the enum will be used as an alias for an enum type that already exists in Lisp. 'options' is a set of keyword/value pairs, both of which are strings. The body consists of the enum values in the form 'name' or (name index).

DEFINE-EXTEND (TYPE (&KEY NAME CONC-NAME OPTIONS DOCUMENTATION) &BODY FIELDS &ENVIRONMENT ENV)

Define an extension to the message named 'type'. 'name' can be used to override the defaultly generated Protobufs message name. The body consists only of fields. 'options' is a set of keyword/value pairs, both of which are strings. Fields take the form (slot &key type name default reader) 'slot' can be either a symbol giving the field name, or a list whose first element is the slot name and whose second element is the index. 'type' is the type of the slot. 'name' can be used to override the defaultly generated Protobufs field name. 'default' is the default value for the slot. 'reader' is a Lisp slot reader function to use to get the value, instead of using 'slot-value'; this is often used when aliasing an existing class. 'writer' is a Lisp slot writer function to use to set the value.

DEFINE-EXTENSION (FROM TO)

Define an extension range within a message. The "body" is the start and end of the range, both inclusive.

DEFINE-GROUP (TYPE (&KEY INDEX ARITY NAME CONC-NAME ALIAS-FOR READER OPTIONS DOCUMENTATION SOURCE-LOCATION) &BODY FIELDS &ENVIRONMENT ENV)

Define a message named 'type' and a Lisp 'defclass', *and* a field named type. This is deprecated in Protobufs, but if you have to use it, you must give 'index' as the field index and 'arity' of :required, :optional or :repeated. 'name' can be used to override the defaultly generated Protobufs message name. The body consists of fields, or 'define-enum' or 'define-message' forms. 'conc-name' will be used as the prefix to the Lisp slot accessors, if it's supplied. If 'alias-for' is given, no Lisp class is defined. Instead, the message will be used as an alias for a class that already exists in Lisp. This feature is intended to be used to define messages that will be serialized from existing Lisp classes; unless you get the slot names or readers exactly right for each field, it will be the case that trying to (de)serialize into a Lisp object won't work. 'options' is a set of keyword/value pairs, both of which are strings. Fields take the form (slot &key type name default reader) 'slot' can be either a symbol giving the field name, or a list whose first element is the slot name and whose second element is the index. 'type' is the type of the slot. 'name' can be used to override the defaultly generated Protobufs field name. 'default' is the default value for the slot. 'reader' is a Lisp slot reader function to use to get the value, instead of using 'slot-value'; this is often used when aliasing an existing class. 'writer' is a Lisp slot writer function to use to set the value.

DEFINE-MESSAGE (TYPE (&KEY NAME CONC-NAME ALIAS-FOR OPTIONS DOCUMENTATION SOURCE-LOCATION) &BODY FIELDS &ENVIRONMENT ENV)

Define a message named 'type' and a Lisp 'defclass'. 'name' can be used to override the defaultly generated Protobufs message name. The body consists of fields, or 'define-enum' or 'define-message' forms. 'conc-name' will be used as the prefix to the Lisp slot accessors, if it's supplied. If 'alias-for' is given, no Lisp class is defined. Instead, the message will be used as an alias for a class that already exists in Lisp. This feature is intended to be used to define messages that will be serialized from existing Lisp classes; unless you get the slot names or readers exactly right for each field, it will be the case that trying to (de)serialize into a Lisp object won't work. 'options' is a set of keyword/value pairs, both of which are strings. Fields take the form (slot &key type name default reader) 'slot' can be either a symbol giving the field name, or a list whose first element is the slot name and whose second element is the index. 'type' is the type of the slot. 'name' can be used to override the defaultly generated Protobufs field name. 'default' is the default value for the slot. 'reader' is a Lisp slot reader function to use to get the value, instead of using 'slot-value'; this is often used when aliasing an existing class. 'writer' is a Lisp slot writer function to use to set the value.

DEFINE-SCHEMA (TYPE (&KEY NAME SYNTAX PACKAGE LISP-PACKAGE IMPORT OPTIMIZE OPTIONS DOCUMENTATION) &BODY MESSAGES &ENVIRONMENT ENV)

Define a schema named 'type', corresponding to a .proto file of that name. 'name' can be used to override the defaultly generated Protobufs name. 'syntax' and 'package' are as they would be in a .proto file. 'lisp-package' can be used to specify a Lisp package if it is different from the Protobufs package given by 'package'. 'import' is a list of pathname strings to be imported. 'optimize' can be either :space (the default) or :speed; if it is :speed, the serialization code will be much faster, but much less compact. 'options' is a property list, i.e., ("key1" "val1" "key2" "val2" ...). The body consists of 'define-enum', 'define-message' or 'define-service' forms.

DEFINE-SERVICE (TYPE (&KEY NAME OPTIONS DOCUMENTATION SOURCE-LOCATION) &BODY METHOD-SPECS)

Define a service named 'type' and Lisp 'defgeneric' for all its methods. 'name' can be used to override the defaultly generated Protobufs service name. 'options' is a set of keyword/value pairs, both of which are strings. The body is a set of method specs of the form (name (input-type [=>] output-type) &key options). 'input-type' and 'output-type' may also be of the form (type &key name).

DEFINE-TYPE-ALIAS (TYPE (&KEY NAME ALIAS-FOR DOCUMENTATION SOURCE-LOCATION) &KEY LISP-TYPE PROTO-TYPE SERIALIZER DESERIALIZER)

Define a Protobufs type alias Lisp 'deftype' named 'type'. 'lisp-type' is the name of the Lisp type. 'proto-type' is the name of a primitive Protobufs type, e.g., 'int32' or 'string'. 'serializer' is a function that takes a Lisp object and generates a Protobufs object. 'deserializer' is a function that takes a Protobufs object and generates a Lisp object. If 'alias-for' is given, no Lisp 'deftype' will be defined.

GENERIC-FUNCTION

Public

CLEAR (OBJECT)

Initialize all of the fields of 'object' to their default values.

CLEAR-EXTENSION (OBJECT SLOT)

Clears the value of the extended slot 'slot' from 'object'

CLEAR-FIELD (OBJECT SLOT)

Initialize the field 'slot' of 'object' to its default value.

DESERIALIZE-OBJECT (TYPE BUFFER &OPTIONAL START END END-TAG)

Deserializes an object of the given type 'type' as a Protobufs object. 'type' is the Lisp name of a Protobufs message (usually the name of a Lisp class) or a 'protobuf-message'. The encoded bytes are in the byte array given by 'buffer' starting at the fixnum index 'start' up to the end of the buffer, given by 'end'. 'start' defaults to 0, 'end' defaults to the length of the buffer. 'end-tag' is used internally to handle the (deprecated) "group" feature. The return values are the object and the index at which deserialization stopped..

FIND-MESSAGE (PROTOBUF TYPE &OPTIONAL RELATIVE-TO)

Given a Protobufs schema or message and a type name or class name, returns the Protobufs message corresponding to the type.

FIND-MESSAGE-FOR-CLASS (CLASS)

Given a class or class name, return the message that globally has that name.

FIND-SCHEMA (NAME)

Given a name (a symbol or string), return the 'protobuf-schema' object having that name.

FIND-SERVICE (PROTOBUF NAME)

Given a Protobufs schema,returns the Protobufs service of the given name.

GET-EXTENSION (OBJECT SLOT)

Returns the value of the extended slot 'slot' in 'object'

HAS-EXTENSION (OBJECT SLOT)

Returns true iff the there is an extended slot named 'slot' in 'object'

HAS-FIELD (OBJECT SLOT)

Returns true iff the field 'slot' in 'object' is initialized.

IS-INITIALIZED (OBJECT)

Returns true iff all of the fields of 'object' are initialized.

MERGE-FROM-ARRAY (OBJECT BUFFER &OPTIONAL START END)

Deserialize the object encoded in 'buffer' and merge it into 'object'. Deserialization starts at the index 'start' and ends at 'end'. 'object' must an object whose Lisp class corresponds to the message being deserialized. The return value is the updated object.

MERGE-FROM-MESSAGE (OBJECT SOURCE)

Merge the fields from the source object 'source' into 'object'. The two objects must be of the same type. Singular fields will be overwritten, with embedded messages being be merged. Repeated fields will be concatenated. The return value is the updated object 'object'.

OBJECT-INITIALIZED-P (OBJECT TYPE)

Returns true iff all of the fields of 'object' are initialized.

OBJECT-SIZE (OBJECT TYPE &OPTIONAL VISITED)

Computes the size in bytes of the object 'object' of type 'type'. 'type' is the Lisp name of a Protobufs message (usually the name of a Lisp class) or a 'protobuf-message'. 'visited' is either a hash table used to cache object sizes, or is nil, in which case the objects must have a '%cached-size' slot in them. The return value is the size of the object in bytes.

OCTET-SIZE (OBJECT)

Returns the number of octets required to encode 'object' using the wire format. 'object' is an object whose Lisp class corresponds to a Protobufs message.

PARSE-TEXT-FORMAT (TYPE &KEY STREAM PARSE-NAME (PARSE-NAME T) (STREAM *STANDARD-INPUT*))

Parses an object of type 'type' from the stream 'stream' using the textual format.

REINITIALIZE-OBJECT (OBJECT TYPE)

Reset all the fields of 'object' to their initial values.

SCHEMA-UPGRADABLE (OLD NEW &OPTIONAL OLD-PARENT NEW-PARENT)

Returns true if and only if the old Protobufs schema can be upgraded to the new schema. 'old' is the old object (schema, enum, message, etc), 'new' is the new one. 'old-parent' is the "parent" of 'old', 'new-parent' is the parent of 'new'. If the schema is not upgradable, the second value is a list of warnings.

SCHEMAS-EQUAL (SCHEMA1 PROTO2)

Returns true if and only if the two Protobufs schemas are equal.

SERIALIZE (OBJECT &OPTIONAL BUFFER START END)

Serialize 'object' into 'buffer' using the wire format, starting at the index 'start' and going no farther than 'end'. 'object' is an object whose Lisp class corresponds to a Protobufs message. Returns two values, the final index and the buffer.

SERIALIZE-OBJECT (OBJECT TYPE BUFFER &OPTIONAL START VISITED)

Serializes the object 'object' of type 'type' into the byte array 'buffer' using the wire format. 'type' is the Lisp name of a Protobufs message (usually the name of a Lisp class) or a 'protobuf-message'. The object is serialized into the byte array given by 'buffer' starting at the fixnum index 'index' using the wire format. 'visited' is a hash table used to cache object sizes; if this is nil, then the object caches its size itself in a '%cached-size' slot. The return value is the buffer containing the serialized object.

SET-EXTENSION (OBJECT SLOT VALUE)

Sets the value of the extended slot 'slot' to 'value' in 'object'

SLOT-INITIALIZED-P (OBJECT TYPE SLOT)

Returns true iff the field 'slot' in 'object' is initialized.

Undocumented

ERROR-FIELD (CONDITION)

ERROR-METHOD (CONDITION)

ERROR-TYPE-NAME (CONDITION)

REINITIALIZE-FIELD (OBJECT MESSAGE FIELD)

REINITIALIZE-SLOT (OBJECT MESSAGE SLOT)

CLASS

Public

PROTOBUF-ENUM

The model class that represents a Protobufs enumeration type.

PROTOBUF-ENUM-VALUE

The model class that represents a Protobufs enumeration value.

PROTOBUF-EXTENSION

The model class that represents an extension range within a Protobufs message.

PROTOBUF-FIELD

The model class that represents one field within a Protobufs message.

PROTOBUF-MESSAGE

The model class that represents a Protobufs message.

PROTOBUF-METHOD

The model class that represents one method with a Protobufs service.

PROTOBUF-OPTION

The model class that represents a Protobufs options, i.e., a keyword/value pair.

PROTOBUF-SCHEMA

The model class that represents a Protobufs schema, i.e., one .proto file.

PROTOBUF-SERVICE

The model class that represents a Protobufs service.

PROTOBUF-TYPE-ALIAS

The model class that represents a Protobufs type alias.

CONDITION

Public

UNDEFINED-FIELD-TYPE (FORMAT-CONTROL OBJECT TYPE FIELD)

Indicates that a schema contains a message with a field whose type is not a primitive type and is not a known message (or extend) or enum.

Undocumented

UNDEFINED-INPUT-TYPE

UNDEFINED-OUTPUT-TYPE

UNDEFINED-STREAM-TYPE