PCL
pcl::XMLDocument Class Reference

XML document parsing and generation More...

#include <XML.h>

Public Types

using const_iterator = XMLNodeList::const_iterator
 
using iterator = XMLNodeList::iterator
 
using parser_option = XMLParserOption::mask_type
 

Public Member Functions

 XMLDocument ()=default
 
 XMLDocument (const XMLDocument &)=delete
 
virtual ~XMLDocument ()
 
void AddNode (XMLNode *node)
 
const_iterator Begin () const
 
const_iterator begin () const
 
void Clear ()
 
void ClearParserOptions ()
 
void DisableAutoFormatting (bool disable=true)
 
void DisableIndentTabs (bool disable=true)
 
const XMLDocTypeDeclarationDocType () const
 
void EnableAutoFormatting (bool enable=true)
 
void EnableIndentTabs (bool enable=true)
 
const_iterator End () const
 
const_iterator end () const
 
int IndentSize () const
 
bool IsAutoFormatting () const
 
bool IsEmpty () const
 
bool IsIndentTabs () const
 
int NodeCount () const
 
XMLDocumentoperator<< (XMLNode *node)
 
XMLDocumentoperator= (const XMLDocument &)=delete
 
const XMLNodeoperator[] (int i) const
 
void Parse (const String &text)
 
XMLElementReleaseRootElement ()
 
void RemoveElementFilter ()
 
void RemoveElementsByFilter (const XMLElementFilter &filter)
 
void RemoveElementsByName (const String &name, bool caseSensitive=true)
 
const XMLElementRootElement () const
 
IsoString Serialize () const
 
IsoString SerializeAsHTML () const
 
void SerializeToFile (const String &path) const
 
void SerializeToFileAsHTML (const String &path) const
 
void SetDocType (const XMLDocTypeDeclaration &docType)
 
void SetElementFilter (XMLElementFilter *filter)
 
void SetIndentSize (int indentSize)
 
void SetParserOption (parser_option option, bool on=true)
 
void SetParserOptions (XMLParserOptions options)
 
void SetRootElement (XMLElement *element)
 
void SetXML (const String &version="1.0", const String &encoding="UTF-8", bool standalone=false)
 
void SetXML (const XMLDeclaration &xml)
 
const XMLDeclarationXML () const
 

Detailed Description

XMLDocument implements parsing and generation of well-formed XML documents.

The Parse() member function reads and interprets a Unicode text string to generate a read-only document object model (DOM) that represents the data entities defined by a well-formed XML document. The DOM can be inspected with several member functions of the XMLDocument class. All XML nodes and elements in a document can be visited recursively with specialized accessor functions and iterators. See the Begin() and End() functions (and their STL-compatible equivalents, begin() and end()), as well as XML(), DocType(), RootElement(), and operator []( int ), among others.

For generation of XML documents, the Serialize() member function builds a new document as a Unicode string encoded in UTF-8. The document's root node and several nodes and critical components must be defined before document generation - see the SetXML(), SetDocType(), AddNode() and SetRootElement() member functions.

For general information on XML, the authoritative sources are the W3C recommendations:

https://www.w3.org/TR/xml/ https://www.w3.org/TR/xml11/ https://www.w3.org/TR/xml-names/

The following example shows how an existing document can be parsed as a new XMLDocument object, and then a new XML document can be generated and written to a disk file, all in just three source code lines:

xml.Parse( File::ReadTextFile( "/path/to/file.xml" ).UTF8ToUTF16() );
File::WriteTextFile( "/tmp/test.xml", xml.Serialize() );
static IsoString ReadTextFile(const String &filePath)
static void WriteTextFile(const String &filePath, const IsoString &text)
XMLDocument()=default

In this case the new document is generated without superfluous space characters. To enable automatic indentation of text lines, see the EnableAutoFormatting(), SetIndentSize() and EnableIndentTabs() member functions.

The following example:

