field string serialization¶

Functionality to serialize a fielded buffer to and from a string representation

semantics¶

Developer creates a mapping-file that defines a set of transformations/serializations for field <-> string bound to an arbitrary unique key.

From this mapping-file the developer generates a cpp file, and then compiles and links the implementation to the executable. This can of course be done via a shared object.

From the code that is going to perform the serialization, the developer uses the C-api to invoke a specific transformation/serialization by providing the arbitrary key (and the input/output - buffer/string)

mapping file¶

The following format can be used:

yaml
json
xml
ini

The file-extension has to correlate with the format.

yaml example:

mapping:
  - key: some_key_1
    note: some documentation

    fields: 
      - name: FLD_STRING1 # name of the field. 
        size: 10 # size of the fixed string representation.
        # alignment: "left"  <- default value
        # padding: " " <- default value, if set, at least on char has to be set .
      
      - name: FLD_STRING2
        size: 20
        alignment: "left"
        padding: "." # will be padded _to the right_ with '.'

  - key: some_key_2
    note: some documentation

    fields: 
      - name: FLD_LONG1
        size: 10
        alignment: "right"
      
      - name: FLD_STRING2
        size: 20
        alignment: "left"

      # other yaml syntax for the same thing
      - { name: FLD_SHORT1, size: 4}

generate the implementation¶

casual-buffer-field-serialize is used to generate the implementation.

as always, use option --help to get additional information on what’s possible

Example:

$ $CASUAL_HOME/bin/casual-buffer-field-serialize --files some-mapping-file.yaml --output some-implementation.cpp

compile and link¶

Compile and link the implementation.

Example:

$ g++ -o some-implementation.o some-implementation.cpp –I$CASUAL_HOME/include -pthread -c -O3 -fpic -std=c++14

Link the object file to the lib/executable to the lib/executable that uses the serialization.

possible build scenarios¶

One mapping-file for all mappings, that generate one cpp implementation file.
- The compiled object file could be linked directly, or via a library.
Many mapping-files that generate one cpp implementation file.
- The compiled object file could be linked directly, or via a library.
Many mapping-files that generates many implementation files.
- These could be linked to one shared object file (lib), that is linked to the executable

invoke the serialization¶

The developer uses the C-api to invoke a specific transformation/serialization by providing the arbitrary key (and the input/output - buffer/string)

Example:

// error handling omitted for clarity

void some_function( const char* buffer)
{
   char memory[ 1024]; // some large enough memory
   casual_field_to_string( memory, sizeof( memory), "some-defined-key", buffer);
   // use the _stringified_ representation...
}


void some_function( const char* memory, long size)
{
   char* buffer = tpalloc( CASUAL_FIELD, NULL, 128); // buffer will be expanded during the transformation
   casual_field_from_string( &buffer, "some-defined-key", memory, size);
   // use the buffer...
}