XMLObject.h

Go to the documentation of this file.

// schematic++ v0.8.0
#ifndef XMLObject_H
#define XMLObject_H
#include <memory>
#include <sstream>
#include <string>
#include <string_view>
#include <unordered_map>
#include <vector>
#include <optional>
#include <functional>
#include <type_traits>
 
#include <xercesc/dom/DOM.hpp>
 
/**
 * @brief The `XML` namespace contains classes representing XML-nodes defined in given XML-schema(s). 
 */
namespace XML {
 
class XMLObject;
 
typedef std::string ClassName;
typedef std::string ElementName;
typedef std::string TextContent;
typedef std::string Namespace;
typedef std::string AttributeName;
 
/**
 * @brief A struct representing the value of an XML-node attribute.
 *
 * The Value struct stores a value and provides implicit conversion and assignment operators
 * to facilitate easy conversion between different types and convenient assignment
 * of values.
 *
 * Example usage:
 * ```
 * Value value;
 * value = "a_string";                  // Assignment using a std::string.
 * value = true;                        // Assignment using a bool.
 * value = 42;                          // Assignment using an int.
 * value = 3.14;                        // Assignment using a double.
 *
 * std::string stringValue = value;     // Implicit conversion to std::string.
 * bool booleanValue = value;           // Implicit conversion to bool.
 * int integerValue = value;            // Implicit conversion to int.
 * double realValue = value;            // Implicit conversion to double.
 * ```
 */
struct Value {
  std::string value;
  operator std::string_view() const { return value; };
  operator std::string() const { return value; };
  operator bool() const { return (value == True); };
  operator int() const { try { return std::stoi(value); } catch(...) { throw std::runtime_error("Cannot convert '" + value + "' to int"); } };
  operator double() const { try { return std::stod(value); } catch(...) { throw std::runtime_error("Cannot convert '" + value + "' to double"); } };
  Value& operator=(const std::string& s) { value = s; return *this; };
  Value& operator=(bool b) { value = (b ? True : False); return *this; };
  Value& operator=(int i) { value = std::to_string(i); return *this; };
  Value& operator=(double d) { value = std::to_string(d); return *this; };
  Value(const std::string& s) : value(s) {};
  Value(bool b) : value(b ? True : False) {};
  Value(int i) : value(std::to_string(i)) {};
  Value(double d) : value(std::to_string(d)) {};
  inline static std::string True = "true";
  inline static std::string False = "false";
};
 
/**
 * @brief A struct representing an attribute of an XML-node.
 *
 * The `Attribute` struct stores information about the namespace, prefix, name, and
 * value of the attribute. 
 */
struct Attribute {
  Namespace xmlns;
  Namespace prefix;
  AttributeName name;
  Value value;
};
 
typedef std::vector<Attribute> Attributes;
typedef std::vector<std::unique_ptr<XMLObject>> Children;
 
/// @brief Template function used to store in factory
template<typename T> XMLObject* createInstance(const Namespace& xmlns, const ClassName& className, const xercesc::DOMElement* element) { return new T(xmlns, className, element, T::defaults); }
 
/// @brief Factory used to create instance depending on element name
typedef std::unordered_map<ElementName, XMLObject* (*)(const Namespace& xmlns, const ClassName& className, const xercesc::DOMElement* element)> Factory;
 
/**
 * @brief Yields `const T` when the deduced `Self` is a const-qualified object, otherwise `T`.
 *
 * Used together with C++23 explicit object parameters ("deducing this") so that a single
 * accessor definition returns const-qualified references from a const object and mutable
 * references from a mutable object. This is needed because child access goes through
 * `std::unique_ptr<XMLObject>`, which does not propagate the object's const-ness to the
 * pointee on its own.
 */
template<typename Self, typename T>
using like_const_t = std::conditional_t<std::is_const_v<std::remove_reference_t<Self>>, const T, T>;
 
 
/**
 * @brief A class representing a node in an XML-tree.
 *
 * The XMLObject class allows to read and store an XML-tree. The root element can be created using
 * - @ref XMLObject::createFromStream(std::istream& xmlStream)
 * - @ref XMLObject::createFromString(const std::string& xmlString)
 * - @ref XMLObject::createFromFile(const std::string& filename)
 *
 * Each object has the following members:
 * - @ref xmlns : refers to the XML namespace
 * - @ref className : refers to the class it belong to
 * - @ref elementName : refers to the name used in the XML
 * - @ref prefix : refers to the namespace prefix in the XML
 * - @ref textContent : textual content of XML element without children
 * - @ref attributes : a list of attributes containing the namespace, prefix, attribute name,
 *   and attribute value
 * - @ref children : a list of child elements
 *
 * Derived classes with dedicated members for attributes and children  are automatically generated by
 * schematic++ according to respective XML schema definition(s).
 *
 * Each XMLObject can be converted to a string using @ref stringify() and printed to an output stream
 * using @ref operator<<(std::ostream& os, const XMLObject* obj) and
 * @ref operator<<(std::ostream& os, const XMLObject& obj) .
 */
class XMLObject {
 
public:
  /**
   * @brief Create an XMLObject from the input stream.
   *
   * @param xmlStream The input stream containing the XML data.
   * @return A pointer to the created XMLObject.
   * @throws std::runtime_error if parsing the XML fails.
   */
    static XMLObject* createFromStream(std::istream& xmlStream);
 