XMLElement* e1 = new XMLElement( "Foo", XMLAttributeList() << XMLAttribute( "version", "1.0" ) );
XMLElement* e2 = new XMLElement( "Bar" );
*e2 << new XMLElement( "bar_child_1" )
<< new XMLElement( "bar_child_2" );
XMLElement* e3 = new XMLElement( "FooBar" );
*e3 << new XMLText( "This is FooBar." );
*e1 << e2 << e3;
xml.SetXML( "1.0" );
xml.SetRootElement( e1 );
xml.EnableAutoFormatting();
xml.SerializeToFile( "/tmp/foobar.xml" );

generates this XML file in /tmp/foobar.xml:

<?xml version="1.0" encoding="UTF-8"?>
<Foo version="1.0">
<Bar>
<bar_child_1/>
<bar_child_2/>
</Bar>
<FooBar>This is FooBar.</FooBar>
</Foo>

Definition at line 2640 of file XML.h.

Member Typedef Documentation

◆ const_iterator

using pcl::XMLDocument::const_iterator = XMLNodeList::const_iterator

Represents an immutable child node list iterator.

Definition at line 2652 of file XML.h.

◆ iterator

using pcl::XMLDocument::iterator = XMLNodeList::iterator

Represents a mutable child node list iterator.

Definition at line 2647 of file XML.h.

◆ parser_option

using pcl::XMLDocument::parser_option = XMLParserOption::mask_type

Represents an option to control the XML parser behavior. Valid options are defined in the XMLParserOption namespace.

Definition at line 2658 of file XML.h.

Constructor & Destructor Documentation

◆ XMLDocument() [1/2]

pcl::XMLDocument::XMLDocument ( )
default

Default constructor. Constructs an empty XML document.

