XML¶
For XML support, you must also include the header <rfl/xml.hpp> and include the pugixml library.
Furthermore, when compiling reflect-cpp, you need to pass -DREFLECTCPP_XML=ON to cmake. If you are using vcpkg or Conan, there
should be an appropriate feature (vcpkg) or option (Conan) that will abstract this away for you.
Simple example¶
Consider the following example:
using Age = rfl::Validator<unsigned int, rfl::Minimum<0>, rfl::Maximum<130>>;
struct Person {
rfl::Rename<"firstName", std::string> first_name;
rfl::Rename<"lastName", std::string> last_name = "Simpson";
std::string town = "Springfield";
rfl::Timestamp<"%Y-%m-%d"> birthday;
Age age;
rfl::Email email;
std::vector<Person> child;
};
const auto bart = Person{.first_name = "Bart",
.birthday = "1987-04-19",
.age = 10,
.email = "[email protected]"};
const auto lisa = Person{.first_name = "Lisa",
.birthday = "1987-04-19",
.age = 8,
.email = "[email protected]"};
const auto maggie = Person{.first_name = "Maggie",
.birthday = "1987-04-19",
.age = 0,
.email = "[email protected]"};
const auto homer = Person{.first_name = "Homer",
.birthday = "1987-04-19",
.age = 45,
.email = "[email protected]",
.child = std::vector<Person>({bart, lisa, maggie})};
rfl::xml::write(homer);
This will result in the following XML string:
<?xml version="1.0" encoding="UTF-8"?>
<Person>
<firstName>Homer</firstName>
<lastName>Simpson</lastName>
<town>Springfield</town>
<birthday>1987-04-19</birthday>
<age>45</age>
<email>[email protected]</email>
<child>
<firstName>Bart</firstName>
<lastName>Simpson</lastName>
<town>Springfield</town>
<birthday>1987-04-19</birthday>
<age>10</age>
<email>[email protected]</email>
</child>
<child>
<firstName>Lisa</firstName>
<lastName>Simpson</lastName>
<town>Springfield</town>
<birthday>1987-04-19</birthday>
<age>8</age>
<email>[email protected]</email>
</child>
<child>
<firstName>Maggie</firstName>
<lastName>Simpson</lastName>
<town>Springfield</town>
<birthday>1987-04-19</birthday>
<age>0</age>
<email>[email protected]</email>
</child>
</Person>
Unlike most other formats, XML distinguishes between attributes and nodes. If you want something to be displayed as an attribute, you must mark it as such:
using Age = rfl::Validator<unsigned int, rfl::Minimum<0>, rfl::Maximum<130>>;
struct Person {
rfl::Rename<"firstName", rfl::Attribute<std::string>> first_name;
rfl::Rename<"lastName", rfl::Attribute<std::string>> last_name = "Simpson";
rfl::Attribute<std::string> town = "Springfield";
rfl::Attribute<rfl::Timestamp<"%Y-%m-%d">> birthday;
rfl::Attribute<Age> age;
rfl::Attribute<rfl::Email> email;
std::vector<Person> child;
};
const auto bart = Person{.first_name = "Bart",
.birthday = "1987-04-19",
.age = 10,
.email = "[email protected]"};
const auto lisa = Person{.first_name = "Lisa",
.birthday = "1987-04-19",
.age = 8,
.email = "[email protected]"};
const auto maggie = Person{.first_name = "Maggie",
.birthday = "1987-04-19",
.age = 0,
.email = "[email protected]"};
const auto homer = Person{.first_name = "Homer",
.birthday = "1987-04-19",
.age = 45,
.email = "[email protected]",
.child = std::vector<Person>({bart, lisa, maggie})};
rfl::xml::write(homer);
This will result in the following XML string:
<?xml version="1.0" encoding="UTF-8"?>
<Person firstName="Homer" lastName="Simpson" town="Springfield" birthday="1987-04-19" age="45" email="[email protected]">
<child firstName="Bart" lastName="Simpson" town="Springfield" birthday="1987-04-19" age="10" email="[email protected]" />
<child firstName="Lisa" lastName="Simpson" town="Springfield" birthday="1987-04-19" age="8" email="[email protected]" />
<child firstName="Maggie" lastName="Simpson" town="Springfield" birthday="1987-04-19" age="0" email="[email protected]" />
</Person>
Note that only boolean values, string values, integral values or floating point values can be represented as attributes.
There also is a special field name called xml_content to be used when you want a value directly inserted into the content.
Again, only boolean values, string values, integral values or floating point values can be represented this way:
struct Person {
std::string xml_content;
rfl::Attribute<std::string> town = "Springfield";
rfl::Attribute<rfl::Timestamp<"%Y-%m-%d">> birthday;
rfl::Attribute<rfl::Email> email;
std::vector<Person> child;
};
const auto bart = Person{.xml_content = "Bart Simpson",
.birthday = "1987-04-19",
.email = "[email protected]"};
const auto lisa = Person{.xml_content = "Lisa Simpson",
.birthday = "1987-04-19",
.email = "[email protected]"};
const auto maggie = Person{.xml_content = "Maggie Simpson",
.birthday = "1987-04-19",
.email = "[email protected]"};
const auto homer = Person{.xml_content = "Homer Simpson",
.birthday = "1987-04-19",
.email = "[email protected]",
.child = std::vector<Person>({bart, lisa, maggie})};
rfl::xml::write(homer);
This will result in the following XML string:
<?xml version="1.0" encoding="UTF-8"?>
<Person town="Springfield" birthday="1987-04-19" email="[email protected]">Homer Simpson<child town="Springfield" birthday="1987-04-19" email="[email protected]">Bart Simpson</child>
<child town="Springfield" birthday="1987-04-19" email="[email protected]">Lisa Simpson</child>
<child town="Springfield" birthday="1987-04-19" email="[email protected]">Maggie Simpson</child>
</Person>
Limitations of the XML format¶
There must be exactly one root node¶
The XML format requires that there must be exactly one root node. Other formats, like JSON, allow you to have an array as the root element. XML disallows that.
The root node must have a name¶
As you may have noticed, reflect-cpp uses the names of fields as the names of the XML nodes or attributes. However, the root node does not have a field name associated with it. So reflect-cpp will use the name of the struct as the name of the root node. This is a problem when the root node is a template parameter, because the name of the root node cannot contain "<" or ">".
In this case, you can explicitly set a root node name like this:
rfl::xml::write<"NameOfTheRootNode">(homer);
No nested arrays¶
Unlike JSON, XML doesn't have an explicit concept of arrays. Array-like structures are represented by simply writing the same field over and over again (i.e. Homer's children in the examples above).
This also implies that something like this cannot be properly represented in XML:
struct Person {
std::string name;
std::vector<std::vector<Person>> child;
};
There is no way to represent a vector of vectors in XML. It's a limitation of the format.
Integers cannot be tags¶
In JSON, it is possible to represent a map with integers as keys like this:
std::map<int, std::string> homer;
homer[1] = "Homer";
homer[2] = "Simpson";
rfl::json::write(homer);
This will be represented as follows:
{"1":"Homer","2":"Simpson"}
In XML, this is impossible. The XML standard requires that the tag must not start with an integer.
Loading and saving¶
You can also load and save to disc using a very similar syntax:
const rfl::Result<Person> result = rfl::xml::load<Person>("/path/to/file.xml");
const auto person = Person{...};
rfl::xml::save("/path/to/file.xml", person);