Qore XML Module: XML Functions

Qore XML Module 1.1

- Main Page
- Modules
- Namespaces
- Classes

All Classes Namespaces Functions Variables Groups
Functions
XML Functions

## Functions
string | Qore::Xml::makeFormattedXMLFragment (hash h, *string encoding)
| serializes a hash into an XML string with whitespace formatting but without an XML header More...
nothing | Qore::Xml::makeFormattedXMLFragment ()
| This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters. More...
string | Qore::Xml::makeFormattedXMLString (string key, hash h, *string encoding)
| serializes a hash into an XML string with whitespace formatting and with an XML header More...
string | Qore::Xml::makeFormattedXMLString (hash h, *string encoding)
| serializes a hash into an XML string with whitespace formatting and with an XML header More...
string | Qore::Xml::makeXMLFragment (hash h, *string encoding)
| serializes a hash into an XML string without whitespace formatting and without an XML header More...
nothing | Qore::Xml::makeXMLFragment ()
| This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters. More...
string | Qore::Xml::makeXMLString (string key, hash h, *string encoding)
| serializes a hash into an XML string without whitespace formatting but with an XML header More...
string | Qore::Xml::makeXMLString (hash h, *string encoding)
| serializes a hash into an XML string without whitespace formatting but with an XML header More...
hash | Qore::Xml::parseXML (string xml, *string encoding)
| Parses an XML string and returns a Qore hash structure. More...
nothing | Qore::Xml::parseXML ()
| This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters. More...
hash | Qore::Xml::parseXMLAsData (string xml, *string encoding)
| Parses an XML string as data (does not necessarily preserve key order) and returns a Qore hash structure. More...
nothing | Qore::Xml::parseXMLAsData ()
| This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters. More...
hash | Qore::Xml::parseXMLAsDataWithRelaxNG (string xml, string relaxng, *string encoding)
| Parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the XML string against a RelaxNG schema string, and returns a Qore hash structure. More...
hash | Qore::Xml::parseXMLAsDataWithSchema (string xml, string xsd, *string encoding)
| Parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the XML string against an XSD schema string, and returns a Qore hash structure. More...
hash | Qore::Xml::parseXMLWithRelaxNG (string xml, string relaxng, *string encoding)
| Parses an XML string, validates the XML string against a RelaxNG schema string, and returns a Qore hash structure. More...
hash | Qore::Xml::parseXMLWithSchema (string xml, string xsd, *string encoding)
| Parses an XML string, validates the XML string against an XSD schema string, and returns a Qore hash structure. More...

## Detailed Description

## Function Documentation

string Qore::Xml::makeFormattedXMLFragment | ( | hash | h,
|  | *string | encoding
| ) |  |

serializes a hash into an XML string with whitespace formatting but without an XML header

Code Flags:
  RET_VALUE_ONLY

Parameters

  h | a hash of data to serialize: the hash can have any number of keys
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, the output string will have the default encoding

Returns
  an XML string corresponding to the input data, with whitespace formatting but without an XML header

Exceptions

  MAKE-XML-ERROR | An error occurred serializing the Qore data to an XML string

Example:
  my string $xml = makeFormattedXMLFragment($hash);

See Also
  Automatic XML Serialization and Deserialization

nothing Qore::Xml::makeFormattedXMLFragment | ( |  | ) |

This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters.

Code Flags:
  RUNTIME_NOOP

string Qore::Xml::makeFormattedXMLString | ( | string | key,
|  | hash | h,
|  | *string | encoding
| ) |  |

serializes a hash into an XML string with whitespace formatting and with an XML header

Code Flags:
  RET_VALUE_ONLY

Parameters

  key | top-level key
  h | the rest of the data to serialize under the top-level key
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, the output string will have the default encoding

Returns
  an XML string corresponding to the input data, with whitespace formatting and with an XML header

Exceptions

  MAKE-XML-ERROR | An error occurred serializing the Qore data to an XML string

Example:
  my string $xml = makeFormattedXMLString("key", $hash);

See Also
  Automatic XML Serialization and Deserialization

string Qore::Xml::makeFormattedXMLString | ( | hash | h,
|  | *string | encoding
| ) |  |

