19
XML Class Generator for C++

This chapter contains the following sections:

Overview of the XML Class Generator for C++

The XML Class Generator takes a Document Type Definition (DTD) or XML Schema and generates classes for each defined element. Those classes are then used in a C++ program to construct XML documents conforming to the DTD.

Input

Input is an XML document containing a DTD, an external DTD, or an XML Schema. IF a complete XML document is provided, the document body itself is ignored; only the DTD is relevant, though the dummy document must conform to the DTD.

Output

Output is a pair of C++ source files, .cpp and .h, named after the DTD if a complete XML document is provided. For an external DTD or Schema, the name of the generated files must be provided. Constructors are provided for each class (element) that allow an object to be created in two different ways: initially empty, then adding the children or data after the initial creation, or created with the initial full set of children or initial data. A method is provided for #PCDATA (and Mixed) elements to set the data and, when appropriate, set an element's attributes.

Relevant XML Standards

The W3C recommendation for Extensible Markup Language (XML) 1.0

The W3C recommendation for Document Object Model Level 1 1.0

The W3C proposed recommendation for Namespaces in XML

The Simple API for XML (SAX) 1.0

Sample Usage

The standalone parser may be called as an executable by invoking

     bin/xmlcg like
     xmlcg [flags] <XML document>

Table 19-1 Optional Flags

Flag	Command	Description
-d	directory	Specify output directory; default is current directory
-e	encoding	Specify default input file encoding
-h	help	show this usage help

XMLClassGenerator Class

Description of XMLClassGenerator

This class contains the methods for generating classes based on a DTD or Schema.

Methods of XMLClassGenerator

generate()

Description

Generates classes for a given DTD or Schema. Returns error code, or 0 on success. The options are described in the following table.

Syntax	Description
uword XMLClassGenerator::generate( DocumentType *dtd, DOMString outdir);	Generates classes for the given DTD. Two files are created in the output directory `outdir` (or in the current directory if `outdir` is `NULL`): `DTDname.h` and `DTDname.cpp`, both named after the DTD. One class is generated for each defined element in the DTD.
uword XMLClassGenerator::generate( Schema *schema, DOMString name, DOMString outdir);	Generates classes for the given Schema. Two files are created in the output directory `outdir` (or in the correct directory if `outdir` is `NULL`): `name.h` and `name.cpp`. One class is generated for each element in the Schema.

Parameter	Description
dtd	Classes will be generated for elements of this DTD.
outdir	Directory where output files will be placed.
schema	Classes will be generated for elements of this Schema.
name	Name for generated files and enclosing C++ namespace.

generated Class (for DTD)

Description of generated

A generated class is produced for each element defined in the DTD, with the same name as the element.

If an element (or attribute) name cannot be used directly as a C++ identifier, it is mapped to a valid identifier by converting it to the compiler character set (ASCII or EBCDIC) and then replacing unmappable characters with the two-letter hex for their code points. For example, the element name "Curaçao" maps to "Curacao". If the remapped name is already used, digits are appended to the end to make it unique; for example, "Curacao0", and so on. Note that elements and attributes created by the generated classes will have the original names. The remapping only applies to the generated code itself, so that it will be syntactically correct in C++. It does not apply to the XML elements and data that are constructed by the these elements.

There are two styles of creation: making an empty element and then adding the children one at a time, or constructing the element with initial data or children. For example, given the element declaration:

