XMLObject.h

Go to the documentation of this file.

// schematic++ v0.4.0
#ifndef XMLObject_H
#define XMLObject_H
#include <memory>
#include <sstream>
#include <string>
#include <string_view>
#include <unordered_map>
#include <vector>
#include <optional>
 
#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 = std::to_string("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 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.
  template<typename T> inline T* is() {
    return dynamic_cast<T*>(this);
  }
 
  template<typename T> inline const T* is() const {
    return dynamic_cast<const T*>(this);
  }
 
  /**
   * @brief Attempt to cast the current instance to the specified type T.
   * @return  A pointer to the casted object.
   * @throws std::runtime_error if the cast fails.
   */
  template<typename T> inline T* get() {
    T* ptr = dynamic_cast<T*>(this);
    if ( ptr == nullptr ) {
      throw std::runtime_error("XMLObject: Illegal cast");
    }
    return ptr;
  }
 
  /**
   * @brief Attempt to cast the current instance to the specified type T.
   * @return  A pointer to the casted object.
   * @throws std::runtime_error if the cast fails.
   */
  template<typename T> inline const T* get() const {
    const T* ptr = dynamic_cast<const T*>(this);
    if ( ptr == nullptr ) {
      throw std::runtime_error("XMLObject: Illegal cast");
    }
    return ptr;
  }
 
private:
  template<typename T>
  void findRecursive(std::vector<std::reference_wrapper<T> >& result, const Children& descendants)
  {
    for (auto& descendant : descendants) {
      if (descendant->is<T>()) {
        result.push_back(*descendant->get<T>());
      }
      findRecursive(result, descendant->children );
    }
  }
 
  template<typename T>
  void findRecursive(std::vector<std::reference_wrapper<const T> >& result, const Children& descendants) const
  {
    for (auto& descendant : descendants) {
      if (descendant->is<const T>()) {
        result.push_back(*descendant->get<const T>());
      }
      findRecursive(result, descendant->children );
    }
  }
 
public:
  /**
   * @brief Find all descendants of type T.
   *
   * @return A vector of references to descendants of type T.
   */
  template<typename T>
  std::vector<std::reference_wrapper<T> > find()
  {
    std::vector<std::reference_wrapper<T> > result;
    findRecursive(result, children);
    return result;
  }
 
  /**
   * @brief Find all descendants of type T.
   *
   * @return A vector of const references to descendants of type T.
   */
  template<typename T>
  std::vector<std::reference_wrapper<const T> > find() const
  {
    std::vector<std::reference_wrapper<const T> > result;
    findRecursive(result, 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 formated string representing the XMLObject including its children.
   *
   * @return A formated string representing the XMLObject.
   */
  std::string format(std::string indentation = "\t", unsigned int depth = 0) const;
 
  /**
   * @brief Get a required child of type T.
   *
   * @return A reference to the required child.
   * @throws std::runtime_error if the required child is not found.
   */
  template<typename T> T& getRequiredChild() {
    for ( auto& child : children ) {
      if ( child->is<T>() ) {
        return *child->get<T>();
      }
    }
    throw std::runtime_error("Failed to get required child of element '" + elementName + "'");
  }
 
  /**
   * @brief Get an optional child of type T.
   *
   * @return An optional containing a reference to the optional child if found,
   *         or `std::nullopt` if the optional child is not found.
   */
  template<typename T> std::optional< std::reference_wrapper<T> > getOptionalChild() {
    for ( auto& child : children ) {
      if ( child->is<T>() ) {
        return *child->get<T>();
      }
    }
    return std::nullopt;
  }
 
  /**
   * @brief Get all children of type T.
   *
   * @return A vector of references to the children of type T.
   */
  template<typename T> std::vector< std::reference_wrapper<T> > getChildren() {
    std::vector< std::reference_wrapper<T> > result;
    for ( auto& child : children ) {
      if ( child->is<T>() ) {
        result.push_back(*child->get<T>());
      }
    }
    return result;
  }
 
  /**
   * @brief Get a required child with the specified element name.
   *
   * @param elementName The name of the child element without namespace prefix.
   * @return A reference to the required child.
   * @throws std::runtime_error if the required child is not found.
   */
  XMLObject& getRequiredChildByName(const ElementName& elementName);
 
  /**
   * @brief Get the optional child with the specified element name.
   *
   * @param elementName The name of the child element without namespace prefix.
   * @return An optional containing a reference to the optional child if found,
   *         or `std::nullopt` if the optional child is not found.
   */
  std::optional< std::reference_wrapper<XMLObject> > getOptionalChildByName(const ElementName& elementName);
 
  /**
   * @brief Get all children with the specified element name.
   *
   * @param elementName The name of the child elements without namespace prefix.
   * @return A vector of references to the children with the specified element name.
   */
  std::vector< std::reference_wrapper<XMLObject> > getChildrenByName(const ElementName& elementName);
 
  /**
   * @brief Get a required attribute with the specified attribute name.
   *
   * @param attributeName The name of the attribute without namespace prefix.
   * @return A reference to the required attribute.
   * @throws std::runtime_error if the required attribute is not found.
   */
  Attribute& getRequiredAttributeByName(const AttributeName& attributeName);
 
  /**
   * @brief Get an optional attribute with the specified attribute name.
   *
   * @param attributeName The name of the attribute without namespace prefix.
   * @return An optional containing a reference to the optional attribute if found,
   *         or `std::nullopt` if the optional attribute is not found.
   */
  std::optional< std::reference_wrapper<Attribute> > getOptionalAttributeByName(const AttributeName& attributeName);
 
 
};
 
/// @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