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.
- 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.
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.
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.
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.
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.
#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;
}