wiki:DataElementDesign

(this page should probably be referenced from future command&control and cc-channel documentation pages)

Data format

Data is represented in a simple format that somewhat represents JSON. This format is directly usable in Python scripts, and the C++ API has a parser in the function Element::create(stringstream& in)

EBNF grammar

<syntax> = <element> ;

<element> = <map> | <list> | <string> | <integer> | <real> | <boolean> ;

<map> = "{" , <map_element> , "}" ; <map_element> = <string> , ":" , <element> , [ "," , <map_element> ] ;

<list> = [ <list_element> ] ; <list_element> = <element> [ "," , <list_element> ] ;

<string> = '"' , { all characters - '"' }, '"' ;

<integer> = [ '-' ] , { digit }

<real> = [ '-' ] , { digit } , '.' , { digit }

<boolean> = "True" | "False"

Example

{
  "some data": "Hello",
  "a number": 123,
  "a list": [ "a", True, 23, 3.1415 ]
}

Data Definition format

Each component contains a file containing a data definition format. This definition is itself in the data format as shown above, and defines the data model used by the component for configuration, and direct commands it accepts. The first is used by configuration tools and the configuration managers to verify whether new configuration data is valid and acceptable by the module.

Format

{ "data_specification":
	{
	"module_name": "<name>",
	"config_data": [ <data_item_spec> ],
	"commands": [ <command_spec> ]
	}
}

data_item_spec:
{
  "item_name":		"<name>",
  "item_type":		"<type>",	// int, double, bool, string
					// list, or map (or any?)
  "optional":		<true|false>,
  "default_value":	<Element>	// element type depending on
					// item type
	                                // mandatory if "optional"
					// is false
  "map_item_spec":	[ <data_item_spec> ],	// only for maps
  "list_item_spec":	<data_item_spec>	// only for lists
}

command_spec:
{
  "command_name":	"<name>",
  "command_args": [ <data_item_spec> ]
}

Example

This is the current version of the parkinglot.spec file. The print_message command is an example of a supported command, that has no real use apart from commands. It is included because the parkinglot currently has no direct commands.

{
  "data_specification": {
    "module_name": "ParkingLot",
    "config_data": [
      {
        "item_name": "port",
        "item_type": "integer",
        "item_optional": false,
        "item_default": 5300
      },
      {
        "item_name": "zones",
        "item_type": "list",
        "item_optional": false,
        "item_default": [ ],
        "list_item_spec": {
          "item_name": "zone_name",
          "item_type": "string",
          "item_optional": false,
          "item_default": ""
        }
      },
      {
        "item_name": "a_records",
        "item_type": "list",
        "item_optional": false,
        "item_default": [ "127.0.0.1" ],
        "list_item_spec": {
          "item_name": "address",
          "item_type": "string",
          "item_optional": false,
          "item_default": ""
        }
      },
      {
        "item_name": "aaaa_records",
        "item_type": "list",
        "item_optional": false,
        "item_default": [ "::1" ],
        "list_item_spec": {
          "item_name": "address",
          "item_type": "string",
          "item_optional": false,
          "item_default": ""
        }
      },
      {
        "item_name": "ns_records",
        "item_type": "list",
        "item_optional": false,
        "item_default": [ "ns1.parking.example", "ns2.parking.example" ],
        "list_item_spec": {
          "item_name": "address",
          "item_type": "string",
          "item_optional": false,
          "item_default": ""
        }
      }
    ],
    "commands": [
      {
        "command_name": "print_message",
        "command_description": "Print the given message to stdout",
        "command_args": [ {
          "item_name": "message",
          "item_type": "string",
          "item_optional": False,
          "item_default": ""
        } ]
      }
    ]
  }
}

Python API

C++ API

  • Data Elements
  • Data Definition
Last modified 8 years ago Last modified on Jan 20, 2010, 8:48:19 AM