libxml++ 2.42.3
Classes | Public Member Functions | Protected Member Functions | List of all members
xmlpp::Document Class Reference

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

#include <libxml++/document.h>

Inheritance diagram for xmlpp::Document:
xmlpp::NonCopyable

Public Member Functions

 Document (_xmlDoc * doc)
 Create a new C++ wrapper for an xmlDoc struct.
 
 Document (const Glib::ustring & version="1.0")
 Create a new document.
 
 ~Document () override
 
CommentNodeadd_comment (const Glib::ustring & content)
 Append a new comment node.
 
ProcessingInstructionNodeadd_processing_instruction (const Glib::ustring & name, const Glib::ustring & content)
 Append a new processing instruction node.
 
_xmlDoc * cobj ()
 Access the underlying libxml implementation.
 
const _xmlDoc * cobj () const
 Access the underlying libxml implementation.
 
Elementcreate_root_node (const Glib::ustring & name, const Glib::ustring & ns_uri=Glib::ustring(), const Glib::ustring & ns_prefix=Glib::ustring())
 Create the root element node.
 
Elementcreate_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.
 
Glib::ustring get_encoding () const
 
Dtdget_internal_subset () const
 Get the internal subset of this document.
 
Elementget_root_node () const
 Return the root node.
 
int process_xinclude (bool generate_xinclude_nodes, bool fixup_base_uris)
 Perform XInclude substitution on the XML document.
 
int process_xinclude (bool generate_xinclude_nodes=true)
 Perform XInclude substitution on the XML document.
 
virtual void set_entity_declaration (const Glib::ustring & name, XmlEntityType type, const Glib::ustring & publicId, const Glib::ustring & systemId, const Glib::ustring & content)
 Add an Entity declaration to the document.
 
void set_internal_subset (const Glib::ustring & name, const Glib::ustring & external_id, const Glib::ustring & system_id)
 Create the internal subset of this document.
 
void write_to_file (const Glib::ustring & filename, const Glib::ustring & encoding=Glib::ustring())
 Write the document to a file.
 
void write_to_file_formatted (const Glib::ustring & filename, const Glib::ustring & encoding=Glib::ustring())
 Write the document to a file.
 
void write_to_stream (std::ostream & output, const Glib::ustring & encoding=Glib::ustring())
 Write the document to a std::ostream.
 
void write_to_stream_formatted (std::ostream & output, const Glib::ustring & encoding=Glib::ustring())
 Write the document to a std::ostream.
 
Glib::ustring write_to_string (const Glib::ustring & encoding=Glib::ustring())
 Write the document to the memory.
 
Glib::ustring write_to_string_formatted (const Glib::ustring & encoding=Glib::ustring())
 Write the document to the memory.
 

Protected Member Functions

_xmlEntity * get_entity (const Glib::ustring & name)
 Retrieve an Entity.
 

Detailed Description

Represents an XML document in the DOM model.

Constructor & Destructor Documentation

◆ Document() [1/2]

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

Create a new document.

Parameters
versionXML version.
Exceptions
xmlpp::internal_errorIf 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
docA pointer to an xmlDoc struct. Must not be nullptr.

◆ ~Document()

xmlpp::Document::~Document ( )
override

Member Function Documentation

◆ add_comment()

CommentNode * xmlpp::Document::add_comment ( const Glib::ustring &  content)

Append a new comment node.

Parameters
contentThe 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 Glib::ustring &  name,
const Glib::ustring &  content 
)

Append a new processing instruction node.

Since libxml++ 2.36:
Parameters
nameThe name of the application to which the instruction is directed.
contentThe 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]

_xmlDoc * xmlpp::Document::cobj ( )

Access the underlying libxml implementation.

◆ cobj() [2/2]

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

Access the underlying libxml implementation.

◆ create_root_node()

Element * xmlpp::Document::create_root_node ( const Glib::ustring &  name,
const Glib::ustring &  ns_uri = Glib::ustring(),
const Glib::ustring &  ns_prefix = Glib::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
nameThe node's name.
ns_uriThe namespace URI. A namespace declaration will be added to this node, because it could not have been declared before.
ns_prefixThe 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_errorIf memory allocation fails.
xmlpp::exceptionIf 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
nodeThe node to copy and insert as the root node of the document. It must be an element node.
recursiveWhether to import the child nodes also. Defaults to true.
Returns
A pointer to the new root node
Exceptions
xmlpp::exceptionIf the node can't be copied.

◆ get_encoding()

Glib::ustring xmlpp::Document::get_encoding ( ) const
Returns
The encoding used in the source from which the document has been loaded.

◆ get_entity()

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

Retrieve an Entity.

The entity can be from an external subset or internally declared.

Parameters
nameThe 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()

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() [1/2]

int xmlpp::Document::process_xinclude ( bool  generate_xinclude_nodes,
bool  fixup_base_uris 
)

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.42:
Parameters
generate_xinclude_nodesGenerate XIncludeStart and XIncludeEnd nodes.
fixup_base_urisAdd 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

◆ process_xinclude() [2/2]

int xmlpp::Document::process_xinclude ( bool  generate_xinclude_nodes = 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_nodesGenerate XIncludeStart and XIncludeEnd nodes.
Returns
The number of substitutions.
Exceptions
xmlpp::exception

◆ set_entity_declaration()

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

Add an Entity declaration to the document.

Parameters
nameThe name of the entity that will be used in an entity reference.
typeThe type of entity.
publicIdThe public ID of the subset.
systemIdThe system ID of the subset.
contentThe 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 Glib::ustring &  name,
const Glib::ustring &  external_id,
const Glib::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
nameThe DTD name.
external_idThe external (PUBLIC) ID, or an empty string.
system_idThe system ID, or an empty string.

◆ write_to_file()

void xmlpp::Document::write_to_file ( const Glib::ustring &  filename,
const Glib::ustring &  encoding = Glib::ustring() 
)

Write the document to a file.

Parameters
filename
encodingIf not provided, UTF-8 is used
Exceptions
xmlpp::exception

◆ write_to_file_formatted()

void xmlpp::Document::write_to_file_formatted ( const Glib::ustring &  filename,
const Glib::ustring &  encoding = Glib::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
encodingIf not provided, UTF-8 is used
Exceptions
xmlpp::exception

◆ write_to_stream()

void xmlpp::Document::write_to_stream ( std::ostream output,
const Glib::ustring &  encoding = Glib::ustring() 
)

Write the document to a std::ostream.

Parameters
outputA reference to the stream in which the document will be written
encodingIf 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 Glib::ustring &  encoding = Glib::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
outputA reference to the stream in which the document will be written
encodingIf not provided, UTF-8 is used
Exceptions
xmlpp::exception
xmlpp::internal_error
Warning
See write_to_stream

◆ write_to_string()

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

Write the document to the memory.

Parameters
encodingIf not provided, UTF-8 is used
Returns
The written document.
Exceptions
xmlpp::exception

◆ write_to_string_formatted()

Glib::ustring xmlpp::Document::write_to_string_formatted ( const Glib::ustring &  encoding = Glib::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
encodingIf not provided, UTF-8 is used
Returns
The written document.
Exceptions
xmlpp::exception