  /**
   * @brief Create an XMLObject from a string representation of XML.
   *
   * @param xmlString The string containing the XML data.
   * @return A pointer to the created XMLObject.
   * @throws std::runtime_error if parsing the XML fails.
   */
    static XMLObject* createFromString(const std::string& xmlString);
 
  /**
   * @brief Create an XMLObject from an XML file.
   *
   * @param filename The path to the XML file.
   * @return A pointer to the created XMLObject.
   * @throws std::runtime_error if loading the file or parsing the XML fails.
   */
    static XMLObject* createFromFile(const std::string& filename);
 
  virtual ~XMLObject() {};
 
protected:
  static XMLObject* createObject(const xercesc::DOMElement* element);
 
template<typename T> friend XMLObject* createInstance(const Namespace& xmlns, const ClassName& className, const xercesc::DOMElement* element);
 
protected:
  XMLObject(const Namespace& xmlns, const ClassName& className, const xercesc::DOMElement* element, const Attributes& defaultAttributes);
 
  inline static Factory factory;
public:
  /// @brief Returns a pointer of type T of the object, const-qualified to match the receiver.
  template<typename T, typename Self> inline auto* is(this Self&& self) {
    return dynamic_cast<like_const_t<Self, T>*>(&self);
  }
 
  /**
   * @brief Attempt to cast the current instance to the specified type T.
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @return  A pointer to the casted object, const-qualified to match the receiver.
   * @throws std::runtime_error if the cast fails.
   */
  template<typename T, typename Self> inline auto* get(this Self&& self) {
    auto* ptr = self.template is<T>();
    if ( ptr == nullptr ) {
      throw std::runtime_error("Failed to cast element '" + self.XMLObject::elementName + "' from class '" + self.XMLObject::className + "' to type '" + typeid(T).name() + "'");
    }
    return ptr;
  }
 
private:
  // T already carries the desired const-ness (baked in by find() below), so this can stay a
  // single const member: child access via unique_ptr yields a mutable XMLObject& regardless.
  template<typename T>
  void findRecursive(std::vector<std::reference_wrapper<T> >& result, const Children& descendants) const
  {
    for (auto& descendant : descendants) {
      if (auto* ptr = descendant->template is<T>()) {
        result.push_back(*ptr);
      }
      findRecursive(result, descendant->children );
    }
  }
 
public:
  /**
   * @brief Find all descendants of type T.
   *
   * @return A vector of references to descendants of type T,
   *         const-qualified to match the receiver.
   */
  template<typename T, typename Self>
  auto find(this Self&& self)
  {
    std::vector<std::reference_wrapper<like_const_t<Self, T> > > result;
    self.findRecursive(result, self.XMLObject::children);
    return result;
  }
 
  Namespace xmlns;
  const ClassName className;
  Namespace prefix;
  ElementName elementName;
 
  TextContent textContent; ///< Textual content of XML element without children
  Children children; ///< Child nodes of the XML element
  Attributes attributes; /// Attributes of the XML element
    inline static const Attributes defaults = {};
 
  /**
   * @brief Convert the XMLObject and its children to a string representation.
   *
   * @return The string representation of the XMLObject.
   */
  std::string stringify() const;
 
  /**
   * @brief Creates formatted string representing the XMLObject including its children.
   *
   * @return A formatted string representing the XMLObject.
   */
  std::string format(std::string indentation = "\t", unsigned int depth = 0) const;
 
  /**
   * @brief Get a required child of type T.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @return A reference to the required child, const-qualified to match the receiver.
   * @throws std::runtime_error if the required child is not found.
   */
  template<typename T, typename Self> auto& getRequiredChild(this Self&& self) {
    for ( auto& child : self.XMLObject::children ) {
      if ( auto* ptr = child->template is<like_const_t<Self, T> >() ) {
        return *ptr;
      }
    }
    throw std::runtime_error("Failed to find required child of type '" + std::string(typeid(T).name()) + "' in element '" + self.XMLObject::elementName + "'");
  }
 