serializes a hash into an XML string with whitespace formatting and with an XML header

Code Flags:
  RET_VALUE_ONLY

Parameters

  h | a hash of data to serialize: the hash must have one top-level key and no more or an exception will be raised
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, the output string will have the default encoding

Returns
  an XML string corresponding to the input data, with whitespace formatting and with an XML header

Exceptions

  MAKE-FORMATTED-XML-STRING-PARAMETER-EXCEPTION | the hash passed not not have a single top-level key (either has no keys or more than one)
  MAKE-XML-ERROR | An error occurred serializing the Qore data to an XML string

Example:
  my string $xml = makeFormattedXMLString($hash);

See Also
  Automatic XML Serialization and Deserialization

string Qore::Xml::makeXMLFragment | ( | hash | h,
|  | *string | encoding
| ) |  |

serializes a hash into an XML string without whitespace formatting and without an XML header

Code Flags:
  RET_VALUE_ONLY

Parameters

  h | a hash of data to serialize: the hash can have any number of keys
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, the output string will have the default encoding

Returns
  an XML string corresponding to the input data, without whitespace formatting and without an XML header

Exceptions

  MAKE-XML-ERROR | An error occurred serializing the Qore data to an XML string

Example:
  my string $xml = makeXMLFragment($hash);

See Also
  Automatic XML Serialization and Deserialization

nothing Qore::Xml::makeXMLFragment | ( |  | ) |

This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters.

Code Flags:
  RUNTIME_NOOP

string Qore::Xml::makeXMLString | ( | string | key,
|  | hash | h,
|  | *string | encoding
| ) |  |

serializes a hash into an XML string without whitespace formatting but with an XML header

Code Flags:
  RET_VALUE_ONLY

Parameters

  key | top-level key
  h | the rest of the data to serialize under the top-level key
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, the output string will have the default encoding

Returns
  an XML string corresponding to the input data, without whitespace formatting but with an XML header

Exceptions

  MAKE-XML-ERROR | An error occurred serializing the Qore data to an XML string

Example:
  my string $xml = makeXMLString("key", $hash);

See Also
  Automatic XML Serialization and Deserialization

string Qore::Xml::makeXMLString | ( | hash | h,
|  | *string | encoding
| ) |  |

serializes a hash into an XML string without whitespace formatting but with an XML header

Code Flags:
  RET_VALUE_ONLY

Parameters

  h | a hash of data to serialize: the hash must have one top-level key and no more or an exception will be raised
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, the output string will have the default encoding

Returns
  an XML string corresponding to the input data, without whitespace formatting but with an XML header

Exceptions

  MAKE-XML-STRING-PARAMETER-EXCEPTION | the hash passed not not have a single top-level key (either has no keys or more than one)
  MAKE-XML-ERROR | An error occurred serializing the Qore data to an XML string

Example:
  my string $xml = makeXMLString($hash);

See Also
  Automatic XML Serialization and Deserialization

hash Qore::Xml::parseXML | ( | string | xml,
|  | *string | encoding
| ) |  |

Parses an XML string and returns a Qore hash structure.

If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret `'^'` and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.

This function should only be used when it is important to maintain the XML element order in the resulting Qore data structure (for example, when the data must be re-serialized to an XML string and the element order within a subelement must be maintained), for example, when parsing and reserializing an OSX property list in XML format. In all other cases, parseXMLAsData() should be used instead.

Code Flags:
  RET_VALUE_ONLY

Parameters

  xml | the XML string to parse
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, all strings in the output hash will have the default encoding

Returns
  a Qore hash structure corresponding to the XML input string

Exceptions

  PARSE-XML-EXCEPTION | Error parsing the XML string

Example:
  my hash $h = parseXML($xmlstr);

See Also
  - parseXMLAsData()
  - Automatic XML Serialization and Deserialization

nothing Qore::Xml::parseXML | ( |  | ) |

This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters.

Code Flags:
  RUNTIME_NOOP

hash Qore::Xml::parseXMLAsData | ( | string | xml,
|  | *string | encoding
| ) |  |

