XML.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/XML.h - Released 2024-06-18T15:48:54Z
// ----------------------------------------------------------------------------
// This file is part of the PixInsight Class Library (PCL).
// PCL is a multiplatform C++ framework for development of PixInsight modules.
//
// Copyright (c) 2003-2024 Pleiades Astrophoto S.L. All Rights Reserved.
//
// Redistribution and use in both source and binary forms, with or without
// modification, is permitted provided that the following conditions are met:
//
// 1. All redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. All redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names
//    of their contributors, may be used to endorse or promote products derived
//    from this software without specific prior written permission. For written
//    permission, please contact info@pixinsight.com.
//
// 4. All products derived from this software, in any form whatsoever, must
//    reproduce the following acknowledgment in the end-user documentation
//    and/or other materials provided with the product:
//
//    "This product is based on software from the PixInsight project, developed
//    by Pleiades Astrophoto and its contributors (https://pixinsight.com/)."
//
//    Alternatively, if that is where third-party acknowledgments normally
//    appear, this acknowledgment must be reproduced in the product itself.
//
// THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
// INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
// DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
// ----------------------------------------------------------------------------
 
#ifndef __PCL_XML_h
#define __PCL_XML_h
 
 
#include <pcl/Defs.h>
 
#include <pcl/Exception.h>
#include <pcl/ReferenceArray.h>
#include <pcl/String.h>
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLDocument;
class PCL_CLASS XMLElement;
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XML
{
public:
 
   XML() = delete;
 
   XML( const XML& ) = delete;
 
   XML& operator =( const XML& ) = delete;
 
   ~XML() = delete;
 
   template <typename T>
   static bool IsWhiteSpaceChar( T c )
   {
      return c == 0x20 || c == 9;
   }
 
   template <typename T>
   static bool IsLineBreakChar( T c )
   {
      return c == 0x0A || c == 0x0D;
   }
 
   template <typename T>
   static bool IsSpaceChar( T c )
   {
      return IsWhiteSpaceChar( c ) || IsLineBreakChar( c );
   }
 
   template <typename T>
   static bool IsNameStartChar( T c )
   {
      return c >= T( 'a' ) && c <= T( 'z' )
         ||  c >= T( 'A' ) && c <= T( 'Z' )
         ||  c == T( '_' )
         ||  c == T( ':' )
         ||  c >= 0xC0    && c <= 0xD6
         ||  c >= 0xD8    && c <= 0xF6
         ||  c >= 0xF8    && c <= 0x2FF
         ||  c >= 0x370   && c <= 0x37D
         ||  c >= 0x37F   && c <= 0x1FFF
         ||  c >= 0x200C  && c <= 0x200D
         ||  c >= 0x2070  && c <= 0x218F
         ||  c >= 0x2C00  && c <= 0x2FEF
         ||  c >= 0x3001  && c <= 0xD7FF
         ||  c >= 0xF900  && c <= 0xFDCF
         ||  c >= 0xFDF0  && c <= 0xFFFD
         ||  uint32( c ) >= 0x10000 && uint32( c ) <= 0xEFFFF;
   }
 
   template <typename T>
   static bool IsNameChar( T c )
   {
      return IsNameStartChar( c )
         ||  c >= T( '0' ) && c <= T( '9' )
         ||  c == T( '-' )
         ||  c == T( '.' )
         ||  c == 0xB7
         ||  c >= 0x0300  && c <= 0x036F
         ||  c >= 0x203F  && c <= 0x2040;
   }
 
   template <typename T>
   static bool IsRestrictedChar( T c )
   {
      return c >= 0x00 && c <= 0x08
         ||  c >= 0x0B && c <= 0x0C
         ||  c >= 0x0E && c <= 0x1F
         ||  c >= 0x7F && c <= 0x84
         ||  c >= 0x86 && c <= 0x9F;
   }
 
   static bool IsValidName( const String& name )
   {
      if ( !name.IsEmpty() )
         if ( IsNameStartChar( *name ) )
            for ( String::const_iterator i = name.Begin(); ; )
            {
               if ( ++i == name.End() )
                  return true;
               if ( !IsNameChar( *i ) )
                  break;
            }
      return false;
   }
 
   static String TrimmedSpaces( String::const_iterator i, String::const_iterator j );
 
   static String TrimmedSpaces( const String& text );
 
   static String CollapsedSpaces( String::const_iterator i, String::const_iterator j );
 
   static String CollapsedSpaces( const String& text );
 
   static String DecodedText( String::const_iterator i, String::const_iterator j );
 
   static String DecodedText( const String& text );
 
   static String EncodedText( String::const_iterator i, String::const_iterator j, bool apos = true )
   {
      return EncodedText( String( i, j ), apos );
   }
 
   static String EncodedText( const String& text, bool apos = true );
 
   static String ReferenceValue( String::const_iterator i, String::const_iterator j );
 
   static String ReferenceValue( const String& reference )
   {
      return ReferenceValue( reference.Begin(), reference.End() );
   }
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLComponent
{
public:
 
   XMLComponent() = default;
 
   XMLComponent( const XMLComponent& ) = default;
 
   virtual ~XMLComponent()
   {
   }
 
   XMLElement* ParentElement() const
   {
      return m_parent;
   }
 
   bool IsTopLevel() const
   {
      return m_parent == nullptr;
   }
 
private:
 
   XMLElement* m_parent = nullptr;
 
   friend class XMLElement;
};
 
// ----------------------------------------------------------------------------
 
namespace XMLNodeType
{
   enum mask_type
   {
      Undefined =              0x00000000,
      ChildNode =              0x80000000,
      Unknown =                0x10000000,
      Element =                0x00000001,
      Text =                   0x00000002,
      CDATA =                  0x00000004,
      ProcessingInstructions = 0x00000008,
      Comment =                0x00000010
   };
 
   String AsString( mask_type type );
}
 
using XMLNodeTypes = Flags<XMLNodeType::mask_type>;
 
// ----------------------------------------------------------------------------
 
struct XMLNodeLocation
{
   int64 line = 0;
 
   int64 column = 0;
 
   XMLNodeLocation() = default;
 
   XMLNodeLocation( int line_, int column_ )
      : line( line_ )
      , column( column_ )
   {
   }
 
   XMLNodeLocation( const XMLNodeLocation& ) = default;
 
   String ToString() const;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLNode : public XMLComponent
{
public:
 
   using node_type = XMLNodeType::mask_type;
 
   XMLNode( node_type type )
      : m_type( type )
   {
   }
 
   XMLNode( const XMLNode& x )
      : m_type( x.NodeType() )
      , m_location( x.m_location )
   {
   }
 
   ~XMLNode() override
   {
   }
 
   bool IsChildNode() const
   {
      return m_type.IsFlagSet( XMLNodeType::ChildNode );
   }
 
   node_type NodeType() const
   {
      return static_cast<node_type>( XMLNodeTypes::flag_type( m_type & unsigned( ~XMLNodeType::ChildNode ) ) );
   }
 
   bool IsElement() const
   {
      return NodeType() == XMLNodeType::Element;
   }
 
   bool IsText() const
   {
      return NodeType() == XMLNodeType::Text;
   }
 
   bool IsComment() const
   {
      return NodeType() == XMLNodeType::Comment;
   }
 
   const XMLNodeLocation& Location() const
   {
      return m_location;
   }
 
   virtual void Serialize( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const = 0;
 
   virtual void SerializeAsHTML( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const
   {
      Serialize( text, autoFormat, indentChar, indentSize, level );
   }
 
   virtual bool NLAfter( const XMLNode& previous ) const;
 
private:
 
   XMLNodeTypes    m_type;
   XMLNodeLocation m_location;
 
   friend class XMLDocument;
   friend class XMLElement;
};
 
using XMLNodeList = ReferenceArray<XMLNode>;
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLParseError : public Error
{
public:
 
   XMLParseError( const XMLNode& node, const String& whileDoing, const String& whatHappened )
      : Error( whileDoing + node.Location().ToString() + ": " + whatHappened )
   {
   }
 
   XMLParseError( const XMLNodeLocation& where, const String& whileDoing, const String& whatHappened )
      : Error( whileDoing + where.ToString() + ": " + whatHappened )
   {
   }
 
   XMLParseError( const XMLParseError& ) = default;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLAttribute : public XMLComponent
{
public:
 
   XMLAttribute() = default;
 
   XMLAttribute( const String& name, const String& value = String() )
      : m_name( name )
      , m_value( value )
   {
   }
 
   XMLAttribute( const XMLAttribute& ) = default;
 
   const String& Name() const
   {
      return m_name;
   }
 
   const String& Value() const
   {
      return m_value;
   }
 
   void SetValue( const String& text )
   {
      m_value = text;
   }
 
   String EncodedValue() const
   {
      return XML::EncodedText( m_value, false/*apos*/ );
   }
 
   bool operator ==( const XMLAttribute& x ) const
   {
      return m_name == x.m_name;
   }
 
   bool operator <( const XMLAttribute& x ) const
   {
      return m_name < x.m_name;
   }
 
private:
 
   String m_name;
   String m_value;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLAttributeList
{
public:
 
   using list_implementation = Array<XMLAttribute>;
 
   using iterator = list_implementation::iterator;
 
   using const_iterator = list_implementation::const_iterator;
 
   XMLAttributeList( const String& text )
   {
      Parse( text );
   }
 
   XMLAttributeList() = default;
 
   XMLAttributeList( const XMLAttributeList& ) = default;
 
   int Length() const
   {
      return int( m_list.Length() );
   }
 
   bool IsEmpty() const
   {
      return m_list.IsEmpty();
   }
 
   const XMLAttribute& operator []( int i ) const
   {
      return m_list[i];
   }
 
   const_iterator Begin() const
   {
      return m_list.Begin();
   }
 
   const_iterator End() const
   {
      return m_list.End();
   }
 
#ifndef __PCL_NO_STL_COMPATIBLE_ITERATORS
   const_iterator begin() const
   {
      return Begin();
   }
 
   const_iterator end() const
   {
      return End();
   }
#endif   // !__PCL_NO_STL_COMPATIBLE_ITERATORS
 
   bool HasAttribute( const String& name ) const
   {
      return m_list.Contains( name );
   }
 
   String AttributeValue( const String& name ) const
   {
      const_iterator a = m_list.Search( name );
      return (a != m_list.End()) ? a->Value() : String();
   }
 
   void SetAttribute( const String& name, const String& value )
   {
      if ( !name.IsEmpty() )
      {
         iterator a = m_list.Search( name );
         if ( a == m_list.End() )
            m_list.Add( XMLAttribute( name, value ) );
         else
            a->SetValue( value );
      }
   }
 
   void SetAttribute( const XMLAttribute& attribute )
   {
      if ( !attribute.Name().IsEmpty() )
      {
         iterator a = m_list.Search( attribute );
         if ( a == m_list.End() )
            m_list.Add( attribute );
         else
            *a = attribute;
      }
   }
 
   XMLAttributeList& operator <<( const XMLAttribute& attribute )
   {
      SetAttribute( attribute );
      return *this;
   }
 
   void SetAttributes( const XMLAttributeList& list )
   {
      for ( auto a : list )
         SetAttribute( a );
   }
 
   XMLAttributeList& operator <<( const XMLAttributeList& list )
   {
      SetAttributes( list );
      return *this;
   }
 
   void RemoveAttribute( const String& name )
   {
      iterator a = m_list.Search( name );
      if ( a != m_list.End() )
         m_list.Remove( a );
   }
 
   void Clear()
   {
      m_list.Clear();
   }
 
   void Sort()
   {
      m_list.Sort();
   }
 
   void Parse( const String& text );
 
   void Serialize( IsoString& text ) const;
 
private:
 
   list_implementation m_list;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLElement : public XMLNode
{
public:
 
   using iterator = XMLNodeList::iterator;
 
   using const_iterator = XMLNodeList::const_iterator;
 
   using child_element_list = ReferenceArray<XMLElement>;
 
   XMLElement()
      : XMLNode( XMLNodeType::Element )
   {
   }
 
   XMLElement( const String& name, const XMLAttributeList& attributes = XMLAttributeList() )
      : XMLNode( XMLNodeType::Element )
      , m_name( name )
      , m_attributes( attributes )
   {
   }
 
   XMLElement( XMLElement& parent, const String& name, const XMLAttributeList& attributes = XMLAttributeList() )
      : XMLNode( XMLNodeType::Element )
      , m_name( name )
      , m_attributes( attributes )
   {
      parent.AddChildNode( this );
   }
 
   XMLElement( const XMLElement& ) = delete;
 
   XMLElement& operator =( const XMLElement& ) = delete;
 
   ~XMLElement() override
   {
      DestroyChildNodes();
   }
 
   bool IsRootElement() const
   {
      return ParentElement() == nullptr;
   }
 
   const String& Name() const
   {
      return m_name;
   }
 
   XMLAttributeList Attributes() const
   {
      return m_attributes;
   }
 
   bool HasAttributes() const
   {
      return !m_attributes.IsEmpty();
   }
 
   bool HasAttribute( const String& name ) const
   {
      return m_attributes.HasAttribute( name );
   }
 
   String AttributeValue( const String& name ) const
   {
      return m_attributes.AttributeValue( name );
   }
 
   void SetAttribute( const String& name, const String& value )
   {
      XMLAttribute a( name, value );
      a.m_parent = this;
      m_attributes.SetAttribute( a );
   }
 
   void SetAttribute( const XMLAttribute& attribute )
   {
      XMLAttribute a( attribute );
      a.m_parent = this;
      m_attributes.SetAttribute( a );
   }
 
   XMLElement& operator <<( const XMLAttribute& attribute )
   {
      SetAttribute( attribute );
      return *this;
   }
 
   void SetAttributes( const XMLAttributeList& list )
   {
      for ( auto a : list )
         SetAttribute( a );
   }
 
   XMLElement& operator <<( const XMLAttributeList& list )
   {
      SetAttributes( list );
      return *this;
   }
 
   void RemoveAttribute( const String& name )
   {
      m_attributes.RemoveAttribute( name );
   }
 
   void ClearAttributes()
   {
      m_attributes.Clear();
   }
 
   void SortAttributes()
   {
      m_attributes.Sort();
   }
 
   template <class BP>
   void SortAttributes( BP p )
   {
      m_attributes.Sort( p );
   }
 
   void ParseAttributes( const String& text )
   {
      XMLAttributeList list( text );
      ClearAttributes();
      SetAttributes( list );
   }
 
   void SerializeAttributes( IsoString& text ) const
   {
      m_attributes.Serialize( text );
   }
 
   int ChildCount() const
   {
      return int( m_childNodes.Length() );
   }
 
   bool IsEmpty() const
   {
      return m_childNodes.IsEmpty();
   }
 
   const XMLNode& operator []( int i ) const
   {
      return m_childNodes[i];
   }
 
   const XMLNode& First() const
   {
      return m_childNodes.First();
   }
 
   const XMLNode& Last() const
   {
      return m_childNodes.Last();
   }
 
   const_iterator Begin() const
   {
      return m_childNodes.Begin();
   }
 
   const_iterator End() const
   {
      return m_childNodes.End();
   }
 
#ifndef __PCL_NO_STL_COMPATIBLE_ITERATORS
   const_iterator begin() const
   {
      return Begin();
   }
 
   const_iterator end() const
   {
      return End();
   }
#endif   // !__PCL_NO_STL_COMPATIBLE_ITERATORS
 
#ifndef __PCL_NO_MUTABLE_XML_ELEMENT_ITERATORS
 
   iterator Begin()
   {
      return m_childNodes.Begin();
   }
 
   iterator End()
   {
      return m_childNodes.End();
   }
 
   const_iterator ConstBegin() const
   {
      return m_childNodes.ConstBegin();
   }
 
   const_iterator ConstEnd() const
   {
      return m_childNodes.ConstEnd();
   }
 
# ifndef __PCL_NO_STL_COMPATIBLE_ITERATORS
   iterator begin()
   {
      return Begin();
   }
 
   iterator end()
   {
      return End();
   }
# endif   // !__PCL_NO_STL_COMPATIBLE_ITERATORS
 
#endif   // !__PCL_NO_MUTABLE_XML_ELEMENT_ITERATORS
 
   bool HasElements() const
   {
      return m_childTypes.IsFlagSet( XMLNodeType::Element );
   }
 
   bool HasText() const
   {
      return m_childTypes.IsFlagSet( XMLNodeType::Text );
   }
 
   bool HasCDATA() const
   {
      return m_childTypes.IsFlagSet( XMLNodeType::CDATA );
   }
 
   bool HasProcessingInstructions() const
   {
      return m_childTypes.IsFlagSet( XMLNodeType::ProcessingInstructions );
   }
 
   bool HasComments() const
   {
      return m_childTypes.IsFlagSet( XMLNodeType::Comment );
   }
 
   String Text() const;
 
   void GetChildElements( child_element_list& list, bool recursive ) const
   {
      for ( const XMLNode& node : m_childNodes )
         if ( node.IsElement() )
         {
            const XMLElement& element = static_cast<const XMLElement&>( node );
            list << &element;
            if ( recursive )
               element.GetChildElements( list, recursive );
         }
   }
 
   child_element_list ChildElements( bool recursive = false ) const
   {
      child_element_list list;
      GetChildElements( list, recursive );
      return list;
   }
 
   void GetChildElementsByName( child_element_list& list, const String& name, bool recursive ) const
   {
      for ( const XMLNode& node : m_childNodes )
         if ( node.IsElement() )
         {
            const XMLElement& element = static_cast<const XMLElement&>( node );
            if ( element.Name() == name )
            {
               list << &element;
               if ( recursive )
                  element.GetChildElementsByName( list, name, recursive );
            }
         }
   }
 
   child_element_list ChildElementsByName( const String& name, bool recursive = false ) const
   {
      child_element_list list;
      GetChildElementsByName( list, name, recursive );
      return list;
   }
 
   bool HasChildElementWithName( const String& name, bool recursive = false ) const
   {
      for ( const XMLNode& node : m_childNodes )
         if ( node.IsElement() )
         {
            const XMLElement& element = static_cast<const XMLElement&>( node );
            if ( element.Name() == name )
               return true;
            if ( recursive )
               if ( element.HasChildElementWithName( name, recursive ) )
                  return true;
         }
      return false;
   }
 
   void GetChildNodesByType( XMLNodeList& list, XMLNodeTypes types, bool recursive ) const
   {
      for ( const XMLNode& node : m_childNodes )
         if ( types.IsFlagSet( node.NodeType() ) )
         {
            list << &node;
            if ( recursive )
               if ( node.IsElement() )
                  static_cast<const XMLElement&>( node ).GetChildNodesByType( list, types, recursive );
         }
   }
 
   XMLNodeList ChildNodesByType( XMLNodeTypes types, bool recursive = false ) const
   {
      XMLNodeList list;
      GetChildNodesByType( list, types, recursive );
      return list;
   }
 
   template <class UP>
   void GetChildNodesThat( XMLNodeList& list, UP u, bool recursive ) const
   {
      for ( const XMLNode& node : m_childNodes )
         if ( u( node ) )
         {
            list << &node;
            if ( recursive )
               if ( node.IsElement() )
                  static_cast<const XMLElement&>( node ).GetChildNodesThat( list, u, recursive );
         }
   }
 
   template <class UP>
   XMLNodeList ChildNodesThat( UP u, bool recursive = false ) const
   {
      XMLNodeList list;
      GetChildNodesThat( list, u, recursive );
      return list;
   }
 
   template <class UP>
   bool HasChildNodeThat( UP u, bool recursive = false ) const
   {
      for ( const XMLNode& node : m_childNodes )
      {
         if ( u( node ) )
            return true;
         if ( recursive )
            if ( node.IsElement() )
               if ( static_cast<const XMLElement&>( node ).HasChildNodeThat( u, recursive ) )
                  return true;
      }
      return false;
   }
 
   void AddChildNode( XMLNode* node )
   {
      m_childNodes << node;
      node->m_parent = this;
      node->m_type.SetFlag( XMLNodeType::ChildNode );
      m_childTypes.SetFlag( node->NodeType() );
   }
 
   XMLElement& operator <<( XMLNode* node )
   {
      AddChildNode( node );
      return *this;
   }
 
   void AddChildNodes( XMLNodeList& nodes )
   {
      for ( XMLNode& node : nodes )
         AddChildNode( &node );
   }
 
   XMLElement& operator <<( XMLNodeList& nodes )
   {
      AddChildNodes( nodes );
      return *this;
   }
 
   void AddChildNode( XMLNode* node, const XMLNodeLocation& location )
   {
      node->m_location = location;
      AddChildNode( node );
   }
 
   void DestroyChildNodes()
   {
      m_childNodes.Destroy();
      m_childTypes = XMLNodeType::Undefined;
   }
 
   XMLNodeList ReleaseChildNodes()
   {
      XMLNodeList nodes = m_childNodes;
      m_childNodes.Clear();
      m_childTypes = XMLNodeType::Undefined;
      return nodes;
   }
 
   void Serialize( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const override;
 
   void SerializeAsHTML( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const override;
 
private:
 
   String           m_name;
   XMLAttributeList m_attributes;
   XMLNodeList      m_childNodes;
   XMLNodeTypes     m_childTypes = XMLNodeType::Undefined;
};
 
// ----------------------------------------------------------------------------
 
using XMLElementList = XMLElement::child_element_list;
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLText : public XMLNode
{
public:
 
   XMLText( const String& text, bool preserveSpaces = true, bool verbatim = false )
      : XMLNode( XMLNodeType::Text )
      , m_text( preserveSpaces ? text : XML::CollapsedSpaces( XML::TrimmedSpaces( text ) ) )
      , m_preserveSpaces( preserveSpaces )
      , m_verbatim( verbatim )
   {
   }
 
   XMLText( const XMLText& ) = default;
 
   const String& Text() const
   {
      return m_text;
   }
 
   bool IsPreserveSpaces() const
   {
      return m_preserveSpaces;
   }
 
   String EncodedText() const
   {
      return XML::EncodedText( m_text );
   }
 
   String SpaceTransformedText( bool collapse, bool trim ) const
   {
      String text = m_text;
      if ( trim )
         text = XML::TrimmedSpaces( text );
      if ( collapse )
         text = XML::CollapsedSpaces( text );
      return text;
   }
 
   void Serialize( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const override;
 
   bool NLAfter( const XMLNode& previous ) const override
   {
      return !m_preserveSpaces;
   }
 
private:
 
   String m_text; // N.B.: This is plain, that is, decoded, text.
   bool   m_preserveSpaces = true;
   bool   m_verbatim = false;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLCDATA : public XMLNode
{
public:
 
   XMLCDATA( const String& data = String() )
      : XMLNode( XMLNodeType::CDATA )
      , m_cdata( data )
   {
   }
 
   XMLCDATA( const XMLCDATA& ) = default;
 
   const String& CData() const
   {
      return m_cdata;
   }
 
   void Serialize( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const override;
 
private:
 
   String m_cdata;
};
 
// ----------------------------------------------------------------------------
 
class XMLProcessingInstructions : public XMLNode
{
public:
 
   XMLProcessingInstructions( const String& target, const String& instructions )
      : XMLNode( XMLNodeType::ProcessingInstructions )
      , m_target( target )
      , m_instructions( instructions )
   {
   }
 
   XMLProcessingInstructions( const XMLProcessingInstructions& ) = default;
 
   const String& Target() const
   {
      return m_target;
   }
 
   const String& Instructions() const
   {
      return m_instructions;
   }
 
   void Serialize( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const override;
 
private:
 
   String m_target;
   String m_instructions;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLComment : public XMLNode
{
public:
 
   XMLComment( const String& comment )
      : XMLNode( XMLNodeType::Comment )
      , m_comment( comment )
   {
   }
 
   XMLComment( const XMLComment& ) = default;
 
   const String& Comment() const
   {
      return m_comment;
   }
 
   void Serialize( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const override;
 
private:
 
   String m_comment;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLUnknownElement : public XMLNode
{
public:
 
   XMLUnknownElement( const String& name, const String& parameters = String() )
      : XMLNode( XMLNodeType::Unknown )
      , m_name( name )
      , m_parameters( parameters )
   {
   }
 
   XMLUnknownElement( const XMLUnknownElement& ) = default;
 
   const String& Name() const
   {
      return m_name;
   }
 
   const String& Parameters() const
   {
      return m_parameters;
   }
 
   void Serialize( IsoString& text, bool autoFormat, char indentChar, unsigned indentSize, unsigned level ) const override;
 
private:
 
   String m_name;
   String m_parameters;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLDeclaration : public XMLComponent
{
public:
 
   XMLDeclaration( const String& version = String(), const String& encoding = String(), bool standalone = false )
      : m_version( version )
      , m_encoding( encoding )
      , m_standalone( standalone )
   {
   }
 
   XMLDeclaration( const XMLDeclaration& ) = default;
 
   const String& Version() const
   {
      return m_version;
   }
 
   const String& DocumentEncoding() const
   {
      return m_encoding;
   }
 
   bool IsStandaloneDocument() const
   {
      return m_standalone;
   }
 
   bool IsDefined() const
   {
      return !m_version.IsEmpty();
   }
 
   void Serialize( IsoString& text ) const;
 
private:
 
   String m_version;
   String m_encoding;
   bool   m_standalone = false;
};
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLDocTypeDeclaration : public XMLComponent
{
public:
 
   XMLDocTypeDeclaration( const String& name = String(), const String& definition = String() )
      : m_name( name )
      , m_definition( definition )
   {
   }
 
   XMLDocTypeDeclaration( const XMLDocTypeDeclaration& ) = default;
 
   const String& Name() const
   {
      return m_name;
   }
 
   const String& Definition() const
   {
      return m_definition;
   }
 
   bool IsDefined() const
   {
      return !m_name.IsEmpty();
   }
 
   void Serialize( IsoString& text ) const;
 
private:
 
   String m_name;
   String m_definition;
};
 
// ----------------------------------------------------------------------------
 
struct XMLElementFilter
{
   virtual ~XMLElementFilter()
   {
   }
 
   virtual bool operator()( const XMLElement* parent, const String& name ) const = 0;
 
   virtual bool operator()( const XMLElement* parent, const String& name, const XMLAttributeList& attributes ) const
   {
      return true;
   }
};
 
// ----------------------------------------------------------------------------
 
namespace XMLParserOption
{
   enum mask_type
   {
      IgnoreComments        = 0x00000001,
      IgnoreUnknownElements = 0x00000002,
      IgnoreStrayCharacters = 0x00000004,
      NormalizeTextSpaces   = 0x00000008
   };
}
 
using XMLParserOptions = Flags<XMLParserOption::mask_type>;
 
// ----------------------------------------------------------------------------
 
class PCL_CLASS XMLDocument
{
public:
 
   using iterator = XMLNodeList::iterator;
 
   using const_iterator = XMLNodeList::const_iterator;
 
   using parser_option = XMLParserOption::mask_type;
 
   XMLDocument() = default;
 
   virtual ~XMLDocument()
   {
      m_nodes.Destroy();
      m_root = nullptr;
      RemoveElementFilter();
   }
 
   XMLDocument( const XMLDocument& ) = delete;
 
   XMLDocument& operator =( const XMLDocument& ) = delete;
 
   const XMLDeclaration& XML() const
   {
      return m_xml;
   }
 
   void SetXML( const XMLDeclaration& xml )
   {
      m_xml = xml;
   }
 
   void SetXML( const String& version = "1.0", const String& encoding = "UTF-8", bool standalone = false )
   {
      SetXML( XMLDeclaration( version, encoding, standalone ) );
   }
 
   const XMLDocTypeDeclaration& DocType() const
   {
      return m_docType;
   }
 
   void SetDocType( const XMLDocTypeDeclaration& docType )
   {
      m_docType = docType;
   }
 
   const XMLElement* RootElement() const
   {
      return m_root;
   }
 
   XMLElement* ReleaseRootElement()
   {
      XMLElement* root = m_root;
      m_nodes.RemovePointer( m_root );
      Clear();
      return root;
   }
 
   int NodeCount() const
   {
      return int( m_nodes.Length() );
   }
 
   bool IsEmpty() const
   {
      return m_nodes.IsEmpty();
   }
 
   const XMLNode& operator []( int i ) const
   {
      return m_nodes[i];
   }
 
   const_iterator Begin() const
   {
      return m_nodes.Begin();
   }
 
   const_iterator End() const
   {
      return m_nodes.End();
   }
 
#ifndef __PCL_NO_STL_COMPATIBLE_ITERATORS
   const_iterator begin() const
   {
      return Begin();
   }
 
   const_iterator end() const
   {
      return End();
   }
#endif   // !__PCL_NO_STL_COMPATIBLE_ITERATORS
 
   void AddNode( XMLNode* node );
 
   XMLDocument& operator <<( XMLNode* node )
   {
      AddNode( node );
      return *this;
   }
 
   void SetRootElement( XMLElement* element );
 
   void Clear();
 
   void RemoveElementsByFilter( const XMLElementFilter& filter )
   {
      XMLElement dum;
      m_nodes.Destroy( dum,
         [&]( const XMLNode& node, const XMLNode& )
         {
            if ( node.IsElement() )
            {
               const XMLElement& element = static_cast<const XMLElement&>( node );
               if ( !filter( nullptr, element.Name() ) ||
                    !filter( nullptr, element.Name(), element.Attributes() ) )
                  return true;
            }
            return false;
         } );
   }
 
   void RemoveElementsByName( const String& name, bool caseSensitive = true )
   {
      XMLElement dum;
      m_nodes.Destroy( dum,
         [&]( const XMLNode& node, const XMLNode& )
         {
            if ( node.IsElement() )
            {
               const XMLElement& element = static_cast<const XMLElement&>( node );
               if ( (caseSensitive ? element.Name().Compare( name ) : element.Name().CompareIC( name )) == 0 )
                  return true;
            }
            return false;
         } );
   }
 
   void SetElementFilter( XMLElementFilter* filter )
   {
      delete m_filter, m_filter = filter;
   }
 
   void RemoveElementFilter()
   {
      SetElementFilter( nullptr );
   }
 
   void SetParserOption( parser_option option, bool on = true )
   {
      m_parserOptions.SetFlag( option, on );
   }
 
   void SetParserOptions( XMLParserOptions options )
   {
      m_parserOptions = options;
   }
 
   void ClearParserOptions()
   {
      m_parserOptions.Clear();
   }
 
   void Parse( const String& text );
 
   bool IsAutoFormatting() const
   {
      return m_autoFormatting;
   }
 
   void EnableAutoFormatting( bool enable = true )
   {
      m_autoFormatting = enable;
   }
 
   void DisableAutoFormatting( bool disable = true )
   {
      EnableAutoFormatting( !disable );
   }
 
   int IndentSize() const
   {
      return m_indentSize;
   }
 
   void SetIndentSize( int indentSize )
   {
      m_indentSize = Range( indentSize, 0, 8 );
   }
 
   bool IsIndentTabs() const
   {
      return m_indentTabs;
   }
 
   void EnableIndentTabs( bool enable = true )
   {
      m_indentTabs = enable;
   }
 
   void DisableIndentTabs( bool disable = true )
   {
      EnableIndentTabs( !disable );
   }
 
   IsoString Serialize() const
   {
      return Serialize( false/*isHTML*/ );
   }
 
   IsoString SerializeAsHTML() const
   {
      return Serialize( true/*isHTML*/ );
   }
 
   void SerializeToFile( const String& path ) const;
 
   void SerializeToFileAsHTML( const String& path ) const;
 
private:
 
   XMLDeclaration        m_xml;
   XMLDocTypeDeclaration m_docType;
   XMLNodeList           m_nodes;
   XMLElement*           m_root = nullptr;
   XMLElementFilter*     m_filter = nullptr;
   XMLParserOptions      m_parserOptions;
   XMLNodeLocation       m_location;
   bool                  m_autoFormatting = false;
   bool                  m_indentTabs = false;
   int                   m_indentSize = 3;
 
   IsoString Serialize( bool isHTML ) const;
};
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_XML_h
 
// ----------------------------------------------------------------------------
// EOF pcl/XML.h - Released 2024-06-18T15:48:54Z