# 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:

``` yaml
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:**
```bash
$ $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:**
```bash
$ 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:**

``` C
// 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...
}
```