Parses an XML string as data (does not necessarily preserve key order) and returns a Qore hash structure.

This function does not preserve hash order with out-of-order duplicate keys; all duplicate keys are collapsed to the same list.

Note that data deserialized with this function may not be reserialized to an identical XML string to the input due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.

For a similar function preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see parseXML().

Code Flags:
  RET_VALUE_ONLY

Parameters

  xml | the XML string to parse
  encoding | an optional string giving the encoding for the output XML string; if this parameter is missing, all strings in the output hash will have the default encoding

Returns
  a Qore hash structure corresponding to the XML input string

Exceptions

  PARSE-XML-EXCEPTION | Error parsing the XML string

Example:
  my hash $h = parseXMLAsData($xmlstr);

See Also
  - parseXML()
  - Automatic XML Serialization and Deserialization

nothing Qore::Xml::parseXMLAsData | ( |  | ) |

This is a variant that is basically a noop, included for backwards-compatibility for functions that ignored type errors in the calling parameters.

Code Flags:
  RUNTIME_NOOP

hash Qore::Xml::parseXMLAsDataWithRelaxNG | ( | string | xml,
|  | string | relaxng,
|  | *string | encoding
| ) |  |

Parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the XML string against a RelaxNG schema string, and returns a Qore hash structure.

If any errors occur parsing the RelaxNG schema string, parsing the XML string, or validating the XML against the XSD, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.

Please note that data deserialized with this function may not be reserialized to an identical XML string to the input due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.

For a similar function preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see parseXMLWithRelaxNG().

The availability of this function depends on the presence of libxml2's `xmlTextReaderRelaxNGSetSchema()` function when the xml module was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG before running this function.

Code Flags:
  RET_VALUE_ONLY

Parameters

  xml | the XML string to parse
  relaxng | the RelaxNG schema string to use to validate the XML string
  encoding | an optional string giving the string encoding of any strings output; if this parameter is missing, the any strings output in the output hash will have UTF-8 encoding

Returns
  a Qore hash structure corresponding to the input

Exceptions

  PARSE-XML-EXCEPTION | error parsing the XML string
  RELAXNG-SYNTAX-ERROR | invalid RelaxNG string
  RELAXNG-VALIDATION-ERROR | the XML did not pass RelaxNG schema validation
  MISSING-FEATURE-ERROR | this exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHRELAXNG before calling this function

Example:
  my hash $h = parseXMLAsDataWithRelaxNG($xml, $relaxng);

See Also
  parseXMLWithSchema(), parseXMLAsDataWithSchema(), parseXMLWithRelaxNG()

hash Qore::Xml::parseXMLAsDataWithSchema | ( | string | xml,
|  | string | xsd,
|  | *string | encoding
| ) |  |

Parses an XML string as data (does not preserve hash order with out-of-order duplicate keys: collapses all to the same list), validates the XML string against an XSD schema string, and returns a Qore hash structure.

If any errors occur parsing the XSD string, parsing the XML string, or validating the XML against the XSD, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.

Please note that data deserialized with this function may not be reserialized to an identical XML string to the input due to the fact that duplicate, out-of-order XML elements are collapsed into lists in the resulting Qore hash, thereby losing the order in the original XML string.

For a similar function preserving the order of keys in the XML in the resulting Qore hash by generating Qore hash element names with numeric suffixes, see parseXMLWithSchema().

If any errors occur parsing the XSD string, parsing the XML string, or validating the XML against the XSD, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.

The availability of this function depends on the presence of libxml2's `xmlTextReaderSetSchema()` function when the xml module was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA before running this function.

Code Flags:
  RET_VALUE_ONLY

Parameters

  xml | the XML string to parse
  xsd | the XSD schema string to use to validate the XML string
  encoding | an optional string giving the string encoding of any strings output; if this parameter is missing, the any strings output in the output hash will have UTF-8 encoding

Returns
  a Qore hash structure corresponding to the input

Exceptions

  PARSE-XML-EXCEPTION | error parsing the XML string
  XSD-SYNTAX-ERROR | invalid XSD string
  XSD-VALIDATION-ERROR | the XML did not pass schema validation
  MISSING-FEATURE-ERROR | this exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHSCHEMA before calling this function

