/** @mainpage Qore XML Module

    @tableofcontents

    @section xmlintro Introduction

    XML functionality in the %Qore xml module is provided by the <a href="http://xmlsoft.org">libxml2 library</a>, which provides a powerful, stable, clean, and thread-safe basis for XML integration in %Qore.  XML provides a way to describe hierarchical data, and thanks to <a href="http://xmlsoft.org">libxml2</a>, the xml module allows for easy serialization and deserialization between XML strings and %Qore data structures.

    This module is released under a choice of two licenses:
    - <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">LGPL 2.1</a>
    - MIT (see COPYING.MIT in the source distribution for more information)
    .
    The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the %Qore library was initialized).

    To use the module in a %Qore script, use the \c %%requires directive as follows:
    @code %requires xml @endcode

    @note XML functionality was included in the main %Qore shared library until version 0.8.1, at which time the code was removed to make this module.

    Classes provided by this module:
    - @ref Qore::Xml::FileSaxIterator "FileSaxIterator": an iterator class for XML strings
    - @ref Qore::Xml::SaxIterator "SaxIterator": an iterator class for XML strings
    - @ref Qore::Xml::XmlDoc "XmlDoc": for analyzing and manipulating XML documents
    - @ref Qore::Xml::XmlNode "XmlNode": gives information about XML data in an XML document
    - @ref Qore::Xml::XmlReader "XmlReader": for parsing or iterating through the elements of an XML document

    Also included with the binary xml module:
    - <a href="../../WSDL/html/index.html">WSDL user module</a>
    - <a href="../../SoapClient/html/index.html">SoapClient user module</a>
    - <a href="../../SoapHandler/html/index.html">SoapHandler user module</a>
    - <a href="../../XmlRpcHandler/html/index.html">XmlRpcHandler user module</a>

    @section optionconstants Module Option Constants
    
    The following constants give information about the availability of XML functionality (dependent on libxml2 features at compile time):

    <b>XML Option Constants</b>
    @htmlonly <style><!-- td.qore { background-color: #5b9409; color: white; } --></style> @endhtmlonly
    <table>
      <tr>
        <td class="qore"><b>Name</b></td>
        <td class="qore"><b>Type</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>@ref Qore::Xml::Option::HAVE_PARSEXMLWITHRELAXNG "HAVE_PARSEXMLWITHRELAXNG"</td>
        <td>\c bool</td>
        <td>Indicates if parseXMLWithRelaxNG() and Qore::Xml::XmlReader::relaxNGValidate() are available</td>
      </tr>
      <tr>
        <td>@ref Qore::Xml::Option::HAVE_PARSEXMLWITHSCHEMA "HAVE_PARSEXMLWITHSCHEMA"</td>
        <td>\c bool</td>
        <td>Indicates if parseXMLWithSchema() and Qore::Xml::XmlReader::schemaValidate() are available</td>
      </tr>
    </table>

    If either of the above constants are \c False, then calling any of the dependent functions or methods will result in a run-time exception.

    @section serialization Automatic XML Serialization and Deserialization

    This section describes automatic XML serialization and deserialization; for iterative or user-controlled XML parsing, see @ref xmlclasses "XML Classes".

    XML serialization (conversion from %Qore data structures to XML strings) in the xml module relies on the fact that %Qore hashes retain insertion order, which means that conversion to and from %Qore data structures and XML strings can be done without data loss and without reordering the XML elements. In general, XML serialization is relatively straighforward, but there are a few issues to be aware of, particularly regarding element attributes and lists. These issues are described in the following paragraphs.

    First, a straightforward example:

    @code
$h = ("record": ("name": ("first": "Fred", "last": "Smith")));
printf("%s\n", makeFormattedXMLString($h));@endcode

    This produces the following result

    @verbatim
<?xml version="1.0" encoding="UTF-8"?>
<record>
  <name>
    <first>Fred</first>
    <last>Smith</last>
  </name>
</record>@endverbatim

    To set XML attributes, the %Qore value must be a hash and the attributes are stored in another hash in the key \c "^attributes^". That is; the value of the \c "^attributes^" key must be a hash, and each member of this hash will represent an attribute-value pair.

    For example:

    @code
$h = ("record": ("^attributes^": ("type": "customer") , 
	         "name": ("first": "Fred", "last": "Smith")));
printf("%s\n", makeFormattedXMLString($h));@endcode

    This produces the following results:

    @verbatim
<?xml version="1.0" encoding="UTF-8"?>
<record type="customer">
  <name>
    <first>Fred</first>
    <last>Smith</last>
  </name>
</record> @endverbatim

    If instead we wanted to have text instead of child data under the "record" node, we must set the \c "^value^" key of the hash along with the \c "^attributes^" key as follows:

    @code
$h = ("record": ("^attributes^": ("type": "customer"), 
	         "^value^": "NO-RECORD"));
printf("%s\n", makeFormattedXMLString($h)); @endcode

    Giving the following results:

    @verbatim <?xml version="1.0" encoding="UTF-8"?>
<record type="customer">NO-RECORD</record>@endverbatim

    Arrays are serialized with repeating node names as follows:

    @code
$h = ("record": ("part": ("part-02-05", "part-99-23", "part-34-28")));
printf("%s\n", makeFormattedXMLString($h));@endcode

    Producing the following results:

    @verbatim
<?xml version="1.0" encoding="UTF-8"?>
<record type="customer">
  <part>part-02-05</part>
  <part>part-99-23</part>
  <part>part-34-28</part>
</record>@endverbatim

    It gets a little trickier when a key should repeated at the same level in an XML string, but other keys come between, for example, take the following XML string:

    @verbatim
<?xml version="1.0" encoding="UTF-8"?>
<para>Keywords: <code>this</code>, <code>that</code>, and <code>the_other</code>.</para>@endverbatim

    It's not possible to use a list, because text is required in between. As described earlier, the \c "^value^" hash key can be used to serialize text in an XML string. In this case, we need to have several text nodes and several code nodes in a mixed-up order to give us the XML string we want. Because qore hases have unique keys (we can't use the same key twice in the same hash), we resort to a key naming trick that allows us to virtually duplicate our key names and therefore arrive at the XML string we want. We do this by appending a \c '^' character to the end of the key name and then some unique text. When serializing hash keys, any text after (and including) the \c '^' character is ignored. For the special key name \c "^value^", we do not need to duplicate the final \c '^' character. Instead we just add unique text to ensure that our hash can contain all the data we want and that it will be serialized in the right order to the XML string as follows:

    @code
$h = ("para": ("^value^": "Keywords: ", 
               "code" : "this", 
               "^value^1" : ", ", 
               "code^1" : "that", 
               "^value^2" : ", and ", 
               "code^2" : "the_other", 
               "^value^3" : "."));
printf("%s\n", makeFormattedXMLString($h));@endcode

    By ignoring the text after the \c '^' character, the above code will serialize to the XML string we want. In general, by using this convention, we can properly serialize multiple out-of-order keys without losing data and still have unique names for our hash keys.

    Note than when deserializing XML strings to %Qore data structures, the above rules are applied in reverse. If any out-of-order duplicate keys are detected, %Qore will automatically generate unique hash key names based on the above rules.

    Also note that \c CDATA text will be generated if a hash key starts with \c '^cdata'; such text will not be processed for escape code substitution. When deserializing XML strings to qore data structures, CDATA text will be placed unmodified under such a hash key as well.

    <b>Functions For XML Serialization and Deserialization</b>
    <table>
      <tr>
        <td class="qore"><b>Function Name</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>makeFormattedXMLFragment()</td>
        <td>Serializes a hash into an XML string with formatting without an XML header.</td>
      </tr>
      <tr>
        <td>makeFormattedXMLString()</td>
        <td>Serializes a hash into an XML string with formatting and an XML header.</td>
      </tr>
      <tr>
        <td>makeXMLFragment()</td>
        <td>Serializes a hash into an XML string without an XML header or formatting.</td>
      </tr>
      <tr>
        <td>makeXMLString()</td>
        <td>Serializes a hash into a complete XML string with an XML header and without formatting.</td>
      </tr>
      <tr>
        <td>parseXMLAsData()</td>
        <td>parses an XML string as data (duplicate, out-of-order XML elements are collapsed into lists) and returns a %Qore hash structure.</td>
      </tr>
      <tr>
        <td>parseXMLAsDataWithRelaxNG()</td>
        <td>parses an XML string as data (duplicate, out-of-order XML elements are collapsed into lists) and validates against a RelaxNG schema string and returns a %Qore hash structure.</td>
      </tr>
      <tr>
        <td>parseXMLAsDataWithSchema()</td>
        <td>parses an XML string as data (duplicate, out-of-order XML elements are collapsed into lists) and validates against an XSD schema string and returns a %Qore hash structure.</td>
      </tr>
      <tr>
        <td>parseXML()</td>
        <td>parses an XML string (XML element order is preserved by appending numeric suffixes to %Qore hash key names when necessary) and returns a %Qore hash structure.</td>
      </tr>
      <tr>
        <td>parseXMLWithRelaxNG()</td>
        <td>parses an XML string (XML element order is preserved by appending numeric suffixes to %Qore hash key names when necessary) and validates against a RelaxNG schema string and returns a %Qore hash structure.</td>
      </tr>
      <tr>
        <td>parseXMLWithSchema()</td>
        <td>parses an XML string (XML element order is preserved by appending numeric suffixes to %Qore hash key names when necessary) and validates against an XSD schema string and returns a %Qore hash structure.</td>
      </tr>
    </table>

    @anchor xmlclasses
    <b>Classes Providing XML Functionality</b>
    <table>
      <tr>
        <td class="qore"><b>Class</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>@ref Qore::Xml::FileSaxIterator "FileSaxIterator"</td>
        <td>An iterator class for file data</td>
      </tr>
      <tr>
        <td>@ref Qore::Xml::SaxIterator "SaxIterator"</td>
        <td>An iterator class for XML strings</td>
      </tr>
      <tr>
        <td>@ref Qore::Xml::XmlDoc "XmlDoc"</td>
        <td>For analyzing and manipulating XML documents</td>
      </tr>
      <tr>
        <td>@ref Qore::Xml::XmlNode "XmlNode"</td>
        <td>Gives information about XML data in an XML document</td>
      </tr>
      <tr>
        <td>@ref Qore::Xml::XmlReader "XmlReader"</td>
        <td>For parsing or iterating through the elements of an XML document</td>
      </tr>
    </table>

    @section XMLRPC XML-RPC

    XML-RPC is a lightweight but powerful XML over HTTP web service protocol.  The xml module includes builtin support for this protocol as described here.  You can find more information about XML-RPC, including specifications and examples at http://xmlrpc.org.

    Information about %Qore's XML-RPC serialization can be found below.

    <b>XML-RPC Serialization in %Qore</b>
    <table>
      <tr>
        <td class="qore"><b>%Qore Type</b></td>
        <td class="qore"><b>XML-RPC Type</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>\c string</td>
        <td>\c string</td>
        <td>direct conversion to UTF-8 string</td>
      </tr>
      <tr>
        <td>\c integer</td>
        <td>\c i4 or \c string</td>
        <td>If the integer requires more than 32 bits to represent, then it is sent as a string</td>
      </tr>
      <tr>
        <td>\c float</td>
        <td>\c double</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c number</td>
        <td>\c double</td>
        <td>conversion to a double for serialization</td>
      </tr>
      <tr>
        <td>\c boolean</td>
        <td>\c boolean</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c date</td>
        <td>\c iso8601</td>
        <td>Absolute date/time values will convert to the default time zone for the calling context for the output string if necessary. Note that relative date/time values (durations) will be serialized with the same format as absolute date/time values.</td>
      </tr>
      <tr>
        <td>\c binary</td>
        <td>\c base64</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c list</td>
        <td>\c array</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>\c hash</td>
        <td>\c struct</td>
        <td>direct conversion</td>
      </tr>
      <tr>
        <td>all others</td>
        <td>n/a</td>
        <td>All other types will cause an \c XML-RPC-SERIALIZATION-ERROR to be raised.</td>
      </tr>
    </table>
	 
    <b>Classes Providing XML-RPC Functionality</b>
    <table>
      <tr>
        <td class="qore"><b>Class</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>Qore::Xml::XmlRpcClient</td>
        <td>For communicating with XML-RPC servers</td>
      </tr>
    </table>

    <b>Functions Providing XML-RPC Functionality</b>
    <table>
      <tr>
        <td class="qore"><b>Function Name</b></td>
        <td class="qore"><b>Description</b></td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCCallString()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call with formatting.</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCCallStringArgs()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call with formatting, taking a single list argument for the argument list.</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCCallStringWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call with formatting and an explicit output encoding</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCCallStringArgsWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call with formatting, taking a single list argument for the argument list and an explicit output encoding</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCFaultResponseString()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC fault response with formatting.</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCFaultResponseStringWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC fault response with formatting and an explicit output encoding.</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCResponseString()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC response with formatting.</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCResponseStringWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC response with formatting and an explicit output encoding.</td>
      </tr>
      <tr>
        <td>makeFormattedXMLRPCValueString()</td>
        <td>Serializes a hash into an XML string in XML-RPC value format with formatting.</td>
      </tr>
      <tr>
        <td>makeXMLRPCCallString()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call without formatting.</td>
      </tr>
      <tr>
        <td>makeXMLRPCCallStringArgs()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call without formatting, taking a single list argument for the argument list.</td>
      </tr>
      <tr>
        <td>makeXMLRPCCallStringWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call without formatting and an explicit output encoding.</td>
      </tr>
      <tr>
        <td>makeXMLRPCCallStringArgsWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC call without formatting, taking a single list argument for the argument list and an explicit output encoding.</td>
      </tr>
      <tr>
        <td>makeXMLRPCFaultResponseString()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC fault response without formatting.</td>
      </tr>
      <tr>
        <td>makeXMLRPCFaultResponseStringWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC fault response without formatting and an explicit output encoding.</td>
      </tr>
      <tr>
        <td>makeXMLRPCResponseString()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC response without formatting.</td>
      </tr>
      <tr>
        <td>makeXMLRPCResponseStringWithEncoding()</td>
        <td>Serializes a hash into an XML string formatted for an XML-RPC response without formatting and an explicit output encoding.</td>
      </tr>
      <tr>
        <td>makeXMLRPCValueString()</td>
        <td>Serializes a hash into an XML string in XML-RPC value format without formatting.</td>
      </tr>
      <tr>
        <td>parseXMLRPCCall()</td>
        <td>deserializies an XML-RPC call string, returning a %Qore hash respresenting the call information.</td>
      </tr>
      <tr>
        <td>parseXMLRPCResponse()</td>
        <td>deserializies an XML-RPC response string, returning a %Qore hash respresenting the response information.</td>
      </tr>
      <tr>
        <td>parseXMLRPCValue()</td>
        <td>deserializies an XML-RPC value tree, returning a %Qore hash respresenting the information.</td>
      </tr>
    </table>

    @section constants XML Constants

    All constants (and classes and namespaces) provided by this module are created under the Qore namespace (the main namespace for the %Qore Programming Language).

    @section codetags Function and Method Tags

    @subsection NOOP NOOP

    Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s).  When variants with this flag are resolved at parse time, a \c "call-with-type-errors" warning is raised (assuming this warning is enabled), unless \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set.  If \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set, then these variants are inaccessible at parse time; resolving to a variant with this flag set at parse time causes an exception to be thrown.

    These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

    This tag is equal to @ref RUNTIME_NOOP, except no runtime effect is caused by resolving a function or method tagged with \c NOOP at runtime; this tag only affects parse time resolution.

    @subsection RUNTIME_NOOP RUNTIME_NOOP

    Code with this flag makes no calculations, but rather returns a constant value.  This flag is given to function and method variants that return a default value depending on the type of argument(s).  When variants with this flag are resolved at parse time, a \c "call-with-type-errors" warning is raised (assuming this warning is enabled), unless \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set.  If \c PO_REQUIRE_TYPES or \c PO_STRICT_ARGS is set, then these variants are inaccessible; resolving to a variant with this flag set at parse time or run time causes an exception to be thrown.

    These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

    This tag is equal to @ref NOOP, except that \c RUNTIME_NOOP is also enforced at runtime.

    @subsection RET_VALUE_ONLY RET_VALUE_ONLY
	
    This flag indicates that the function or method has no side effects; it only returns a value, for example.

    This tag is identical to @ref CONSTANT except that functions or methods tagged with \c RET_VALUE_ONLY could throw exceptions.

    @subsection CONSTANT CONSTANT
	
    This flag indicates that the function or method has no side effects and does not throw any exceptions.

    This tag is identical to @ref RET_VALUE_ONLY except that functions or methods tagged with \c CONSTANT do not throw exceptions.

    @subsection DEPRECATED DEPRECATED
	
    Code with this flag is deprecated and may be removed in a future version of this module; if a variant with this flag is resolved at parse time, a \c "deprecated" warning is raised (assuming this warning is enabled).

    @section xmlreleasenotes Release Notes

    @subsection xml13 xml Module Version 1.3
    <b>Changes and Bug Fixes in This Release</b>
    - added the @ref Qore::Xml::SaxIterator "SaxIterator" and @ref Qore::Xml::FileSaxIterator "FileSaxIterator" classes
    - many SOAP messaging and WSDL handling fixes
    - allow for XSD imports without a URI scheme to be imported with custom logic
    - <a href="../../SoapClient/html/index.html">SoapClient</a> fixes: fixed URI request path, fixed agent string, added optional logging closures, added SOAP headers to info hash when available
    - <a href="../../SoapHandler/html/index.html">SoapHandler</a> changes:  
      - allow SOAP serialization errors to be logged at the source
      - added support for matching requests by soap action values
    - user modules moved to top-level qore module directory from version-specific module directory since they are valid for multiple versions of qore

    @subsection xml12 xml Module Version 1.2
    <b>Changes and Bug Fixes in This Release</b>
    - implemented dynamic unbinding of service methods in the <a href="../../SoapHandler/html/index.html">SoapHandler</a> module
    - fixed bugs in @ref Qore::Xml::XmlReader::toQore() "XmlReader::toQore()" and @ref Qore::Xml::XmlReader::toQoreData() "XmlReader::toQoreData()" for SAX parsing
    - implemented enhanced logging for the <a href="../../XmlRpcHandler/html/index.html">XmlRpcHandler</a> module
    - doc updates

    @subsection xml11 xml Module Version 1.1
    <b>Changes and Bug Fixes in This Release</b>
    - fixed internal XMl to Qore processing for extreme cases
    - fixed makeFormattedXMLString() to really format the output
    - fixed XML-RPC parsing with empty elements in structures
    - added additional validation to XML-RPC parsing (checking close elements)
    - set the character encoding correctly in the outgoing \c "Content-Type" request header
    - added suport for the new arbitrary-precision numeric type introduced with Qore 0.8.6
*/