XML Type Support - liuli-neko/NekoProtoTools GitHub Wiki

This page details the specific C++ types supported for deserialization (parsing XML into C++ objects) by the NekoProto::XmlSerializer and describes the expected XML structure.

❗ Important Limitation: Currently, the XmlSerializer only supports deserialization (input). It can parse XML data and populate your C++ objects, but it cannot serialize C++ objects into an XML format.

Related Concepts:

• Serializers Interface|Serializers-Interface
• Supported Types Overview|Supported-Types-Overview

To use the XmlSerializer, ensure you have enabled the XML feature (enable_xml = true) in your xmake.lua configuration, which adds a dependency on the RapidXML library. See Installation.

Include the core header <nekoproto/proto/xml_serializer.hpp> and the necessary type support headers (<nekoproto/proto/types/...>) for the standard library types used in your data structures.

The XmlSerializer generally expects XML data to map to your C++ structures in the following way:

• Struct/Class: Corresponds to an XML element.
• Members: Corresponds to child elements within the parent struct/class element. The name of the child element is expected to match the name of the C++ member variable listed in the NEKO_SERIALIZER macro.
• Basic Types: The text content of an element is parsed into the corresponding C++ basic type (int, float, string, bool).
• Containers (e.g., vector, list): Often represented by a parent element (matching the member name) containing multiple child elements (often with a generic name like "item" or matching the member name repeatedly) for each item in the container.
• Maps: Typically represented as a sequence of key-value pairs, often using nested elements like <entry><key>...</key><value>...</value></entry>.

Note: The exact expected structure can be sensitive. The deserializer relies heavily on matching element names declared in NEKO_SERIALIZER to element names in the XML document.

The following table outlines the C++ types supported for deserialization and the expected XML structure fragment:

C++ Type	Supported (Input)	Expected XML Element Content / Structure	Required Type Header (nekoproto/proto/types/...)	Notes
bool	✅	<memberName>true</memberName> or <memberName>1</memberName>	(builtin)	Parses "true", "1" as true; others likely false. Case-sensitive? (TBD)
int8_t .. uint64_t	✅	<memberName>123</memberName>	(builtin)	Parses standard integer text.
float, double	✅	<memberName>123.45</memberName>	(builtin)	Parses standard floating-point text.
std::string	✅	<memberName>Some Text</memberName>	string.hpp	Uses the element's text content.
enum class/enum	✅	<memberName>EnumValueAsString</memberName> or <memberName>IntVal</memberName>	enum.hpp	Attempts to parse string first, then integer.
std::vector<T> (and List, Deque)	✅	<memberName><item>...</item><item>...</item></memberName>	vector.hpp, etc.	Expects child elements (e.g., "item") for each value T.
std::array<T, N>	✅	<memberName><item>...</item> ... </memberName> (N items)	array.hpp	Expects exactly N child items.
std::set<T> (and Multisets)	✅	<memberName><item>...</item><item>...</item></memberName>	set.hpp, etc.	Expects child elements for each value T.
std::any	❌	-	-	Not supported.
Attributes	❌	(Not typically parsed directly into members)	-	Deserialization primarily focuses on element content/structure.

(builtin): Support provided directly by <nekoproto/proto/types/types.hpp>.

• Deserialization Only: As stated, you can only parse XML into C++ objects, not create XML from them with this serializer.
• Name Matching: The deserializer relies heavily on the names used in the NEKO_SERIALIZER macro matching the element names in the XML document.
• Structure Sensitivity: The expected nesting and structure (e.g., <item> for vectors, <entry>/<key>/<value> for maps) must generally be followed for successful parsing. The exact required structure might require inspection of the XmlSerializer implementation or experimentation.
• Error Handling: Robustness against malformed XML may vary. Parsing might fail if the structure deviates significantly from expectations.
• XML Attributes: Direct mapping of XML attributes to C++ members is generally not supported by this serializer; it primarily works with element names and text content.

While limited to input, the XmlSerializer provides a way to integrate NekoProtoTools with systems or configurations that utilize the XML format, leveraging the same NEKO_SERIALIZER definitions used for other formats. Contributions to add XML serialization capabilities would be welcome!