liboctopus

This library provides C++ data structures exactly corresponding to the Octopus format (and Octopus Manifest) and also contains parser and serializer classes for simple conversion to and from a JSON string representation.

Maintainer guidelines

Always make sure to update the version of the Octopus specification in octopus.h and octopus-manifest.h.
Parser and serializer classes are machine-generated by json-cpp-gen. Do not modify them by hand and make sure to re-generate them before committing by running json-cpp-gen with json-config.json as argument.

How to use

Build the library using CMake or incorporate it in your project as a CMake subproject. There are no external library dependencies.

You may either include only the specific headers that you need, or by including <octopus/octopus.h> you will get all Octopus structures and by including <octopus-manifest/octopus-manifest.h> you will get all Octopus Manifest structures. Parsers, serializers, and the validator must be included individually. All structures and functions are in the octopus namespace.

The Octopus and Octopus Manifest structures correspond to the Octopus specification so refer to that for explanation of structure members.

Parsing

To parse data from JSON, call:

// XyzParser is either Parser or ManifestParser
octopus::XyzParser::Error error = octopus::XyzParser::parse(
    outputDataStructure, // An output data structure supported by the parser
    jsonString // (const char *) A null-terminated UTF-8 JSON string
);

The call succeeded if !error. Otherwise:

error.type is the error type (an enumeration)
- error.typeString() translates it to a C string (const char *)
error.position is the approximate position of the error in bytes within the JSON string. On success, this will be set to the position immediately following the consumed JSON data.

Serialization

To serialize data to JSON, call:

// XyzSerializer is either Serializer or ManifestSerializer
octopus::XyzSerializer::Error error = octopus::XyzSerializer::serialize(
    jsonString, // The target std::string in which the JSON will be stored
    inputDataStructure // An input data structure supported by the serializer
);

The call succeeded if !error. Otherwise:

error.type is the error type (an enumeration)
- error.typeString() translates it to a C string (const char *)
error.datapoint is the pointer to the specific field that failed to serialize.

Validation

The library also supports a validation function that checks whether the Octopus data are consistent and conform to the rules of the Octopus format. You may call it as:

std::set<std::string> layerIdSet;
std::string errorMessage; // Validation error message will be stored here
const void *badDatapoint = nullptr; // Pointer to invalid data field will be stored here
bool result = octopus::validate(
    octopusData, // octopus::Octopus structure
    layerIdSet, // Encountered layer ID's will be stored here
    &errorMessage, // Can be null if not interested
    &badDatapoint // Can be null if not interested
);

The layerIdSet may be pre-filled with ID's from other components of the same design. The validation will fail if a duplicate layer ID is encountered.

Example usage

#include <string>
#include <fstream>
#include <octopus/octopus.h>
#include <octopus/parser.h>

int main(int argc, const char *const *argv) {
    // Read Octopus file in argv[1] to octopusJson string:
    std::string octopusJson((std::istreambuf_iterator<char>(std::ifstream(argv[1]))), std::istreambuf_iterator<char>());
    // octopusData will represent the Octopus as structured data
    octopus::Octopus octopusData;
    // Parse octopusData from octopusJson
    octopus::Parser::Error error = octopus::Parser::parse(octopusData, octopusJson.c_str());
    // Check for parse error
    if (error)
        return (int) error.type;
    // Success - here we can work with the loaded Octopus data
    return 0;
}