  /**
   * @brief Get an optional child of type T.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @return An optional reference to the optional child (const-qualified to match the
   *         receiver) if found, or `std::nullopt` if the optional child is not found.
   */
  template<typename T, typename Self> auto getOptionalChild(this Self&& self) {
    using E = like_const_t<Self, T>;
    for ( auto& child : self.XMLObject::children ) {
      if ( auto* ptr = child->template is<E>() ) {
        return std::optional< std::reference_wrapper<E> >(*ptr);
      }
    }
    return std::optional< std::reference_wrapper<E> >(std::nullopt);
  }
 
  /**
   * @brief Get all children of type T.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @return A vector of references to the children of type T,
   *         const-qualified to match the receiver.
   */
  template<typename T, typename Self> auto getChildren(this Self&& self) {
    using E = like_const_t<Self, T>;
    std::vector< std::reference_wrapper<E> > result;
    for ( auto& child : self.XMLObject::children ) {
      if ( auto* ptr = child->template is<E>() ) {
        result.push_back(*ptr);
      }
    }
    return result;
  }
 
  /**
   * @brief Get a required child with the specified element name.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @param name The name of the child element without namespace prefix.
   * @return A reference to the required child, const-qualified to match the receiver.
   * @throws std::runtime_error if the required child is not found.
   */
  template<typename Self> auto& getRequiredChildByName(this Self&& self, const ElementName& name) {
    for ( auto& child : self.XMLObject::children ) {
      if ( child->elementName == name ) {
        return static_cast<like_const_t<Self, XMLObject>&>(*child);
      }
    }
    throw std::runtime_error("Failed to get required child '" + name + "' of element '" + self.XMLObject::elementName + "'");
  }
 
  /**
   * @brief Get the optional child with the specified element name.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @param name The name of the child element without namespace prefix.
   * @return An optional reference to the optional child (const-qualified to match the
   *         receiver) if found, or `std::nullopt` if the optional child is not found.
   */
  template<typename Self> auto getOptionalChildByName(this Self&& self, const ElementName& name) {
    using O = like_const_t<Self, XMLObject>;
    for ( auto& child : self.XMLObject::children ) {
      if ( child->elementName == name ) {
        return std::optional< std::reference_wrapper<O> >(static_cast<O&>(*child));
      }
    }
    return std::optional< std::reference_wrapper<O> >(std::nullopt);
  }
 
  /**
   * @brief Get all children with the specified element name.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @param name The name of the child elements without namespace prefix.
   * @return A vector of references to the children with the specified element name,
   *         const-qualified to match the receiver.
   */
  template<typename Self> auto getChildrenByName(this Self&& self, const ElementName& name) {
    using O = like_const_t<Self, XMLObject>;
    std::vector< std::reference_wrapper<O> > result;
    for ( auto& child : self.XMLObject::children ) {
      if ( child->elementName == name ) {
        result.push_back(static_cast<O&>(*child));
      }
    }
    return result;
  }
 
  /**
   * @brief Get a required attribute with the specified attribute name.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @param name The name of the attribute without namespace prefix.
   * @return A reference to the required attribute, const-qualified to match the receiver.
   * @throws std::runtime_error if the required attribute is not found.
   */
  template<typename Self> auto& getRequiredAttributeByName(this Self&& self, const AttributeName& name) {
    for ( auto& attribute : self.XMLObject::attributes ) {
      if ( attribute.name == name ) {
        return attribute;
      }
    }
    throw std::runtime_error("Failed to get required attribute '" + name + "' of element '" + self.XMLObject::elementName + "'");
  }
 
  /**
   * @brief Get an optional attribute with the specified attribute name.
   *
   * @param self The object the call is made on; its const-ness determines that of the result.
   * @param name The name of the attribute without namespace prefix.
   * @return An optional reference to the optional attribute (const-qualified to match the
   *         receiver) if found, or `std::nullopt` if the optional attribute is not found.
   */
  template<typename Self> auto getOptionalAttributeByName(this Self&& self, const AttributeName& name) {
    using A = like_const_t<Self, Attribute>;
    for ( auto& attribute : self.XMLObject::attributes ) {
      if ( attribute.name == name ) {
        return std::optional< std::reference_wrapper<A> >(attribute);
      }
    }
    return std::optional< std::reference_wrapper<A> >(std::nullopt);
  }
 
 
};
 
/// @brief  Allows printing of stringified XML object
std::ostream& operator<<(std::ostream& os, const XMLObject* obj);
/// @brief  Allows printing of stringified XML object
std::ostream& operator<<(std::ostream& os, const XMLObject& obj);
 
} // end namespace XML
 
#endif // XML_H