Example:
  my hash $h = parseXMLAsDataWithSchema($xml, $xsd);

See Also
  parseXMLWithSchema(), parseXMLWithRelaxNG(), parseXMLAsDataWithRelaxNG()

hash Qore::Xml::parseXMLWithRelaxNG | ( | string | xml,
|  | string | relaxng,
|  | *string | encoding
| ) |  |

Parses an XML string, validates the XML string against a RelaxNG schema string, and returns a Qore hash structure.

If any errors occur parsing the RelaxNG string, parsing the XML string, or validating the XML against the RelaxNG schema, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.

If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret "^" and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.

This function should only be used when it is important to maintain the XML element order in the resulting Qore data structure (for example, when the data must be re-serialized to an XML string and the element order within a subelement must be maintained), for example, when parsing and reserializing an OSX property list in XML format. Otherwise parseXMLAsDataWithRelaxNG() should be used instead.

The availability of this function depends on the presence of libxml2's `xmlTextReaderRelaxNGSetSchema()` function when the xml module was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHRELAXNG before running this function.

Code Flags:
  RET_VALUE_ONLY

Parameters

  xml | the XML string to parse
  relaxng | the RelaxNG schema string to use to validate the XML string
  encoding | an optional string giving the string encoding of any strings output; if this parameter is missing, the any strings output in the output hash will have UTF-8 encoding

Returns
  a Qore hash structure corresponding to the input

Exceptions

  PARSE-XML-EXCEPTION | error parsing the XML string
  RELAXNG-SYNTAX-ERROR | invalid RelaxNG string
  RELAXNG-VALIDATION-ERROR | the XML did not pass RelaxNG schema validation
  MISSING-FEATURE-ERROR | this exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHRELAXNG before calling this function

Example:
  my hash $h = parseXMLWithRelaxNG($xml, $relaxng);

See Also
  parseXMLWithSchema(), parseXMLAsDataWithSchema(), parseXMLAsDataWithRelaxNG()

hash Qore::Xml::parseXMLWithSchema | ( | string | xml,
|  | string | xsd,
|  | *string | encoding
| ) |  |

Parses an XML string, validates the XML string against an XSD schema string, and returns a Qore hash structure.

If any errors occur parsing the XSD string, parsing the XML string, or validating the XML against the XSD, exceptions are thrown. If no encoding string argument is passed, then all strings in the resulting hash will be in UTF-8 encoding regardless of the input encoding of the XML string.

If duplicate, out-of-order XML elements are found in the input string, they are deserialized to Qore hash elements with the same name as the XML element but including a caret `'^'` and a numeric prefix to maintain the same key order in the Qore hash as in the input XML string.

This function should only be used when it is important to maintain the XML element order in the resulting Qore data structure (for example, when the data must be re-serialized to an XML string and the element order within a subelement must be maintained), for example, when parsing and reserializing an OSX property list in XML format. Otherwise parseXMLAsDataWithSchema() should be used instead.

The availability of this function depends on the presence of libxml2's `xmlTextReaderSetSchema()` function when the xml module was compiled; for maximum portability check the constant HAVE_PARSEXMLWITHSCHEMA before running this function.

Code Flags:
  RET_VALUE_ONLY

Parameters

  xml | the XML string to parse
  xsd | the XSD schema string to use to validate the XML string
  encoding | an optional string giving the string encoding of any strings output; if this parameter is missing, the any strings output in the output hash will have UTF-8 encoding

Returns
  a Qore hash structure corresponding to the input

Exceptions

  PARSE-XML-EXCEPTION | error parsing the XML string
  XSD-SYNTAX-ERROR | invalid XSD string
  XSD-VALIDATION-ERROR | the XML did not pass schema validation
  MISSING-FEATURE-ERROR | this exception is thrown when the function is not available; for maximum portability, check the constant HAVE_PARSEXMLWITHSCHEMA before calling this function

Example:
  my hash $h = parseXMLWithSchema($xml, $xsd);

See Also
  parseXMLAsDataWithSchema(), parseXMLWithRelaxNG(), parseXMLAsDataWithRelaxNG()