<!ELEMENT B (#PCDATA | F)*>

The following constructors will be provided:

Constructor	Description
B(Document *doc);	makes an empty element with no children
B(Document *doc, String data);	initializes it with PCDATA
(Document doc, F theF);	initialized with a single child node of element F

An element like B, that may contain PCDATA, can also add the data post-construction using:

     void addData( Document *doc, String data);

The following usages are equivalent:

     b = new B("data");

and

     b = new B();
     b->addData("data");

Similarly, the following are also equivalent:

     f=newF(...);
     b=new B(f);

and

     f=newF(...);
     b=newE();
     b->addNode(F);

The presence of modifiers '?' (optional),'*' (zero or more), and '+' (one or more) is ignored when forming the constructors. For example, for the element:

     <!ELEMENT Sample (A* | (B, (C? | (D, E)*)) | F)+>

the following constructors are made as if the modifiers were not present:

     Sample(Document *doc);
     Sample(Document *doc, A *theA);
     Sample(Document *doc, B *theB, C *theC);
     Sample(Document *doc, B *theB, D *theD, E *theE);
     Sample(Document *doc, F *theF);

If the desired final elements cannot be made using one of the forms that take initial children, an empty element must be declared first so nodes can be added as needed with addNode().

For each attribute for an element, a method is provided to set its value, named setattrname(). For example, for the element declaration,

     <!ELEMENT D (#PCDATA)>
     <!ATTLIST D foo CDATA #REQUIRED>

class D will have the method

      Attr* setfoo(String value);

Note: The constructed element is not tested for validity as it is being made. The user must explicitly call the XMLParser's validate() method on the final element.

Methods of generated

Table 19-2 Summary of Methods of generated (for DTD)

Method	Description
class()	Constructor.
addData()	Adds PCDATA to the element.
addNode()	Adds a node to the element.
setattribute()	Sets one of the element's attributes.

class()

Description

Class constructor. Constructs an element which will belong to the given document. See the example given at the beginning of this section. The options are described in the following table.

Syntax	Description
class( Document *doc);	Makes the element with no children; requires use `addData()` and `addNode()` as appropriate to fill it out.
class( Document *doc, ...);	Used to provide initial data or children, the exact choices of which depend on the element definition.

Parameter	Description
doc	Document to which the element belongs.
...	Varying arguments, depending on the element definition.

addData()

Description

Adds data to the element by appending to it a PCDATA subnode with the given value. If multiple addData calls are made, the node will have multiple PCDATA subnodes, which should be normalized when construction is finished using XMLParser::normalize().

Syntax

void addData( Document *doc,
              String data);

Parameter	Description
doc	Document to which the element belongs.
data	Data to be added.

addNode()

Description

Adds/appends a child node to the element. No effort is made to validate the resulting element structure at this time; it is the user's responsibility to form the element properly, which may be verified with XMLParser::validate().

Prototype

void addNode( node thenode);

Parameter	Description
thenode	Node to be added.

setattribute()

Description

Sets the element's attribute with the given value. One method is provided for each attribute, named after the attribute as setattribute(). Returns the created attribute.

Prototype

Attr* setattribute( String value);

Parameter	Description
value	The attribute's value.

generated Class (for Schema)

Description of generated

All generated classes are enclosed in a C++ namespace with the same name as the generated files; for example, Foo.cpp will contain namespace Foo.

A generated class is produced for each element in the Schema. It has the same name as the element, except for local elements which have the parent element's name prefixed.

If an element (or attribute) name cannot be used directly as a C++ identifier, it is mapped to a valid identifier by converting it to the compiler character set (ASCII or EBCDIC) and then replacing unmappable characters with the two-letter hex for their code points. For example, the element name "Curaçao" maps to "Curacao". If the remapped name is already used, digits are appended to the end to make it unique; for example, "Curacao0", and so on. Note that elements and attributes created by the generated classes will have the original names. The remapping only applies to the generated code itself, so that it will be syntactically correct in C++, not to the XML elements and data which are constructed by them.

There are two styles of creation: making an empty element and then adding the children one at a time, or constructing the element with initial data or children. For example, the following constructors will be provided given the element declaration:

     <element name="foo">
        <complexType content="mixed">
           <element ref="thing" minOccurs="0"/>
           <attribute name="bar" use="required" type="int"/>
        </complexType>
     </element>

the following constructors will be provided:

     foo(Document *doc); 
          // Makes an empty element with no children

     foo(Document *doc, DOMString s);
          // Initializes it with PCDATA

     foo(Document *doc, Que::thing *the_thing);
          // Initialized with a single child node of element thing

An element like foo that may contain PCDATA is also given a method to add the data post-construction:

     void foo::addData(Document *doc, DQMString s);

Each possible child element of foo also is given an "assembler":

     void foo::addNode(Queue::thing *the_thing);

The following usages are equivalent:

     f = new Queue::foo("data");

and

     f = new Queue::foo();
     f->addData("data");

Similarly, the following are also equivalent:

     f = new Queue::foo(...);
     t = new Queue::thing(...);

and

     f = new Queue::foo(...);
     t = new Queue::thing(...);
     f->addNode(t);

Not all possible combinations of initial elements are provided constructors, especially considering variable occurrences. If no constructor is appropriate, the element must be built-up. For example, consider the element definition

     <element name="map-data">
        <complexType content="mixed">
           <element ref="aq:item" minOccurs="0" maxOccurs="*"/>
        </complexType>
     </element>

A map-data element may contain any number of aq:item children. In such cases, a constructor is provided which allows only one occurrence; additional occurrences must be assembled, like the following example which needs four:

     md = new Queue::map~data(doc, i1);
     md->addNode(i2);
     md->addNode(i3); 
     md->addNode(i4);

For each attribute of an element, a method is provided to set its value, named

set_attrname(). For example, for the element declaration,

     <element name="client-operation">
        <complexType content="mixed">
           <element name="txid" type="string" minOccurs="0"/>
           <attribute name="opcode" use="required" type="aq:opcode_type"/>
        </complexType> 
     </element>

a method would be provided to set the attribute:

     Attr* client_operation::set_opcode(DOMString s);

Note: The constructed element is not tested for validity as it is being made. The user must explicitly call the XMLSchema's validate method on the final element.

Methods of generated

Table 19-3 Summary of Methods of generated (for Schema)

Method	Description
class()	Class constructor.
addData()	Adds PCDATA to the element
addNode()	Adds a node to the element
set_attribute()	Sets one of the element's attributes

class()

Description

Constructs an element which will belong to the given document. See the example given at the beginning of this section. The options are described in the following table.

Syntax	Description
class( Document *doc);	Makes the element with no children; requires use `addData()` and `addNode()` as appropriate to fill it out.
class( Document *doc, ...);	Used to provide initial data or children, the exact choices of which depend on the element definition.

Parameter	Description
doc	Document to which the element belongs.
...	Varying arguments, depending on the element definition.

addData()

Description

Syntax

void addData( Document *doc,

                    String data);

Parameter	Description
doc	Document to which the element belongs.
data	Data to be added

addNode()

Description

Syntax

void addNode( node the_node);

Parameter	Description
the_node	The node to be added.

set_attribute()

Description

Sets the element's attribute with the given value. Returns the created attribute. One method is provided for each attribute, named after the attribute as set_attribute().

Syntax

Attr* set_attribute( String value);

19 XML Class Generator for C++

Overview of the XML Class Generator for C++

Input

Output

Relevant XML Standards

Sample Usage

Table 19-1 Optional Flags

XMLClassGenerator Class

Description of XMLClassGenerator

Methods of XMLClassGenerator

generate()

Description

generated Class (for DTD)

Description of generated

Methods of generated

Table 19-2 Summary of Methods of generated (for DTD)

class()

Description

addData()

Description

Syntax

addNode()

Description

Prototype

setattribute()

Description

Prototype

generated Class (for Schema)

Description of generated

Methods of generated

Table 19-3 Summary of Methods of generated (for Schema)

class()

Description

addData()

Description

Syntax

addNode()

Description

Syntax

set_attribute()

Description

Syntax

19
XML Class Generator for C++