libxml++: xmlpp::Document Class Reference
Represents an XML document in the DOM model. More...
#include <libxml++/document.h>
Public Member Functions | |
Document (const ustring& version="1.0") | |
Create a new document. More... | |
Document (_xmlDoc* doc) | |
Create a new C++ wrapper for an xmlDoc struct. More... | |
~Document () override | |
CommentNode* | add_comment (const ustring& content) |
Append a new comment node. More... | |
ProcessingInstructionNode* | add_processing_instruction (const ustring& name, const ustring& content) |
Append a new processing instruction node. More... | |
_xmlDoc* | cobj () noexcept |
Access the underlying libxml implementation. More... | |
const _xmlDoc* | cobj () const noexcept |
Access the underlying libxml implementation. More... | |
Element* | create_root_node (const ustring& name, const ustring& ns_uri=ustring(), const ustring& ns_prefix=ustring()) |
Create the root element node. More... | |
Element* | create_root_node_by_import (const Node* node, bool recursive=true) |
Create a root element node by importing the node from another document, without affecting the source node. More... | |
ustring | get_encoding () const |
Dtd* | get_internal_subset () const |
Get the internal subset of this document. More... | |
Element* | get_root_node () |
Return the root node. More... | |
const Element* | get_root_node () const |
Return the root node. More... | |
int | process_xinclude (bool generate_xinclude_nodes=true, bool fixup_base_uris=true) |
Perform XInclude substitution on the XML document. More... | |
virtual void | set_entity_declaration (const ustring& name, XmlEntityType type, const ustring& publicId, const ustring& systemId, const ustring& content) |
Add an Entity declaration to the document. More... | |
void | set_internal_subset (const ustring& name, const ustring& external_id, const ustring& system_id) |
Create the internal subset of this document. More... | |
void | write_to_file (const std::string& filename, const ustring& encoding=ustring()) |
Write the document to a file. More... | |
void | write_to_file_formatted (const std::string& filename, const ustring& encoding=ustring()) |
Write the document to a file. More... | |
void | write_to_stream (std::ostream& output, const ustring& encoding=ustring()) |
Write the document to a std::ostream. More... | |
void | write_to_stream_formatted (std::ostream& output, const ustring& encoding=ustring()) |
Write the document to a std::ostream. More... | |
ustring | write_to_string (const ustring& encoding=ustring()) |
Write the document to the memory. More... | |
ustring | write_to_string_formatted (const ustring& encoding=ustring()) |
Write the document to the memory. More... | |
Protected Member Functions | |
_xmlEntity* | get_entity (const ustring& name) |
Retrieve an Entity. More... | |
Protected Member Functions inherited from xmlpp::NonCopyable | |
NonCopyable () noexcept | |
NonCopyable (const NonCopyable&)=delete | |
NonCopyable (NonCopyable&&)=delete | |
virtual | ~NonCopyable () |
NonCopyable& | operator= (const NonCopyable&)=delete |
NonCopyable& | operator= (NonCopyable&&)=delete |
Detailed Description
Represents an XML document in the DOM model.
Constructor & Destructor Documentation
|
explicit |
Create a new document.
- Parameters
-
version XML version.
- Exceptions
-
xmlpp::internal_error If memory allocation fails.
|
explicit |
Create a new C++ wrapper for an xmlDoc struct.
The created xmlpp::Document takes ownership of the xmlDoc. When the Document is deleted, so is the xmlDoc and all its nodes.
- Parameters
-
doc A pointer to an xmlDoc struct. Must not be nullptr
.
- Exceptions
-
xmlpp::internal_error If doc is nullptr
.
|
override |
Member Function Documentation
CommentNode* xmlpp::Document::add_comment | ( | const ustring& | content | ) |
Append a new comment node.
- Parameters
-
content The text. This should be unescaped - see ContentNode::set_content().
- Returns
- The new comment node.
- Exceptions
-
xmlpp::internal_error
ProcessingInstructionNode* xmlpp::Document::add_processing_instruction | ( | const ustring& | name, |
const ustring& | content | ||
) |
Append a new processing instruction node.
- Parameters
-
name The name of the application to which the instruction is directed. content The content of the instruction. This should be unescaped - see ContentNode::set_content().
- Returns
- The new processing instruction node.
- Exceptions
-
xmlpp::internal_error
|
noexcept |
Access the underlying libxml implementation.
|
noexcept |
Access the underlying libxml implementation.
Element* xmlpp::Document::create_root_node | ( | const ustring& | name, |
const ustring& | ns_uri = ustring() , |
||
const ustring& | ns_prefix = ustring() |
||
) |
Create the root element node.
If the document already contains a root element node, it is replaced, and the old root element node and all its descendants are deleted.
- Parameters
-
name The node's name. ns_uri The namespace URI. A namespace declaration will be added to this node, because it could not have been declared before. ns_prefix The namespace prefix to associate with the namespace. If no namespace prefix is specified then the namespace URI will be the default namespace.
- Returns
- A pointer to the new root node.
- Exceptions
-
xmlpp::internal_error If memory allocation fails. xmlpp::exception If a new namespace node cannot be created.
Create a root element node by importing the node from another document, without affecting the source node.
If the document already contains a root element node, it is replaced, and the old root element node and all its descendants are deleted.
- Parameters
-
node The node to copy and insert as the root node of the document. It must be an element node. recursive Whether to import the child nodes also. Defaults to true.
- Returns
- A pointer to the new root node
- Exceptions
-
xmlpp::exception If the node can't be copied.
ustring xmlpp::Document::get_encoding | ( | ) | const |
- Returns
- The encoding used in the source from which the document has been loaded.
|
protected |
Retrieve an Entity.
The entity can be from an external subset or internally declared.
- Parameters
-
name The name of the entity to get.
- Returns
- A pointer to the libxml2 entity structure, or
nullptr
if not found.
Dtd* xmlpp::Document::get_internal_subset | ( | ) | const |
Get the internal subset of this document.
- Returns
- A pointer to the DTD, or
nullptr
if not found.
Element* xmlpp::Document::get_root_node | ( | ) |
Return the root node.
This function does not create a default root node if it doesn't exist.
- Returns
- A pointer to the root node if it exists,
nullptr
otherwise.
const Element* xmlpp::Document::get_root_node | ( | ) | const |
Return the root node.
This function does not create a default root node if it doesn't exist.
- Returns
- A pointer to the root node if it exists,
nullptr
otherwise.
int xmlpp::Document::process_xinclude | ( | bool | generate_xinclude_nodes = true , |
bool | fixup_base_uris = true |
||
) |
Perform XInclude substitution on the XML document.
XInclude substitution may both add and delete nodes in the document, as well as change the type of some nodes. All pointers to deleted nodes and nodes whose type is changed become invalid. (The node type represented by an underlying xmlNode struct can change. The type of a C++ wrapper can't change. The old wrapper is deleted, and a new one is created if and when it's required.)
Parser::set_parser_options() and DomParser::set_xinclude_options() do not affect Document::process_xinclude().
- Parameters
-
generate_xinclude_nodes Generate XIncludeStart and XIncludeEnd nodes. fixup_base_uris Add or replace xml:base attributes in included element nodes, if necessary to preserve the target of relative URIs.
- Returns
- The number of substitutions.
- Exceptions
-
xmlpp::exception
|
virtual |
Add an Entity declaration to the document.
- Parameters
-
name The name of the entity that will be used in an entity reference. type The type of entity. publicId The public ID of the subset. systemId The system ID of the subset. content The value of the Entity. In entity reference substitutions, this is the replacement value.
- Exceptions
-
xmlpp::internal_error
void xmlpp::Document::set_internal_subset | ( | const ustring& | name, |
const ustring& | external_id, | ||
const ustring& | system_id | ||
) |
Create the internal subset of this document.
If the document already has an internal subset, a new one is not created.
- Parameters
-
name The DTD name. external_id The external (PUBLIC) ID, or an empty string. system_id The system ID, or an empty string.
void xmlpp::Document::write_to_file | ( | const std::string & | filename, |
const ustring& | encoding = ustring() |
||
) |
Write the document to a file.
- Parameters
-
filename encoding If not provided, UTF-8 is used
- Exceptions
-
xmlpp::exception
void xmlpp::Document::write_to_file_formatted | ( | const std::string & | filename, |
const ustring& | encoding = ustring() |
||
) |
Write the document to a file.
The output is formatted by inserting whitespaces, which is easier to read for a human, but may insert unwanted significant whitespaces. Use with care !
- Parameters
-
filename encoding If not provided, UTF-8 is used
- Exceptions
-
xmlpp::exception
void xmlpp::Document::write_to_stream | ( | std::ostream & | output, |
const ustring& | encoding = ustring() |
||
) |
Write the document to a std::ostream.
- Parameters
-
output A reference to the stream in which the document will be written encoding If not provided, UTF-8 is used
- Exceptions
-
xmlpp::exception xmlpp::internal_error
- Warning
- This method is much less efficient than write_to_string if you want to dump the document to a buffer or the standard output. Writing to a fstream is almost as fast as write_to_file
void xmlpp::Document::write_to_stream_formatted | ( | std::ostream & | output, |
const ustring& | encoding = ustring() |
||
) |
Write the document to a std::ostream.
The output is formatted by inserting whitespaces, which is easier to read for a human, but may insert unwanted significant whitespaces. Use with care !
- Parameters
-
output A reference to the stream in which the document will be written encoding If not provided, UTF-8 is used
- Exceptions
-
xmlpp::exception xmlpp::internal_error
- Warning
- See write_to_stream
Write the document to the memory.
- Parameters
-
encoding If not provided, UTF-8 is used
- Returns
- The written document.
- Exceptions
-
xmlpp::exception
Write the document to the memory.
The output is formatted by inserting whitespaces, which is easier to read for a human, but may insert unwanted significant whitespaces. Use with care !
- Parameters
-
encoding If not provided, UTF-8 is used
- Returns
- The written document.
- Exceptions
-
xmlpp::exception