Represents an XML document in the DOM model. More...

#include <libxml++/document.h>

Inheritance diagram for xmlpp::Document:

Public Member Functions
	Document (_xmlDoc * doc)
	Create a new C++ wrapper for an xmlDoc struct. More...

	Document (const ustring & version="1.0")
	Create a new document. 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...

const _xmlDoc *	cobj () const noexcept
	Access the underlying libxml implementation. More...

_xmlDoc *	cobj () 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
	Get the encoding used in the source from which the document has been loaded. More...

std::optional< ustring >	get_encoding2 () const
	Get the encoding used in the source from which the document has been loaded. More...

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...

Public Member Functions inherited from xmlpp::NonCopyable
	NonCopyable (const NonCopyable &)=delete

	NonCopyable (NonCopyable &&)=delete

NonCopyable &	operator= (const NonCopyable &)=delete

NonCopyable &	operator= (NonCopyable &&)=delete

Protected Member Functions
_xmlEntity *	get_entity (const ustring & name)
	Retrieve an Entity. More...

Protected Member Functions inherited from xmlpp::NonCopyable
	NonCopyable () noexcept

virtual	~NonCopyable ()

Detailed Description

Represents an XML document in the DOM model.

Constructor & Destructor Documentation

◆ Document() [1/2]

xmlpp::Document::Document ( const ustring & version = "1.0" )

explicit

Create a new document.

Parameters

version XML version.

Exceptions

xmlpp::internal_error If memory allocation fails.

◆ Document() [2/2]

xmlpp::Document::Document ( _xmlDoc * doc )

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.

◆ ~Document()

xmlpp::Document::~Document ( )

override

Member Function Documentation

◆ add_comment()

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

◆ add_processing_instruction()

ProcessingInstructionNode* xmlpp::Document::add_processing_instruction	(	const ustring &	name,
		const ustring &	content
	)

Append a new processing instruction node.

Since libxml++ 2.36:

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

◆ cobj() [1/2]

const _xmlDoc* xmlpp::Document::cobj ( ) const

noexcept

Access the underlying libxml implementation.

◆ cobj() [2/2]

_xmlDoc* xmlpp::Document::cobj ( )

noexcept

Access the underlying libxml implementation.

◆ create_root_node()

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_root_node_by_import()

Element* xmlpp::Document::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.

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.

◆ get_encoding()

ustring xmlpp::Document::get_encoding ( ) const

Get the encoding used in the source from which the document has been loaded.

Returns: The encoding used in the source from which the document has been loaded.

Deprecated:: 5.6: Use get_encoding2() instead.

◆ get_encoding2()

std::optional<ustring> xmlpp::Document::get_encoding2 ( ) const

Get the encoding used in the source from which the document has been loaded.

Returns: The encoding used in the source from which the document has been loaded, if any, else no value.

Since libxml++ 5.6:

◆ get_entity()

_xmlEntity* xmlpp::Document::get_entity ( const ustring & name )

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.

◆ get_internal_subset()

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.

◆ get_root_node() [1/2]

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.

◆ get_root_node() [2/2]

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.

◆ process_xinclude()

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().

Since libxml++ 2.36:

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

◆ set_entity_declaration()

virtual void xmlpp::Document::set_entity_declaration	(	const ustring &	name,
		XmlEntityType	type,
		const ustring &	publicId,
		const ustring &	systemId,
		const ustring &	content
	)

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

◆ set_internal_subset()

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.

◆ write_to_file()

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

◆ write_to_file_formatted()

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

◆ write_to_stream()

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

◆ write_to_stream_formatted()

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_to_string()

ustring xmlpp::Document::write_to_string ( const ustring & encoding = ustring() )

Write the document to the memory.

Parameters

encoding If not provided, UTF-8 is used

Returns: The written document.

Exceptions

xmlpp::exception

◆ write_to_string_formatted()

ustring xmlpp::Document::write_to_string_formatted ( const ustring & encoding = ustring() )

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

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Document() [1/2]

◆ Document() [2/2]

◆ ~Document()

Member Function Documentation

◆ add_comment()

◆ add_processing_instruction()

◆ cobj() [1/2]

◆ cobj() [2/2]

◆ create_root_node()

◆ create_root_node_by_import()

◆ get_encoding()

◆ get_encoding2()

◆ get_entity()

◆ get_internal_subset()

◆ get_root_node() [1/2]

◆ get_root_node() [2/2]

◆ process_xinclude()

◆ set_entity_declaration()

◆ set_internal_subset()

◆ write_to_file()

◆ write_to_file_formatted()

◆ write_to_stream()

◆ write_to_stream_formatted()

◆ write_to_string()

◆ write_to_string_formatted()