fieldz is a Python3 implementation of a protocol meant to be generally compatible with Google's Protocol Buffers.
There are currently 20 defined field types. These fall into several categories distinguished by the first one or two characters of the type name:
f
for fixed-lengthfs
for fixed-length, signedfu
for fixed-length, unsignedv
for variable-lengthvs
for variable-length, signedvu
for variable-length, unsignedl
for length-encoded, meaning that the field begins with its length encoded as a variable length integer, a varint
Varints are used to efficiently store integer values in the smallest possible number of bytes.
The actual field types are
vBool
, a booleanvEnum
, an enumvInt32
, a 32-bit integervInt64
, a 64-bit integervuInt32
, a 32-bit unsigned integervsInt32
, a 32-bit signed integervuInt64
, a 64-bit unsigned integervsInt64
, a 64-bit signed integerfuInt32
, an unsigned 32-bit floating point valuefsInt32
, a signed 32-bit floating point valuefFloat
, a floating point number, a 32-bit valuefuInt64
, a fixed length unsigned integerfsInt64
, a fixed lenth signed integerfDouble
, a fixed length double, a 64-bit valuelString
, a varint L followed by a UTF-encoded string of that lengthlBytes
, a varint L followed by L byteslMsg
, a varint L followed by a message declaration of that lengthfBytes16
, a field of 16 bytesfBytes20
, a string of 20 bytes, such as an SHA1 hashfBytes32
, a string of 32 bytes, such as an SHA256 hash
Acceptable field, message, and enum names consist of an alphabetic character (which may be an underscore, '_') followed by zero or more alphabetic characters, underscores, or digits.
So the following are acceptable names:
_abc123
but the following are not acceptable:
5_abc123
(begins with a digit)$abc123
(contains a dollar sign)a.b
(contains a dot)
Acceptable protocol names are like field and message names except that they may be dotted. That is, an acceptable protocol name consists of one or more otherwise acceptable names; where there is more than one such component name, the component names are separated by single dots ('.'). So any name which is an acceptable message or field name is also an acceptable protocol name.
Examples of acceptable protocol names:
a
a_b.cd.ef
Invalid protocol names:
a..b
(sequence of more than one dot).ab
(leading dot)ab.
(trailing dot)
A message declaration describes the possibly recursive structure of a message to be passed over the wire or stored compressed on disk.
A typical message looks like:
message logEntry {
timestamp fuInt32
nodeID fBytes20
key fBytes20
length vuInt32
by lString
path lString
}
Message names consist of an alphabetic character (which may be an underscore, '_') followed by zero or more alphabetic characters, underscores, or digits. The name must be followed in the declaration line by a colon (':').
Field declarations are usually indented below the message
line.
This particular message is called logEntry
. The message has six fields
but no constituent messages enums
A protocol declaration consists of a header line like
protocol org.xlattice.zoggery
followed by zero or more enum and/or message declarations.
Pre-alpha. Code and unit tests exist, but some tests fail.
More information on the fieldz project can be found here