Enhancement: Standardized JSON Schema for defining control block structures

[lcarcaramo]

Is your feature request related to a problem? Please describe.
Create a standardized JSON schema for defining control block structures to enable users to extract/format control blocks that are not known to CBXP.

Enable extracting unknown control blocks from memory and enable them to be found relative to a known control block maybe?

Describe the solution you'd like
N/A

Describe alternatives you've considered
N/A

Additional context
N/A

[lcarcaramo]

Implementation Ideas

JSON schema validator for JSON for Modern C++: https://github.com/pboettch/json-schema-validator

Preload known control blocks into a hash map. The JSON mappings will be added to generated header files at compile time.

User provided control block mappings can be provided using CBXPPATH, which is analogous to PATH, LIBPATH, PYTHONPATH, etc...

So CBXP would start with the preloaded control block mappings, load mappings from /etc/cbxp, and then /u/user/cbxp-json in the example below.

export CBXPATH=/u/user/cbxp-json:/etc/cbxp

control_block_explorer.hpp

std::unordered_map<std::string, ControlBlock> buildControlBlockMap() {
  // Load known control blocks
  std::unordered_map<std::string, ControlBlock> control_blocks =
    {
        {"psa", ControlBlock(PSA_JSON)},
        {"cvt", ControlBlock(CVT_JSON)},
        {"ecvt", ControlBlock(ECVT_JSON)},
        {"asvt", ControlBlock(ASVT_JSON)},
        {"ascb", ControlBlock(ASCB_JSON)},
        {"assb", ControlBlock(ASSB_JSON)},
        {"oucb", ControlBlock(OUCB_JSON)}
    };

    // Load custom control blocks
   std::string env_p(std::getenv("CBXPPATH"));
    if (!env_p.empty()) {
      // Logic for loading custom control block mappings, overwriting any that were already loaded with custom mappings as well.
    }
}

std::unordered_map<std::string, ControlBlock> control_blocks = buildControlBlockMap()

control_block.hpp

class ControlBlock {
 private:
  static const nlohmann::json_schema::json_validator cbxp_schema_validator_ {CBXP_SCHEMA_JSON};
  ...
 public:
  ControlBlock(nlohmann::json control_block_mapping) {
    ...
    cbxp_schema_validator_.validate(control_block_mapping);
    // Logic for loading control block mapping information.
    // Have structs/objects for loading information for each control block field into a hashmap???
  }

Finding Control Block in live memory

Maybe the ControlBlockExplorer class can handle this? ControlBlock can have a getPointedToBy() method that can be used by ControlBlockExplorer to figure out how to to get to that control block?

Example flow:

1. Extract ecvt
2. Is ecvt root control block? (No)
3. Get control blocks that point to ecvt (cvt).
4. Check cvt includables (ecvt, asvt).
5. Is cvt root control block? (No)
6. Get control blocks that point to cvt (psa).
7. Check psa includables (cvt).
8. Is psa root control block? (Yes)
9. Build and chain of pointers and extract the ecvt control block.

The exact algorithm for finding may end up being different. Maybe in addition to having a hashmap, we also should have a tree structure that describes how to get to each control block from a root control block?

[lcarcaramo]

Iinitial Schema 90% complete:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Control Block",
  "description": "CBXP Control Block Schema",
  "type": "object",
  "properties": {
    "version": {
      "description": "CBXP control block schema version",
      "const": 1
    },
    "name": {
      "description": "Control block name",
      "type": "string",
      "minLength": 1,
      "maxLength": 8
    },
    "commonName": {
      "description": "Full control block name",
      "type": "string",
      "minLength": 1
    },
    "description": {
      "description": "Control block description",
      "type": "string"
    },
    "pointedToBy": {
      "description": "List of control blocks that points to this control block",
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "controlBlock": {
      "description": "List of control block fields",
      "type": "array",
      "items": {
        "type": "object",
        "oneOf": [
          {
            "properties": {
              "name": {
                "description": "Name of the control block field",
                "type": "string",
                "minLength": 1,  
                "maxLength": 8
              },
              "description": {
                "description": "Control block field description",
                "type": "string"
              },
              "offset": {
                "description": "Decimal offset to the control block field",
                "type": "integer"
              },
              "length": {
                "description": "Decimal length of the control block field",
                "type": "integer"
              },
              "type": {
                "description": "Control block field type",
                "enum": ["string", "integer", "hex", "bitstring"]
              }
            },
            "required": [
              "name",
              "offset",
              "length",
              "type"
            ],
            "additionalProperties": false
          },
          {
            "properties": {
              "name": {
                "description": "Name of the control block field",
                "type": "string",
                "minLength": 1,  
                "maxLength": 8
              },
              "description": {
                "description": "Control block field description",
                "type": "string"
              },
              "offset": {
                "description": "Decimal offset to the control block field",
                "type": "integer"
              },
              "length": {
                "description": "Decimal length of the control block field",
                "enum": [4, 8]
              },
              "type": {
                "description": "Control block field type",
                "const": "hex"
              },
              "pointsTo": {
                "description": "Control block field that this control block points to",
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "name",
              "offset",
              "length",
              "type",
              "pointsTo"
            ],
            "additionalProperties": false
          }
        ]
      }
    }
  },
  "required": [
    "version",
    "name",
    "commonName",
    "pointedToBy",
    "controlBlock"
  ],
  "additionalProperties": false
}