Scoped XML: A quick way to write XML (write only)
[XML]

This module contains classes to write an XML document following a "open on create - close on destroy" idiom. More...

Classes
class	CLAM::XmlFragment
	This is the first scoped object you should create for a XML fragment. More...
class	CLAM::XmlContent
	An scoped XML writer object inserting plain content to the current XML level. More...
class	CLAM::XmlElement
	An scoped XML writer object that opens a new element on construction and closes it on destruction. More...
class	CLAM::XmlAttribute
	An scoped XML writer object that inserts on construction an XML atribute to the last open XML element. More...

---

Detailed Description

This module contains classes to write an XML document following a "open on create - close on destroy" idiom.

That means that by simply creating an element object you are opening a tag and when the element object goes out of scope the element is automatically closed. The C++ stack frame managing rules assure that the XML will be well balanced.

This system only provides writing XML and has no mapping to CLAM data as CLAM::XmlStorage has. See the XmlStorage way .

Two aproaches can be convined to generate XML with scoped objects:

1. Using function calls: Define a function call that will write an element and will call other functions to write children elements.
2. Using local scopes: Local scopes allows to define an stack frame without calling a new function. So you can write code like that:

    XmlFragment(std::cout);
    { XmlElement element("Configuration");
           { XmlElement element("Parameter");
                   XmlAttribute attrib("name","SpectralHeight");
                   XmlContent content(1276.3);
           }
           { XmlElement element("Parameter");
                   XmlAttribute attrib("name","Filename");
                   XmlContent content("Voice.wav");
           }
    }
   

The first scoped object must be a top level one like XmlFragment (XmlDocument will be available soon). That element defines the target ostream where the XML will be written.

Note:

Use ostringstream if you want to write XML to a string.

Remarks:

You can build as many XmlFragments and XmlDocuments as you want along your program but never having two of them instanciated at the same time, since scoped objects find the current TopLevel scoped object for the current XML writting context. Be also careful on different threads writting XML scopedly.

Warning:

Be sure to create local variables and not temporary elements, since the following bad-friend code:

 // Wrong code
 XmlElement("MyTag");
 {
        XmlElement("Child");
        XmlContent("hello");
 }

will close the tag inmediatelly writting <MyTag /><Child />hello instead the probably intended: <MyTag><Child>hello</Child></MyTag> the correct code should be:

 XmlElement element("MyTag");
 {
        XmlElement element("Child");
        XmlContent content("hello");
 }

Those classes are useful when are local stack variables. If you create instances with new you loose the autobalancing feature.

Bug:

Special chars are not escaped in attributes and plain content.