Package: hrprotoparser
HRPROTOPARSERhrprotoparser stands for "Human Readable PROTOcol PARSER"This is the core library to produce a network abstraction layer for communication.Why not procol buffers or flat buffers or zmq ?This library aims to provide a trivially simple protocol, suited for embedded applications.ZMQ is more like a socket abstraction, and even if it support request / reply, there is no such thing as "protocol" (but you can use hrp over zmq !)Protocol buffers is interesting, but is not "that simple", and needs unpacking the data. It is the way to go in the general case, since it is widely used. HRP offers an even simpler protocol, eaiser to parse, and more oriented RPC.Flat buffers : This one is a tough opponent since it is the official alternative to protocol buffers for performence oriented. It is However high-level oriented. HRP is low-level and mostly C-oriented, and its binary format is quite simpler than flat buffers.Another benefit form HRPP is how it is architectured : one core library parsing the protocol file, and generated codes are simple skbs templates. This way, you can customize every aspect of the generated code with a trivial synthax.InstallationFirst install the packet with pip:pip install hrprotoparser(Orpip install .if cloned from git).Then you have to clone the skbs templates to generate protocols :If you have cloned this repository from git, you only have to get the submodules with :git submodule update --init --recursiveOr if you installed from pypi, then clone the template repository only in some folder :git clone https://github.com/hl037/hrprotoparser-skbs-templates skbs-templateThen go to the directorycd skbs-templateand run :for i in hrpp*; do skbs install --symlink $i; done...To install the templates.Now, you can start using hrpp.UsageTo use one of the provided template, do the following :skbs gen @hrpp_C <dest> -- -p protocol.hrpwhere@hrpp_Ccan be replaced by any hrpp template, and<dest>is the destination directory.To get help, simply do :skbs gen @hrpp_C <dest> -- --helpYou can also simply print the protocol content with :skbs gen @hrpp_C <dest> -- --infoSynthaxThe protocol sythax is close to the C/C++/Java family.The protocol definition is entirely parseable using only regular expressions.There are 5 statement types : Flag, Constant, Structure, Enumeration, and Packets.Any text that doesn't match a statement is comment. (No // or # everywhere, you can document the protocol directly inside the definition).FlagsPattern :F <FlagName> = <ConstantValue>A flag is some kind of configuration. There are standard flags changing the binary format of the protocol encoding. See the "Standard Flags" section for more details.ConstantsPattern :C <Type> <ConstantName> = <ConstantValue> // Optionnal documentation commentA constant can be used as an array size or a packet type.EnumerationsPattern :E <EnumName> : <Type> {Pattern of an enum constant :<ConstantName> = <ConstantValue> // Optionnal documentation commentPattern of the block end :}An enumeration groups constants under a same specialized type. This is only pure semantic and the binary format of the protocol doesn't care if a value is an enum, or an integer / float.StructPattern :S <Struct>  {Pattern of a struct field :<Type> <FieldName> // Optionnal docummentation commentPattern of the block end :}A structure groups reusable fields for packets. They can be nested at will.PacketPattern :<Direction> <PacketName> (<PacketType>) {Pattern of the fields and of the end of packet are the same as structThePacketTypeis either directly an integer, or a constant name.The Direction may be one of :>"client to server"<"server to client"<>"any direction"[NOT IMPLEMENTED YET]PeerA > PeerB"PeerA to PeerB"[NOT IMPLEMENTED YET]PeerB < PeerA"PeerB to PeerA" (a response)DatatypesBase datatypeint8/char,uint8/byte: signed and unsigned integer of 8 bitsint16,uint16: signed and unsigned integer of 16 bitsint32,uint32: signed and unsigned integer of 32 bitsint64,uint64: signed and unsigned integer of 64 bitsfloat32: floating point number using 32 bitsfloat64: floating point number using 64 bitsArray typesArray are constructed recursively as<Type>[<ItemCount>]Note: Multidimensionnal indice order is reversed compared to the C one : the first dimension is the right-most.Any Base type, struct and array can be "arrayed".Variable length arrays are only supported as last, optionnally nested, struct field. This is the same rule as the C programming language.
To make an array variable length, simply leave the  empty.Standard flagsFlagPSIZESize of the header field specifying the packet size :-1: Variable size of packet size : the packet size is a packed variable int. One should concatenate the 7 least signifient bits as long as the most significant bit is 1. The bytes are sent LSB first.0: Deduced packet size : The packet size is deduced from the packet type. In this mode, use of variable length array is forbidden.nwithn > 0: Fixed size of packet size : The packet size field occupies n bytesFlagTSIZESize of header field specifying the packet type :-1: Variable size of packet type : the pacjet type is packed as a variable int, with the same binary format as previouslynwithn > 0: Fixed packet type size : The packet type field occupies n bytes.Binary formatThe binary format of the protocol is very simple :
It is the concatenation of the packet size (if one), the packet type, and the C binary representation of the structure on a little endian machine with an alignment of 1.DisclaimerSome part of the code base is quite old (2014). It works but may not be the most beautiful code I've ever done... May be some day I will rewrite it from scratch...LicenseCopyright © 2014-2020 Léo Flaventin HauchecorneThis program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.You should have received a copy of the GNU General Public License
along with this program.  If not, seehttps://www.gnu.org/licenses/.