Chapter 1. Trial.Protocol

Trial.Protocol is a header-only library^[1] for processing (parsing, manipulating, and generating) encoded data for network wire protocols. Trial.Protocol contains several interfaces for parsing and generating encoded data, as well as a heterogeneous tree data structure that can be used as a parse tree.

Currently supported protocols^[2] are:

JSON
BinToken

Levels of Abstraction

Protocol processing can be done at any of three levels of abstraction:

Incremental processors transforms the data token by token. There are two types of incremental processing: (i) push processing where the processing is done automatically and each token causes a callback to be invoked, and (ii) pull processing where the user has to advance manually from one token to the next.^[3] Incremental processing is also called stream processing.
Serialization archives are used to transform directly between the protocol format and C++ data structures. The serialization archives do not go through an intermediate representation and can therefore perform faster and in less memory. The mapping between the protocol format and the C++ data structures can be specified both (i) intrusively by augmenting the C++ data structure with the mapping, and (ii) non-intrusively by specifying the mapping in separate function outside the C++ data structure.
Tree processing^[4] transforms the the entire encoded data into a generic tree structure which can then be examined and manipulated with tree operations.

At each level of abstraction there are processors for both parsing and generating protocol formats. These are summarized below.

	Parser	Generator
Incremental	The encoded input can be parsed token by token with an incremental parser. For each token we can query the current token type and value.	The encoded output can be generated token by token with an incremental generator.
Serialization	The encoded input can be deserialized directly into arbitrary C++ data structures with an input archive.	Arbitrary C++ data structures can be serialized directly into encoded output with an output archive.
Tree	The encoded input can be parsed into a dedicated parse tree.	The dedicated parse tree can be transformed into an encoded output.

The protocol generators can write the encoded output to different types of buffers as long as an adapter exists for the buffer type. The correct header files must be included for this to work seamlessly.

	Note
For brevity all examples in this documentation assumes using namespace trial::protocol;

Note

For brevity all examples in this documentation assumes

using namespace trial::protocol;

^[1] Trial.Protocol serialization relies on Boost.Serialization, which is not header-only. Serialization is an optional feature.

^[2] Trial.Protocol only supports protocols that can be tokenized without using a schema.

^[3] Pull processors resembles a ForwardIterator, albeit with an interface closer to the Iterator pattern.

^[4] Tree processing is similar to creating a Document Object Model.