For serialization of XML documents, this constructor defines the following default settings:

  • Auto-formatting disabled.
  • Use space characters (#x20) for indentation.
  • Indentation size = 3 spaces.

◆ ~XMLDocument()

virtual pcl::XMLDocument::~XMLDocument ( )
inlinevirtual

Virtual destructor. Recursively destroys all XML elements, declarations and auxiliary data associated with this object.

Definition at line 2676 of file XML.h.

◆ XMLDocument() [2/2]

pcl::XMLDocument::XMLDocument ( const XMLDocument )
delete

Copy constructor. This constructor is disabled because XMLDocument represents unique objects.

Member Function Documentation

◆ AddNode()

void pcl::XMLDocument::AddNode ( XMLNode node)

Appends a new top-level XML node to this document.

If the specified node already belongs to an XMLDocument object, or if a null pointer is specified, this member function will throw an Error exception.

The specified node will be appended to the current list of document nodes. If there is a root element in this document, the new node will be appended after the root element.

The node will be owned by this document object, which will destroy and deallocate it automatically when appropriate.

◆ Begin()

const_iterator pcl::XMLDocument::Begin ( ) const
inline

Returns an immutable iterator located at the beginning of the list of nodes of this XML document.

Definition at line 2804 of file XML.h.

◆ begin()

const_iterator pcl::XMLDocument::begin ( ) const
inline

STL-compatible iteration. Equivalent to Begin() const.

Definition at line 2822 of file XML.h.

◆ Clear()

void pcl::XMLDocument::Clear ( )

Destroys and deallocates all nodes and elements in this XML document object, and initializes all internal structures to a default state, yielding an uninitialized object.

If there is an element filter or a set of parser options defined for this object, they are preserved by this function. See RemoveElementFilter() to remove a filter set by a previous call to SetElementFilter(). See also ClearParserOptions() to reset parser options set by previous calls to SetParserOption().

◆ ClearParserOptions()

void pcl::XMLDocument::ClearParserOptions ( )
inline

Resets all parser options defined for this object by a previous call to SetParserOption() or SetParserOptions().

Definition at line 2987 of file XML.h.

◆ DisableAutoFormatting()

void pcl::XMLDocument::DisableAutoFormatting ( bool  disable = true)
inline

Disables the auto-formatting feature for generation of XML code. See IsAutoFormatting() for more information.

Definition at line 3043 of file XML.h.

◆ DisableIndentTabs()

void pcl::XMLDocument::DisableIndentTabs ( bool  disable = true)
inline

Disables the use of tabulator characters (#x09) for indentation. See IsIndentTabs() for more information.

Definition at line 3116 of file XML.h.

◆ DocType()

const XMLDocTypeDeclaration& pcl::XMLDocument::DocType ( ) const
inline

Returns a reference to the (immutable) XML document type declaration object associated with this document.

Definition at line 2725 of file XML.h.

◆ EnableAutoFormatting()

void pcl::XMLDocument::EnableAutoFormatting ( bool  enable = true)
inline

Enables the auto-formatting feature for generation of XML code. See IsAutoFormatting() for more information.

Definition at line 3034 of file XML.h.

◆ EnableIndentTabs()

void pcl::XMLDocument::EnableIndentTabs ( bool  enable = true)
inline

Enables the use of tabulator characters (#x09) for indentation. See IsIndentTabs() for more information.

Definition at line 3107 of file XML.h.

◆ End()

const_iterator pcl::XMLDocument::End ( ) const
inline

Returns an immutable iterator located at the end of the list of nodes of this XML document.

Definition at line 2813 of file XML.h.

◆ end()

const_iterator pcl::XMLDocument::end ( ) const
inline

STL-compatible iteration. Equivalent to End() const.

Definition at line 2830 of file XML.h.

◆ IndentSize()

int pcl::XMLDocument::IndentSize ( ) const
inline

Returns the number of space characters (#x20) used for each indentation level of text lines, when the auto-formatting feature is enabled and space characters are used for indentation.

When tabulator characters (#x09) are used for indentation, this setting is ignored and a single tabulator is always used for each indentation level. See IsAutoFormatting() and SetIndentSize() for more information.

Definition at line 3057 of file XML.h.

◆ IsAutoFormatting()

bool pcl::XMLDocument::IsAutoFormatting ( ) const
inline

Returns true iff the auto-formatting feature is enabled for XML serialization with this XMLDocument object.

When auto-formatting is enabled, ignorable line breaks (#x0A) and white space characters (either spaces (#x20) or tabulators (#x09)) are used to separate XML nodes and to indent text lines, respectively, improving readability of generated XML code. When auto-formatting is disabled, no superfluous white space characters are generated. The only exception is XMLText child nodes with space preservation enabled, which always ignore all indentation and formatting settings in order to reproduce their text contents without modification.

The auto-formatting feature is always disabled by default for newly constructed XMLDocument objects. This is because the main purpose and utility of XMLDocument is parsing and generation of XML documents intended for automated data management, without direct user intervention. Auto-formatting is only useful for human readability of XML source code.

Definition at line 3025 of file XML.h.

◆ IsEmpty()

bool pcl::XMLDocument::IsEmpty ( ) const
inline

Returns true iff this is an empty XML document. An empty document has no XML nodes.

Definition at line 2785 of file XML.h.

◆ IsIndentTabs()

bool pcl::XMLDocument::IsIndentTabs ( ) const
inline

Returns true if tabulator characters (#x09) are used for indentation of text lines, when the auto-formatting feature is enabled. Returns false if space characters (#x20) are used for indentation.

By default, text indentation is always performed using space characters by newly constructed XMLDocument objects.

Definition at line 3098 of file XML.h.

◆ NodeCount()

int pcl::XMLDocument::NodeCount ( ) const
inline

Returns the number of nodes in this XML document, or zero if this is an empty or uninitialized XMLDocument object.

Definition at line 2776 of file XML.h.

◆ operator<<()

XMLDocument& pcl::XMLDocument::operator<< ( XMLNode node)
inline

Insertion operator. Returns a reference to this XMLDocument object.

This operator is equivalent to AddNode( XMLNode* ).

Definition at line 2857 of file XML.h.

◆ operator=()

XMLDocument& pcl::XMLDocument::operator= ( const XMLDocument )
delete

Copy assignment. This operator is disabled because XMLDocument represents unique objects.

◆ operator[]()

const XMLNode& pcl::XMLDocument::operator[] ( int  i) const
inline

Returns a reference to the (immutable) document node at the specified zero-based index i. No bounds checking is performed: if the specified index is invalid, this function invokes undefined behavior.

Definition at line 2795 of file XML.h.

◆ Parse()

void pcl::XMLDocument::Parse ( const String text)

XML document parser. Reads and interprets the specified Unicode text string, which must be encoded in UTF-16, as a well-formed XML document.

This member function generates a document object model (DOM) to represent the data entities defined by the source XML document. The DOM can then be inspected with several member functions of the XMLDocument class. All XML nodes and elements can be visited recursively with specialized iterators. See the Begin() and End() functions (and their STL-compatible equivalents, begin() and end()), as well as XML(), DocType(), RootElement() and operator []( int ), among others.

◆ ReleaseRootElement()

XMLElement* pcl::XMLDocument::ReleaseRootElement ( )
inline

Releases the root element of this XML document.

This function returns the root element and causes this object to forget it. The caller will be responsible for destroying and deallocating the returned XMLElement instance as appropriate. This function performs an implicit call to Clear(), so the document will be empty after calling it.

If there is no root element, for example when this is an uninitialized XMLDocument instance, this function returns nullptr.

See also
RootElement(), SetRootElement()

Definition at line 2764 of file XML.h.

◆ RemoveElementFilter()

void pcl::XMLDocument::RemoveElementFilter ( )
inline

Removes an element filter set by a previous call to SetElementFilter(). If no filter has been defined for this object, this function has no effect.

Definition at line 2958 of file XML.h.

◆ RemoveElementsByFilter()

void pcl::XMLDocument::RemoveElementsByFilter ( const XMLElementFilter filter)
inline

Removes all top-level elements rejected by the specified filter.

For each top-level XML element in this document (including the root element), the specified filter object will be evaluated to accept or reject it. Rejected elements will be destroyed and removed.

See XMLElementFilter for a complete description of the element filtering functionality.

Definition at line 2901 of file XML.h.

References pcl::XMLNode::IsElement().

◆ RemoveElementsByName()

void pcl::XMLDocument::RemoveElementsByName ( const String name,
bool  caseSensitive = true 
)
inline

Destroys and removes all top-level elements with the specified name.

Note
The XML root element can be removed by this member function.

Definition at line 2923 of file XML.h.

References pcl::XMLNode::IsElement().

◆ RootElement()

const XMLElement* pcl::XMLDocument::RootElement ( ) const
inline

Returns a pointer to the (immutable) root element of this XML document. If there is no root element, for example when this is an uninitialized XMLDocument instance, this function returns nullptr.

See also
ReleaseRootElement(), SetRootElement()

Definition at line 2746 of file XML.h.

◆ Serialize()

IsoString pcl::XMLDocument::Serialize ( ) const
inline

Serializes this XML document. Returns the generated serialization as a Unicode string encoded in UTF-8.

To serialize a well-formed XML document, this object must be initialized first by defining a root element (see SetRootElement()) and other document nodes, as necessary (see SetXML(), SetDocType(), and AddNode()).

For formatting and indentation settings, see IsAutoFormatting(), IndentSize() and IsIndentTabs().

Definition at line 3132 of file XML.h.

◆ SerializeAsHTML()

IsoString pcl::XMLDocument::SerializeAsHTML ( ) const
inline

Serializes this XML document following a set of rules and exceptions pertaining to HTML. Returns the generated serialization as a Unicode string encoded in UTF-8.

In particular, HTML restricts self-closing tags to a reduced subset of void elements. See section 13.1.2 of the HTML Living Standard for details:

https://html.spec.whatwg.org/multipage/syntax.html#void-elements

See Serialize() for more information on XML serializations.

Definition at line 3150 of file XML.h.

◆ SerializeToFile()

void pcl::XMLDocument::SerializeToFile ( const String path) const

Serializes this XML document and writes the result to a file at the specified path with UTF-8 encoding.

See Serialize() for more information.

Warning
If a file already exists at the specified path, its previous contents will be lost after calling this function.

◆ SerializeToFileAsHTML()

void pcl::XMLDocument::SerializeToFileAsHTML ( const String path) const

Serializes this XML document following a set of rules and exceptions pertaining to HTML and writes the result to a file at the specified path with UTF-8 encoding.

See Serialize() for more information.

Warning
If a file already exists at the specified path, its previous contents will be lost after calling this function.

◆ SetDocType()

void pcl::XMLDocument::SetDocType ( const XMLDocTypeDeclaration docType)
inline

Associates a new XML document type declaration object with this XML document.

Definition at line 2734 of file XML.h.

◆ SetElementFilter()

void pcl::XMLDocument::SetElementFilter ( XMLElementFilter filter)
inline

Sets a new element filter for this object. The specified object will be owned by this XMLDocument instance, which will destroy and deallocate it when appropriate.

See XMLElementFilter for a complete description of the element filtering functionality. See RemoveElementFilter() to remove the element filter set by this function.

Definition at line 2948 of file XML.h.

◆ SetIndentSize()

void pcl::XMLDocument::SetIndentSize ( int  indentSize)
inline

Sets the number of indentation space characters.

Parameters
indentSizeNumber of space characters (#x20) used for a level of indentation of text lines in generated XML code, when the auto-formatting feature is enabled and space characters are used for indentation. The valid range of values is from zero (for no indentation) to 8 characters.

When the indentation size is zero and auto-formatting is enabled, each document node is generated in a separate line without any indentation. XMLText child nodes with space preservation enabled will always ignore all indentation and formatting settings, in order to reproduce their text contents without modification.

When tabulator characters (#x09) are used for indentation, this setting is ignored and a single tabulator character is always used for each indentation level.

The default indentation size is 3 for newly constructed XMLDocument objects.

Definition at line 3085 of file XML.h.

References pcl::Range().

◆ SetParserOption()

void pcl::XMLDocument::SetParserOption ( parser_option  option,
bool  on = true 
)
inline

Enables or disables an XML document parser option for this object. Valid options are defined in the XMLParserOption namespace. See ClearParserOptions() to reset all parser options to a default state.

Definition at line 2968 of file XML.h.

◆ SetParserOptions()

void pcl::XMLDocument::SetParserOptions ( XMLParserOptions  options)
inline

Sets the specified parser options. Valid options are defined in the XMLParserOption namespace. See ClearParserOptions() to reset all parser options to a default state.

Definition at line 2978 of file XML.h.

◆ SetRootElement()

void pcl::XMLDocument::SetRootElement ( XMLElement element)

Sets the root element of this XML document.

If the specified element already belongs to an XMLDocument object, if a null pointer is specified, or if a root node has already been defined for this document, this member function will throw an Error exception.

The specified element will be appended to the current list of document nodes. The element will be owned by this document object, which will destroy and deallocate it automatically when appropriate.

See also
RootElement(), ReleaseRootElement()

◆ SetXML() [1/2]

void pcl::XMLDocument::SetXML ( const String version = "1.0",
const String encoding = "UTF-8",
bool  standalone = false 
)
inline

Defines an XML declaration in this XML document with the specified version, encoding and standalone attributes.

Definition at line 2716 of file XML.h.

◆ SetXML() [2/2]

void pcl::XMLDocument::SetXML ( const XMLDeclaration xml)
inline

Defines an XML declaration in this XML document.

Definition at line 2707 of file XML.h.

◆ XML()

const XMLDeclaration& pcl::XMLDocument::XML ( ) const
inline

Returns a reference to the (immutable) XML declaration object associated with this document.

Definition at line 2699 of file XML.h.


The documentation for this class was generated from the following file: