- Generated on Sun Jan 14 2024 20:52:47 for PCL by
1.8.17
|
PCL
|
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 XMLDocTypeDeclaration & | DocType () 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 |
| XMLDocument & | operator<< (XMLNode *node) |
| XMLDocument & | operator= (const XMLDocument &)=delete |
| const XMLNode & | operator[] (int i) const |
| void | Parse (const String &text) |
| XMLElement * | ReleaseRootElement () |
| void | RemoveElementFilter () |
| void | RemoveElementsByFilter (const XMLElementFilter &filter) |
| void | RemoveElementsByName (const String &name, bool caseSensitive=true) |
| const XMLElement * | RootElement () 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 XMLDeclaration & | XML () const |
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:
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:
generates this XML file in /tmp/foobar.xml:
| using pcl::XMLDocument::const_iterator = XMLNodeList::const_iterator |
| using pcl::XMLDocument::iterator = XMLNodeList::iterator |
| 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.
|
default |
Default constructor. Constructs an empty XML document.
For serialization of XML documents, this constructor defines the following default settings:
|
inlinevirtual |
|
delete |
Copy constructor. This constructor is disabled because XMLDocument represents unique objects.
| 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.
|
inline |
|
inline |
STL-compatible iteration. Equivalent to Begin() const.
| 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().
|
inline |
Resets all parser options defined for this object by a previous call to SetParserOption() or SetParserOptions().
|
inline |
Disables the auto-formatting feature for generation of XML code. See IsAutoFormatting() for more information.
|
inline |
Disables the use of tabulator characters (#x09) for indentation. See IsIndentTabs() for more information.
|
inline |
|
inline |
Enables the auto-formatting feature for generation of XML code. See IsAutoFormatting() for more information.
|
inline |
Enables the use of tabulator characters (#x09) for indentation. See IsIndentTabs() for more information.
|
inline |
|
inline |
STL-compatible iteration. Equivalent to End() 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.
|
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.
|
inline |
|
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.
|
inline |
|
inline |
Insertion operator. Returns a reference to this XMLDocument object.
This operator is equivalent to AddNode( XMLNode* ).
|
delete |
Copy assignment. This operator is disabled because XMLDocument represents unique objects.
|
inline |
| 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.
|
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.
|
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.
|
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().
|
inline |
Destroys and removes all top-level elements with the specified name.
Definition at line 2923 of file XML.h.
References pcl::XMLNode::IsElement().
|
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.
|
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().
|
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.
| 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.
| 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.
|
inline |
|
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.
|
inline |
Sets the number of indentation space characters.
| indentSize | Number 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().
|
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.
|
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.
| 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.
|
inline |
|
inline |
1.8.17