(Updated 2005-09-20) A general explanation of the current and recommended approach for parameterfiles and XML can be found here: The XML file format of the Parameter files
Biggest Problems here:
simth::DeviceManagercan be used to retrieve information from these files. In the factory method, the code block which previously hold all the PropertyList::addProperty() method calls now is replaced by a call to the
simth::DeviceManagerthat will: 1. read the XML file for that Device, and 2. return the defined PropertyList.
The DTD for the devicelist XML files is as follows:
<!-- ............................................................ --> <!-- Typical Invocation: # <!DOCTYPE devicelist PUBLIC # "-//TUHH//Simthetic Devicelist V1.0//EN" # "devicelist.dtd"> Purpose: This DTD was developed to specify the properties of a Device in the simulations system Simthetic. Basically, an XML file adhering to this XML should specify everything about a device that is needed by any GUI. --> <!-- ............................................................ --> <!-- A devicelist file can include many device definitions. The include element (see explanation there) can appear file-wide here, or can appear in particular devices. --> <!ELEMENT devicelist (include*, device*) > <!-- Each device element describes one C++ class. The C++ typename has to appear in the type attribute. The libraryname attribute contains the name of the shared library this device is implemented in. The extends attribute contains the name of the C++ base class, if this device is derived from another one. The abstract attribute is true if the C++ class is an abstract class. --> <!ELEMENT device (include*, description, inputinterfaces?, outputinterfaces?, overriddenproperties?, propertylist?) > <!ATTLIST device name CDATA #REQUIRED type ID #REQUIRED libraryname CDATA #REQUIRED extends CDATA #IMPLIED abstract (true|false) "false"> <!-- The include element should point to the file name that contains the devicelist of the base class. This is just for helping the DeviceManager finding all necessary xml files. --> <!ELEMENT include (#PCDATA)> <!ELEMENT description (#PCDATA)> <!-- The input- and outputinterfaces describe all the interfaces of a device. The attribute "multiplied_by" contains the name of a property, which, if it is set, gives the number of multiple instances of this interface that will actually exist. --> <!ELEMENT inputinterfaces (interface*)> <!ELEMENT outputinterfaces (interface*)> <!ELEMENT interface (description?)> <!ATTLIST interface type CDATA #REQUIRED multiplied_by CDATA #IMPLIED> <!-- Sometimes, a derived class will override properties of the base class by its own values as defined in the C++ code. The names of these properties are listed in this element. --> <!ELEMENT overriddenproperties (value*)> <!-- Most important for the definition of a useful simulation scenario: The propertylist describes all properties that are available in this device. The propertylist defined here is also directly used inside simthetic when the objects are created. --> <!ELEMENT propertylist (property*)> <!ELEMENT property (default?, description, option*)> <!ATTLIST property name CDATA #REQUIRED type (bool | int | unsigned | double | complex | string | list_string | enum | sequencelength | vector_octal_int | vector_double | octal_int ) #REQUIRED empty_default (true|false) "false" obsolete (true|false) "false" grouping CDATA #IMPLIED> <!-- For most property types, the option element describes possible values that particularly make sense for this property (please add appropriate descriptions). But for properties of type 'enum' the semantics are different: For 'enum' properties, the property is only allowed to have values that are mentioned here as option elements. --> <!ELEMENT option (value, description?)> <!-- The default element simply contains a default value for a property. If it is empty and the property attribute empty_default is false, then this property has to be set in the simulation parameter file. --> <!ELEMENT default (#PCDATA)> <!ELEMENT value (#PCDATA)>
This interim approach fortunately does not require any further changed in Simthetic's structure for those devices that are already PropertyList-based. It can therefore be implemented step-by-step.
This is done as follows: The class simth::ParameterDescription reads the XML PropertyList file. The StreamDrivenSimulationSystem will read all PropertyList, populate it with values from the simth::ParameterDescription, and then pass it as argument to the constructor when the object is newly created. The device objects are created through the factory function from simth::DeviceFactory::allDevices().
The current DTD for the XML-based parameter file is the following:
<!-- ............................................................ --> <!-- Typical Invocation: # <!DOCTYPE parameterfile PUBLIC # "-//TUHH//Simthetic Parameterfile V1.0//EN" # "parameterfile.dtd"> Purpose: Proposed DTD for specifying the parameters of one concrete simulation run of the simthetic simulation system. This file is meant for the final solution where every Device of Simthetic is solely configured via a PropertyList. In this final case, this parameter file would simply "fill in the values" for all properties of the used devices. --> <!-- ............................................................ --> <!ELEMENT parameterfile (simulationparameters*)> <!ATTLIST parameterfile xmlns:gui CDATA #FIXED "http://simthetic.sourceforge.net/dtd/gui/1.0"> <!-- Note: The URL for the namespace does not have to point to any valid location. It is simply used to distinguish from possible other namespaces. --> <!ELEMENT simulationparameters (title?, devicevalues?, variables?, devicesvalues, loopvariables, connectionlist, gui:objects?) > <!-- title = (unimplemented) Short descriptive title of this simulation devicevalues = This holds the global properties of the simulation system. The name is (admittantly) misleading, but this is by far the easiest implementation, hence we stick with this element here. variables = A list of string variables (name and value) that can be re-used in the values of other properties by writing $(variable_name). devicesvalues = The list of devices and their properties loopvariables = The list of loop variables and their settings connectionlist = The list of connections between the devices gui:objects = List of additional GUI objects (text, lines) which might be useful for explaining the system. --> <!ELEMENT title (#PCDATA)> <!ELEMENT description (#PCDATA)> <!ELEMENT variables (variabledef*)> <!ELEMENT variabledef (description?, value)> <!ATTLIST variabledef name ID #REQUIRED> <!ELEMENT value (#PCDATA)> <!ELEMENT propertyvalues (propertyvalue*)> <!ELEMENT propertyvalue (value)> <!ATTLIST propertyvalue name CDATA #REQUIRED> <!ELEMENT devicesvalues (devicevalues*)> <!ELEMENT devicevalues (description | propertyvalues | gui:point)*> <!ATTLIST devicevalues id ID #REQUIRED type CDATA #REQUIRED gui:rotation CDATA #IMPLIED> <!ELEMENT loopvariables (loopvariable*)> <!ELEMENT loopvariable (description?, value+)> <!ATTLIST loopvariable id ID #REQUIRED name CDATA #REQUIRED type CDATA #REQUIRED> <!ELEMENT connectionlist (connection*)> <!ELEMENT connection (description?, gui:point*)> <!ATTLIST connection fromid IDREF #REQUIRED fromintf CDATA #REQUIRED toid IDREF #REQUIRED tointf CDATA #REQUIRED active (true|false) "true"> <!ELEMENT gui:point EMPTY> <!ATTLIST gui:point x CDATA #REQUIRED y CDATA #REQUIRED> <!ELEMENT gui:objects (gui:text | gui:polygon)*> <!ELEMENT gui:text (gui:point, value)> <!ATTLIST gui:text gui:rotation CDATA #IMPLIED> <!ELEMENT gui:polygon (gui:point*)>
The object creation itself does already fully support the PropertyList-based object creation.
b. Implement infrastructure for generating a PropertyList from XML file (depends on a.) -- completed.
c. Implement auto-generation of documentation from a device's XML file (depends on a.) (For this XML -> HTML conversion XSLT is probably appropriate?) -- completed for doxygen by propertyheader.xsl stylesheet.
f. Define XML format for simulation parameter XML files. -- almost completed, see parameterfile.dtd.
g. Change simulation setup procedures and functions in StreamdrivenSystem so that PropertyLists are populated with values from XML simulation parameter files. (depends on a, b, c, e, f)
e. Convert existing class code to get their parameters from a PropertyList instead from constructor arguments. about 50% completed.
b. completed (30 hours)
c. completed (10 hours)
d. 10 hours
e. 50 hours
g. completed (8 hours)