libxml-cxx/README.md

C++ XML Class Library
=====================

This is a C++ class for reading and writing XML structures.

  - Specify your XML schema in C++ using common C++ syntax, such as shift, dereference, etc.
  - Verify the schema of XML files while they are read from a stream.
  - Map and store your own C++ classes to XML and restore them back.

Rationale
---------

The initial idea was to map C++ data structures to XML files for configuration files that can easily be edited by hand.

This library does not need any kind of C++ code parser or special pre compiler. You can specify a schema entirly in native C++. The schema is verified when XML is read and exceptions are thrown when the XML to be parse is invalid. Exceptions specify exactly the location and reason of the problem, so that the editor of the XML file can easily find and correct the problem.

C++ classes can inherit `xml::Serialize` and become serializable this way. All you need to do is to overwrite one single method, where you declare XML tag names for the class name and for all members.

More rationale: See also [Related Pages](pages.html) in the doxygen project documentation.


Basics
------

Include file:

```cpp
#include <xml-cxx/xml.hxx>
```

Link option:
```
-lxml-cxx
```


Factory with Schema Declaration
-------------------------------

Small example on how to [declare an XML schema](group_freexml.html), you may then use `template.read(is)` to read XML from a stream:

```cpp
// start with root element: <root id="">
xml::Factory template(xml::Node("root").attr("id", xml::optional)
                      // <root> contains any number of <child>
                      <<xml::String("child")
                      // must contain exactly one <other>
                      <<(xml::Node("other").limits(1, 1)
                         // <other> contains min 2 max 4 <text>
                         <<xml::String("text").limits(2, 4)));
```


Using Macros Instead of Literal Text
------------------------------------

If you prefere using [constants](group_xmlConst.html) instead of literal texts, you can declare the node names before you use them:

```cpp
XML_NODE(root);
XML_STRING(child);
[...]
```

```cpp
xml::Factory template(xml::node::root.clone()->attr("id", xml::optional)
                      <<*xml::string::child.clone()
                      [...]
```


Serialize Classes, Join Classes with XML
----------------------------------------

When inheriting from `xml::Serialize`, your class inherits the methods `xml::Serialize::loadXml` and `xml::Serialize::saveXml`. Simply overwrite `xml::Serialize::initXmlMembers` to make your class [serializable](group_serialization.html):

```cpp
class MyClass: public xml::Serialize {
  [...]
  protected:
    void initXmlMembers() {
      className("MyClass");
      persist(i, "i");
      persist(s, "s");
      persist(l, "l");
    }
  private:
    int i;
    std::string s;
    xml::List<std::string> l; // same behaviour as std::list
};
```


Known Limitations
-----------------

  - XML-Comments are only ignored, not read, not stored.
  - Mixed tags and text is not supported. Tags may either contain other tags only (type xml::Node) or text only (type `xml::String`). -> This is intended behaviour!
  - Unlimited recursion is not possible (e.g. `<p><p><p></p></p></p>`;)
  - Exceptions should be optional, best effort otherwise (option "strict")


### Limitations of Serialization

  - Only the following types are intended to be serialized:  
    (It is possible to use other techniques, but that's not recommended)
     - basic C++ types (except pointer)
     - `std::string`
     - classes derieved from `xml::Serialize`
     - most standard containers, but in their xml-form, e.g. `xml::List` instead of `std::list` (`xml::List` inherits `std::list`)
     - Optional values are supported through `xml::Optional`
     - `std::bitset`, `std::priority_queue`, `std::queue` and `std::stack` are not implemented
     - Polymorfic serialisation is not yet implemented